Index: /trunk/doc/manual/Config.kmk
===================================================================
--- /trunk/doc/manual/Config.kmk	(revision 73275)
+++ /trunk/doc/manual/Config.kmk	(revision 73276)
@@ -46,7 +46,9 @@
  # use docbook from our tools directory
  VBOX_PATH_DOCBOOK        ?= $(PATH_DEVTOOLS)/common/DocBook/v1.69.1
- VBOX_PATH_DOCBOOK_DTD    ?= $(PATH_DEVTOOLS)/common/docbook-xml/v4.3
+ VBOX_PATH_DOCBOOK_DTD    ?= $(PATH_DEVTOOLS)/common/docbook-xml/v4.5
  VBOX_XML_CATALOG         ?= $(VBOX_PATH_MANUAL_OUTBASE)/catalog
  VBOX_XML_CATALOG_DOCBOOK ?= $(VBOX_PATH_MANUAL_OUTBASE)/docbook
+ VBOX_XML_CATALOG_MANUAL  ?= $(VBOX_PATH_MANUAL_OUTBASE)/manual
+ VBOX_XML_ENTITIES        ?= $(VBOX_PATH_MANUAL_OUTBASE)/all-entities.ent
 else
  # use docbook of the build host
@@ -67,22 +69,4 @@
 
 ##
-# Non-pattern-rule approach to editing XSLT files.
-# $(evalcall2 def_vbox_replace_paths_in_xslt)
-# @param    1   The XSLT source file (relative to Makefile dir).
-# @param    2   Optional output subdirectory (leading slash).
-define def_vbox_replace_paths_in_xslt
-OTHER_CLEAN += $$(VBOX_PATH_MANUAL_OUTBASE)$2/$(notdir $1)
-$$(VBOX_PATH_MANUAL_OUTBASE)$2/$(notdir $1): $$(VBOX_PATH_MANUAL_SRC)/$1 | $$$$(dir $$$$@)
-	$$(call MSG_L1,Pre-processing $$(<) to $$(@))
-	$$(QUIET)$$(SED) \
-		-e 's|@VBOX_PATH_DOCBOOK@|$$(VBOX_PATH_DOCBOOK)|g' \
-		-e 's|@VBOX_PATH_MANUAL_SRC@|$$(VBOX_PATH_MANUAL_SRC)|g' \
-		-e 's|@VBOX_PATH_MANUAL_OUTBASE@|$$(VBOX_PATH_MANUAL_OUTBASE)|g' \
-		-e 's|@VBOX_PATH_MANUAL_OUT_LANG@|$$(VBOX_PATH_MANUAL_OUTBASE)$2|g' \
-		--output "$$(@)" $$<
-endef
-
-
-##
 # Emits rules for preprocessing refentry sources (applying remarks element),
 # and for producing the actual man pages.
@@ -96,5 +80,5 @@
 		$(3) \
 		$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \
-		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) \
+		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
 		$$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@)
 	$$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
@@ -118,5 +102,5 @@
 		$$(VBOX_DOCBOOK_REFENTRY_TO_H_HELP) \
                $(2) \
-		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE) | $$$$(dir $$$$@)
+		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) $(MAKEFILE) | $$$$(dir $$$$@)
 	$$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(filter %.xml,$$^),$$(patsubst %.ts,%,$$@))
 	$$(QUIET)$$(APPEND) -tn "$$@" \
@@ -168,4 +152,7 @@
 		'  <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/" catalog="file:///$(VBOX_XML_CATALOG_DOCBOOK)"/>' \
 		'  <delegateURI uriStartString="http://www.oasis-open.org/docbook/"         catalog="file:///$(VBOX_XML_CATALOG_DOCBOOK)"/>' \
+		'  <delegateSystem systemIdStartString="$(VBOX_PATH_MANUAL_SRC)"            catalog="file:///$(VBOX_XML_CATALOG_MANUAL)"/>' \
+		'  <delegateURI uriStartString="$(VBOX_PATH_MANUAL_SRC)"                    catalog="file:///$(VBOX_XML_CATALOG_MANUAL)"/>' \
+		'  <delegateURI uriStartString="$(VBOX_PATH_MANUAL_OUTBASE)"                catalog="file:///$(VBOX_XML_CATALOG_MANUAL)"/>' \
 		'</catalog>'
 
@@ -177,14 +164,14 @@
 		'<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \
 		'<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \
-		'  <public publicId="-//OASIS//ELEMENTS DocBook XML Information Pool V4.3//EN"          uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbpoolx.mod"/>' \
-		'  <public publicId="-//OASIS//DTD DocBook XML V4.3//EN"                                uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd"/>' \
-		'  <public publicId="-//OASIS//ENTITIES DocBook XML Character Entities V4.3//EN"        uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbcentx.mod"/>' \
-		'  <public publicId="-//OASIS//ENTITIES DocBook XML Notations V4.3//EN"                 uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbnotnx.mod"/>' \
-		'  <public publicId="-//OASIS//ENTITIES DocBook XML Additional General Entities V4.3//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbgenent.mod"/>' \
-		'  <public publicId="-//OASIS//ELEMENTS DocBook XML Document Hierarchy V4.3//EN"        uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbhierx.mod"/>' \
+		'  <public publicId="-//OASIS//ELEMENTS DocBook XML Information Pool V4.5//EN"          uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbpoolx.mod"/>' \
+		'  <public publicId="-//OASIS//DTD DocBook XML V4.5//EN"                                uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd"/>' \
+		'  <public publicId="-//OASIS//ENTITIES DocBook XML Character Entities V4.5//EN"        uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbcentx.mod"/>' \
+		'  <public publicId="-//OASIS//ENTITIES DocBook XML Notations V4.5//EN"                 uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbnotnx.mod"/>' \
+		'  <public publicId="-//OASIS//ENTITIES DocBook XML Additional General Entities V4.5//EN" uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbgenent.mod"/>' \
+		'  <public publicId="-//OASIS//ELEMENTS DocBook XML Document Hierarchy V4.5//EN"        uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/dbhierx.mod"/>' \
 		'  <public publicId="-//OASIS//DTD XML Exchange Table Model 19990315//EN"               uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/soextblx.dtd"/>' \
-		'  <public publicId="-//OASIS//DTD DocBook XML CALS Table Model V4.3//EN"               uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/calstblx.dtd"/>' \
-		'  <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.3" rewritePrefix="file:///$(VBOX_PATH_DOCBOOK_DTD)"/>' \
-		'  <rewriteURI         uriStartString="http://www.oasis-open.org/docbook/xml/4.3" rewritePrefix="file:///$(VBOX_PATH_DOCBOOK_DTD)"/>' \
+		'  <public publicId="-//OASIS//DTD DocBook XML CALS Table Model V4.5//EN"               uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/calstblx.dtd"/>' \
+		'  <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4.5" rewritePrefix="file:///$(VBOX_PATH_DOCBOOK_DTD)"/>' \
+		'  <rewriteURI         uriStartString="http://www.oasis-open.org/docbook/xml/4.5" rewritePrefix="file:///$(VBOX_PATH_DOCBOOK_DTD)"/>' \
 		'  <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN"   uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsa.ent"/>' \
 		'  <public publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN"  uri="file:///$(VBOX_PATH_DOCBOOK_DTD)/ent/iso-amsb.ent"/>' \
@@ -208,15 +195,51 @@
 		'</catalog>'
 
+ # Create a docbook catalog file for xsltproc that points to the local manual files in non-default locations
+ $(VBOX_XML_CATALOG_MANUAL): $(MAKEFILE_CURRENT) | $$(dir $$@)
+	$(call MSG_L1,Creating catalog $@)
+	$(QUIET)$(APPEND) -tn "$@" \
+		'<?xml version="1.0"?>' \
+		'<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \
+		'<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/user_ChangeLogImpl.xml" uri="file://$(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/user_VBoxManage_CommandsOverview.xml" uri="file://$(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xsl" uri="file://$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/user_man_VBoxManage-mediumio.xml" uri="file://$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_man_VBoxManage-mediumio.xml"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/user_man_VBoxManage-debugvm.xml" uri="file://$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_man_VBoxManage-debugvm.xml"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/user_man_VBoxManage-extpack.xml" uri="file://$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_man_VBoxManage-extpack.xml"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/user_man_VBoxManage-unattended.xml" uri="file://$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_man_VBoxManage-unattended.xml"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/user_isomakercmd-man.xml" uri="file://$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_isomakercmd-man.xml"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef_apiref.xml" uri="file://$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef_apiref.xml"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/all-entities.ent" uri="file://$(VBOX_PATH_MANUAL_OUTBASE)/all-entities.ent"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/html/docbook.xsl" uri="file://$(VBOX_PATH_DOCBOOK)/html/docbook.xsl"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/html/chunk.xsl" uri="file://$(VBOX_PATH_DOCBOOK)/html/chunk.xsl"/>' \
+		'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/htmlhelp/htmlhelp.xsl" uri="file://$(VBOX_PATH_DOCBOOK)/htmlhelp/htmlhelp.xsl"/>' \
+		'</catalog>'
+
 endif # VBOX_XML_CATALOG
 
 
+ifdef VBOX_XML_ENTITIES
+
+ $(VBOX_XML_ENTITIES): $(MAKEFILE_CURRENT) | $$(dir $$@)
+	$(call MSG_L1,Creating entities $@)
+	$(QUIET)$(APPEND) -tn "$@" \
+		'<!ENTITY VBOX_PRODUCT SYSTEM "$(VBOX_PATH_MANUAL_SRC)/ent-vbox-product.xml" >' \
+		'<!ENTITY VBOX_VERSION_MAJOR "$(VBOX_VERSION_MAJOR)" >' \
+		'<!ENTITY VBOX_VERSION_MINOR "$(VBOX_VERSION_MINOR)" >' \
+		'<!ENTITY VBOX_VERSION_BUILD "$(VBOX_VERSION_MINOR)" >' \
+		'<!ENTITY VBOX_VERSION_STRING "$(VBOX_VERSION_STRING)" >' \
+		'<!ENTITY VBOX_VENDOR "$(VBOX_VENDOR)" >' \
+		'<!ENTITY VBOX_C_YEAR "$(VBOX_C_YEAR)" >'
+
+endif # VBOX_XML_ENTITIES
+
+
 #
 # Generate rules for editing the refentry to C/H style sheets.
 #
-$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-C-help.xsl,)
-VBOX_DOCBOOK_REFENTRY_TO_C_HELP = $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-C-help.xsl
-
-$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-H-help.xsl,)
-VBOX_DOCBOOK_REFENTRY_TO_H_HELP = $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-H-help.xsl
+VBOX_DOCBOOK_REFENTRY_TO_C_HELP = $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-C-help.xsl
+
+VBOX_DOCBOOK_REFENTRY_TO_H_HELP = $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-H-help.xsl
 
 #
Index: /trunk/doc/manual/Makefile.kmk
===================================================================
--- /trunk/doc/manual/Makefile.kmk	(revision 73275)
+++ /trunk/doc/manual/Makefile.kmk	(revision 73276)
@@ -37,5 +37,5 @@
 #   -- PDF file via LaTeX: pre-process the XML files in PATH_TARGET, then
 #      run our custom "dblatex" perl script on UserManual.xml, which parses
-#      the XML (using the Perl SAX parsers) and dumps a matching latex file
+#      the XML (using the Perl SAX parsers) and dumps a matching LaTeX file
 #      to UserManual.tex. This is then regularly processed by pdflatex to
 #      generate PDF.
@@ -125,33 +125,4 @@
 
 
-##
-# Non-pattern-rule approach to editing XML files.
-# $(evalcall2 def_vbox_replace_stuff_in_xml)
-# @param    1   The XSLT source file (relative to Makefile dir).
-# @param    2   Optional output subdirectory (leading slash).
-#
-define def_vbox_replace_stuff_in_xml
-OTHER_CLEAN += $$(VBOX_PATH_MANUAL_OUTBASE)$2/$(notdir $1)
-$$(VBOX_PATH_MANUAL_OUTBASE)$2/$(notdir $1): $$(VBOX_PATH_MANUAL_SRC)/$1 $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@)
-	$$(call MSG_L1,Pre-processing $$(<) to $$(@))
-	$$(QUIET)$$(SED) \
-		-e 's|@VBOX_PATH_DOCBOOK@|$$(VBOX_PATH_DOCBOOK)|g' \
-		-e 's|@VBOX_PATH_MANUAL_SRC@|$$(VBOX_PATH_MANUAL_SRC)|g' \
-		-e 's|@VBOX_PATH_MANUAL_OUTBASE@|$$(VBOX_PATH_MANUAL_OUTBASE)|g' \
-		-e 's|@VBOX_PATH_MANUAL_OUT_LANG@|$$(VBOX_PATH_MANUAL_OUTBASE)$2|g' \
-               \
-		-e 's/@VBOX_VERSION_MAJOR@/$$(VBOX_VERSION_MAJOR)/g' \
-	        -e 's/@VBOX_VERSION_MINOR@/$$(VBOX_VERSION_MINOR)/g' \
-	        -e 's/@VBOX_VERSION_BUILD@/$$(VBOX_VERSION_BUILD)/g' \
-	        -e 's/@VBOX_VERSION_STRING@/$$(VBOX_VERSION_STRING)/g' \
-	        -e 's/@VBOX_VENDOR@/$$(VBOX_VENDOR)/g' \
-	        -e 's/@VBOX_PRODUCT@/$$(VBOX_PRODUCT)/g' \
-	        -e 's/@VBOX_C_YEAR@/$$(VBOX_C_YEAR)/g' \
-               \
-		--output "$$(@)" $$<
-endef
-
-
-
 #
 # Targets
@@ -204,29 +175,34 @@
  endif
 
- VBOX_MANUAL_XML_CHANGELOG = \
- 	user_ChangeLogImpl.xml
-
  VBOX_MANUAL_XML_FILES = \
  	UserManual.xml \
+ 	user_Introduction.xml \
+ 	user_Installation.xml \
+ 	user_BasicConcepts.xml \
+ 	user_GuestAdditions.xml \
+ 	user_Storage.xml \
+ 	user_Networking.xml \
+ 	user_Frontends.xml \
+ 	user_VBoxManage.xml \
  	user_AdvancedTopics.xml \
- 	user_BasicConcepts.xml \
- 	user_Glossary.xml \
- 	user_Frontends.xml \
- 	user_Installation.xml \
- 	user_GuestAdditions.xml \
- 	user_Introduction.xml \
+ 	user_Technical.xml \
+ 	user_VirtualBoxAPI.xml \
+ 	user_Troubleshooting.xml \
+ 	user_Security.xml \
  	user_KnownIssues.xml \
+ 	user_ChangeLog.xml \
+ 	user_ThirdParty.xml \
  	user_PrivacyPolicy.xml \
- 	user_Security.xml \
- 	user_Technical.xml \
- 	user_ThirdParty.xml \
- 	user_Troubleshooting.xml \
- 	user_VBoxManage.xml \
- 	user_VirtualBoxAPI.xml \
- 	user_Storage.xml \
- 	user_Networking.xml
-
- VBOX_MANUAL_XML_FILES_INCL_CHANGELOG = $(VBOX_MANUAL_XML_FILES) \
- 	user_ChangeLog.xml
+ 	user_Glossary.xml
+
+ VBOX_MANUAL_XML_FILES_COMMON = \
+ 	$(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml
+
+$(foreach lang,$(VBOX_MANUAL_LANGUAGES), \
+ $(eval VBOX_MANUAL_XML_FILES_GENERATED_$$(lang) := \
+ 	$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
+	$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/overview_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
+	$$(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml \
+ 	$$(VBOX_PATH_MANUAL_OUTBASE)/$$(lang)/user_isomakercmd-man.xml))
 
  VBOX_SDKREF_XML_FILES = \
@@ -267,7 +243,7 @@
  	$(VBOX_XML_CATALOG) \
  	$(VBOX_XML_CATALOG_DOCBOOK) \
+ 	$(VBOX_XML_CATALOG_MANUAL) \
+ 	$(VBOX_XML_ENTITIES) \
  	$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/, \
- 		$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG) \
-               $(VBOX_MANUAL_XML_REFENTRY_FILES) \
                $(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
                $(patsubst man_%,%.1,$(basename $(VBOX_MANUAL_XML_REFENTRY_FILES))) \
@@ -293,11 +269,12 @@
                HTMLHelp/toc.hhc \
                HTMLHelp/htmlhelp.hhp \
- 		titlepage-htmlhelp.xsl \
 		UserManual.pdf \
 		VirtualBox.chm \
 		ChangeLog.html \
 		validatemanual.run \
+		validateaccessibility.run \
+		validatesdkref.run \
 		)) \
- 	$(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG) \
+ 	$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl \
  	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/overview_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
  	$(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml \
@@ -308,5 +285,4 @@
 	\
  	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \
-		$(VBOX_SDKREF_XML_FILES) \
 		$(VBOX_SDKREF_LATEX_FILES_TARGET) \
 		SDKRef.pdf \
@@ -315,5 +291,4 @@
 	\
  	$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/, \
-		$(VBOX_ACCESSIBILITY_XML_FILES) \
 		$(VBOX_ACCESSIBILITY_LATEX_FILES_TARGET) \
 		html-single/Accessibility.html \
@@ -381,50 +356,4 @@
 if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK))
 
-
-##########################################################################################
-#
-#  Rules: Preprocess DocBook XML files
-#  (preliminary step for both CHM and PDF generation)
-#
-##########################################################################################
-
-#
-# The following rules for $(VBOX_PATH_MANUAL_OUTBASE)/*.xml process the XML files
-# in doc/manual to allow for some magic variable replacements. The PDF and CHM
-# targets do not depend on the XML files in doc/manual, but those in
-# $(VBOX_PATH_MANUAL_OUTBASE) instead, which we copy there from here, after that magic
-# processing.
-#
-# So, before copying, the following steps are performed:
-#
-# -- $VBOX_VERSION_* strings are replaced with the actual current VBox version.
-# -- $VBOX_MANAGE_OUTPUT (in VBoxManage.xml) is replaced with the current
-#    output of the actual VBoxManage program, to save us from having to
-#    update the manual all the time.
-#
-
-# Only one changelog for all languages
-# $(VBOX_PATH_MANUAL_OUTBASE)/$(VBOX_MANUAL_XML_CHANGELOG): $(VBOX_PATH_MANUAL_SRC)/$(VBOX_MANUAL_XML_CHANGELOG) | $$(dir $$@)
-# 	$(QUIET)$(INSTALL) -m 0644 $< $@
-
-# Manual dependency on user_ChangeLogImpl.xml
-$(foreach lang,$(VBOX_MANUAL_LANGUAGES) \
-,$(eval $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_ChangeLog.xml: $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml))
-
-# Manual dependency for user_VBoxManage.xml.
-$(foreach lang,$(VBOX_MANUAL_LANGUAGES), \
-$(eval $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_VBoxManage.xml: $(VBOX_PATH_MANUAL_SRC)/$(lang)/user_VBoxManage.xml \
-	$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
-	$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/overview_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \
-	$(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml ))
-
-# Manual dependency for user_AdvancedTopics.xml.
-$(foreach lang,$(VBOX_MANUAL_LANGUAGES) \
-,$(eval $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_AdvancedTopics.xml: $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_isomakercmd-man.xml))
-
-# Intermediate step to do some variable replacement in the document.
-$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG) \
-,$(evalcall2 def_vbox_replace_stuff_in_xml,/$(lang)/$(file),/$(lang))))
-
 ##
 # Morph man pages into manual sections.
@@ -436,5 +365,5 @@
 $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/user_$(2): $(3) \
 		$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl \
-		$$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \
+		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
 		$$(VBOX_VERSION_STAMP) | $$(dir $$@)
 	$$(call MSG_TOOL,xsltproc $$(notdir $$(filter %.xsl,$$^)),,$$(filter %.xml,$$^),$$@)
@@ -453,5 +382,5 @@
 		$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-overview.xsl \
 		$$(patsubst overview_%,$$(VBOX_PATH_MANUAL_SRC)/en_US/%,$$(notdir $$@)) \
-		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \
+		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
                | $$(dir $$@)
 	$(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@)
@@ -463,5 +392,5 @@
 	$(QUIET)$(APPEND) -tn "$@" \
 		'<?xml version="1.0" encoding="UTF-8"?>' \
-               '<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">' \
+               '<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">' \
                '<sect1> <!-- this will be skipped via xpointer in the include. --> '
 	$(QUIET)$(REDIRECT) -wo $@.dumpopts -E 'VBOX_LOG_FLAGS=disabled' -E 'VBOX_LOG_DEST=nofile' \
@@ -511,5 +440,4 @@
 	$$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)'
 endef
-
 $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_cp_images_pdf))
 
@@ -521,45 +449,55 @@
 ##########################################################################################
 
-$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/UserManual.pdf): \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.pdf : \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.tex \
-		$(if $(VBOX_OSE),,$(VBOX_PATH_MANUAL_OUTBASE)/%/ucs.sty) \
-		$(foreach f,$(VBOX_MANUAL_LANGUAGES),\
-		  $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/,$(VBOX_MANUAL_PNG_FILES_$(f)))) | $$(dir $$@)
+
+# Generate PDF from LaTeX
+# Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
+define def_vbox_usermanual_tex_to_pdf
+local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
+$$(out_dir)/UserManual.pdf: \
+		$$(out_dir)/UserManual.tex \
+		$$(if $$(VBOX_OSE),,$$(out_dir)/ucs.sty) \
+		$$(addprefix $$(out_dir)/,$$(VBOX_MANUAL_PNG_FILES_$(lang))) | $$$$(dir $$$$@)
 # PDF generation via Latex: generate the .tex file
-	$(call MSG_L1,pdflatex $< (four passes) -> $@)
-	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex
-	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex
-	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex
-	$(QUIET)$(REDIRECT) -w+ti /dev/null -C $(@D) -- $(VBOX_PDFLATEX_CMD) UserManual.tex
-	$(QUIET)$(SED) -ne '/Warning: Hyper reference/p' $(basename $<).log
-	$(QUIET)$(SED) -n \
+	$$(call MSG_L1,pdflatex $$< (four passes) -> $$@)
+	$$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex
+	$$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex
+	$$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex
+	$$(QUIET)$$(REDIRECT) -w+ti /dev/null -C $$(@D) -- $$(VBOX_PDFLATEX_CMD) UserManual.tex
+	$$(QUIET)$$(SED) -ne '/Warning: Hyper reference/p' $$(basename $$<).log
+	$$(QUIET)$$(SED) -n \
 		-e '/Warning: There were \(undefined references\|multiply-defined labels\)/{p; q 1}' \
-		$(basename $@).log
-	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)
-
-# generate temporary LaTeX source from processed XML
-$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/UserManual.tex): \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.tex : \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.xml \
-		$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
-		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/%/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
-		$(if $(and $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_DOCBOOK_DTD)),$(VBOX_PATH_MANUAL_OUTBASE)/%/validatemanual.run,) \
-		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE_CURRENT)
-	$(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@)
-	$(QUIET)$(RM) -f $(addprefix $(@D)/,$(VBOX_MANUAL_LATEX_FILES_TARGET))
+		$$(basename $$@).log
+	$$(call MSG_L1,Fresh LaTeX-generated PDF is now at $$@)
+endef
+$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_tex_to_pdf))
+
+# Generate LaTeX from XML
+# Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
+define def_vbox_usermanual_xml_to_tex
+local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
+$$(out_dir)/UserManual.tex: \
+		$$(addprefix $$(VBOX_PATH_MANUAL_SRC)/$(lang)/,$$(VBOX_MANUAL_XML_FILES)) \
+		$$(VBOX_MANUAL_XML_FILES_COMMON) \
+		$$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \
+		$$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
+		$$(if $$(VBOX_HAVE_XMLLINT),$$(out_dir)/validatemanual.run,) \
+		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
+		$$(VBOX_XML_ENTITIES) $$(MAKEFILE_CURRENT)
+	$$(call MSG_TOOL,xsltproc $$(notdir $$(filter %.xsl,$$^)),,$$(firstword $$(filter %.xml,$$^)),$$@)
+	$$(QUIET)$$(RM) -f $$(addprefix $$(@D)/,$$(VBOX_MANUAL_LATEX_FILES_TARGET))
 #   generate TeX source from processed docbook and store it in UserManual.tex.tmp;
-#   pass current language to xsltproc in TARGETLANG variable (extract it from the
-#   current directory, should become "de_DE" or the like)
-	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG $(notdir $(@D)) \
-		-o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $<
+#   pass current language to xsltproc in TARGETLANG variable
+	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG $(lang) \
+		-o $$@.tmp $$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $$<
 #   for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word;
 #   the \QUOTE{} was inserted by docbook2latex.xsl for all quotes _outside_ of screen sections
-	$(QUIET)$(SED) \
+	$$(QUIET)$$(SED) \
 		-e 's|^\\QUOTE{}|\\OQ{}|g' \
 		-e 's|\(\W\)\\QUOTE{}|\1\\OQ{}|g' \
 		-e 's|\(\w\)\\QUOTE{}|\1\\CQ{}|g' \
-		--output $@ $@.tmp
-	$(QUIET)$(RM) -f $@.tmp
+		--output $$@ $$@.tmp
+	$$(QUIET)$$(RM) -f $$@.tmp
+endef
+$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_xml_to_tex))
 
 # Useful aliases
@@ -577,7 +515,9 @@
 validatemanual_$(lang):: $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/validatemanual.run
 $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/validatemanual.run: \
-		$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/UserManual.xml \
-		$$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
-		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(MAKEFILE_CURRENT) | $$$$(dir $$$$@)
+		$$(addprefix $$(VBOX_PATH_MANUAL_SRC)/$(lang)/,$$(VBOX_MANUAL_XML_FILES)) \
+		$$(VBOX_MANUAL_XML_FILES_COMMON) \
+		$$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \
+		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
+		$$(VBOX_XML_ENTITIES) $$(MAKEFILE_CURRENT) | $$$$(dir $$$$@)
 	$$(call MSG_L1,Validating $$<)
 	$$(QUIET)$$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$<
@@ -585,4 +525,7 @@
 endef
 $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_validate_xml))
+
+
+# Handy aliases.
 validatemanual:: $(foreach lang,$(VBOX_MANUAL_LANGUAGES),validatemanual_$(lang))
 
@@ -605,18 +548,14 @@
 	$(QUIET)$(VBOX_XSLTPROC) $(VBOX_XSLTPROC_OPTS) --xinclude --nonet -o $@ $< $(VBOX_DOC_XIDL_SRC_TMP)
 
-$(evalcall2 def_vbox_replace_stuff_in_xml,/en_US/SDKRef.xml,/en_US)
-$(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.xml: $(VBOX_MANUAL_APIREF_TMP)
-
-# Turn SDKRef.xml into latex.
+# Turn SDKRef.xml into LaTeX.
 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.tex: \
-		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_SDKREF_XML_FILES)) \
+		$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_SDKREF_XML_FILES)) \
+		$(VBOX_MANUAL_APIREF_TMP) \
 		$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
-		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE_CURRENT) | $$(dir $$@)
+		$(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run,) \
+		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
+		$(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@)
 	$(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@)
 	$(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_SDKREF_LATEX_FILES_TARGET))
-##      check it for validity first.
-#if defined(VBOX_HAVE_XMLLINT) && defined(VBOX_PATH_DOCBOOK_DTD)
-#	$(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $<
-#endif
 #	generate TeX source from processed docbook and store it in SDKRef.tex.tmp
 	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \
@@ -646,7 +585,19 @@
 	$(call MSG_L1,Fresh LaTeX-generated PDF is now at $@)
 
+# Validating SDKRef.xml. It is invoked automatically at build time,
+# but can also be manually invoked via the 'validate-sdkref' alias.
+$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run: \
+		$(VBOX_PATH_MANUAL_SRC)/en_US/SDKRef.xml \
+		$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_SDKREF_XML_FILES)) \
+		$(VBOX_MANUAL_APIREF_TMP) \
+		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
+		$(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@)
+	$(call MSG_L1,Validating $<)
+	$(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $<
+	$(QUIET)$(APPEND) -t "$@" "done"
+
 
 # Handy aliases.
-validate-sdkref:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/SDKRef.xml
+validate-sdkref:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatesdkref.run
 sdkref:: $(PATH_STAGE_BIN)/sdk/docs/SDKRef.pdf
 
@@ -657,17 +608,13 @@
 #
 
-$(evalcall2 def_vbox_replace_stuff_in_xml,/en_US/Accessibility.xml,/en_US)
-
-# Turn Accessibility.xml into latex.
+# Turn Accessibility.xml into LaTeX.
 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.tex: \
-		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
+		$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
 		$(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl \
-		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE_CURRENT) | $$(dir $$@)
+		$(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run,) \
+		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
+		$(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@)
 	$(call MSG_TOOL,xsltproc $(notdir $(filter %.xsl,$^)),,$(firstword $(filter %.xml,$^)),$@)
 	$(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_ACCESSIBILITY_LATEX_FILES_TARGET))
-#	check it for validity first.
-if defined(VBOX_HAVE_XMLLINT) && defined(VBOX_PATH_DOCBOOK_DTD)
-	$(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $<
-endif
 #	generate TeX source from processed docbook and store it in Accessibility.tex.tmp
 	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \
@@ -698,18 +645,31 @@
 
 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html: \
-		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \
-		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
-		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \
-		| $$(dir $$@)
+		$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
+		$(VBOX_DOCBOOK_HTML_ONE_PAGE_FORMATCFG) \
+		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
+		$(VBOX_XML_ENTITIES) | $$(dir $$@)
 	$(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
 	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) \
 		--output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html \
-		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \
-		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.xml
+		$(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl \
+		$<
+
+# Validating Accessibility.xml. It is invoked automatically at build time,
+# but can also be manually invoked via the 'validate-accessibility' alias.
+$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run: \
+		$(VBOX_PATH_MANUAL_SRC)/en_US/Accessibility.xml \
+		$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_ACCESSIBILITY_XML_FILES)) \
+		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
+		$(VBOX_XML_ENTITIES) $(MAKEFILE_CURRENT) | $$(dir $$@)
+	$(call MSG_L1,Validating $<)
+	$(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $<
+	$(QUIET)$(APPEND) -t "$@" "done"
+
 
 # Handy aliases.
-validate-accessibility:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/Accessibility.xml
+validate-accessibility:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/validateaccessibility.run
 accessibility:: $(PATH_STAGE_BIN)/Accessibility.pdf
 accessibility-html:: $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/Accessibility.html
+
 
 
@@ -722,22 +682,11 @@
  # Microsoft Help Compiler.
  #
- $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-htmlhelp-formatcfg.xsl,/$(lang)))
-
- # Manual formatcfg dependencies for the above.
- $(foreach lang,$(VBOX_MANUAL_LANGUAGES), $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/docbook-htmlhelp-formatcfg.xsl): \
+ VBOX_DOCBOOK_HTMLHELP_FORMATCFG = \
+ 	$(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl \
  	$(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \
  	$(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl
 
- $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/VirtualBox.chm): \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/VirtualBox.chm: \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/HTMLHelp/htmlhelp.hhp \
-		$(foreach f,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/,$(VBOX_MANUAL_PNG_FILES_$(f))))
-	$(call MSG_L1,hhc $<,=> $@)
-	$(QUIET)$(RM) -f $@
-	$(QUIET)$(VBOX_HHC) $(subst /,\\,$<)
-	$(call MSG_L1,Fresh CHM is now at $@)
-
  # Prepare the XSL file for our title page, htmlhelp variant.
- $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/titlepage-htmlhelp.xsl): \
+ $(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl: \
 		$(VBOX_PATH_MANUAL_SRC)/titlepage-htmlhelp.xml $(MAKEFILE_CURRENT) | $$(dir $$@)
 	$(call MSG_L1,xsltproc $<)
@@ -746,32 +695,52 @@
 	$(QUIET)$(MV) -f $@.tmp $@
 
- $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/HTMLHelp/htmlhelp.hhp): \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/HTMLHelp/htmlhelp.hhp: \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/UserManual.xml \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/docbook-htmlhelp-formatcfg.xsl \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/titlepage-htmlhelp.xsl \
-		$(VBOX_PATH_MANUAL_OUTBASE)/%/validatemanual.run \
-		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/%/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
-		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK)
-	$(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
-	$(QUIET)$(RM) -f $@
-	$(QUIET)$(MKDIR) -p $(@D)
-	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --output $(@D)/ \
+ # Generate CHM from HHP
+ # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
+ define def_vbox_usermanual_hhp_to_chm
+ local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
+ $$(out_dir)/VirtualBox.chm: \
+		$$(out_dir)/HTMLHelp/htmlhelp.hhp \
+		$$(addprefix $$(out_dir)/HTMLHelp/,$$(VBOX_MANUAL_PNG_FILES_$(lang)))
+	$$(call MSG_L1,hhc $$<,=> $$@)
+	$$(QUIET)$$(RM) -f $$@
+	$$(QUIET)$$(VBOX_HHC) $$(subst /,\\,$$<)
+	$$(call MSG_L1,Fresh CHM is now at $$@)
+ endef
+ $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_hhp_to_chm))
+
+ # Generate HHP from XML
+ # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
+ define def_vbox_usermanual_xml_to_hhp
+ local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)
+ $$(out_dir)/HTMLHelp/htmlhelp.hhp: \
+		$$(addprefix $$(VBOX_PATH_MANUAL_SRC)/$(lang)/,$$(VBOX_MANUAL_XML_FILES)) \
+		$$(VBOX_MANUAL_XML_FILES_COMMON) \
+		$$(VBOX_MANUAL_XML_FILES_GENERATED_$(lang)) \
+		$$(VBOX_DOCBOOK_HTMLHELP_FORMATCFG) \
+		$$(VBOX_PATH_MANUAL_OUTBASE)/titlepage-htmlhelp.xsl \
+		$$(if $$(VBOX_HAVE_XMLLINT),$$(out_dir)/validatemanual.run,) \
+		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
+		$$(VBOX_XML_ENTITIES)
+	$$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
+	$$(QUIET)$$(RM) -f $$@
+	$$(QUIET)$$(MKDIR) -p $$(@D)
+	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$(@D)/ \
 		--stringparam htmlhelp.chm \
-		$(subst /,\\,$(@D)/../VirtualBox.chm) \
-		$(HTMLHELPOPTS) $(@D)/../docbook-htmlhelp-formatcfg.xsl \
-		$<
+		$$(subst /,\\,$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/VirtualBox.chm) \
+		$$(HTMLHELPOPTS) $$(VBOX_PATH_MANUAL_SRC)/docbook-htmlhelp-formatcfg.xsl \
+		$$<
+ endef
+ $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(evalcall2 def_vbox_usermanual_xml_to_hhp))
 
  # copy the PNG files.
  # Note: out_dir needs to be referenced with an escaped $ so it doesn't expand as eval expands it input.
- define def_vbox_cp_images_html
+ define def_vbox_cp_images_htmlhelp
  local out_dir := $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/HTMLHelp
- $$(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
-			$$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@)
+ $(addprefix $$(out_dir)/,$(VBOX_MANUAL_PNG_FILES_$(lang))): \
+		$$(out_dir)/%: $(VBOX_PATH_MANUAL_SRC)/$(lang)/% | $$$$(dir $$$$@)
 	$$(call MSG_L1,Copying temporary $$< => $$@)
-	$$(QUIET)$$(CP) -f $$< $$@
+	$$(QUIET)$$(INSTALL_STAGING) -m0644 -- '$$<' '$$(@D)'
  endef
-
- $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_html)))
+ $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(eval $(def_vbox_cp_images_htmlhelp)))
 
  # Packing the docs into a zip file
@@ -789,39 +758,44 @@
 #
 ##########################################################################################
-$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-html-one-page-formatcfg.xsl,/en_US)
-$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-html-chunks-formatcfg.xsl,/en_US)
-
-# Manual formatcfg dependencies.
-$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \
-$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl: \
+VBOX_DOCBOOK_HTML_ONE_PAGE_FORMATCFG = \
+	$(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl \
 	$(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \
 	$(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl
 
 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html: \
-		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \
-		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
-		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \
+		$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_XML_FILES)) \
+		$(VBOX_MANUAL_XML_FILES_COMMON) \
+		$(VBOX_MANUAL_XML_FILES_GENERATED_en_US) \
+		$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \
+		$(VBOX_DOCBOOK_HTML_ONE_PAGE_FORMATCFG) \
 		$(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatemanual.run,) \
-		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \
-		| $$(dir $$@)
+		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
+		$$(VBOX_XML_ENTITIES) | $$(dir $$@)
 	$(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
 	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) \
 		--output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \
-		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \
-		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml
+		$(VBOX_PATH_MANUAL_SRC)/docbook-html-one-page-formatcfg.xsl \
+		$<
+
+VBOX_DOCBOOK_HTML_CHUNKS_FORMATCFG = \
+	$(VBOX_PATH_MANUAL_SRC)/docbook-html-chunks-formatcfg.xsl \
+	$(VBOX_PATH_MANUAL_SRC)/common-formatcfg.xsl \
+	$(VBOX_PATH_MANUAL_SRC)/common-html-formatcfg.xsl
 
 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html: \
-		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl \
-		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG)) \
-		$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \
+		$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_XML_FILES)) \
+		$(VBOX_MANUAL_XML_FILES_COMMON) \
+		$(VBOX_MANUAL_XML_FILES_GENERATED_en_US) \
+		$(VBOX_DOCBOOK_HTML_CHUNKS_FORMATCFG) \
+		$(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_PNG_FILES_en_US)) \
 		$(if $(VBOX_HAVE_XMLLINT),$(VBOX_PATH_MANUAL_OUTBASE)/en_US/validatemanual.run,) \
-		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \
-		| $$(dir $$@)
+		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
+		$(VBOX_XML_ENTITIES) | $$(dir $$@)
 	$(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
 	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) \
 		--output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \
 		--stringparam chunk.section.depth 0 \
-		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-chunks-formatcfg.xsl \
-		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.xml
+		$(VBOX_PATH_MANUAL_SRC)/docbook-html-chunks-formatcfg.xsl \
+		$<
 
 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/UserManual.zip: \
@@ -841,14 +815,12 @@
 # ChangeLog.html
 #
-# This XSLT rule depends on $(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml, which is build by the complex rule
-#    $(foreach f,$(VBOX_MANUAL_LANGUAGES),$(VBOX_PATH_MANUAL_OUTBASE)/$f/user_ChangeLog.xml): ...
-# much further above. That rule takes en_US/user_ChangeLog.xml and replaces $VIRTUALBOX_CHANGELOG_IMPL
-# with the actual change log contained in user_ChangeLogImpl.xml
-#
-$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-changelog-formatcfg.xsl,/en_US)
+# This XSLT rule formats en_US/user_ChangeLog.xml (which includes the actual change log
+# contained in user_ChangeLogImpl.xml) as a standalone HTML file.
+#
 $(VBOX_PATH_MANUAL_OUTBASE)/en_US/ChangeLog.html: \
-		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-changelog-formatcfg.xsl \
+		$(VBOX_PATH_MANUAL_SRC)/en_US/docbook-changelog-formatcfg.xsl \
 		$(VBOX_PATH_MANUAL_OUTBASE)/en_US/user_ChangeLog.xml \
-		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) | $$(dir $$@)
+		$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) \
+		$(VBOX_XML_ENTITIES) | $$(dir $$@)
 	$(call MSG_TOOL,xsltproc $(notdir $(firstword $(filter %.xsl,$^))),,$(firstword $(filter %.xml,$^)),$@)
 	$(QUIET)$(call VBOX_XSLTPROC_WITH_CAT) --output "$@" "$<" $(filter %.xml,$^)
@@ -865,5 +837,4 @@
 # VBoxManage man pages (parts also required by VBoxManage built-in help).
 #
-$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-manpage.xsl,)
 
 ##
@@ -877,5 +848,5 @@
 		$$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2) \
 		$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \
-		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) \
+		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK)  $$(VBOX_XML_CATALOG_MANUAL) \
 		$$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@)
 	$$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
@@ -883,5 +854,5 @@
 	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ \
 		$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl $$<
-if defined(VBOX_HAVE_XMLLINT) && "$(USER)" == "bird" # Effing stuff happends on build servers, probably kmk related...
+if defined(VBOX_HAVE_XMLLINT)
 	$$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$@
 endif
@@ -889,10 +860,10 @@
 $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(patsubst man_%,%.1,$(basename $(2))): \
 		$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2) \
-		$$(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-manpage.xsl \
-		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) \
+		$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage.xsl \
+		$$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
 		$$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@)
 	$$(call MSG_TOOL,xsltproc $$(notdir $$(firstword $$(filter %.xsl,$$^))),,$$(firstword $$(filter %.xml,$$^)),$$@)
 	$$(QUIET)$$(RM) -f "$$@"
-	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ $$(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-manpage.xsl $$<
+	$$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage.xsl $$<
 endef
 $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \
Index: /trunk/doc/manual/docbook-changelog-formatcfg.xsl
===================================================================
--- /trunk/doc/manual/docbook-changelog-formatcfg.xsl	(revision 73275)
+++ /trunk/doc/manual/docbook-changelog-formatcfg.xsl	(revision 73276)
@@ -3,6 +3,6 @@
 
 <!-- Single html file template -->
-<xsl:import href="@VBOX_PATH_DOCBOOK@/html/docbook.xsl"/>
-<xsl:import href="@VBOX_PATH_MANUAL_SRC@/common-formatcfg.xsl"/>
+<xsl:import href="html/docbook.xsl"/>
+<xsl:import href="common-formatcfg.xsl"/>
 
 <!-- Adjust some params -->
Index: /trunk/doc/manual/docbook-html-chunks-formatcfg.xsl
===================================================================
--- /trunk/doc/manual/docbook-html-chunks-formatcfg.xsl	(revision 73275)
+++ /trunk/doc/manual/docbook-html-chunks-formatcfg.xsl	(revision 73276)
@@ -3,8 +3,8 @@
 
 <!-- Single html file template -->
-<xsl:import href="@VBOX_PATH_DOCBOOK@/html/chunk.xsl"/>
+<xsl:import href="html/chunk.xsl"/>
 
-<xsl:import href="@VBOX_PATH_MANUAL_SRC@/common-formatcfg.xsl"/>
-<xsl:import href="@VBOX_PATH_MANUAL_SRC@/common-html-formatcfg.xsl"/>
+<xsl:import href="common-formatcfg.xsl"/>
+<xsl:import href="common-html-formatcfg.xsl"/>
 
 <!-- Adjust some params -->
Index: /trunk/doc/manual/docbook-html-one-page-formatcfg.xsl
===================================================================
--- /trunk/doc/manual/docbook-html-one-page-formatcfg.xsl	(revision 73275)
+++ /trunk/doc/manual/docbook-html-one-page-formatcfg.xsl	(revision 73276)
@@ -3,8 +3,8 @@
 
 <!-- Single html file template -->
-<xsl:import href="@VBOX_PATH_DOCBOOK@/html/docbook.xsl"/>
+<xsl:import href="html/docbook.xsl"/>
 
-<xsl:import href="@VBOX_PATH_MANUAL_SRC@/common-formatcfg.xsl"/>
-<xsl:import href="@VBOX_PATH_MANUAL_SRC@/common-html-formatcfg.xsl"/>
+<xsl:import href="common-formatcfg.xsl"/>
+<xsl:import href="common-html-formatcfg.xsl"/>
 
 <!-- Adjust some params -->
Index: /trunk/doc/manual/docbook-htmlhelp-formatcfg.xsl
===================================================================
--- /trunk/doc/manual/docbook-htmlhelp-formatcfg.xsl	(revision 73275)
+++ /trunk/doc/manual/docbook-htmlhelp-formatcfg.xsl	(revision 73276)
@@ -2,9 +2,9 @@
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
 
-<xsl:import href="@VBOX_PATH_DOCBOOK@/htmlhelp/htmlhelp.xsl"/>
-<xsl:import href="@VBOX_PATH_MANUAL_SRC@/common-formatcfg.xsl"/>
-<xsl:import href="@VBOX_PATH_MANUAL_SRC@/common-html-formatcfg.xsl"/>
+<xsl:import href="htmlhelp/htmlhelp.xsl"/>
+<xsl:import href="common-formatcfg.xsl"/>
+<xsl:import href="common-html-formatcfg.xsl"/>
 
-<xsl:include href="@VBOX_PATH_MANUAL_OUT_LANG@/titlepage-htmlhelp.xsl"/>
+<xsl:include href="titlepage-htmlhelp.xsl"/>
 
 <!-- Override the style sheet stuff from common-html-formatcfg.xsl, we don't
Index: /trunk/doc/manual/docbook-refentry-to-C-help.xsl
===================================================================
--- /trunk/doc/manual/docbook-refentry-to-C-help.xsl	(revision 73275)
+++ /trunk/doc/manual/docbook-refentry-to-C-help.xsl	(revision 73276)
@@ -23,6 +23,6 @@
   >
 
-  <xsl:import href="@VBOX_PATH_MANUAL_SRC@/string.xsl"/>
-  <xsl:import href="@VBOX_PATH_MANUAL_SRC@/common-formatcfg.xsl"/>
+  <xsl:import href="string.xsl"/>
+  <xsl:import href="common-formatcfg.xsl"/>
 
   <xsl:output method="text" version="1.0" encoding="utf-8" indent="yes"/>
Index: /trunk/doc/manual/docbook-refentry-to-H-help.xsl
===================================================================
--- /trunk/doc/manual/docbook-refentry-to-H-help.xsl	(revision 73275)
+++ /trunk/doc/manual/docbook-refentry-to-H-help.xsl	(revision 73276)
@@ -22,5 +22,5 @@
   >
 
-  <xsl:import href="@VBOX_PATH_MANUAL_SRC@/string.xsl"/>
+  <xsl:import href="string.xsl"/>
 
   <xsl:output method="text" version="1.0" encoding="utf-8" indent="yes"/>
Index: /trunk/doc/manual/docbook-refentry-to-manpage.xsl
===================================================================
--- /trunk/doc/manual/docbook-refentry-to-manpage.xsl	(revision 73275)
+++ /trunk/doc/manual/docbook-refentry-to-manpage.xsl	(revision 73276)
@@ -19,6 +19,5 @@
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 
-  <xsl:import href="@VBOX_PATH_DOCBOOK@/manpages/docbook.xsl"/>
-<!--  <xsl:import href="@VBOX_PATH_MANUAL_SRC@/common-formatcfg.xsl"/> -->
+  <xsl:import href="manpages/docbook.xsl"/>
 
   <!--
Index: /trunk/doc/manual/docbook2latex.xsl
===================================================================
--- /trunk/doc/manual/docbook2latex.xsl	(revision 73275)
+++ /trunk/doc/manual/docbook2latex.xsl	(revision 73276)
@@ -697,4 +697,9 @@
   </xsl:template>
 
+  <xsl:template match="trademark">
+    <xsl:apply-templates />
+    <xsl:text>\textsuperscript{\textregistered}</xsl:text>
+  </xsl:template>
+
   <!-- for some reason, DocBook insists of having image data nested this way always:
        mediaobject -> imageobject -> imagedata
Index: /trunk/doc/manual/en_US/Accessibility.xml
===================================================================
--- /trunk/doc/manual/en_US/Accessibility.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/Accessibility.xml	(revision 73276)
@@ -1,21 +1,25 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
+
 <book>
   <bookinfo>
-    <title>@VBOX_PRODUCT@<superscript>®</superscript></title>
+    <title>&VBOX_PRODUCT;</title>
 
     <subtitle>Accessibility Reference</subtitle>
 
-    <edition>Version @VBOX_VERSION_STRING@</edition>
-
-    <corpauthor>@VBOX_VENDOR@</corpauthor>
-
-    <address>http://www.virtualbox.org</address>
+    <edition>Version &VBOX_VERSION_STRING;</edition>
+
+    <corpauthor>&VBOX_VENDOR;</corpauthor>
+
+    <address>https://www.virtualbox.org</address>
 
     <copyright>
-      <year>2016-@VBOX_C_YEAR@</year>
-
-      <holder>@VBOX_VENDOR@</holder>
+      <year>2016-&VBOX_C_YEAR;</year>
+
+      <holder>&VBOX_VENDOR;</holder>
     </copyright>
   </bookinfo>
Index: /trunk/doc/manual/en_US/SDKRef.xml
===================================================================
--- /trunk/doc/manual/en_US/SDKRef.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/SDKRef.xml	(revision 73276)
@@ -1,21 +1,25 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
+
 <book>
   <bookinfo>
-    <title>@VBOX_PRODUCT@<superscript>®</superscript></title>
+    <title>&VBOX_PRODUCT;</title>
 
     <subtitle>Programming Guide and Reference</subtitle>
 
-    <edition>Version @VBOX_VERSION_STRING@</edition>
-
-    <corpauthor>@VBOX_VENDOR@</corpauthor>
+    <edition>Version &VBOX_VERSION_STRING;</edition>
+
+    <corpauthor>&VBOX_VENDOR;</corpauthor>
 
     <address>http://www.virtualbox.org</address>
 
     <copyright>
-      <year>2004-@VBOX_C_YEAR@</year>
-
-      <holder>@VBOX_VENDOR@</holder>
+      <year>2004-&VBOX_C_YEAR;</year>
+
+      <holder>&VBOX_VENDOR;</holder>
     </copyright>
   </bookinfo>
@@ -1198,5 +1202,5 @@
 
                 <para>And it will print
-                "@VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@".</para>
+                "&VBOX_VERSION_MAJOR;.&VBOX_VERSION_MINOR;.&VBOX_VERSION_BUILD;".</para>
               </listitem>
 
@@ -3086,9 +3090,9 @@
 
         <para><screen>
-DECLVBGL(int) VbglHGCMConnect (VBGLHGCMHANDLE *pHandle, VBoxGuestHGCMConnectInfo *pData);
+DECLR0VBGL(int) VbglR0HGCMConnect(VBGLHGCMHANDLE *pHandle, const char *pszServiceName, HGCMCLIENTID *pidClient);
           </screen> Connects to the service: <screen>
     VBoxGuestHGCMConnectInfo data;
 
-    memset (&amp;data, sizeof (VBoxGuestHGCMConnectInfo));
+    memset(&amp;data, sizeof(VBoxGuestHGCMConnectInfo));
 
     data.result   = VINF_SUCCESS;
@@ -3096,5 +3100,5 @@
     strcpy (data.Loc.u.host.achName, "VBoxSharedFolders");
 
-    rc = VbglHGCMConnect (&amp;handle, &amp;data);
+    rc = VbglHGCMConnect (&amp;handle, "VBoxSharedFolders"&amp;data);
 
     if (RT_SUCCESS (rc))
@@ -3915,5 +3919,5 @@
 
     <sect1>
-      <title>Incompatible API changes with version 5.3</title>
+      <title>Incompatible API changes with version x.x</title>
 
       <itemizedlist>
@@ -3936,20 +3940,16 @@
             </listitem>
 
-            <listitem><para>The <link linkend="FileCopyFlag">FileCopyFlag</link> flags for
-              <link linkend="IGuestSession__directoryCopyFromGuest">IGuestSession::directoryCopyFromGuest()</link>
-              have been implemented.</para>
-            </listitem>
-
             <listitem>
               <para>The following methods have been implemented:
-                <link linkend="IGuestSession__directoryCopyFromGuest">IGuestSession::directoryCopyFromGuest()</link> and
-                <link linkend="IGuestSession__directoryCopyToGuest">IGuestSession::directoryCopyToGuest()</link>,
-                <link linkend="IFile__queryInfo">IGuestFile::queryInfo()</link>,
-                <link linkend="IFile__querySize">IGuestFile::querySize()</link>.
+                <computeroutput>IGuestSession::directoryCopyFromGuest()</computeroutput> and
+                <computeroutput>IGuestSession::directoryCopyToGuest()</computeroutput>.
               </para>
 
               <para>The following attributes have been implemented:
-                IGuestFsObjInfo::accessTime, IGuestFsObjInfo::birthTime, IGuestFsObjInfo::changeTime and
-                IGuestFsObjInfo::modificationTime.</para>
+                <computeroutput>IGuestFsObjInfo::accessTime</computeroutput>,
+                <computeroutput>IGuestFsObjInfo::birthTime</computeroutput>,
+                <computeroutput>IGuestFsObjInfo::changeTime</computeroutput> and
+                <computeroutput>IGuestFsObjInfo::modificationTime</computeroutput>.
+              </para>
 
             </listitem>
Index: /trunk/doc/manual/en_US/UserManual.xml
===================================================================
--- /trunk/doc/manual/en_US/UserManual.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/UserManual.xml	(revision 73276)
@@ -1,77 +1,88 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<book>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
+<book id="VBOXU" lang="en">
+
+<!-- VBox bookinfo section -->
+
   <bookinfo>
-    <title>@VBOX_PRODUCT@<superscript>®</superscript></title>
+
+    <title>&VBOX_PRODUCT;</title>
 
     <subtitle>User Manual</subtitle>
 
     <edition>Version
-    @VBOX_VERSION_STRING@</edition>
+    &VBOX_VERSION_STRING;</edition>
 
-    <corpauthor>@VBOX_VENDOR@</corpauthor>
+    <corpauthor>Oracle Corporation</corpauthor>
 
-    <address>http://www.virtualbox.org</address>
+    <address>https://www.virtualbox.org</address>
 
     <copyright>
-      <year>2004-@VBOX_C_YEAR@</year>
 
-      <holder>@VBOX_VENDOR@</holder>
+      <year>2004-&VBOX_C_YEAR;</year>
+
+      <holder>Oracle Corporation</holder>
+
     </copyright>
+
   </bookinfo>
 
-  <xi:include href="user_Introduction.xml" xpointer="element(/1)"
+  <xi:include href="user_Introduction.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_Installation.xml" xpointer="element(/1)"
+  <xi:include href="user_Installation.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_BasicConcepts.xml" xpointer="element(/1)"
+  <xi:include href="user_BasicConcepts.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_GuestAdditions.xml" xpointer="element(/1)"
+  <xi:include href="user_GuestAdditions.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_Storage.xml" xpointer="element(/1)"
+  <xi:include href="user_Storage.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_Networking.xml" xpointer="element(/1)"
+  <xi:include href="user_Networking.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_Frontends.xml" xpointer="element(/1)"
+  <xi:include href="user_Frontends.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_VBoxManage.xml" xpointer="element(/1)"
+  <xi:include href="user_VBoxManage.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_AdvancedTopics.xml" xpointer="element(/1)"
+  <xi:include href="user_AdvancedTopics.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_Technical.xml" xpointer="element(/1)"
+  <xi:include href="user_Technical.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_VirtualBoxAPI.xml" xpointer="element(/1)"
+  <xi:include href="user_VirtualBoxAPI.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_Troubleshooting.xml" xpointer="element(/1)"
+  <xi:include href="user_Troubleshooting.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_Security.xml" xpointer="element(/1)"
-              xmlns:xi="http://www.w3.org/2001/XInclude" />
-
-  <xi:include href="user_KnownIssues.xml" xpointer="element(/1)"
+  <xi:include href="user_Security.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_ChangeLog.xml" xpointer="element(/1)"
+  <xi:include href="user_KnownIssues.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_ThirdParty.xml" xpointer="element(/1)"
+  <xi:include href="user_ChangeLog.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_PrivacyPolicy.xml" xpointer="element(/1)"
+  <xi:include href="user_ThirdParty.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <xi:include href="user_Glossary.xml" xpointer="element(/1)"
+  <xi:include href="user_PrivacyPolicy.xml"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_Glossary.xml"
+    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
 </book>
Index: /trunk/doc/manual/en_US/man_VBoxManage-debugvm.xml
===================================================================
--- /trunk/doc/manual/en_US/man_VBoxManage-debugvm.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/man_VBoxManage-debugvm.xml	(revision 73276)
@@ -13,5 +13,5 @@
     hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
  -->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <refentry id="vboxmanage-debugvm" lang="en">
 
Index: /trunk/doc/manual/en_US/man_VBoxManage-extpack.xml
===================================================================
--- /trunk/doc/manual/en_US/man_VBoxManage-extpack.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/man_VBoxManage-extpack.xml	(revision 73276)
@@ -13,5 +13,5 @@
     hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
  -->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <refentry id="vboxmanage-extpack" lang="en">
 
Index: /trunk/doc/manual/en_US/man_VBoxManage-mediumio.xml
===================================================================
--- /trunk/doc/manual/en_US/man_VBoxManage-mediumio.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/man_VBoxManage-mediumio.xml	(revision 73276)
@@ -13,5 +13,5 @@
     hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
  -->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <refentry id="vboxmanage-mediumio" lang="en">
 
Index: /trunk/doc/manual/en_US/man_VBoxManage-unattended.xml
===================================================================
--- /trunk/doc/manual/en_US/man_VBoxManage-unattended.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/man_VBoxManage-unattended.xml	(revision 73276)
@@ -13,5 +13,5 @@
     hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
  -->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <refentry id="vboxmanage-unattended" lang="en">
 
Index: /trunk/doc/manual/en_US/user_AdvancedTopics.xml
===================================================================
--- /trunk/doc/manual/en_US/user_AdvancedTopics.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_AdvancedTopics.xml	(revision 73276)
@@ -1,680 +1,988 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="AdvancedTopics">
-  <title>Advanced topics</title>
+
+  <title>Advanced Topics</title>
 
   <sect1 id="vboxsdl">
-    <title>VBoxSDL, the simplified VM displayer</title>
-
-    <sect2>
+
+    <title>VBoxSDL, The Simplified VM Displayer</title>
+
+    <sect2 id="vboxsdl-intro">
+
       <title>Introduction</title>
 
-      <para>VBoxSDL is a simple graphical user interface (GUI) that lacks the
-      nice point-and-click support which VirtualBox, our main GUI, provides.
-      VBoxSDL is currently primarily used internally for debugging VirtualBox
-      and therefore not officially supported. Still, you may find it useful
-      for environments where the virtual machines are not necessarily
-      controlled by the same person that uses the virtual machine.<note>
-          <para>VBoxSDL is not available on the Mac OS X host platform.</para>
-        </note></para>
-
-      <para>As you can see in the following screenshot, VBoxSDL does indeed
-      only provide a simple window that contains only the "pure" virtual
-      machine, without menus or other controls to click upon and no additional
-      indicators of virtual machine activity:</para>
-
-      <para><mediaobject>
+      <para>
+        VBoxSDL is a simple graphical user interface (GUI) that lacks
+        the nice point-and-click support of the main GUI, VirtualBox.
+        VBoxSDL is currently primarily used internally for debugging
+        VirtualBox and therefore not officially supported. But you may
+        find it useful for environments where the virtual machines are
+        not necessarily controlled by the same person that uses the
+        virtual machine.
+      </para>
+
+      <note>
+        <para>
+          VBoxSDL is not available on the Mac OS X host platform.
+        </para>
+      </note>
+
+      <para>
+        As shown in the following screenshot, VBoxSDL provides a simple
+        window that contains only the "pure" virtual machine, without
+        menus or other controls to click and with no additional
+        indicators of virtual machine activity.
+      </para>
+
+      <para>
+        <mediaobject>
           <imageobject>
             <imagedata align="center" fileref="images/vbox-sdl.png"
                        width="10cm" />
           </imageobject>
-        </mediaobject></para>
-
-      <para>To start a virtual machine with VBoxSDL instead of the VirtualBox
-      GUI, enter the following on a command line:<screen>VBoxSDL --startvm &lt;vm&gt;</screen></para>
-
-      <para>where <computeroutput>&lt;vm&gt;</computeroutput> is, as usual
-      with VirtualBox command line parameters, the name or UUID of an existing
-      virtual machine.</para>
+        </mediaobject>
+      </para>
+
+      <para>
+        To start a virtual machine with VBoxSDL instead of the
+        VirtualBox GUI, enter the following on a command line:
+      </para>
+
+<screen>VBoxSDL --startvm &lt;vm&gt;</screen>
+
+      <para>
+        where <computeroutput>&lt;vm&gt;</computeroutput> is the name or
+        UUID of an existing virtual machine.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Secure labeling with VBoxSDL</title>
-
-      <para>When running guest operating systems in full screen mode, the guest
-      operating system usually has control over the whole screen. This could
-      present a security risk as the guest operating system might fool the
-      user into thinking that it is either a different system (which might
-      have a higher security level) or it might present messages on the screen
-      that appear to stem from the host operating system.</para>
-
-      <para>In order to protect the user against the above mentioned security
-      risks, the secure labeling feature has been developed. Secure labeling
-      is currently available only for VBoxSDL. When enabled, a portion of the
-      display area is reserved for a label in which a user defined message is
-      displayed. The label height in set to 20 pixels in VBoxSDL. The label
-      font color and background color can be optionally set as hexadecimal RGB
-      color values. The following syntax is used to enable secure
-      labeling:</para>
-
-      <screen>VBoxSDL --startvm "VM name"
+    <sect2 id="vboxsdl-secure-label">
+
+      <title>Secure Labeling with VBoxSDL</title>
+
+      <para>
+        When running guest operating systems in full screen mode, the
+        guest operating system usually has control over the whole
+        screen. This could present a security risk as the guest
+        operating system might fool the user into thinking that it is
+        either a different system, which might have a higher security
+        level, or it might present messages on the screen that appear to
+        stem from the host operating system.
+      </para>
+
+      <para>
+        In order to protect the user against the above mentioned
+        security risks, the secure labeling feature has been developed.
+        Secure labeling is currently available only for VBoxSDL. When
+        enabled, a portion of the display area is reserved for a label
+        in which a user defined message is displayed. The label height
+        is set to 20 pixels in VBoxSDL. The label font color and
+        background color can be optionally set as hexadecimal RGB color
+        values. The following syntax is used to enable secure labeling:
+      </para>
+
+<screen>VBoxSDL --startvm "VM name"
       --securelabel --seclabelfnt ~/fonts/arial.ttf
       --seclabelsiz 14 --seclabelfgcol 00FF00 --seclabelbgcol 00FFFF</screen>
 
-      <para>In addition to enabling secure labeling, a TrueType font has to be
-      supplied. To use another font size than 12 point use the parameter
-      <computeroutput>--seclabelsiz</computeroutput>.</para>
-
-      <para>The label text can be set with <screen>VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"</screen>
-      Changing this label will take effect immediately.</para>
-
-      <para>Typically, full screen resolutions are limited to certain
-      "standard" geometries such as 1024 x 768. Increasing this by twenty
-      lines is not usually feasible, so in most cases, VBoxSDL will chose the
-      next higher resolution, e.g. 1280 x 1024 and the guest's screen will not
-      cover the whole display surface. If VBoxSDL is unable to choose a higher
-      resolution, the secure label will be painted on top of the guest's
-      screen surface. In order to address the problem of the bottom part of
-      the guest screen being hidden, VBoxSDL can provide custom video modes to
-      the guest that are reduced by the height of the label. For Windows
-      guests and recent Solaris and Linux guests, the VirtualBox Guest
-      Additions automatically provide the reduced video modes. Additionally,
-      the VESA BIOS has been adjusted to duplicate its standard mode table
-      with adjusted resolutions. The adjusted mode IDs can be calculated using
-      the following formula:</para>
-
-      <screen>reduced_modeid = modeid + 0x30</screen>
-
-      <para>For example, in order to start Linux with 1024 x 748 x 16, the
-      standard mode 0x117 (1024 x 768 x 16) is used as a base. The Linux video
-      mode kernel parameter can then be calculated using:</para>
-
-      <screen>vga = 0x200 | 0x117 + 0x30
+      <para>
+        In addition to enabling secure labeling, a TrueType font has to
+        be supplied. To use another font size than 12 point use the
+        parameter <computeroutput>--seclabelsiz</computeroutput>.
+      </para>
+
+      <para>
+        The label text can be set with:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxSDL/SecureLabel" "The Label"</screen>
+
+      <para>
+        Changing this label will take effect immediately.
+      </para>
+
+      <para>
+        Typically, full screen resolutions are limited to certain
+        standard geometries such as 1024 x 768. Increasing this by
+        twenty lines is not usually feasible, so in most cases, VBoxSDL
+        will chose the next higher resolution, such as 1280 x 1024 and
+        the guest's screen will not cover the whole display surface. If
+        VBoxSDL is unable to choose a higher resolution, the secure
+        label will be painted on top of the guest's screen surface. In
+        order to address the problem of the bottom part of the guest
+        screen being hidden, VBoxSDL can provide custom video modes to
+        the guest that are reduced by the height of the label. For
+        Windows guests and recent Solaris and Linux guests, the
+        VirtualBox Guest Additions automatically provide the reduced
+        video modes. Additionally, the VESA BIOS has been adjusted to
+        duplicate its standard mode table with adjusted resolutions. The
+        adjusted mode IDs can be calculated using the following formula:
+      </para>
+
+<screen>reduced_modeid = modeid + 0x30</screen>
+
+      <para>
+        For example, in order to start Linux with 1024 x 748 x 16, the
+        standard mode 0x117 (1024 x 768 x 16) is used as a base. The
+        Linux video mode kernel parameter can then be calculated using:
+      </para>
+
+<screen>vga = 0x200 | 0x117 + 0x30
 vga = 839</screen>
 
-      <para>The reason for duplicating the standard modes instead of only
-      supplying the adjusted modes is that most guest operating systems
-      require the standard VESA modes to be fixed and refuse to start with
-      different modes.</para>
-
-      <para>When using the X.org VESA driver, custom modelines have to be
-      calculated and added to the configuration (usually in
-      <literal>/etc/X11/xorg.conf</literal>. A handy tool to determine
-      modeline entries can be found at <literal><ulink
-      url="http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html">http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html</ulink></literal>.)</para>
+      <para>
+        The reason for duplicating the standard modes instead of only
+        supplying the adjusted modes is that most guest operating
+        systems require the standard VESA modes to be fixed and refuse
+        to start with different modes.
+      </para>
+
+      <para>
+        When using the X.org VESA driver, custom modelines have to be
+        calculated and added to the configuration, usually in
+        <literal>/etc/X11/xorg.conf</literal>. A handy tool to determine
+        modeline entries can be found at:
+        <ulink
+      url="http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html">http://www.tkk.fi/Misc/Electronics/faq/vga2rgb/calc.html</ulink>.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Releasing modifiers with VBoxSDL on Linux</title>
-
-      <para>When switching from a X virtual terminal (VT) to another VT using
-      Ctrl-Alt-Fx while the VBoxSDL window has the input focus, the guest will
-      receive Ctrl and Alt keypress events without receiving the corresponding
-      key release events. This is an architectural limitation of Linux. In
-      order to reset the modifier keys, it is possible to send
-      <computeroutput>SIGUSR1</computeroutput> to the VBoxSDL main thread
-      (first entry in the <computeroutput>ps</computeroutput> list). For
-      example, when switching away to another VT and saving the virtual
-      machine from this terminal, the following sequence can be used to make
-      sure the VM is not saved with stuck modifiers:</para>
-
-      <para><screen>kill -usr1 &lt;pid&gt;
-VBoxManage controlvm "Windows 2000" savestate</screen></para>
+    <sect2 id="vboxsdl-modifier-release">
+
+      <title>Releasing Modifiers with VBoxSDL on Linux</title>
+
+      <para>
+        When switching from a X virtual terminal (VT) to another VT
+        using Ctrl-Alt-F<replaceable>x</replaceable> while the VBoxSDL
+        window has the input focus, the guest will receive Ctrl and Alt
+        keypress events without receiving the corresponding key release
+        events. This is an architectural limitation of Linux. In order
+        to reset the modifier keys, it is possible to send
+        <computeroutput>SIGUSR1</computeroutput> to the VBoxSDL main
+        thread, the first entry in the
+        <computeroutput>ps</computeroutput> list. For example, when
+        switching away to another VT and saving the virtual machine from
+        this terminal, the following sequence can be used to make sure
+        the VM is not saved with stuck modifiers:
+      </para>
+
+<screen>kill -usr1 &lt;pid&gt;
+VBoxManage controlvm "Windows 2000" savestate</screen>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="autologon">
-    <title>Automated guest logons</title>
-
-    <para>VirtualBox provides Guest Addition modules for Windows, Linux and
-    Solaris to enable automated logons on the guest.</para>
-
-    <para>When a guest operating system is running in a virtual machine, it
-    might be desirable to perform coordinated and automated logons using
-    credentials from a master logon system. (With "credentials", we are
-    referring to logon information consisting of user name, password and
-    domain name, where each value might be empty.)</para>
+
+    <title>Automated Guest Logons</title>
+
+    <para>
+      VirtualBox provides Guest Addition modules for Windows, Linux, and
+      Solaris to enable automated logons on the guest.
+    </para>
+
+    <para>
+      When a guest operating system is running in a virtual machine, it
+      might be desirable to perform coordinated and automated logons
+      using credentials from a master logon system. Credentials are user
+      name, password, and domain name, where each value might be empty.
+    </para>
 
     <sect2 id="autologon_win">
-      <title>Automated Windows guest logons</title>
-
-      <para>Since Windows NT, Windows has provided a modular system logon
-      subsystem ("Winlogon") which can be customized and extended by means of
-      so-called GINA modules (Graphical Identification and Authentication).
-      With Windows Vista and Windows 7, the GINA modules were replaced with a
-      new mechanism called "credential providers". The VirtualBox Guest
-      Additions for Windows come with both, a GINA and a credential provider
-      module, and therefore enable any Windows guest to perform automated
-      logons.</para>
-
-      <para>To activate the VirtualBox GINA or credential provider module,
-      install the Guest Additions with using the command line switch
-      <computeroutput>/with_autologon</computeroutput>. All the following
-      manual steps required for installing these modules will be then done by
-      the installer.</para>
-
-      <para>To manually install the VirtualBox GINA module, extract the Guest
-      Additions (see <xref linkend="windows-guest-file-extraction" />) and
-      copy the file <computeroutput>VBoxGINA.dll</computeroutput> to the
-      Windows <computeroutput>SYSTEM32</computeroutput> directory. Then, in
-      the registry, create the following key: <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>
-      with a value of <computeroutput>VBoxGINA.dll</computeroutput>.</para>
+
+      <title>Automated Windows Guest Logons</title>
+
+      <para>
+        Since Windows NT, Windows has provided a modular system logon
+        subsystem, called Winlogon, which can be customized and extended
+        by means of so-called GINA (Graphical Identification and
+        Authentication) modules. With Windows Vista and Windows 7, the
+        GINA modules were replaced with a new mechanism called
+        credential providers. The VirtualBox Guest Additions for Windows
+        come with both, a GINA and a credential provider module, and
+        therefore enable any Windows guest to perform automated logons.
+      </para>
+
+      <para>
+        To activate the VirtualBox GINA or credential provider module,
+        install the Guest Additions using the command line switch
+        <computeroutput>/with_autologon</computeroutput>. All the
+        following manual steps required for installing these modules
+        will be then done by the installer.
+      </para>
+
+      <para>
+        To manually install the VirtualBox GINA module, extract the
+        Guest Additions as shown in
+        <xref linkend="windows-guest-file-extraction" /> and copy the
+        file <computeroutput>VBoxGINA.dll</computeroutput> to the
+        Windows <computeroutput>SYSTEM32</computeroutput> directory.
+        Then, in the registry, create the following key with a value of
+        <computeroutput>VBoxGINA.dll</computeroutput>.:
+      </para>
+
+<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon\GinaDLL</screen>
 
       <note>
-        <para>The VirtualBox GINA module is implemented as a wrapper around
-        the standard Windows GINA module
-        (<computeroutput>MSGINA.DLL</computeroutput>). As a result, it will
-        most likely not work correctly with 3rd party GINA modules.</para>
+        <para>
+          The VirtualBox GINA module is implemented as a wrapper around
+          the standard Windows GINA module,
+          <computeroutput>MSGINA.DLL</computeroutput>. As a result, it
+          may not work correctly with third party GINA modules.
+        </para>
       </note>
 
-      <para>To manually install the VirtualBox credential provider module,
-      extract the Guest Additions (see <xref
-      linkend="windows-guest-file-extraction" />) and copy the file
-      <computeroutput>VBoxCredProv.dll</computeroutput> to the Windows
-      <computeroutput>SYSTEM32</computeroutput> directory. Then, in the
-      registry, create the following keys:<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
+      <para>
+        To manually install the VirtualBox credential provider module,
+        extract the Guest Additions as shown in
+        <xref
+      linkend="windows-guest-file-extraction" /> and copy
+        the file <computeroutput>VBoxCredProv.dll</computeroutput> to
+        the Windows <computeroutput>SYSTEM32</computeroutput> directory.
+        In the registry, create the following keys:
+
+<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\
            Authentication\Credential Providers\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
 
 HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}
 
-HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen></para>
-
-      <para>with all default values (the key named
-      <computeroutput>(Default)</computeroutput> in each key) set to
-      <computeroutput>VBoxCredProv</computeroutput>. After that a new string
-      named <screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen>
-      with a value of <computeroutput>Apartment</computeroutput> has to be
-      created.</para>
-
-      <para>To set credentials, use the following command on a
-      <emphasis>running</emphasis> VM:</para>
-
-      <screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen>
-
-      <para>While the VM is running, the credentials can be queried by the
-      VirtualBox logon modules (GINA or credential provider) using the
-      VirtualBox Guest Additions device driver. When Windows is in "logged
-      out" mode, the logon modules will constantly poll for credentials and if
-      they are present, a logon will be attempted. After retrieving the
-      credentials, the logon modules will erase them so that the above command
-      will have to be repeated for subsequent logons.</para>
-
-      <para>For security reasons, credentials are not stored in any persistent
-      manner and will be lost when the VM is reset. Also, the credentials are
-      "write-only", i.e. there is no way to retrieve the credentials from the
-      host side. Credentials can be reset from the host side by setting empty
-      values.</para>
-
-      <para>Depending on the particular variant of the Windows guest, the
-      following restrictions apply: <orderedlist>
-          <listitem>
-            <para>For <emphasis role="bold">Windows XP guests,</emphasis> the
-            logon subsystem needs to be configured to use the classic logon
-            dialog as the VirtualBox GINA module does not support the XP-style
-            welcome dialog.</para>
-          </listitem>
-
-          <listitem>
-            <para>For <emphasis role="bold">Windows Vista, Windows 7
-            and Windows 8 guests,</emphasis> the logon subsystem does not support
-            the so-called Secure Attention Sequence
-            (<computeroutput>CTRL+ALT+DEL</computeroutput>). As a result, the
-            guest's group policy settings need to be changed to not use the
-            Secure Attention Sequence. Also, the user name given is only
-            compared to the true user name, not the user friendly name. This
-            means that when you rename a user, you still have to supply the
-            original user name (internally, Windows never renames user
-            accounts).</para>
-          </listitem>
-
-          <listitem>
-            <para>Auto-logon handling of the built-in Windows Remote Desktop
-            Service (formerly known as Terminal Services) is disabled by
-            default. To enable it, create the registry key <screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen>
-            with a <computeroutput>DWORD</computeroutput> value of
-            <computeroutput>1</computeroutput>.</para>
-          </listitem>
-        </orderedlist></para>
-
-      <para>The following command forces VirtualBox to keep the credentials
-      after they were read by the guest and on VM reset: <screen>VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen>Note
-      that this is a potential security risk as a malicious application
-      running on the guest could request this information using the proper
-      interface.</para>
+HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32</screen>
+      </para>
+
+      <para>
+        All default values, the key named
+        <computeroutput>Default</computeroutput>, must be set to
+        <computeroutput>VBoxCredProv</computeroutput>.
+      </para>
+
+      <para>
+        Create a new string named as follows, with a value of
+        <computeroutput>Apartment</computeroutput>.
+      </para>
+
+<screen>HKEY_CLASSES_ROOT\CLSID\{275D3BCC-22BB-4948-A7F6-3A3054EBA92B}\InprocServer32\ThreadingModel</screen>
+
+      <para>
+        To set credentials, use the following command on a
+        <emphasis>running</emphasis> VM:
+      </para>
+
+<screen>VBoxManage controlvm "Windows XP" setcredentials "John Doe" "secretpassword" "DOMTEST"</screen>
+
+      <para>
+        While the VM is running, the credentials can be queried by the
+        VirtualBox logon modules, GINA or credential provider, using the
+        VirtualBox Guest Additions device driver. When Windows is in
+        <emphasis>logged out</emphasis> mode, the logon modules will
+        constantly poll for credentials and if they are present, a logon
+        will be attempted. After retrieving the credentials, the logon
+        modules will erase them so that the above command will have to
+        be repeated for subsequent logons.
+      </para>
+
+      <para>
+        For security reasons, credentials are not stored in any
+        persistent manner and will be lost when the VM is reset. Also,
+        the credentials are write-only. There is no way to retrieve the
+        credentials from the host side. Credentials can be reset from
+        the host side by setting empty values.
+      </para>
+
+      <para>
+        Depending on the particular variant of the Windows guest, the
+        following restrictions apply:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            For <emphasis role="bold">Windows XP guests.</emphasis> The
+            logon subsystem needs to be configured to use the classic
+            logon dialog as the VirtualBox GINA module does not support
+            the XP-style welcome dialog.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Windows Vista, Windows 7, and Windows
+            8 guests.</emphasis> The logon subsystem does not support
+            the so-called Secure Attention Sequence,
+            <computeroutput>Ctrl+Alt+Del</computeroutput>. As a result,
+            the guest's group policy settings need to be changed to not
+            use the Secure Attention Sequence. Also, the user name given
+            is only compared to the true user name, not the user
+            friendly name. This means that when you rename a user, you
+            still have to supply the original user name as Windows never
+            renames user accounts internally.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Auto-logon handling of the built-in
+            <emphasis role="bold">Windows Remote Desktop
+            Service</emphasis>, formerly known as Terminal Services, is
+            disabled by default. To enable it, create the following
+            registry key with a <computeroutput>DWORD</computeroutput>
+            value of <computeroutput>1</computeroutput>.
+          </para>
+
+<screen>HKEY_LOCAL_MACHINE\SOFTWARE\Oracle\VirtualBox Guest Additions\AutoLogon</screen>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        The following command forces VirtualBox to keep the credentials
+        after they were read by the guest and on VM reset:
+
+<screen>VBoxManage setextradata "Windows XP" VBoxInternal/Devices/VMMDev/0/Config/KeepCredentials 1</screen>
+
+        Note that this is a potential security risk, as a malicious
+        application running on the guest could request this information
+        using the proper interface.
+      </para>
+
     </sect2>
 
     <sect2 id="autologon_unix">
-      <title>Automated Linux/Unix guest logons</title>
-
-      <para>Starting with version 3.2, VirtualBox provides a custom PAM module
-      (Pluggable Authentication Module) which can be used to perform automated
-      guest logons on platforms which support this framework. Virtually all
-      modern Linux/Unix distributions rely on PAM.</para>
-
-      <para>For automated logons on Ubuntu (or Ubuntu-derived) distributions
-      using LightDM as the display manager, please see
-      <xref linkend="autologon_unix_lightdm" />.</para>
-
-      <para>The <computeroutput>pam_vbox.so</computeroutput> module itself
-      <emphasis role="bold">does not</emphasis> do an actual verification of
-      the credentials passed to the guest OS; instead it relies on other
-      modules such as <computeroutput>pam_unix.so</computeroutput> or
-      <computeroutput>pam_unix2.so</computeroutput> down in the PAM stack to
-      do the actual validation using the credentials retrieved by
-      <computeroutput>pam_vbox.so</computeroutput>. Therefore
-      <computeroutput>pam_vbox.so</computeroutput> has to be on top of the
-      authentication PAM service list.</para>
+
+      <title>Automated Linux and Unix Guest Logons</title>
+
+      <para>
+        Starting with version 3.2, VirtualBox provides a custom PAM
+        module (Pluggable Authentication Module) which can be used to
+        perform automated guest logons on platforms which support this
+        framework. Virtually all modern Linux and Unix distributions
+        rely on PAM.
+      </para>
+
+      <para>
+        For automated logons on Ubuntu, or Ubuntu-derived, distributions
+        using LightDM as the display manager, see
+        <xref linkend="autologon_unix_lightdm" />.
+      </para>
+
+      <para>
+        The <computeroutput>pam_vbox.so</computeroutput> module itself
+        <emphasis>does not</emphasis> do an actual verification of the
+        credentials passed to the guest OS. Instead it relies on other
+        modules such as <computeroutput>pam_unix.so</computeroutput> or
+        <computeroutput>pam_unix2.so</computeroutput> down in the PAM
+        stack to do the actual validation using the credentials
+        retrieved by <computeroutput>pam_vbox.so</computeroutput>.
+        Therefore <computeroutput>pam_vbox.so</computeroutput> has to be
+        on top of the authentication PAM service list.
+      </para>
 
       <note>
-        <para>The <computeroutput>pam_vbox.so</computeroutput> only supports
-        the <computeroutput>auth</computeroutput> primitive. Other primitives
-        such as <computeroutput>account</computeroutput>,
-        <computeroutput>session</computeroutput> or
-        <computeroutput>password</computeroutput> are not supported.</para>
+        <para>
+          The <computeroutput>pam_vbox.so</computeroutput> module only
+          supports the <computeroutput>auth</computeroutput> primitive.
+          Other primitives such as
+          <computeroutput>account</computeroutput>,
+          <computeroutput>session</computeroutput>, or
+          <computeroutput>password</computeroutput> are not supported.
+        </para>
       </note>
 
-      <para>The <computeroutput>pam_vbox.so</computeroutput> module is shipped
-      as part of the Guest Additions but it is not installed and/or activated
-      on the guest OS by default. In order to install it, it has to be copied
-      from
-      <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</computeroutput>
-      to the security modules directory, usually
-      <computeroutput>/lib/security/</computeroutput> on 32-bit guest Linuxes
-      or <computeroutput>/lib64/security/</computeroutput> on 64-bit ones.
-      Please refer to your guest OS documentation for the correct PAM module
-      directory.</para>
-
-      <para>For example, to use <computeroutput>pam_vbox.so</computeroutput>
-      with a Ubuntu Linux guest OS and GDM (the GNOME Desktop Manager) to
-      logon users automatically with the credentials passed by the host, the
-      guest OS has to be configured like the following:</para>
+      <para>
+        The <computeroutput>pam_vbox.so</computeroutput> module is
+        shipped as part of the Guest Additions but it is not installed
+        and/or activated on the guest OS by default. In order to install
+        it, it has to be copied from
+        <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</computeroutput>
+        to the security modules directory. This is usually
+        <computeroutput>/lib/security/</computeroutput> on 32-bit Linux
+        guests or <computeroutput>/lib64/security/</computeroutput> on
+        64-bit Linux guests. Please refer to your guest OS documentation
+        for the correct PAM module directory.
+      </para>
+
+      <para>
+        For example, to use <computeroutput>pam_vbox.so</computeroutput>
+        with a Ubuntu Linux guest OS and the GNOME Desktop Manager (GDM)
+        to logon users automatically with the credentials passed by the
+        host, configure the guest OS as follows:
+      </para>
 
       <orderedlist>
+
         <listitem>
-          <para>The <computeroutput>pam_vbox.so</computeroutput> module has to
-          be copied to the security modules directory, in this case it is
-          <computeroutput>/lib/security</computeroutput>.</para>
+          <para>
+            Copy the <computeroutput>pam_vbox.so</computeroutput> module
+            to the security modules directory. In this case,
+            <computeroutput>/lib/security</computeroutput>.
+          </para>
         </listitem>
 
         <listitem>
-          <para>Edit the PAM configuration file for GDM found at
-          <computeroutput>/etc/pam.d/gdm</computeroutput>, adding the line
-          <computeroutput>auth requisite pam_vbox.so</computeroutput> at the
-          top. Additionally, in most Linux distributions there is a file called
-          <computeroutput>/etc/pam.d/common-auth</computeroutput>. This file
-          is included in many other services (like the GDM file mentioned
-          above). There you also have to add the line <computeroutput>auth
-          requisite pam_vbox.so</computeroutput>.</para>
+          <para>
+            Edit the PAM configuration file for GDM, found at
+            <computeroutput>/etc/pam.d/gdm</computeroutput>. Add the
+            line <computeroutput>auth requisite
+            pam_vbox.so</computeroutput> at the top. Additionally, in
+            most Linux distributions there is a file called
+            <computeroutput>/etc/pam.d/common-auth</computeroutput>.
+            This file is included in many other services, like the GDM
+            file mentioned above. There you also have to add the line
+            <computeroutput>auth requisite pam_vbox.so</computeroutput>.
+          </para>
         </listitem>
 
         <listitem>
-          <para>If authentication against the shadow database using
-          <computeroutput>pam_unix.so</computeroutput> or
-          <computeroutput>pam_unix2.so</computeroutput> is desired, the
-          argument <computeroutput>try_first_pass</computeroutput> for
-          <computeroutput>pam_unix.so</computeroutput> or
-          <computeroutput>use_first_pass</computeroutput> for
-          <computeroutput>pam_unix2.so</computeroutput> is needed in order to
-          pass the credentials from the VirtualBox module to the shadow
-          database authentication module. For Ubuntu, this needs to be added
-          to <computeroutput>/etc/pam.d/common-auth</computeroutput>, to the
-          end of the line referencing
-          <computeroutput>pam_unix.so</computeroutput>. This argument tells
-          the PAM module to use credentials already present in the stack, i.e.
-          the ones provided by the VirtualBox PAM module.</para>
+          <para>
+            If authentication against the shadow database using
+            <computeroutput>pam_unix.so</computeroutput> or
+            <computeroutput>pam_unix2.so</computeroutput> is desired,
+            the argument <computeroutput>try_first_pass</computeroutput>
+            for <computeroutput>pam_unix.so</computeroutput> or
+            <computeroutput>use_first_pass</computeroutput> for
+            <computeroutput>pam_unix2.so</computeroutput> is needed in
+            order to pass the credentials from the VirtualBox module to
+            the shadow database authentication module. For Ubuntu, this
+            needs to be added to
+            <computeroutput>/etc/pam.d/common-auth</computeroutput>, to
+            the end of the line referencing
+            <computeroutput>pam_unix.so</computeroutput>. This argument
+            tells the PAM module to use credentials already present in
+            the stack, such as the ones provided by the VirtualBox PAM
+            module.
+          </para>
         </listitem>
+
       </orderedlist>
 
-      <para><warning>
-          <para>An incorrectly configured PAM stack can effectively prevent
-          you from logging into your guest system!</para>
-        </warning></para>
-
-      <para>To make deployment easier, you can pass the argument
-      <computeroutput>debug</computeroutput> right after the
-      <computeroutput>pam_vbox.so</computeroutput> statement. Debug log output
-      will then be recorded using syslog.</para>
-
-      <para><note>
-          <para>By default, pam_vbox will not wait for credentials to arrive
-          from the host, in other words: When a login prompt is shown (for
-          example by GDM/KDM or the text console) and pam_vbox does not yet
-          have credentials it does not wait until they arrive. Instead the
-          next module in the PAM stack (depending on the PAM configuration)
-          will have the chance for authentication.</para>
-        </note></para>
-
-      <para>Starting with VirtualBox 4.1.4 pam_vbox supports various guest
-      property parameters which all reside in
-      <computeroutput>/VirtualBox/GuestAdd/PAM/</computeroutput>. These
-      parameters allow pam_vbox to wait for credentials to be provided by the
-      host and optionally can show a message while waiting for those. The
-      following guest properties can be set:</para>
-
-      <orderedlist>
+      <warning>
+        <para>
+          An incorrectly configured PAM stack can effectively prevent
+          you from logging into your guest system.
+        </para>
+      </warning>
+
+      <para>
+        To make deployment easier, you can pass the argument
+        <computeroutput>debug</computeroutput> right after the
+        <computeroutput>pam_vbox.so</computeroutput> statement. Debug
+        log output will then be recorded using syslog.
+      </para>
+
+      <note>
+        <para>
+          By default, pam_vbox will not wait for credentials to arrive
+          from the host. When a login prompt is shown, for example by
+          GDM/KDM or the text console, and pam_vbox does not yet have
+          credentials it does not wait until they arrive. Instead the
+          next module in the PAM stack, depending on the PAM
+          configuration, will have the chance for authentication.
+        </para>
+      </note>
+
+      <para>
+        Starting with VirtualBox 4.1.4 pam_vbox supports various guest
+        property parameters which all reside in
+        <computeroutput>/VirtualBox/GuestAdd/PAM/</computeroutput>.
+        These parameters allow pam_vbox to wait for credentials to be
+        provided by the host and optionally can show a message while
+        waiting for those. The following guest properties can be set:
+      </para>
+
+      <itemizedlist>
+
         <listitem>
-          <para><computeroutput>CredsWait</computeroutput>: Set to "1" if
-          pam_vbox should start waiting until credentials arrive from the
-          host. Until then no other authentication methods such as manually
-          logging in will be available. If this property is empty or get
-          deleted no waiting for credentials will be performed and pam_vbox
-          will act like before (see paragraph above). This property must be
-          set read-only for the guest
-          (<computeroutput>RDONLYGUEST</computeroutput>).</para>
+          <para>
+            <computeroutput>CredsWait</computeroutput>: Set to 1 if
+            pam_vbox should start waiting until credentials arrive from
+            the host. Until then no other authentication methods such as
+            manually logging in will be available. If this property is
+            empty or gets deleted no waiting for credentials will be
+            performed and pam_vbox will act like before. This property
+            must be set read-only for the guest
+            (<computeroutput>RDONLYGUEST</computeroutput>).
+          </para>
         </listitem>
 
         <listitem>
-          <para><computeroutput>CredsWaitAbort</computeroutput>: Aborts waiting
-          for credentials when set to any value. Can be set from host and the
-          guest.</para>
+          <para>
+            <computeroutput>CredsWaitAbort</computeroutput>: Aborts
+            waiting for credentials when set to any value. Can be set
+            from host and the guest.
+          </para>
         </listitem>
 
         <listitem>
-          <para><computeroutput>CredsWaitTimeout</computeroutput>: Timeout (in
-          seconds) to let pam_vbox wait for credentials to arrive. When no
-          credentials arrive within this timeout, authentication of pam_vbox
-          will be set to failed and the next PAM module in chain will be
-          asked. If this property is not specified, set to "0" or an invalid
-          value, an infinite timeout will be used. This property must be set
-          read-only for the guest
-          (<computeroutput>RDONLYGUEST</computeroutput>).</para>
+          <para>
+            <computeroutput>CredsWaitTimeout</computeroutput>: Timeout,
+            in seconds, to let pam_vbox wait for credentials to arrive.
+            When no credentials arrive within this timeout,
+            authentication of pam_vbox will be set to failed and the
+            next PAM module in chain will be asked. If this property is
+            not specified, set to 0 or an invalid value, an infinite
+            timeout will be used. This property must be set read-only
+            for the guest
+            (<computeroutput>RDONLYGUEST</computeroutput>).
+          </para>
         </listitem>
-      </orderedlist>
-
-      <para>To customize pam_vbox further there are the following guest
-      properties:</para>
-
-      <orderedlist>
+
+      </itemizedlist>
+
+      <para>
+        To customize pam_vbox further there are the following guest
+        properties:
+      </para>
+
+      <itemizedlist>
+
         <listitem>
-          <para><computeroutput>CredsMsgWaiting</computeroutput>: Custom
-          message showed while pam_vbox is waiting for credentials from the
-          host. This property must be set read-only for the guest
-          (<computeroutput>RDONLYGUEST</computeroutput>).</para>
+          <para>
+            <computeroutput>CredsMsgWaiting</computeroutput>: Custom
+            message showed while pam_vbox is waiting for credentials
+            from the host. This property must be set read-only for the
+            guest (<computeroutput>RDONLYGUEST</computeroutput>).
+          </para>
         </listitem>
 
         <listitem>
-          <para><computeroutput>CredsMsgWaitTimeout</computeroutput>: Custom
-          message showed when waiting for credentials by pam_vbox timed out,
-          e.g. did not arrive within time. This property must be set read-only
-          for the guest (<computeroutput>RDONLYGUEST</computeroutput>).</para>
+          <para>
+            <computeroutput>CredsMsgWaitTimeout</computeroutput>: Custom
+            message showed when waiting for credentials by pam_vbox has
+            timed out. For example, they did not arrive within time.
+            This property must be set read-only for the guest
+            (<computeroutput>RDONLYGUEST</computeroutput>).
+          </para>
         </listitem>
-      </orderedlist>
-
-      <para><note>
-          <para>If a pam_vbox guest property does not have set the right flags
-          (<computeroutput>RDONLYGUEST</computeroutput>) this property will be
-          ignored then and - depending on the property - a default value will
-          be set. This can result in pam_vbox not waiting for credentials.
-          Consult the appropriate syslog file for more information and use the
-          <computeroutput>debug</computeroutput> option.</para>
-        </note></para>
+
+      </itemizedlist>
+
+      <note>
+        <para>
+          If a pam_vbox guest property does not have the correct flag
+          set (<computeroutput>RDONLYGUEST</computeroutput>) the
+          property is ignored and, depending on the property, a default
+          value will be used. This can result in pam_vbox not waiting
+          for credentials. Consult the appropriate syslog file for more
+          information and use the <computeroutput>debug</computeroutput>
+          option.
+        </para>
+      </note>
 
       <sect3 id="autologon_unix_lightdm">
-        <title>VirtualBox Greeter for Ubuntu / LightDM</title>
-
-        <para>Starting with version 4.2.12, VirtualBox comes with an own greeter
-        module named vbox-greeter which can be used with LightDM 1.0.1 or later.
-        LightDM is the default display manager since Ubuntu 10.11 and therefore
-        also can be used for automated guest logons.</para>
-
-        <para>vbox-greeter does not need the pam_vbox module described above
-        in order to function -- it comes with its own authentication mechanism
-        provided by LightDM. However, to provide maximum of flexibility both
-        modules can be used together on the same guest.</para>
-
-        <para>As for the pam_vbox module, vbox-greeter is shipped as part of
-        the Guest Additions but it is not installed and/or activated on the
-        guest OS by default For installing vbox-greeter automatically upon
-        Guest Additions installation, use the
-        <computeroutput>--with-autologon</computeroutput> switch when starting
-        the VBoxLinuxAdditions.run file:</para><screen># ./VBoxLinuxAdditions.run -- --with-autologon</screen>
-
-        <para>For manual or postponed installation, the
-        <computeroutput>vbox-greeter.desktop</computeroutput>
-        file has to be copied from
+
+        <title>VirtualBox Greeter for Ubuntu/LightDM</title>
+
+        <para>
+          Starting with version 4.2.12, VirtualBox comes with an own
+          greeter module named vbox-greeter which can be used with
+          LightDM 1.0.1 or later. LightDM is the default display manager
+          since Ubuntu 10.11 and therefore also can be used for
+          automated guest logons.
+        </para>
+
+        <para>
+          vbox-greeter does not need the pam_vbox module described above
+          in order to function. It comes with its own authentication
+          mechanism provided by LightDM. However, to provide maximum of
+          flexibility both modules can be used together on the same
+          guest.
+        </para>
+
+        <para>
+          As with the pam_vbox module, vbox-greeter is shipped as part
+          of the Guest Additions but it is not installed or activated on
+          the guest OS by default. To install vbox-greeter automatically
+          upon Guest Additions installation, use the
+          <computeroutput>--with-autologon</computeroutput> switch when
+          starting the VBoxLinuxAdditions.run file:
+        </para>
+
+<screen># ./VBoxLinuxAdditions.run -- --with-autologon</screen>
+
+        <para>
+          For manual or postponed installation, the
+          <computeroutput>vbox-greeter.desktop</computeroutput> file has
+          to be copied from
+          <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</computeroutput>
+          to the <computeroutput>xgreeters</computeroutput> directory,
+          usually
+          <computeroutput>/usr/share/xgreeters/</computeroutput>. Please
+          refer to your guest OS documentation for the correct LightDM
+          greeter directory.
+        </para>
+
+        <para>
+          The vbox-greeter module itself already was installed by the
+          VirtualBox Guest Additions installer and resides in
+          <computeroutput>/usr/sbin/</computeroutput>. To enable
+          vbox-greeter as the standard greeter module, the file
+          <computeroutput>/etc/lightdm/lightdm.conf</computeroutput>
+          needs to be edited:
+        </para>
+
+        <para>
+<screen>[SeatDefaults]
+greeter-session=vbox-greeter</screen>
+        </para>
+
+        <note>
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                The LightDM server needs to be fully restarted in order
+                for vbox-greeter to be used as the default greeter. As
+                root, run <computeroutput>service lightdm
+                --full-restart</computeroutput> on Ubuntu, or simply
+                restart the guest.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                vbox-greeter is independent of the graphical session
+                chosen by the user, such as Gnome, KDE, or Unity.
+                However, it requires FLTK 1.3 for representing its own
+                user interface.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </note>
+
+        <para>
+          There are numerous guest properties which can be used to
+          further customize the login experience. For automatically
+          logging in users, the same guest properties apply as for
+          pam_vbox. See <xref linkend="autologon_unix" />.
+        </para>
+
+        <para>
+          In addition to the above mentioned guest properties,
+          vbox-greeter allows further customization of its user
+          interface. These special guest properties all reside in
+          <computeroutput>/VirtualBox/GuestAdd/Greeter/</computeroutput>:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <computeroutput>HideRestart</computeroutput>: Set to 1 if
+              vbox-greeter should hide the button to restart the guest.
+              This property must be set read-only for the guest
+              (<computeroutput>RDONLYGUEST</computeroutput>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>HideShutdown</computeroutput>: Set to 1 if
+              vbox-greeter should hide the button to shutdown the guest.
+              This property must be set read-only for the guest
+              (<computeroutput>RDONLYGUEST</computeroutput>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>BannerPath</computeroutput>: Path to a
+              .PNG file for using it as a banner on the top. The image
+              size must be 460 x 90 pixels, any bit depth. This property
+              must be set read-only for the guest
+              (<computeroutput>RDONLYGUEST</computeroutput>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>UseTheming</computeroutput>: Set to 1 for
+              turning on the following theming options. This property
+              must be set read-only for the guest
+              (<computeroutput>RDONLYGUEST</computeroutput>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>Theme/BackgroundColor</computeroutput>:
+              Hexadecimal RRGGBB color for the background. This property
+              must be set read-only for the guest
+              (<computeroutput>RDONLYGUEST</computeroutput>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>Theme/LogonDialog/HeaderColor</computeroutput>:
+              Hexadecimal RRGGBB foreground color for the header text.
+              This property must be set read-only for the guest
+              (<computeroutput>RDONLYGUEST</computeroutput>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>Theme/LogonDialog/BackgroundColor</computeroutput>:
+              Hexadecimal RRGGBB color for the logon dialog background.
+              This property must be set read-only for the guest
+              (<computeroutput>RDONLYGUEST</computeroutput>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>Theme/LogonDialog/ButtonColor</computeroutput>:
+              Hexadecimal RRGGBB background color for the logon dialog
+              button. This property must be set read-only for the guest
+              (<computeroutput>RDONLYGUEST</computeroutput>).
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <note>
+          <para>
+            The same restrictions for the guest properties above apply
+            as for the ones specified in the pam_vbox section.
+          </para>
+        </note>
+
+      </sect3>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="adv-config-win-guest">
+
+    <title>Advanced Configuration for Windows Guests</title>
+
+    <sect2 id="sysprep">
+
+      <title>Automated Windows System Preparation</title>
+
+      <para>
+        Beginning with Windows NT 4.0, Microsoft offers a system
+        preparation tool called Sysprep, to prepare a Windows system for
+        deployment or redistribution. Whereas Windows 2000 and XP ship
+        with Sysprep on the installation medium, the tool also is
+        available for download on the Microsoft web site. In a standard
+        installation of Windows Vista and 7, Sysprep is already
+        included. Sysprep mainly consists of an executable called
+        <computeroutput>sysprep.exe</computeroutput> which is invoked by
+        the user to put the Windows installation into preparation mode.
+      </para>
+
+      <para>
+        Starting with VirtualBox 3.2.2, the Guest Additions offer a way
+        to launch a system preparation on the guest operating system in
+        an automated way, controlled from the host system. See
+        <xref linkend="guestadd-guestcontrol" /> for details of how to
+        use this feature with the special identifier
+        <computeroutput>sysprep</computeroutput> as the program to
+        execute, along with the user name
+        <computeroutput>sysprep</computeroutput> and password
+        <computeroutput>sysprep</computeroutput> for the credentials.
+        Sysprep then gets launched with the required system rights.
+      </para>
+
+      <note>
+        <para>
+          Specifying the location of "sysprep.exe" is
+          <emphasis
+        role="bold">not possible</emphasis>. Instead
+          the following paths are used, based on the operating system:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <computeroutput>C:\sysprep\sysprep.exe</computeroutput>
+              for Windows NT 4.0, 2000 and XP
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>%WINDIR%\System32\Sysprep\sysprep.exe</computeroutput>
+              for Windows Vista, 2008 Server and 7
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          The Guest Additions will automatically use the appropriate
+          path to execute the system preparation tool.
+        </para>
+      </note>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="adv-config-linux-guest">
+
+    <title>Advanced Configuration for Linux and Solaris Guests</title>
+
+    <sect2 id="linux-guest-manual-setup">
+
+      <title>Manual Setup of Selected Guest Services on Linux</title>
+
+      <para>
+        The VirtualBox Guest Additions contain several different
+        drivers. If for any reason you do not wish to set them all up,
+        you can install the Guest Additions using the following command:
+      </para>
+
+<screen>  sh ./VBoxLinuxAdditions.run no_setup</screen>
+
+      <para>
+        After this, you will need to at least compile the kernel modules
+        by running the command as root:
+      </para>
+
+<screen>  rcvboxadd setup</screen>
+
+      <para>
+        You will need to replace <emphasis>lib</emphasis> by
+        <emphasis>lib64</emphasis> on some 64bit guests, and on older
+        guests without the udev service you will need to add the
+        <emphasis>vboxadd</emphasis> service to the default runlevel to
+        ensure that the modules get loaded.
+      </para>
+
+      <para>
+        To setup the time synchronization service, add the service
+        vboxadd-service to the default runlevel. To set up the X11 and
+        OpenGL part of the Guest Additions, run the command
+
+<screen>  rcvboxadd-x11 setup</screen>
+
+        You do not need to enable any services for this.
+      </para>
+
+      <para>
+        To recompile the guest kernel modules, use this command:
+
+<screen>  rcvboxadd setup</screen>
+
+        After compilation you should reboot your guest to ensure that
+        the new modules are actually used.
+      </para>
+
+    </sect2>
+
+    <sect2 id="guestxorgsetup">
+
+      <title>Guest Graphics and Mouse Driver Setup in Depth</title>
+
+      <para>
+        This section assumes that you are familiar with configuring the
+        X.Org server using xorg.conf and optionally the newer mechanisms
+        using hal or udev and xorg.conf.d. If not you can learn about
+        them by studying the documentation which comes with X.Org.
+      </para>
+
+      <para>
+        The VirtualBox Guest Additions include the following drivers for
+        X.Org versions:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            X11R6.8/X11R6.9 and XFree86 version 4.3 (vboxvideo_drv_68.o
+            and vboxmouse_drv_68.o)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            X.Org Server versions 1.3 and later (vboxvideo_drv_13.so
+            vboxmouse_drv_13.so, and later versions).
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        By default these drivers can be found in the folowing directory:
+      </para>
+
+      <para>
         <computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</computeroutput>
-        to the <computeroutput>xgreeters</computeroutput> directory, usually
-        <computeroutput>/usr/share/xgreeters/</computeroutput>.
-        Please refer to your guest OS documentation for the correct LightDM
-        greeter directory.</para>
-
-        <para>The vbox-greeter module itself already was installed by the
-        VirtualBox Guest Additions installer and resides in
-        <computeroutput>/usr/sbin/</computeroutput>. To enable vbox-greeter as
-        the standard greeter module, the file
-        <computeroutput>/etc/lightdm/lightdm.conf</computeroutput> needs to be
-        edited:</para>
-
-        <para><screen>[SeatDefaults]
-greeter-session=vbox-greeter</screen></para>
-
-        <note><para>The LightDM server needs to be fully restarted in order to
-        get vbox-greeter used as the default greeter. As root, do a
-        <computeroutput>service lightdm --full-restart</computeroutput> on
-        Ubuntu, or simply restart the guest.</para></note>
-
-        <note><para>vbox-greeter is independent of the graphical session chosen
-        by the user (like Gnome, KDE, Unity etc). However, it requires FLTK 1.3
-        for representing its own user interface.</para></note>
-
-        <para>There are numerous guest properties which can be used to further
-        customize the login experience. For automatically logging in users, the
-        same guest properties apply as for pam_vbox, see
-        <xref linkend="autologon_unix" />.</para>
-
-        <para>In addition to the above mentioned guest properties, vbox-greeter
-        allows further customization of its user interface. These special guest
-        properties all reside in
-        <computeroutput>/VirtualBox/GuestAdd/Greeter/</computeroutput>:</para>
-
-        <orderedlist>
-          <listitem>
-            <para><computeroutput>HideRestart</computeroutput>: Set to "1" if
-            vbox-greeter should hide the button to restart the guest. This
-            property must be set read-only for the guest
-            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>HideShutdown</computeroutput>: Set to "1" if
-            vbox-greeter should hide the button to shutdown the guest. This
-            property must be set read-only for the guest
-            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>BannerPath</computeroutput>: Path to a .PNG
-            file for using it as a banner on the top. The image size must be
-            460 x 90 pixels, any bit depth. This property must be
-            set read-only for the guest
-            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>UseTheming</computeroutput>: Set to "1" for
-            turning on the following theming options. This property must be
-            set read-only for the guest
-            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>Theme/BackgroundColor</computeroutput>:
-            Hexadecimal RRGGBB color for the background. This property must be
-            set read-only for the guest
-            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>Theme/LogonDialog/HeaderColor</computeroutput>:
-            Hexadecimal RRGGBB foreground color for the header text. This
-            property must be set read-only for the guest
-            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>Theme/LogonDialog/BackgroundColor</computeroutput>:
-            Hexadecimal RRGGBB color for the logon dialog background. This
-            property must be set read-only for the guest
-            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>Theme/LogonDialog/ButtonColor</computeroutput>:
-            Hexadecimal RRGGBB background color for the logon dialog button. This
-            property must be set read-only for the guest
-            (<computeroutput>RDONLYGUEST</computeroutput>).</para>
-          </listitem>
-        </orderedlist>
-
-        <note><para>The same restrictions for the guest properties above apply
-        as for the ones specified in the pam_vbox section.</para></note>
-      </sect3>
-    </sect2>
-  </sect1>
-
-  <sect1>
-    <title>Advanced configuration for Windows guests</title>
-
-    <sect2 id="sysprep">
-      <title>Automated Windows system preparation</title>
-
-      <para>Beginning with Windows NT 4.0, Microsoft offers a "system
-      preparation" tool (in short: Sysprep) to prepare a Windows system for
-      deployment or redistribution. Whereas Windows 2000 and XP ship with
-      Sysprep on the installation medium, the tool also is available for
-      download on the Microsoft web site. In a standard installation of
-      Windows Vista and 7, Sysprep is already included. Sysprep mainly
-      consists of an executable called
-      <computeroutput>sysprep.exe</computeroutput> which is invoked by the
-      user to put the Windows installation into preparation mode.</para>
-
-      <para>Starting with VirtualBox 3.2.2, the Guest Additions offer a way to
-      launch a system preparation on the guest operating system in an
-      automated way, controlled from the host system. To achieve that, see
-      <xref linkend="guestadd-guestcontrol" /> for using the feature with the
-      special identifier <computeroutput>sysprep</computeroutput> as the
-      program to execute, along with the user name
-      <computeroutput>sysprep</computeroutput> and password
-      <computeroutput>sysprep</computeroutput> for the credentials. Sysprep
-      then gets launched with the required system rights.</para>
-
-      <note>
-        <para>Specifying the location of "sysprep.exe" is <emphasis
-        role="bold">not possible</emphasis> -- instead the following paths are
-        used (based on the operating system): <itemizedlist>
-            <listitem>
-              <para><computeroutput>C:\sysprep\sysprep.exe</computeroutput>
-              for Windows NT 4.0, 2000 and XP</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>%WINDIR%\System32\Sysprep\sysprep.exe</computeroutput>
-              for Windows Vista, 2008 Server and 7</para>
-            </listitem>
-          </itemizedlist> The Guest Additions will automatically use the
-        appropriate path to execute the system preparation tool.</para>
-      </note>
-    </sect2>
-  </sect1>
-
-  <sect1>
-    <title>Advanced configuration for Linux and Solaris guests</title>
-
-    <sect2>
-      <title>Manual setup of selected guest services on Linux</title>
-
-      <para>The VirtualBox Guest Additions contain several different drivers.
-      If for any reason you do not wish to set them all up, you can install
-      the Guest Additions using the following command:</para>
-
-      <screen>  sh ./VBoxLinuxAdditions.run no_setup</screen>
-
-      <para>After this, you will need to at least compile the kernel modules
-      by running the command <screen>  rcvboxadd setup</screen>
-      as root (you will need to replace <emphasis>lib</emphasis> by
-      <emphasis>lib64</emphasis> on some 64bit guests), and on older guests
-      without the udev service you will need to add the
-      <emphasis>vboxadd</emphasis> service to the default runlevel to ensure
-      that the modules get loaded.</para>
-
-      <para>To setup the time synchronization service,
-      add the service vboxadd-service to the default runlevel. To set up the
-      X11 and OpenGL part of the Guest Additions, run the command
-      <screen>  rcvboxadd-x11 setup</screen>
-      (you do not need to enable any services for this).</para>
-
-      <para>To recompile the guest kernel modules, use this command:
-      <screen>  rcvboxadd setup</screen>
-      After compilation you should reboot your guest to ensure that the new
-      modules are actually used.</para>
-    </sect2>
-
-    <sect2 id="guestxorgsetup">
-      <title>Guest graphics and mouse driver setup in depth</title>
-
-      <para>This section assumes that you are familiar with configuring the
-      X.Org server using xorg.conf and optionally the newer mechanisms using
-      hal or udev and xorg.conf.d. If not you can learn about them by studying
-      the documentation which comes with X.Org.</para>
-
-      <para>The VirtualBox Guest Additions come with drivers for X.Org
-      versions <itemizedlist>
-          <listitem>
-            <para>X11R6.8/X11R6.9 and XFree86 version 4.3 (vboxvideo_drv_68.o and vboxmouse_drv_68.o)</para>
-          </listitem>
-
-          <listitem>
-            <para>X11R7.0 (vboxvideo_drv_70.so and vboxmouse_drv_70.so)</para>
-          </listitem>
-
-          <listitem>
-            <para>X11R7.1 (vboxvideo_drv_71.so and vboxmouse_drv_71.so)</para>
-          </listitem>
-
-          <listitem>
-            <para>X.Org Server versions 1.3 and later (vboxvideo_drv_13.so and vboxmouse_drv_13.so and so on).</para>
-          </listitem>
-        </itemizedlist> By default these drivers can be found in the
-      directory</para>
-
-      <para><computeroutput>/opt/VBoxGuestAdditions-&lt;version&gt;/other/</computeroutput></para>
-
-      <para>and the correct versions for the X server are symbolically linked
-      into the X.Org driver directories.</para>
-
-      <para>For graphics integration to work correctly, the X server must load
-      the vboxvideo driver (many recent X server versions look for it
-      automatically if they see that they are running in VirtualBox) and for
-      an optimal user experience the guest kernel drivers must be loaded and
-      the Guest Additions tool VBoxClient must be running as a client in the X
-      session. For mouse integration to work correctly, the guest kernel
-      drivers must be loaded and in addition, in X servers from X.Org X11R6.8
-      to X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver must be
-      loaded and associated with /dev/mouse or /dev/psaux; in X.Org server 1.3
-      or later a driver for a PS/2 mouse must be loaded and the right
-      vboxmouse driver must be associated with /dev/vboxguest.</para>
-
-      <para>The VirtualBox guest graphics driver can use any graphics
-      configuration for which the virtual resolution fits into the virtual
-      video memory allocated to the virtual machine (minus a small amount used
-      by the guest driver) as described in <xref
-      linkend="settings-display" />. The driver will offer a range of standard
-      modes at least up to the default guest resolution for all active guest
-      monitors. In X.Org Server 1.3 and later the default mode can be changed
-      by setting the output property VBOX_MODE to
-      "&lt;width&gt;x&lt;height&gt;" for any guest monitor. When VBoxClient
-      and the kernel drivers are active this is done automatically when the
-      host requests a mode change. The driver for older versions can only
-      receive new modes by querying the host for requests at regular
-      intervals.</para>
-
-      <para>With pre-1.3 X Servers you can also add your own modes to the X
-      server configuration file. You simply need to add them to the "Modes"
-      list in the "Display" subsection of the "Screen" section. For example,
-      the section shown here has a custom 2048x800 resolution mode
-      added:</para>
-
-      <screen>Section "Screen"
+      </para>
+
+      <para>
+        The correct versions for the X server are symbolically linked
+        into the X.Org driver directories.
+      </para>
+
+      <para>
+        For graphics integration to work correctly, the X server must
+        load the vboxvideo driver. Many recent X server versions look
+        for it automatically if they see that they are running in
+        VirtualBox. For an optimal user experience the guest kernel
+        drivers must be loaded and the Guest Additions tool VBoxClient
+        must be running as a client in the X session. For mouse
+        integration to work correctly, the guest kernel drivers must be
+        loaded and in addition, in X servers from X.Org X11R6.8 to
+        X11R7.1 and in XFree86 version 4.3 the right vboxmouse driver
+        must be loaded and associated with /dev/mouse or /dev/psaux. In
+        X.Org server 1.3 or later a driver for a PS/2 mouse must be
+        loaded and the right vboxmouse driver must be associated with
+        /dev/vboxguest.
+      </para>
+
+      <para>
+        The VirtualBox guest graphics driver can use any graphics
+        configuration for which the virtual resolution fits into the
+        virtual video memory allocated to the virtual machine, minus a
+        small amount used by the guest driver, as described in
+        <xref
+      linkend="settings-display" />. The driver will offer
+        a range of standard modes at least up to the default guest
+        resolution for all active guest monitors. In X.Org Server 1.3
+        and later the default mode can be changed by setting the output
+        property VBOX_MODE to "&lt;width&gt;x&lt;height&gt;" for any
+        guest monitor. When VBoxClient and the kernel drivers are active
+        this is done automatically when the host requests a mode change.
+        The driver for older versions can only receive new modes by
+        querying the host for requests at regular intervals.
+      </para>
+
+      <para>
+        With pre-1.3 X Servers you can also add your own modes to the X
+        server configuration file. You simply need to add them to the
+        "Modes" list in the "Display" subsection of the "Screen"
+        section. For example, the following section has a custom
+        2048x800 resolution mode added:
+      </para>
+
+<screen>Section "Screen"
         Identifier    "Default Screen"
         Device        "VirtualBox graphics card"
@@ -686,140 +994,224 @@
         EndSubSection
 EndSection</screen>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="cpuhotplug">
-    <title>CPU hot-plugging</title>
-
-    <para>With virtual machines running modern server operating systems,
-    VirtualBox supports CPU hot-plugging.<footnote>
-        <para>Support for CPU hot-plugging was introduced with VirtualBox
-        3.2.</para>
-      </footnote> Whereas on a physical computer this would mean that a CPU
-    can be added or removed while the machine is running, VirtualBox supports
-    adding and removing virtual CPUs while a virtual machine is
-    running.</para>
-
-    <para>CPU hot-plugging works only with guest operating systems that
-    support it. So far this applies only to Linux and Windows Server 2008 x64
-    Data Center Edition. Windows supports only hot-add while Linux supports
-    hot-add and hot-remove but to use this feature with more than 8 CPUs a
-    64bit Linux guest is required.</para>
-
-    <para>At this time, CPU hot-plugging requires using the VBoxManage
-    command-line interface. First, hot-plugging needs to be enabled for a
-    virtual machine:<screen>VBoxManage modifyvm "VM name" --cpuhotplug on</screen></para>
-
-    <para>After that, the <computeroutput>--cpus</computeroutput> option specifies the maximum number of CPUs
-    that the virtual machine can have:<screen>VBoxManage modifyvm "VM name" --cpus 8</screen>When
-    the VM is off, you can then add and remove virtual CPUs with the
-    <computeroutput>modifyvm --plugcpu</computeroutput> and
-    <computeroutput>--unplugcpu</computeroutput> subcommands, which take the number of the
-    virtual CPU as a parameter, like this:<screen>VBoxManage modifyvm "VM name" --plugcpu 3
-VBoxManage modifyvm "VM name" --unplugcpu 3</screen>Note that CPU 0 can never
-    be removed.</para>
-
-    <para>While the VM is running, CPUs can be added and removed with the
-    <computeroutput>controlvm plugcpu</computeroutput> and
-    <computeroutput>unplugcpu</computeroutput> commands
-    instead:<screen>VBoxManage controlvm "VM name" plugcpu 3
-VBoxManage controlvm "VM name" unplugcpu 3</screen></para>
-
-    <para>See <xref linkend="vboxmanage-modifyvm" /> and <xref
-    linkend="vboxmanage-controlvm" /> for details.</para>
-
-    <para>With Linux guests, the following applies: To prevent ejection while
-    the CPU is still used it has to be ejected from within the guest before.
-    The Linux Guest Additions contain a service which receives hot-remove
-    events and ejects the CPU. Also, after a CPU is added to the VM it is not
-    automatically used by Linux. The Linux Guest Additions service will take
-    care of that if installed. If not a CPU can be started with the following
-    command:<screen>echo 1 &gt; /sys/devices/system/cpu/cpu&lt;id&gt;/online</screen></para>
+
+    <title>CPU Hot-Plugging</title>
+
+    <para>
+      With virtual machines running modern server operating systems,
+      VirtualBox supports CPU hot-plugging.
+
+      <footnote>
+
+        <para>
+          Support for CPU hot-plugging was introduced with VirtualBox
+          3.2.
+        </para>
+
+      </footnote>
+
+      Whereas on a physical computer this would mean that a CPU can be
+      added or removed while the machine is running, VirtualBox supports
+      adding and removing virtual CPUs while a virtual machine is
+      running.
+    </para>
+
+    <para>
+      CPU hot-plugging works only with guest operating systems that
+      support it. So far this applies only to Linux and Windows Server
+      2008 x64 Data Center Edition. Windows supports only hot-add while
+      Linux supports hot-add and hot-remove but to use this feature with
+      more than 8 CPUs a 64bit Linux guest is required.
+    </para>
+
+    <para>
+      At this time, CPU hot-plugging requires using the VBoxManage
+      command-line interface. First, hot-plugging needs to be enabled
+      for a virtual machine:
+
+<screen>VBoxManage modifyvm "VM name" --cpuhotplug on</screen>
+    </para>
+
+    <para>
+      After that, the <computeroutput>--cpus</computeroutput> option
+      specifies the maximum number of CPUs that the virtual machine can
+      have:
+
+<screen>VBoxManage modifyvm "VM name" --cpus 8</screen>
+
+      When the VM is off, you can then add and remove virtual CPUs with
+      the <computeroutput>modifyvm --plugcpu</computeroutput> and
+      <computeroutput>--unplugcpu</computeroutput> subcommands, which
+      take the number of the virtual CPU as a parameter, like this:
+
+<screen>VBoxManage modifyvm "VM name" --plugcpu 3
+VBoxManage modifyvm "VM name" --unplugcpu 3</screen>
+
+      Note that CPU 0 can never be removed.
+    </para>
+
+    <para>
+      While the VM is running, CPUs can be added and removed with the
+      <computeroutput>controlvm plugcpu</computeroutput> and
+      <computeroutput>unplugcpu</computeroutput> commands instead:
+
+<screen>VBoxManage controlvm "VM name" plugcpu 3
+VBoxManage controlvm "VM name" unplugcpu 3</screen>
+    </para>
+
+    <para>
+      See <xref linkend="vboxmanage-modifyvm" /> and
+      <xref
+    linkend="vboxmanage-controlvm" /> for details.
+    </para>
+
+    <para>
+      With Linux guests, the following applies:
+    </para>
+
+    <para>
+      To prevent ejection while the CPU is still used it has to be
+      ejected from within the guest before. The Linux Guest Additions
+      contain a service which receives hot-remove events and ejects the
+      CPU. Also, after a CPU is added to the VM it is not automatically
+      used by Linux. The Linux Guest Additions service will take care of
+      that if installed. If not a CPU can be started with the following
+      command:
+    </para>
+
+<screen>echo 1 &gt; /sys/devices/system/cpu/cpu&lt;id&gt;/online</screen>
+
   </sect1>
 
   <sect1 id="pcipassthrough">
-    <title>PCI passthrough</title>
-
-    <para>When running on Linux hosts, with a recent enough kernel (at least
-    version <computeroutput>2.6.31</computeroutput>) experimental host PCI
-    devices passthrough is available.<footnote>
-        <para>Experimental support for PCI passthrough was introduced with
-        VirtualBox 4.1.</para>
-      </footnote></para>
+
+    <title>PCI Passthrough</title>
+
+    <para>
+      When running on Linux hosts, with a recent enough kernel, at least
+      version <computeroutput>2.6.31</computeroutput>, experimental host
+      PCI devices passthrough is available.
+
+      <footnote>
+
+        <para>
+          Experimental support for PCI passthrough was introduced with
+          VirtualBox 4.1.
+        </para>
+
+      </footnote>
+    </para>
 
     <note>
-      <para>The PCI passthrough module is shipped as a VirtualBox extension
-      package, which must be installed separately. See <xref
-      linkend="intro-installing" /> for more information.</para>
+      <para>
+        The PCI passthrough module is shipped as a VirtualBox extension
+        package, which must be installed separately. See
+        <xref
+      linkend="intro-installing" />.
+      </para>
     </note>
 
-    <para>Essentially this feature allows to directly use physical PCI devices
-    on the host by the guest even if host doesn't have drivers for this
-    particular device. Both, regular PCI and some PCI Express cards, are
-    supported. AGP and certain PCI Express cards are not supported at the
-    moment if they rely on GART (Graphics Address Remapping Table) unit
-    programming for texture management as it does rather non-trivial operations
-    with pages remapping interfering with IOMMU. This limitation may be lifted
-    in future releases.</para>
-
-    <para>To be fully functional, PCI passthrough support in VirtualBox
-    depends upon an IOMMU hardware unit which is not yet too widely available.
-    If the device uses bus mastering (i.e. it performs DMA to the OS memory on
-    its own), then an IOMMU is required, otherwise such DMA transactions may
-    write to the wrong physical memory address as the device DMA engine is
-    programmed using a device-specific protocol to perform memory
-    transactions. The IOMMU functions as translation unit mapping physical
-    memory access requests from the device using knowledge of the guest
-    physical address to host physical addresses translation rules.</para>
-
-    <para>Intel's solution for IOMMU is marketed as "Intel Virtualization
-    Technology for Directed I/O" (VT-d), and AMD's one is called AMD-Vi. So
-    please check if your motherboard datasheet has appropriate technology.
-    Even if your hardware doesn't have a IOMMU, certain PCI cards may work
-    (such as serial PCI adapters), but the guest will show a warning on boot
-    and the VM execution will terminate if the guest driver will attempt to
-    enable card bus mastering.</para>
-
-    <para>It is very common that the BIOS or the host OS disables the IOMMU by
-    default. So before any attempt to use it please make sure that
-    <orderedlist>
-        <listitem>
-          <para>Your motherboard has an IOMMU unit.</para>
-        </listitem>
-
-        <listitem>
-          <para>Your CPU supports the IOMMU.</para>
-        </listitem>
-
-        <listitem>
-          <para>The IOMMU is enabled in the BIOS.</para>
-        </listitem>
-
-        <listitem>
-          <para>The VM must run with VT-x/AMD-V and nested paging
-          enabled.</para>
-        </listitem>
-
-        <listitem>
-          <para>Your Linux kernel was compiled with IOMMU support (including
-          DMA remapping, see <computeroutput>CONFIG_DMAR</computeroutput>
-          kernel compilation option). The PCI stub driver
-          (<computeroutput>CONFIG_PCI_STUB</computeroutput>) is required as
-          well.</para>
-        </listitem>
-
-        <listitem>
-          <para>Your Linux kernel recognizes and uses the IOMMU unit
-          (<computeroutput>intel_iommu=on</computeroutput> boot option could
-          be needed). Search for DMAR and PCI-DMA in kernel boot log.</para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>Once you made sure that the host kernel supports the IOMMU, the next
-    step is to select the PCI card and attach it to the guest. To figure out
-    the list of available PCI devices, use the
-    <computeroutput>lspci</computeroutput> command. The output will look like
-    this:</para>
-    <screen>01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450]
+    <para>
+      Essentially this feature allows a guest to directly use physical
+      PCI devices on the host, even if host does not have drivers for
+      this particular device. Both, regular PCI and some PCI Express
+      cards, are supported. AGP and certain PCI Express cards are not
+      supported at the moment if they rely on Graphics Address Remapping
+      Table (GART) unit programming for texture management as it does
+      rather non-trivial operations with pages remapping interfering
+      with IOMMU. This limitation may be lifted in future releases.
+    </para>
+
+    <para>
+      To be fully functional, PCI passthrough support in VirtualBox
+      depends upon an IOMMU hardware unit which is not yet too widely
+      available. If the device uses bus mastering, for example it
+      performs DMA to the OS memory on its own, then an IOMMU is
+      required. Otherwise such DMA transactions may write to the wrong
+      physical memory address as the device DMA engine is programmed
+      using a device-specific protocol to perform memory transactions.
+      The IOMMU functions as translation unit mapping physical memory
+      access requests from the device using knowledge of the guest
+      physical address to host physical addresses translation rules.
+    </para>
+
+    <para>
+      Intel's solution for IOMMU is called Intel Virtualization
+      Technology for Directed I/O (VT-d), and AMD's solution is called
+      AMD-Vi. Check your motherboard datasheet for the appropriate
+      technology. Even if your hardware does not have a IOMMU, certain
+      PCI cards may work, such as serial PCI adapters, but the guest
+      will show a warning on boot and the VM execution will terminate if
+      the guest driver will attempt to enable card bus mastering.
+    </para>
+
+    <para>
+      It is very common that the BIOS or the host OS disables the IOMMU
+      by default. So before any attempt to use it please make sure that
+      the following apply:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Your motherboard has an IOMMU unit.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Your CPU supports the IOMMU.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The IOMMU is enabled in the BIOS.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The VM must run with VT-x/AMD-V and nested paging enabled.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Your Linux kernel was compiled with IOMMU support, including
+          DMA remapping. See the
+          <computeroutput>CONFIG_DMAR</computeroutput> kernel
+          compilation option. The PCI stub driver
+          (<computeroutput>CONFIG_PCI_STUB</computeroutput>) is required
+          as well.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Your Linux kernel recognizes and uses the IOMMU unit. The
+          <computeroutput>intel_iommu=on</computeroutput> boot option
+          could be needed. Search for DMAR and PCI-DMA in kernel boot
+          log.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Once you made sure that the host kernel supports the IOMMU, the
+      next step is to select the PCI card and attach it to the guest. To
+      figure out the list of available PCI devices, use the
+      <computeroutput>lspci</computeroutput> command. The output will
+      look as follows:
+    </para>
+
+<screen>01:00.0 VGA compatible controller: ATI Technologies Inc Cedar PRO [Radeon HD 5450]
 01:00.1 Audio device: ATI Technologies Inc Manhattan HDMI Audio [Mobility Radeon HD 5000 Series]
 02:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL8111/8168B PCI Express Gigabit
@@ -828,363 +1220,590 @@
 03:00.1 IDE interface: JMicron Technology Corp. JMB362/JMB363 Serial ATA Controller (rev 03)
 06:00.0 VGA compatible controller: nVidia Corporation G86 [GeForce 8500 GT] (rev a1)</screen>
-    <para>The first column is a PCI address (in format
-    <computeroutput>bus:device.function</computeroutput>). This address could
-    be used to identify the device for further operations. For example, to
-    attach a PCI network controller on the system listed above to the second
-    PCI bus in the guest, as device 5, function 0, use the following command:
-    <screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen>
-    To detach same device, use <screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen>
-    Please note that both host and guest could freely assign a different PCI
-    address to the card attached during runtime, so those addresses only apply
-    to the address of the card at the moment of attachment (host), and during
-    BIOS PCI init (guest).</para>
-
-    <para>If the virtual machine has a PCI device attached, certain
-    limitations apply: <orderedlist>
+
+    <para>
+      The first column is a PCI address, in the format
+      <computeroutput>bus:device.function</computeroutput>. This address
+      could be used to identify the device for further operations. For
+      example, to attach a PCI network controller on the system listed
+      above to the second PCI bus in the guest, as device 5, function 0,
+      use the following command:
+    </para>
+
+<screen>VBoxManage modifyvm "VM name" --pciattach 02:00.0@01:05.0</screen>
+
+    <para>
+      To detach the same device, use:
+    </para>
+
+<screen>VBoxManage modifyvm "VM name" --pcidetach 02:00.0</screen>
+
+    <para>
+      Please note that both host and guest could freely assign a
+      different PCI address to the card attached during runtime, so
+      those addresses only apply to the address of the card at the
+      moment of attachment (host), and during BIOS PCI init (guest).
+    </para>
+
+    <para>
+      If the virtual machine has a PCI device attached, certain
+      limitations apply:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Only PCI cards with non-shared interrupts, such as those using
+          MSI on the host, are supported at the moment.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          No guest state can be reliably saved or restored. The internal
+          state of the PCI card cannot be retrieved.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Teleportation, also called live migration, does not work. The
+          internal state of the PCI card cannot be retrieved.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          No lazy physical memory allocation. The host will preallocate
+          the whole RAM required for the VM on startup, as we cannot
+          catch physical hardware accesses to the physical memory.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="webcam-passthrough">
+
+    <title>Webcam Passthrough</title>
+
+    <sect2 id="webcam-using-guest">
+
+      <title>Using a Host Webcam in the Guest</title>
+
+      <para>
+        VirtualBox 4.3 includes an experimental feature which allows a
+        guest to use a host webcam. This complements the general USB
+        passthrough support which was the typical way of using host
+        webcams in earlier versions. The webcam passthrough support can
+        handle non-USB video sources in theory, but this is completely
+        untested.
+      </para>
+
+      <note>
+        <para>
+          The webcam passthrough module is shipped as part of the Oracle
+          VM VirtualBox extension pack, which must be installed
+          separately. See <xref
+        linkend="intro-installing" />.
+        </para>
+      </note>
+
+      <para>
+        The host webcam can be attached to the VM using Devices menu in
+        the VM menu bar. The Webcams menu contains a list of available
+        video input devices on the host. Clicking on a webcam name
+        attaches or detaches the corresponding host device.
+      </para>
+
+      <para>
+        The VBoxManage command line tool can be used to enable webcam
+        passthrough. Please see the host-specific sections below for
+        additional details. The following commands are available:
+      </para>
+
+      <itemizedlist>
+
         <listitem>
-           <para>Only PCI cards with non-shared interrupts (such as using MSI on host) are supported at the moment.</para>
+          <para>
+            Get a list of host webcams, or other video input devices:
+          </para>
+
+<screen>VBoxManage list webcams</screen>
+
+          <para>
+            The output format is as follows:
+          </para>
+
+<screen>alias "user friendly name"
+host path or identifier</screen>
+
+          <para>
+            The alias can be used as a shortcut in other commands. Alias
+            '.0' means the default video input device on the host. Alias
+            '.1', '.2'means first, second video input device, and so on.
+            The device order is host-specific.
+          </para>
         </listitem>
 
         <listitem>
-           <para>No guest state can be reliably saved/restored (as the internal state of the PCI card could not be retrieved).</para>
+          <para>
+            Attach a webcam to a running VM:
+
+<screen>VBoxManage controlvm "VM name" webcam attach [host_path|alias [settings]]</screen>
+
+            This will attach a USB webcam device to the guest.
+          </para>
+
+          <para>
+            The <computeroutput>settings</computeroutput> parameter is a
+            string
+            <computeroutput>Setting1=Value1;Setting2=Value2</computeroutput>,
+            which enables you to configure the emulated webcam device.
+            The following settings are supported:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <computeroutput>MaxFramerate</computeroutput>: The
+                highest rate at which video frames are sent to the
+                guest. A higher frame rate requires more CPU power.
+                Therefore sometimes it is useful to set a lower limit.
+                Default is no limit and allow the guest to use all frame
+                rates supported by the host webcam.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>MaxPayloadTransferSize</computeroutput>:
+                How many bytes the emulated webcam can send to the guest
+                at a time. Default value is 3060 bytes, which is used by
+                some webcams. Higher values can slightly reduce CPU
+                load, if the guest is able to use larger buffers.
+                However, a high
+                <computeroutput>MaxPayloadTransferSize</computeroutput>
+                might be not supported by some guests.
+              </para>
+            </listitem>
+
+          </itemizedlist>
         </listitem>
 
         <listitem>
-           <para>Teleportation (live migration) doesn't work (for the same reason).</para>
+          <para>
+            Detach a webcam from a running VM:
+
+<screen>VBoxManage controlvm "VM name" webcam detach [host_path|alias]</screen>
+          </para>
         </listitem>
 
         <listitem>
-           <para>No lazy physical memory allocation. The host will preallocate the whole RAM required for the VM on startup
-           (as we cannot catch physical hardware accesses to the physical memory).</para>
+          <para>
+            List the webcams attached to a running VM:
+
+<screen>VBoxManage controlvm "VM name" webcam list</screen>
+
+            The output contains the path or alias which was used in the
+            <computeroutput>webcam attach</computeroutput> command for
+            each attached webcam.
+          </para>
         </listitem>
-      </orderedlist></para>
+
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="webcam-win-hosts">
+
+      <title>Windows Hosts</title>
+
+      <para>
+        When the webcam device is detached from the host, the emulated
+        webcam device is automatically detached from the guest.
+      </para>
+
+    </sect2>
+
+    <sect2 id="webcam-mac-hosts">
+
+      <title>Mac OS X Hosts</title>
+
+      <para>
+        OS X version 10.9 or later is required.
+      </para>
+
+      <para>
+        When the webcam device is detached from the host, the emulated
+        webcam device remains attached to the guest and must be manually
+        detached using the <computeroutput>VBoxManage controlvm "VM
+        name" webcam detach ...</computeroutput> command.
+      </para>
+
+    </sect2>
+
+    <sect2 id="webcam-linux-hosts">
+
+      <title>Linux and Solaris Hosts</title>
+
+      <para>
+        When the webcam is detached from the host the emulated webcam
+        device is automatically detached from the guest only if the
+        webcam is streaming video. If the emulated webcam is inactive it
+        should be manually detached using the <computeroutput>VBoxManage
+        controlvm "VM name" webcam detach ...</computeroutput> command.
+      </para>
+
+      <para>
+        Aliases <computeroutput>.0</computeroutput> and
+        <computeroutput>.1</computeroutput> are mapped to
+        <computeroutput>/dev/video0</computeroutput>, alias
+        <computeroutput>.2</computeroutput> is mapped to
+        <computeroutput>/dev/video1</computeroutput> and so forth.
+      </para>
+
+    </sect2>
+
   </sect1>
 
-  <sect1>
-    <title>Webcam passthrough</title>
-
-    <sect2 id="webcam-passthrough">
-      <title>Using a host webcam in the guest</title>
-
-      <para>VirtualBox 4.3 includes an experimental feature which allows a guest to use
-      a host webcam. This complements the general USB passthrough support which was the
-      typical way of using host webcams in earlier versions. The webcam passthrough support
-      can handle non-USB video sources in theory, but this is completely untested.</para>
-
-      <note>
-        <para>The webcam passthrough module is shipped as part of the Oracle VM VirtualBox
-        extension pack, which must be installed separately. See <xref
-        linkend="intro-installing" /> for more information.</para>
-      </note>
-
-      <para>The host webcam can be attached to the VM using "Devices" menu in the VM menu bar.
-      The "Webcams" menu contains a list of available video input devices on the host.
-      Clicking on a webcam name attaches or detaches the corresponding host device.</para>
-
-      <para>The VBoxManage command line tool can be used to enable webcam passthrough.
-      Please see the host-specific sections below for additional details.
-      The following commands are available:
-        <itemizedlist>
-          <listitem><para>Get a list of host webcams (or other video input devices):
-            <screen>VBoxManage list webcams</screen>
-            The output format:
-            <screen>alias "user friendly name"
-host path or identifier</screen>
-            The alias can be used as a shortcut in other commands. Alias '.0' means
-            default video input device on the host, '.1', '.2', etc mean first, second, etc
-            video input device. The device order is host-specific.
-          </para></listitem>
-          <listitem><para>Attach a webcam to a running VM:
-            <screen>VBoxManage controlvm "VM name" webcam attach [host_path|alias [settings]]</screen>
-            This will attach a USB webcam device to the guest.</para>
-
-            <para>The <computeroutput>settings</computeroutput> parameter is a string
-            <computeroutput>Setting1=Value1;Setting2=Value2</computeroutput>, which allows to
-            configure the emulated webcam device. The following settings are supported:
-            <itemizedlist>
-              <listitem>
-                <para><computeroutput>MaxFramerate</computeroutput> The highest rate at which video frames
-                are sent to the guest. A higher frame rate requires more CPU power. Therefore sometimes
-                it is useful to set a lower limit. Default is no limit and allow the guest to use all
-                frame rates supported by the host webcam.</para>
-              </listitem>
-              <listitem>
-                <para><computeroutput>MaxPayloadTransferSize</computeroutput> How many bytes the emulated
-                webcam can send to the guest at a time. Default value is 3060 bytes, which is used by
-                some webcams. Higher values can slightly reduce CPU load, if the guest is able to use
-                larger buffers. However, a high <computeroutput>MaxPayloadTransferSize</computeroutput>
-                might be not supported by some guests.</para>
-              </listitem>
-            </itemizedlist>
-          </para></listitem>
-          <listitem><para>Detach a webcam from a running VM:
-            <screen>VBoxManage controlvm "VM name" webcam detach [host_path|alias]</screen>
-          </para></listitem>
-          <listitem><para>List webcams attached to a running VM:
-            <screen>VBoxManage controlvm "VM name" webcam list</screen>
-            The output contains path or alias which was used in 'webcam attach' command for
-            each attached webcam.
-          </para></listitem>
-        </itemizedlist>
-      </para>
+  <sect1 id="adv-display-config">
+
+    <title>Advanced Display Configuration</title>
+
+    <sect2 id="customvesa">
+
+      <title>Custom VESA Resolutions</title>
+
+      <para>
+        Apart from the standard VESA resolutions, the VirtualBox VESA
+        BIOS allows you to add up to 16 custom video modes which will be
+        reported to the guest operating system. When using Windows
+        guests with the VirtualBox Guest Additions, a custom graphics
+        driver will be used instead of the fallback VESA solution so
+        this information does not apply.
+      </para>
+
+      <para>
+        Additional video modes can be configured for each VM using the
+        extra data facility. The extra data key is called
+        <literal>CustomVideoMode&lt;x&gt;</literal> with
+        <literal>x</literal> being a number from 1 to 16. Please note
+        that modes will be read from 1 until either the following number
+        is not defined or 16 is reached. The following example adds a
+        video mode that corresponds to the native display resolution of
+        many notebook computers:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</screen>
+
+      <para>
+        The VESA mode IDs for custom video modes start at
+        <literal>0x160</literal>. In order to use the above defined
+        custom video mode, the following command line has be supplied to
+        Linux:
+      </para>
+
+<screen>vga = 0x200 | 0x160
+vga = 864</screen>
+
+      <para>
+        For guest operating systems with VirtualBox Guest Additions, a
+        custom video mode can be set using the video mode hint feature.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Windows hosts</title>
-
-      <para>When the webcam device is detached from the host, the emulated webcam device is
-      automatically detached from the guest.</para>
+    <sect2 id="max-resolution-guests">
+
+      <title>Configuring the Maximum Resolution of Guests When Using the Graphical
+        Frontend</title>
+
+      <para>
+        When guest systems with the Guest Additions installed are
+        started using the graphical frontend, the normal VirtualBox
+        application, they will not be allowed to use screen resolutions
+        greater than the host's screen size unless the user manually
+        resizes them by dragging the window, switching to full screen or
+        seamless mode or sending a video mode hint using VBoxManage.
+        This behavior is what most users will want, but if you have
+        different needs, it is possible to change it by issuing one of
+        the following commands from the command line:
+      </para>
+
+<screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen>
+
+      <para>
+        will remove all limits on guest resolutions.
+      </para>
+
+<screen>VBoxManage setextradata global GUI/MaxGuestResolution &gt;width,height&lt;</screen>
+
+      <para>
+        manually specifies a maximum resolution.
+      </para>
+
+<screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen>
+
+      <para>
+        restores the default settings. Note that these settings apply
+        globally to all guest systems, not just to a single machine.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Mac OS X hosts</title>
-
-      <para>OS X version 10.9 or newer is required.</para>
-
-      <para>When the webcam device is detached from the host, the emulated webcam device
-      remains attached to the guest and must be manually detached using the
-      <computeroutput>VBoxManage controlvm "VM name" webcam detach ...</computeroutput> command.</para>
+  </sect1>
+
+  <sect1 id="adv-storage-config">
+
+    <title>Advanced Storage Configuration</title>
+
+    <sect2 id="rawdisk">
+
+      <title>Using a Raw Host Hard Disk From a Guest</title>
+
+      <para>
+        Starting with version 1.4, as an alternative to using virtual
+        disk images as described in <xref linkend="storage" />,
+        VirtualBox can also present either entire physical hard disks or
+        selected partitions as virtual disks to virtual machines.
+      </para>
+
+      <para>
+        With VirtualBox, this type of access is called <emphasis>raw
+        hard disk access</emphasis>. It allows a guest operating system
+        to access its virtual hard disk without going through the host
+        OS file system. The actual performance difference for image
+        files vs. raw disk varies greatly depending on the overhead of
+        the host file system, whether dynamically growing images are
+        used, and on host OS caching strategies. The caching indirectly
+        also affects other aspects such as failure behavior. For
+        example, whether the virtual disk contains all data written
+        before a host OS crash. Consult your host OS documentation for
+        details on this.
+      </para>
+
+      <warning>
+        <para>
+          Raw hard disk access is for expert users only. Incorrect use
+          or use of an outdated configuration can lead to
+          <emphasis
+          role="bold">total loss of data
+          </emphasis>on the physical disk. Most importantly,
+          <emphasis>do not</emphasis> attempt to boot the partition with
+          the currently running host operating system in a guest. This
+          will lead to severe data corruption.
+        </para>
+      </warning>
+
+      <para>
+        Raw hard disk access, both for entire disks and individual
+        partitions, is implemented as part of the VMDK image format
+        support. As a result, you will need to create a special VMDK
+        image file which defines where the data will be stored. After
+        creating such a special VMDK image, you can use it like a
+        regular virtual disk image. For example, you can use the
+        VirtualBox Manager, see <xref linkend="vdis" />, or
+        <computeroutput>VBoxManage</computeroutput> to assign the image
+        to a virtual machine.
+      </para>
+
+      <sect3 id="rawdisk-access-entire-physical-disk">
+
+        <title>Access to Entire Physical Hard Disk</title>
+
+        <para>
+          While this variant is the simplest to set up, you must be
+          aware that this will give a guest operating system direct and
+          full access to an <emphasis>entire physical disk</emphasis>.
+          If your <emphasis>host</emphasis> operating system is also
+          booted from this disk, please take special care to not access
+          the partition from the guest at all. On the positive side, the
+          physical disk can be repartitioned in arbitrary ways without
+          having to recreate the image file that gives access to the raw
+          disk.
+        </para>
+
+        <para>
+          On a Linux host, to create an image that represents an entire
+          physical hard disk which will not contain any actual data, as
+          this will all be stored on the physical disk, use the command
+
+<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
+      -rawdisk /dev/sda</screen>
+
+          This creates the image <code>/path/to/file.vmdk</code>, which
+          must be an absolute path. All data will be read and written
+          from <code>/dev/sda</code>.
+        </para>
+
+        <para>
+          On a Windows host, instead of the above device specification,
+          use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host,
+          instead of the above device specification use e.g.
+          <code>/dev/disk1</code>. Note that on OS X you can only get
+          access to an entire disk if no volume is mounted from it.
+        </para>
+
+        <para>
+          Creating the image requires read/write access for the given
+          device. Read/write access is also later needed when using the
+          image from a virtual machine. On some host platforms, such as
+          Windows Vista and later, raw disk access may be restricted and
+          not permitted by the host OS in some situations.
+        </para>
+
+        <para>
+          Just like with regular disk images, this does not
+          automatically attach the newly created image to a virtual
+          machine. This can be done as follows:
+
+<screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller"
+      --port 0 --device 0 --type hdd --medium /path/to/file.vmdk</screen>
+
+          When this is done the selected virtual machine will boot from
+          the specified physical disk.
+        </para>
+
+      </sect3>
+
+      <sect3 id="rawdisk-access-disk-partitions">
+
+        <title>Access to Individual Physical Hard Disk Partitions</title>
+
+        <para>
+          This <emphasis>raw partition support</emphasis> is quite
+          similar to the full hard disk access described above. However,
+          in this case, any partitioning information will be stored
+          inside the VMDK image. This means that you can install a
+          different boot loader in the virtual hard disk without
+          affecting the host's partitioning information. While the guest
+          will be able to <emphasis>see</emphasis> all partitions that
+          exist on the physical disk, access will be filtered in that
+          reading from partitions for which no access is allowed the
+          partitions will only yield zeroes, and all writes to them are
+          ignored.
+        </para>
+
+        <para>
+          To create a special image for raw partition support, which
+          will contain a small amount of data, on a Linux host, use the
+          command:
+        </para>
+
+<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
+      -rawdisk /dev/sda -partitions 1,5</screen>
+
+        <para>
+          The command is identical to the one for full hard disk access,
+          except for the additional
+          <computeroutput>-partitions</computeroutput> parameter. This
+          example would create the image <code>/path/to/file.vmdk</code>
+          (which, again, must be absolute), and partitions 1 and 5 of
+          <code>/dev/sda</code> would be made accessible to the guest.
+        </para>
+
+        <para>
+          VirtualBox uses the same partition numbering as your Linux
+          host. As a result, the numbers given in the above example
+          would refer to the first primary partition and the first
+          logical drive in the extended partition, respectively.
+        </para>
+
+        <para>
+          On a Windows host, instead of the above device specification,
+          use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host,
+          instead of the above device specification use
+          <code>/dev/disk1</code>, for example. Note that on OS X you
+          can only use partitions which are not mounted. Eject the
+          respective volume first. Partition numbers are the same on
+          Linux, Windows, and Mac OS X hosts.
+        </para>
+
+        <para>
+          The numbers for the list of partitions can be taken from the
+          output of
+
+<screen>VBoxManage internalcommands listpartitions -rawdisk /dev/sda</screen>
+
+          The output lists the partition types and sizes to give the
+          user enough information to identify the partitions necessary
+          for the guest.
+        </para>
+
+        <para>
+          Images which give access to individual partitions are specific
+          to a particular host disk setup. You cannot transfer these
+          images to another host. Also, whenever the host partitioning
+          changes, the image <emphasis>must be recreated</emphasis>.
+        </para>
+
+        <para>
+          Creating the image requires read/write access for the given
+          device. Read/write access is also later needed when using the
+          image from a virtual machine. If this is not feasible, there
+          is a special variant for raw partition access, currently only
+          available on Linux hosts, that avoids having to give the
+          current user access to the entire disk. To set up such an
+          image, use:
+        </para>
+
+<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
+      -rawdisk /dev/sda -partitions 1,5 -relative</screen>
+
+        <para>
+          When used from a virtual machine, the image will then refer
+          not to the entire disk, but only to the individual partitions.
+          In this example, <code>/dev/sda1</code> and
+          <code>/dev/sda5</code>. As a consequence, read/write access is
+          only required for the affected partitions, not for the entire
+          disk. During creation however, read-only access to the entire
+          disk is required to obtain the partitioning information.
+        </para>
+
+        <para>
+          In some configurations it may be necessary to change the MBR
+          code of the created image. For example, to replace the Linux
+          boot loader that is used on the host by another boot loader.
+          This allows for example the guest to boot directly to Windows,
+          while the host boots Linux from the "same" disk. For this
+          purpose the <computeroutput>-mbr</computeroutput> parameter is
+          provided. It specifies a file name from which to take the MBR
+          code. The partition table is not modified at all, so a MBR
+          file from a system with totally different partitioning can be
+          used. An example of this is:
+        </para>
+
+<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
+      -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr</screen>
+
+        <para>
+          The modified MBR will be stored inside the image, not on the
+          host disk.
+        </para>
+
+        <para>
+          The created image can be attached to a storage controller in a
+          VM configuration as usual.
+        </para>
+
+      </sect3>
+
     </sect2>
 
-    <sect2>
-      <title>Linux and Solaris hosts</title>
-
-      <para>When the webcam is detached from the host the emulated webcam device is
-      automatically detached from the guest only if the webcam is streaming video.
-      If the emulated webcam is inactive it should be manually detached using the
-      <computeroutput>VBoxManage controlvm "VM name" webcam detach ...</computeroutput> command.</para>
-
-      <para>Aliases <computeroutput>.0</computeroutput> and <computeroutput>.1</computeroutput> are mapped
-      to <computeroutput>/dev/video0</computeroutput>, alias <computeroutput>.2</computeroutput> is mapped
-      to <computeroutput>/dev/video1</computeroutput> and so forth.</para>
-    </sect2>
-  </sect1>
-
-  <sect1>
-    <title>Advanced display configuration</title>
-
-    <sect2 id="customvesa">
-      <title>Custom VESA resolutions</title>
-
-      <para>Apart from the standard VESA resolutions, the VirtualBox VESA BIOS
-      allows you to add up to 16 custom video modes which will be reported to
-      the guest operating system. When using Windows guests with the
-      VirtualBox Guest Additions, a custom graphics driver will be used
-      instead of the fallback VESA solution so this information does not
-      apply.</para>
-
-      <para>Additional video modes can be configured for each VM using the
-      extra data facility. The extra data key is called
-      <literal>CustomVideoMode&lt;x&gt;</literal> with <literal>x</literal>
-      being a number from 1 to 16. Please note that modes will be read from 1
-      until either the following number is not defined or 16 is reached. The
-      following example adds a video mode that corresponds to the native
-      display resolution of many notebook computers:</para>
-
-      <screen>VBoxManage setextradata "VM name" "CustomVideoMode1" "1400x1050x16"</screen>
-
-      <para>The VESA mode IDs for custom video modes start at
-      <literal>0x160</literal>. In order to use the above defined custom video
-      mode, the following command line has be supplied to Linux:</para>
-
-      <screen>vga = 0x200 | 0x160
-vga = 864</screen>
-
-      <para>For guest operating systems with VirtualBox Guest Additions, a
-      custom video mode can be set using the video mode hint feature.</para>
-    </sect2>
-
-    <sect2>
-      <title>Configuring the maximum resolution of guests when using the
-      graphical frontend</title>
-
-      <para>When guest systems with the Guest Additions installed are started
-      using the graphical frontend (the normal VirtualBox application), they
-      will not be allowed to use screen resolutions greater than the host's
-      screen size unless the user manually resizes them by dragging the
-      window, switching to full screen or seamless mode or sending a video mode
-      hint using VBoxManage. This behavior is what most users will want, but
-      if you have different needs, it is possible to change it by issuing one
-      of the following commands from the command line:</para>
-
-      <screen>VBoxManage setextradata global GUI/MaxGuestResolution any</screen>
-
-      <para>will remove all limits on guest resolutions.</para>
-
-      <screen>VBoxManage setextradata global GUI/MaxGuestResolution &gt;width,height&lt;</screen>
-
-      <para>manually specifies a maximum resolution.</para>
-
-      <screen>VBoxManage setextradata global GUI/MaxGuestResolution auto</screen>
-
-      <para>restores the default settings. Note that these settings apply
-      globally to all guest systems, not just to a single machine.</para>
-    </sect2>
-  </sect1>
-
-  <sect1>
-    <title>Advanced storage configuration</title>
-
-    <sect2 id="rawdisk">
-      <title>Using a raw host hard disk from a guest</title>
-
-      <para>Starting with version 1.4, as an alternative to using virtual disk
-      images (as described in detail in <xref linkend="storage" />),
-      VirtualBox can also present either entire physical hard disks or
-      selected partitions thereof as virtual disks to virtual machines.</para>
-
-      <para>With VirtualBox, this type of access is called "raw hard disk
-      access"; it allows a guest operating system to access its virtual hard
-      disk without going through the host OS file system. The actual
-      performance difference for image files vs. raw disk varies greatly
-      depending on the overhead of the host file system, whether dynamically
-      growing images are used, and on host OS caching strategies. The caching
-      indirectly also affects other aspects such as failure behavior, i.e.
-      whether the virtual disk contains all data written before a host OS
-      crash. Consult your host OS documentation for details on this.</para>
-
-      <para><warning>
-          <para>Raw hard disk access is for expert users only. Incorrect use
-          or use of an outdated configuration can lead to <emphasis
-          role="bold">total loss of data </emphasis>on the physical disk. Most
-          importantly, <emphasis>do not</emphasis> attempt to boot the
-          partition with the currently running host operating system in a
-          guest. This will lead to severe data corruption.</para>
-        </warning></para>
-
-      <para>Raw hard disk access -- both for entire disks and individual
-      partitions -- is implemented as part of the VMDK image format support.
-      As a result, you will need to create a special VMDK image file which
-      defines where the data will be stored. After creating such a special
-      VMDK image, you can use it like a regular virtual disk image. For
-      example, you can use the VirtualBox Manager (<xref linkend="vdis" />)
-      or <computeroutput>VBoxManage</computeroutput> to assign the image to a
-      virtual machine.</para>
-
-      <sect3>
-        <title>Access to entire physical hard disk</title>
-
-        <para>While this variant is the simplest to set up, you must be aware
-        that this will give a guest operating system direct and full access to
-        an <emphasis>entire physical disk</emphasis>. If your
-        <emphasis>host</emphasis> operating system is also booted from this
-        disk, please take special care to not access the partition from the
-        guest at all. On the positive side, the physical disk can be
-        repartitioned in arbitrary ways without having to recreate the image
-        file that gives access to the raw disk.</para>
-
-        <para>To create an image that represents an entire physical hard disk
-        (which will not contain any actual data, as this will all be stored on
-        the physical disk), on a Linux host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
-      -rawdisk /dev/sda</screen>This creates the image
-        <code>/path/to/file.vmdk</code> (must be absolute), and all data will
-        be read and written from <code>/dev/sda</code>.</para>
-
-        <para>On a Windows host, instead of the above device specification,
-        use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead
-        of the above device specification use e.g. <code>/dev/disk1</code>.
-        Note that on OS X you can only get access to an entire disk if no
-        volume is mounted from it.</para>
-
-        <para>Creating the image requires read/write access for the given
-        device. Read/write access is also later needed when using the image
-        from a virtual machine. On some host platforms (e.g. Windows Vista
-        and later), raw disk access may be restricted and not permitted by
-        the host OS in some situations.</para>
-
-        <para>Just like with regular disk images, this does not automatically
-        attach the newly created image to a virtual machine. This can be done
-        with e.g. <screen>VBoxManage storageattach WindowsXP --storagectl "IDE Controller"
-      --port 0 --device 0 --type hdd --medium /path/to/file.vmdk</screen>When
-        this is done the selected virtual machine will boot from the specified
-        physical disk.</para>
-      </sect3>
-
-      <sect3>
-        <title>Access to individual physical hard disk partitions</title>
-
-        <para>This "raw partition support" is quite similar to the "full hard
-        disk" access described above. However, in this case, any partitioning
-        information will be stored inside the VMDK image, so you can e.g.
-        install a different boot loader in the virtual hard disk without
-        affecting the host's partitioning information. While the guest will be
-        able to <emphasis>see</emphasis> all partitions that exist on the
-        physical disk, access will be filtered in that reading from partitions
-        for which no access is allowed the partitions will only yield zeroes,
-        and all writes to them are ignored.</para>
-
-        <para>To create a special image for raw partition support (which will
-        contain a small amount of data, as already mentioned), on a Linux
-        host, use the command<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
-      -rawdisk /dev/sda -partitions 1,5</screen></para>
-
-        <para>As you can see, the command is identical to the one for "full
-        hard disk" access, except for the additional
-        <computeroutput>-partitions</computeroutput> parameter. This example
-        would create the image <code>/path/to/file.vmdk</code> (which, again,
-        must be absolute), and partitions 1 and 5 of <code>/dev/sda</code>
-        would be made accessible to the guest.</para>
-
-        <para>VirtualBox uses the same partition numbering as your Linux host.
-        As a result, the numbers given in the above example would refer to the
-        first primary partition and the first logical drive in the extended
-        partition, respectively.</para>
-
-        <para>On a Windows host, instead of the above device specification,
-        use e.g. <code>\\.\PhysicalDrive0</code>. On a Mac OS X host, instead
-        of the above device specification use e.g. <code>/dev/disk1</code>.
-        Note that on OS X you can only use partitions which are not mounted
-        (eject the respective volume first). Partition numbers are the same on
-        Linux, Windows and Mac OS X hosts.</para>
-
-        <para>The numbers for the list of partitions can be taken from the
-        output of<screen>VBoxManage internalcommands listpartitions -rawdisk /dev/sda</screen>The
-        output lists the partition types and sizes to give the user enough
-        information to identify the partitions necessary for the guest.</para>
-
-        <para>Images which give access to individual partitions are specific
-        to a particular host disk setup. You cannot transfer these images to
-        another host; also, whenever the host partitioning changes, the image
-        <emphasis>must be recreated</emphasis>.</para>
-
-        <para>Creating the image requires read/write access for the given
-        device. Read/write access is also later needed when using the image
-        from a virtual machine. If this is not feasible, there is a special
-        variant for raw partition access (currently only available on Linux
-        hosts) that avoids having to give the current user access to the
-        entire disk. To set up such an image, use<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
-      -rawdisk /dev/sda -partitions 1,5 -relative</screen>When used from a
-        virtual machine, the image will then refer not to the entire disk, but
-        only to the individual partitions (in the example
-        <code>/dev/sda1</code> and <code>/dev/sda5</code>). As a consequence,
-        read/write access is only required for the affected partitions, not
-        for the entire disk. During creation however, read-only access to the
-        entire disk is required to obtain the partitioning information.</para>
-
-        <para>In some configurations it may be necessary to change the MBR
-        code of the created image, e.g. to replace the Linux boot loader that
-        is used on the host by another boot loader. This allows e.g. the guest
-        to boot directly to Windows, while the host boots Linux from the
-        "same" disk. For this purpose the
-        <computeroutput>-mbr</computeroutput> parameter is provided. It
-        specifies a file name from which to take the MBR code. The partition
-        table is not modified at all, so a MBR file from a system with totally
-        different partitioning can be used. An example of this is<screen>VBoxManage internalcommands createrawvmdk -filename /path/to/file.vmdk
-      -rawdisk /dev/sda -partitions 1,5 -mbr winxp.mbr</screen>The modified
-        MBR will be stored inside the image, not on the host disk.</para>
-
-        <para>The created image can be attached to a storage controller in a
-        VM configuration as usual.</para>
-      </sect3>
-    </sect2>
-
     <sect2 id="changevpd">
-      <title>Configuring the hard disk vendor product data (VPD)</title>
-
-      <para>VirtualBox reports vendor product data for its virtual hard disks
-      which consist of hard disk serial number, firmware revision and model
-      number. These can be changed using the following commands:</para>
-
-      <screen>VBoxManage setextradata "VM name"
+
+      <title>Configuring the Hard Disk Vendor Product Data (VPD)</title>
+
+      <para>
+        VirtualBox reports vendor product data for its virtual hard
+        disks which consist of hard disk serial number, firmware
+        revision and model number. These can be changed using the
+        following commands:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial"
 VBoxManage setextradata "VM name"
@@ -1193,14 +1812,18 @@
       "VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"</screen>
 
-      <para>The serial number is a 20 byte alphanumeric string, the firmware
-      revision an 8 byte alphanumeric string and the model number a 40 byte
-      alphanumeric string. Instead of "Port0" (referring to the first port),
-      specify the desired SATA hard disk port.</para>
-
-      <para>The above commands apply to virtual machines with an AHCI (SATA)
-      controller. The commands for virtual machines with an IDE controller
-      are:</para>
-
-      <screen>VBoxManage setextradata "VM name"
+      <para>
+        The serial number is a 20 byte alphanumeric string, the firmware
+        revision an 8 byte alphanumeric string and the model number a 40
+        byte alphanumeric string. Instead of Port0, referring to the
+        first port, specify the desired SATA hard disk port.
+      </para>
+
+      <para>
+        The above commands apply to virtual machines with an AHCI (SATA)
+        controller. The commands for virtual machines with an IDE
+        controller are:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/SerialNumber" "serial"
 VBoxManage setextradata "VM name"
@@ -1209,14 +1832,18 @@
       "VBoxInternal/Devices/piix3ide/0/Config/PrimaryMaster/ModelNumber" "model"</screen>
 
-      <para>For hard disks it's also possible to mark the
-      drive as having a non-rotational medium with:</para>
-
-      <screen>VBoxManage setextradata "VM name"
+      <para>
+        For hard disks it is also possible to mark the drive as having a
+        non-rotational medium with:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/ahci/0/Config/Port0/NonRotational" "1"</screen>
 
-      <para>Additional three parameters are needed for CD/DVD drives to report
-      the vendor product data:</para>
-
-      <screen>VBoxManage setextradata "VM name"
+      <para>
+        Additional three parameters are needed for CD/DVD drives to
+        report the vendor product data:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIVendorId" "vendor"
 VBoxManage setextradata "VM name"
@@ -1225,26 +1852,38 @@
       "VBoxInternal/Devices/ahci/0/Config/Port0/ATAPIRevision" "revision"</screen>
 
-      <para>The vendor id is an 8 byte alphanumeric string, the product id an
-      16 byte alphanumeric string and the revision a 4 byte alphanumeric
-      string. Instead of "Port0" (referring to the first port), specify the
-      desired SATA hard disk port.</para>
+      <para>
+        The vendor id is an 8 byte alphanumeric string, the product id
+        an 16 byte alphanumeric string and the revision a 4 byte
+        alphanumeric string. Instead of Port0, referring to the first
+        port, specify the desired SATA hard disk port.
+      </para>
+
     </sect2>
 
     <sect2 id="iscsi-intnet">
-      <title>Access iSCSI targets via Internal Networking</title>
-
-      <para>As an experimental feature, VirtualBox allows for accessing an
-      iSCSI target running in a virtual machine which is configured for using
-      Internal Networking mode. Please see <xref linkend="storage-iscsi" />;
-      <xref linkend="network_internal" />; and <xref
-      linkend="vboxmanage-storageattach" /> for additional information.</para>
-
-      <para>The IP stack accessing Internal Networking must be configured in
-      the virtual machine which accesses the iSCSI target. A free static IP
-      and a MAC address not used by other virtual machines must be chosen. In
-      the example below, adapt the name of the virtual machine, the MAC
-      address, the IP configuration and the Internal Networking name
-      ("MyIntNet") according to your needs. The following eight commands must
-      first be issued:<screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Trusted 1
+
+      <title>Access iSCSI Targets via Internal Networking</title>
+
+      <para>
+        As an experimental feature, VirtualBox allows for accessing an
+        iSCSI target running in a virtual machine which is configured
+        for using Internal Networking mode. See
+        <xref linkend="storage-iscsi" />,
+        <xref linkend="network_internal" />, and
+        <xref
+      linkend="vboxmanage-storageattach" />.
+      </para>
+
+      <para>
+        The IP stack accessing Internal Networking must be configured in
+        the virtual machine which accesses the iSCSI target. A free
+        static IP and a MAC address not used by other virtual machines
+        must be chosen. In the example below, adapt the name of the
+        virtual machine, the MAC address, the IP configuration, and the
+        Internal Networking name (MyIntNet) according to your needs. The
+        following eight commands must first be issued:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Trusted 1
 VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/MAC 08:00:27:01:02:0f
 VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/Config/IP 10.0.9.1
@@ -1253,46 +1892,66 @@
 VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/Network MyIntNet
 VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/TrunkType 2
-VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen></para>
-
-      <para>Finally the iSCSI disk must be attached with the
-      <computeroutput>--intnet</computeroutput> option to tell the iSCSI
-      initiator to use internal networking:<screen>VBoxManage storageattach ... --medium iscsi
-         --server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet</screen></para>
-
-      <para>Compared to a "regular" iSCSI setup, IP address of the target
-      <emphasis>must</emphasis> be specified as a numeric IP address, as there
-      is no DNS resolver for internal networking.</para>
-
-      <para>The virtual machine with the iSCSI target should be started before
-      the VM using it is powered on. If a virtual machine using an iSCSI disk
-      is started without having the iSCSI target powered up, it can take up to
-      200 seconds to detect this situation. The VM will fail to power
-      up.</para>
+VBoxManage setextradata "VM name" VBoxInternal/Devices/IntNetIP/0/LUN#0/Config/IsService 1</screen>
+
+      <para>
+        Finally the iSCSI disk must be attached with the
+        <computeroutput>--intnet</computeroutput> option to tell the
+        iSCSI initiator to use internal networking:
+
+<screen>VBoxManage storageattach ... --medium iscsi
+         --server 10.0.9.30 --target iqn.2008-12.com.sun:sampletarget --intnet</screen>
+      </para>
+
+      <para>
+        Compared to a regular iSCSI setup, the IP address of the target
+        <emphasis>must</emphasis> be specified as a numeric IP address,
+        as there is no DNS resolver for internal networking.
+      </para>
+
+      <para>
+        The virtual machine with the iSCSI target should be started
+        before the VM using it is powered on. If a virtual machine using
+        an iSCSI disk is started without having the iSCSI target powered
+        up, it can take up to 200 seconds to detect this situation. The
+        VM will fail to power up.
+      </para>
+
     </sect2>
+
   </sect1>
 
-  <sect1>
-    <title>Legacy commands for using serial ports</title>
-
-    <para>Starting with version 1.4, VirtualBox provided support for virtual
-    serial ports, which, at the time, was rather complicated to set up with a
-    sequence of <computeroutput>VBoxManage setextradata</computeroutput>
-    statements. Since version 1.5, that way of setting up serial ports is no
-    longer necessary and <emphasis>deprecated.</emphasis> To set up virtual
-    serial ports, use the methods now described in <xref
-    linkend="serialports" />.<note>
-        <para>For backwards compatibility, the old
+  <sect1 id="serialports-legacy-cmds">
+
+    <title>Legacy Commands for Using Serial Ports</title>
+
+    <para>
+      Starting with version 1.4, VirtualBox provided support for virtual
+      serial ports, which, at the time, was rather complicated to set up
+      with a sequence of <computeroutput>VBoxManage
+      setextradata</computeroutput> statements. Since version 1.5, that
+      way of setting up serial ports is no longer necessary and
+      <emphasis>deprecated.</emphasis> To set up virtual serial ports,
+      use the methods described in <xref
+    linkend="serialports" />.
+    </para>
+
+    <note>
+      <para>
+        For backwards compatibility, the old
         <computeroutput>setextradata</computeroutput> statements, whose
-        description is retained below from the old version of the manual, take
-        <emphasis>precedence</emphasis> over the new way of configuring serial
-        ports. As a result, if configuring serial ports the new way doesn't
-        work, make sure the VM in question does not have old configuration
-        data such as below still active.</para>
-      </note></para>
-
-    <para>The old sequence of configuring a serial port used the following 6
-    commands:</para>
-
-    <screen>VBoxManage setextradata "VM name"
+        description is retained below from the old version of the
+        manual, take <emphasis>precedence</emphasis> over the new way of
+        configuring serial ports. As a result, if configuring serial
+        ports the new way does not work, make sure the VM in question
+        does not have old configuration data such as below still active.
+      </para>
+    </note>
+
+    <para>
+      The old sequence of configuring a serial port used the following
+      commands:
+    </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/serial/0/Config/IRQ" 4
 VBoxManage setextradata "VM name"
@@ -1307,128 +1966,191 @@
       "VBoxInternal/Devices/serial/0/LUN#0/AttachedDriver/Config/IsServer" 1</screen>
 
-    <para>This sets up a serial port in the guest with the default settings
-    for COM1 (IRQ 4, I/O address 0x3f8) and the
-    <computeroutput>Location</computeroutput> setting assumes that this
-    configuration is used on a Windows host, because the Windows named pipe
-    syntax is used. Keep in mind that on Windows hosts a named pipe must
-    always start with <computeroutput>\\.\pipe\</computeroutput>. On Linux the
-    same configuration settings apply, except that the path name for the
-    <computeroutput>Location</computeroutput> can be chosen more freely. Local
-    domain sockets can be placed anywhere, provided the user running
-    VirtualBox has the permission to create a new file in the directory. The
-    final command above defines that VirtualBox acts as a server, i.e. it
-    creates the named pipe itself instead of connecting to an already existing
-    one.</para>
+    <para>
+      This sets up a serial port in the guest with the default settings
+      for COM1 (IRQ 4, I/O address 0x3f8) and the
+      <computeroutput>Location</computeroutput> setting assumes that
+      this configuration is used on a Windows host, because the Windows
+      named pipe syntax is used. Keep in mind that on Windows hosts a
+      named pipe must always start with
+      <computeroutput>\\.\pipe\</computeroutput>. On Linux the same
+      configuration settings apply, except that the path name for the
+      <computeroutput>Location</computeroutput> can be chosen more
+      freely. Local domain sockets can be placed anywhere, provided the
+      user running VirtualBox has the permission to create a new file in
+      the directory. The final command above defines that VirtualBox
+      acts as a server. It creates the named pipe itself instead of
+      connecting to an already existing one.
+    </para>
+
   </sect1>
 
   <sect1 id="changenat">
-    <title>Fine-tuning the VirtualBox NAT engine</title>
-
-    <sect2>
-      <title>Configuring the address of a NAT network interface</title>
-
-      <para>In NAT mode, the guest network interface is assigned to the IPv4
-      range <computeroutput>10.0.x.0/24</computeroutput> by default where
-      <computeroutput>x</computeroutput> corresponds to the instance of the
-      NAT interface +2. So <computeroutput>x</computeroutput> is 2 when there
-      is only one NAT instance active. In that case the guest is assigned to
-      the address <computeroutput>10.0.2.15</computeroutput>, the gateway is
-      set to <computeroutput>10.0.2.2</computeroutput> and the name server can
-      be found at <computeroutput>10.0.2.3</computeroutput>.</para>
-
-      <para>If, for any reason, the NAT network needs to be changed, this can
-      be achieved with the following command:</para>
-
-      <screen>VBoxManage modifyvm "VM name" --natnet1 "192.168/16"</screen>
-
-      <para>This command would reserve the network addresses from
-      <computeroutput>192.168.0.0</computeroutput> to
-      <computeroutput>192.168.254.254</computeroutput> for the first NAT
-      network instance of "VM name". The guest IP would be assigned to
-      <computeroutput>192.168.0.15</computeroutput> and the default gateway
-      could be found at <computeroutput>192.168.0.2</computeroutput>.</para>
+
+    <title>Fine Tuning the VirtualBox NAT Engine</title>
+
+    <sect2 id="nat-address-config">
+
+      <title>Configuring the Address of a NAT Network Interface</title>
+
+      <para>
+        In NAT mode, the guest network interface is assigned to the IPv4
+        range <computeroutput>10.0.x.0/24</computeroutput> by default
+        where <computeroutput>x</computeroutput> corresponds to the
+        instance of the NAT interface +2. So
+        <computeroutput>x</computeroutput> is 2 when there is only one
+        NAT instance active. In that case the guest is assigned to the
+        address <computeroutput>10.0.2.15</computeroutput>, the gateway
+        is set to <computeroutput>10.0.2.2</computeroutput> and the name
+        server can be found at
+        <computeroutput>10.0.2.3</computeroutput>.
+      </para>
+
+      <para>
+        If the NAT network needs to be changed, use the following
+        command:
+      </para>
+
+<screen>VBoxManage modifyvm "VM name" --natnet1 "192.168/16"</screen>
+
+      <para>
+        This command would reserve the network addresses from
+        <computeroutput>192.168.0.0</computeroutput> to
+        <computeroutput>192.168.254.254</computeroutput> for the first
+        NAT network instance of "VM name". The guest IP would be
+        assigned to <computeroutput>192.168.0.15</computeroutput> and
+        the default gateway could be found at
+        <computeroutput>192.168.0.2</computeroutput>.
+      </para>
+
     </sect2>
 
     <sect2 id="nat-adv-tftp">
-      <title>Configuring the boot server (next server) of a NAT network
-      interface</title>
-
-      <para>For network booting in NAT mode, by default VirtualBox uses a
-      built-in TFTP server at the IP address 10.0.2.4. This default behavior
-      should work fine for typical remote-booting scenarios. However, it is
-      possible to change the boot server IP and the location of the boot image
-      with the following commands: <screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2
-VBoxManage modifyvm "VM name" --nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen></para>
+
+      <title>Configuring the Boot Server (Next Server) of a NAT Network Interface</title>
+
+      <para>
+        For network booting in NAT mode, by default VirtualBox uses a
+        built-in TFTP server at the IP address 10.0.2.4. This default
+        behavior should work fine for typical remote-booting scenarios.
+        However, it is possible to change the boot server IP and the
+        location of the boot image with the following commands:
+
+<screen>VBoxManage modifyvm "VM name" --nattftpserver1 10.0.2.2
+VBoxManage modifyvm "VM name" --nattftpfile1 /srv/tftp/boot/MyPXEBoot.pxe</screen>
+      </para>
+
     </sect2>
 
     <sect2 id="nat-adv-settings">
-      <title>Tuning TCP/IP buffers for NAT</title>
-
-      <para>The VirtualBox NAT stack performance is often determined by its
-      interaction with the host's TCP/IP stack and the size of several buffers
-      (<computeroutput>SO_RCVBUF</computeroutput> and
-      <computeroutput>SO_SNDBUF</computeroutput>). For certain setups users
-      might want to adjust the buffer size for a better performance. This can
-      by achieved using the following commands (values are in kilobytes and
-      can range from 8 to 1024): <screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</screen>
-      This example illustrates tuning the NAT settings. The first parameter is
-      the MTU, then the size of the socket's send buffer and the size of the
-      socket's receive buffer, the initial size of the TCP send window, and
-      lastly the initial size of the TCP receive window. Note that specifying
-      zero means fallback to the default value.</para>
-
-      <para>Each of these buffers has a default size of 64KB and default MTU
-      is 1500.</para>
+
+      <title>Tuning TCP/IP Buffers for NAT</title>
+
+      <para>
+        The VirtualBox NAT stack performance is often determined by its
+        interaction with the host's TCP/IP stack and the size of several
+        buffers (<computeroutput>SO_RCVBUF</computeroutput> and
+        <computeroutput>SO_SNDBUF</computeroutput>). For certain setups
+        users might want to adjust the buffer size for a better
+        performance. This can by achieved using the following commands,
+        where values are in kilobytes and can range from 8 to 1024:
+
+<screen>VBoxManage modifyvm "VM name" --natsettings1 16000,128,128,0,0</screen>
+
+        This example illustrates tuning the NAT settings. The first
+        parameter is the MTU, then the size of the socket's send buffer
+        and the size of the socket's receive buffer, the initial size of
+        the TCP send window, and lastly the initial size of the TCP
+        receive window. Note that specifying zero means fallback to the
+        default value.
+      </para>
+
+      <para>
+        Each of these buffers has a default size of 64KB and default MTU
+        is 1500.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Binding NAT sockets to a specific interface</title>
-
-      <para>By default, VirtualBox's NAT engine will route TCP/IP packets
-      through the default interface assigned by the host's TCP/IP stack. (The
-      technical reason for this is that the NAT engine uses sockets for
-      communication.) If, for some reason, you want to change this behavior,
-      you can tell the NAT engine to bind to a particular IP address instead.
-      Use the following command: <screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</screen></para>
-
-      <para>After this, all outgoing traffic will be sent through the
-      interface with the IP address 10.45.0.2. Please make sure that this
-      interface is up and running prior to this assignment.</para>
+    <sect2 id="nat-bind-sockets">
+
+      <title>Binding NAT Sockets to a Specific Interface</title>
+
+      <para>
+        By default, VirtualBox's NAT engine will route TCP/IP packets
+        through the default interface assigned by the host's TCP/IP
+        stack. The technical reason for this is that the NAT engine uses
+        sockets for communication. If you want to change this behavior,
+        you can tell the NAT engine to bind to a particular IP address
+        instead. Use the following command:
+
+<screen>VBoxManage modifyvm "VM name" --natbindip1 "10.45.0.2"</screen>
+      </para>
+
+      <para>
+        After this, all outgoing traffic will be sent through the
+        interface with the IP address 10.45.0.2. Please make sure that
+        this interface is up and running prior to this assignment.
+      </para>
+
     </sect2>
 
     <sect2 id="nat-adv-dns">
-      <title>Enabling DNS proxy in NAT mode</title>
-
-      <para>The NAT engine by default offers the same DNS servers to the guest
-      that are configured on the host. In some scenarios, it can be desirable
-      to hide the DNS server IPs from the guest, for example when this
-      information can change on the host due to expiring DHCP leases. In this
-      case, you can tell the NAT engine to act as DNS proxy using the
-      following command: <screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen></para>
+
+      <title>Enabling DNS Proxy in NAT Mode</title>
+
+      <para>
+        The NAT engine by default offers the same DNS servers to the
+        guest that are configured on the host. In some scenarios, it can
+        be desirable to hide the DNS server IPs from the guest, for
+        example when this information can change on the host due to
+        expiring DHCP leases. In this case, you can tell the NAT engine
+        to act as DNS proxy using the following command:
+      </para>
+
+<screen>VBoxManage modifyvm "VM name" --natdnsproxy1 on</screen>
+
     </sect2>
 
     <sect2 id="nat_host_resolver_proxy">
-      <title>Using the host's resolver as a DNS proxy in NAT mode</title>
-
-      <para>For resolving network names, the DHCP server of the NAT engine
-      offers a list of registered DNS servers of the host. If for some reason
-      you need to hide this DNS server list and use the host's resolver
-      settings, thereby forcing the VirtualBox NAT engine to intercept DNS
-      requests and forward them to host's resolver, use the following command:
-      <screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen>
-      Note that this setting is similar to the DNS proxy mode, however whereas
-      the proxy mode just forwards DNS requests to the appropriate servers,
-      the resolver mode will interpret the DNS requests and use the host's DNS
-      API to query the information and return it to the guest.</para>
-
-        <sect3 id="nat_host_resolver_name_intercepting">
-          <title>User-defined host name resolving</title>
-          <para>In some cases it might be useful to intercept the name resolving mechanism,
-            providing a user-defined IP address on a particular DNS request. The intercepting
-            mechanism allows the user to map not only a single host but domains and even more
-            complex naming conventions if required.</para>
-            <para>
-              The following command sets a rule for mapping a name to a specified IP:</para>
-            <screen>VBoxManage setextradata "VM name" \
+
+      <title>Using the Host's Resolver as a DNS Proxy in NAT Mode</title>
+
+      <para>
+        For resolving network names, the DHCP server of the NAT engine
+        offers a list of registered DNS servers of the host. If for some
+        reason you need to hide this DNS server list and use the host's
+        resolver settings, thereby forcing the VirtualBox NAT engine to
+        intercept DNS requests and forward them to host's resolver, use
+        the following command:
+      </para>
+
+<screen>VBoxManage modifyvm "VM name" --natdnshostresolver1 on</screen>
+
+      <para>
+        Note that this setting is similar to the DNS proxy mode, however
+        whereas the proxy mode just forwards DNS requests to the
+        appropriate servers, the resolver mode will interpret the DNS
+        requests and use the host's DNS API to query the information and
+        return it to the guest.
+      </para>
+
+      <sect3 id="nat_host_resolver_name_intercepting">
+
+        <title>User-Defined Host Name Resolving</title>
+
+        <para>
+          In some cases it might be useful to intercept the name
+          resolving mechanism, providing a user-defined IP address on a
+          particular DNS request. The intercepting mechanism allows the
+          user to map not only a single host but domains and even more
+          complex naming conventions if required.
+        </para>
+
+        <para>
+          The following command sets a rule for mapping a name to a
+          specified IP:
+        </para>
+
+<screen>VBoxManage setextradata "VM name" \
       "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
       &lt;unique rule name of interception rule&gt;/HostIP" &lt;IPv4&gt;
@@ -1436,6 +2158,11 @@
       "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
       &lt;unique rule name&gt;/HostName" &lt;name of host&gt;</screen>
-    <para>The following command sets a rule for mapping a pattern name to a specified IP:</para>
-            <screen>VBoxManage setextradata "VM name" \
+
+        <para>
+          The following command sets a rule for mapping a pattern name
+          to a specified IP:
+        </para>
+
+<screen>VBoxManage setextradata "VM name" \
       "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
       &lt;unique rule name&gt;/HostIP" &lt;IPv4&gt;
@@ -1443,8 +2170,17 @@
       "VBoxInternal/Devices/{pcnet,e1000}/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
       &lt;unique rule name&gt;/HostNamePattern" &lt;hostpattern&gt;</screen>
-    <para>The host pattern may include <computeroutput>"|", "?" and "*"</computeroutput>.</para>
-    <para>This example demonstrates how to instruct the host-resolver mechanism to resolve
-      all domain and probably some mirrors of www.blocked-site.info site with IP 127.0.0.1:</para>
-    <screen>VBoxManage setextradata "VM name" \
+
+        <para>
+          The host pattern may include <computeroutput>"|", "?" and
+          "*"</computeroutput>.
+        </para>
+
+        <para>
+          This example demonstrates how to instruct the host-resolver
+          mechanism to resolve all domain and probably some mirrors of
+          www.blocked-site.info site with IP 127.0.0.1:
+        </para>
+
+<screen>VBoxManage setextradata "VM name" \
       "VBoxInternal/Devices/e1000/0/LUN#0/AttachedDriver/Config/HostResolverMappings/ \
       all_blocked_site/HostIP" 127.0.0.1
@@ -1453,39 +2189,62 @@
       all_blocked_site/HostNamePattern" "*.blocked-site.*|*.fb.org"</screen>
 
-    <para>The host resolver mechanism should be enabled to use user-defined
-      mapping rules, otherwise they don't have any effect.</para>
-        </sect3>
+        <para>
+          The host resolver mechanism should be enabled to use
+          user-defined mapping rules, otherwise they do not have any
+          effect.
+        </para>
+
+      </sect3>
+
     </sect2>
 
     <sect2 id="nat-adv-alias">
-      <title>Configuring aliasing of the NAT engine</title>
-
-      <para>By default, the NAT core uses aliasing and uses random ports when
-      generating an alias for a connection. This works well for the most
-      protocols like SSH, FTP and so on. Though some protocols might need a
-      more transparent behavior or may depend on the real port number the
-      packet was sent from. It is possible to change the NAT mode via the
-      VBoxManage frontend with the following commands: <screen>VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly</screen>
-      and <screen>VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen>
-      The first example disables aliasing and switches NAT into transparent
-      mode, the second example enforces preserving of port values. These modes
-      can be combined if necessary.</para>
+
+      <title>Configuring Aliasing of the NAT Engine</title>
+
+      <para>
+        By default, the NAT core uses aliasing and uses random ports
+        when generating an alias for a connection. This works well for
+        the most protocols like SSH, FTP and so on. Though some
+        protocols might need a more transparent behavior or may depend
+        on the real port number the packet was sent from. It is possible
+        to change the NAT mode via the VBoxManage frontend with the
+        following commands:
+
+<screen>VBoxManage modifyvm "VM name" --nataliasmode1 proxyonly</screen>
+
+        and
+
+<screen>VBoxManage modifyvm "Linux Guest" --nataliasmode1 sameports</screen>
+
+        The first example disables aliasing and switches NAT into
+        transparent mode, the second example enforces preserving of port
+        values. These modes can be combined if necessary.
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="changedmi">
-    <title>Configuring the BIOS DMI information</title>
-
-    <para>The DMI data VirtualBox provides to guests can be changed for a
-    specific VM. Use the following commands to configure the DMI BIOS
-    information. In case your VM is configured to use EFI firmware you need to
-    replace <code>pcbios</code> by <code>efi</code> in the keys.</para>
-
-    <glosslist>
-      <glossentry>
-        <glossterm>DMI BIOS information</glossterm>
-        <glossdef>
-          <para>(type 0)</para>
-          <screen>VBoxManage setextradata "VM name"
+
+    <title>Configuring the BIOS DMI Information</title>
+
+    <para>
+      The DMI data that VirtualBox provides to guests can be changed for
+      a specific VM. Use the following commands to configure the DMI
+      BIOS information. In case your VM is configured to use EFI
+      firmware you need to replace <code>pcbios</code> by
+      <code>efi</code> in the keys.
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          DMI BIOS information (type 0)
+        </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSVendor"        "BIOS Vendor"
 VBoxManage setextradata "VM name"
@@ -1501,12 +2260,12 @@
 VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiBIOSFirmwareMinor" 4</screen>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>DMI system information</glossterm>
-        <glossdef>
-          <para>(type 1)</para>
-          <screen>VBoxManage setextradata "VM name"
+      </listitem>
+
+      <listitem>
+        <para>
+          DMI system information (type 1)
+        </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiSystemVendor"      "System Vendor"
 VBoxManage setextradata "VM name"
@@ -1523,12 +2282,12 @@
       "VBoxInternal/Devices/pcbios/0/Config/DmiSystemUuid"
                                                "9852bf98-b83c-49db-a8de-182c42c7226b"</screen>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>DMI board information</glossterm>
-        <glossdef>
-          <para>(type 2)</para>
-          <screen>VBoxManage setextradata "VM name"
+      </listitem>
+
+      <listitem>
+        <para>
+          DMI board information (type 2)
+        </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiBoardVendor"       "Board Vendor"
 VBoxManage setextradata "VM name"
@@ -1544,12 +2303,12 @@
 VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiBoardBoardType"    10</screen>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>DMI system enclosure or chassis</glossterm>
-        <glossdef>
-          <para>(type 3)</para>
-          <screen>VBoxManage setextradata "VM name"
+      </listitem>
+
+      <listitem>
+        <para>
+          DMI system enclosure or chassis (type 3)
+        </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiChassisVendor"     "Chassis Vendor"
 VBoxManage setextradata "VM name"
@@ -1561,277 +2320,411 @@
 VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiChassisAssetTag"   "Chassis Tag"</screen>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>DMI processor information</glossterm>
-        <glossdef>
-          <para>(type 4)</para>
-          <screen>VBoxManage setextradata "VM name"
+      </listitem>
+
+      <listitem>
+        <para>
+          DMI processor information (type 4)
+        </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiProcManufacturer"  "GenuineIntel"
 VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiProcVersion"       "Pentium(R) III"</screen>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>DMI OEM strings</glossterm>
-        <glossdef>
-          <para>(type 11)</para>
-          <screen>VBoxManage setextradata "VM name"
+      </listitem>
+
+      <listitem>
+        <para>
+          DMI OEM strings (type 11)
+        </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxVer"        "vboxVer_1.2.3"
 VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/pcbios/0/Config/DmiOEMVBoxRev"        "vboxRev_12345"</screen>
-        </glossdef>
-      </glossentry>
-    </glosslist>
-
-    <para>If a DMI string is not set, the default value of VirtualBox is used.
-    To set an empty string use
-    <computeroutput>"&lt;EMPTY&gt;"</computeroutput>.</para>
-
-    <para>Note that in the above list, all quoted parameters (DmiBIOSVendor,
-    DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be strings. If
-    such a string is a valid number, the parameter is treated as number and
-    the VM will most probably refuse to start with an
-    <computeroutput>VERR_CFGM_NOT_STRING</computeroutput> error. In that case,
-    use <computeroutput>"string:&lt;value&gt;"</computeroutput>, for instance
-    <screen>VBoxManage setextradata "VM name"
-      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial"      "string:1234"</screen></para>
-
-    <para>Changing this information can be necessary to provide the DMI
-    information of the host to the guest to prevent Windows from asking for a
-    new product key. On Linux hosts the DMI BIOS information can be obtained
-    with <screen>dmidecode -t0</screen>and the DMI system information can be
-    obtained with <screen>dmidecode -t1</screen></para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      If a DMI string is not set, the default value of VirtualBox is
+      used. To set an empty string use
+      <computeroutput>"&lt;EMPTY&gt;"</computeroutput>.
+    </para>
+
+    <para>
+      Note that in the above list, all quoted parameters (DmiBIOSVendor,
+      DmiBIOSVersion but not DmiBIOSReleaseMajor) are expected to be
+      strings. If such a string is a valid number, the parameter is
+      treated as number and the VM will most probably refuse to start
+      with an <computeroutput>VERR_CFGM_NOT_STRING</computeroutput>
+      error. In that case, use
+      <computeroutput>"string:&lt;value&gt;"</computeroutput>. For
+      example:
+    </para>
+
+<screen>VBoxManage setextradata "VM name"
+      "VBoxInternal/Devices/pcbios/0/Config/DmiSystemSerial"      "string:1234"</screen>
+
+    <para>
+      Changing this information can be necessary to provide the DMI
+      information of the host to the guest to prevent Windows from
+      asking for a new product key. On Linux hosts, the DMI BIOS
+      information can be obtained with:
+
+<screen>dmidecode -t0</screen>
+
+      The DMI system information can be obtained with:
+
+<screen>dmidecode -t1</screen>
+    </para>
+
   </sect1>
 
   <sect1 id="changeacpicust">
-    <title>Configuring the custom ACPI table</title>
-
-    <para>VirtualBox can be configured to present an custom ACPI table to
-    the guest. Use the following command to configure this:</para>
-
-    <screen>VBoxManage setextradata "VM name"
+
+    <title>Configuring the Custom ACPI Table</title>
+
+    <para>
+      VirtualBox can be configured to present an custom ACPI table to
+      the guest. Use the following command to configure this:
+    </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/acpi/0/Config/CustomTable" "/path/to/table.bin"</screen>
 
-    <para>Configuring a custom ACPI table can prevent Windows
-      Vista and Windows 7 from asking for a new product key. On Linux hosts,
-      one of the host tables can be read from
-    <filename>/sys/firmware/acpi/tables/</filename>.</para>
+    <para>
+      Configuring a custom ACPI table can prevent Windows Vista and
+      Windows 7 from asking for a new product key. On Linux hosts, one
+      of the host tables can be read from
+      <filename>/sys/firmware/acpi/tables/</filename>.
+    </para>
+
   </sect1>
 
-  <sect1>
-    <title>Fine-tuning timers and time synchronization</title>
+  <sect1 id="fine-tune-timers">
+
+    <title>Fine Tuning Timers and Time Synchronization</title>
 
     <sect2 id="changetscmode">
-      <title>Configuring the guest time stamp counter (TSC) to reflect guest
-      execution</title>
-
-      <para>By default, VirtualBox keeps all sources of time visible to the
-      guest synchronized to a single time source, the monotonic host time.
-      This reflects the assumptions of many guest operating systems, which
-      expect all time sources to reflect "wall clock" time. In special
-      circumstances it may be useful however to make the TSC (time stamp
-      counter) in the guest reflect the time actually spent executing the
-      guest.</para>
-
-      <para>This special TSC handling mode can be enabled on a per-VM basis,
-      and for best results must be used only in combination with hardware
-      virtualization. To enable this mode use the following command:</para>
-
-      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" 1</screen>
-
-      <para>To revert to the default TSC handling mode use:</para>
-
-      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution"</screen>
-
-      <para>Note that if you use the special TSC handling mode with a guest
-      operating system which is very strict about the consistency of time
-      sources you may get a warning or error message about the timing
-      inconsistency. It may also cause clocks to become unreliable with some
-      guest operating systems depending on how they use the TSC.</para>
+
+      <title>Configuring the Guest Time Stamp Counter (TSC) to Reflect Guest
+        Execution</title>
+
+      <para>
+        By default, VirtualBox keeps all sources of time visible to the
+        guest synchronized to a single time source, the monotonic host
+        time. This reflects the assumptions of many guest operating
+        systems, which expect all time sources to reflect "wall clock"
+        time. In special circumstances it may be useful however to make
+        the time stamp counter (TSC) in the guest reflect the time
+        actually spent executing the guest.
+      </para>
+
+      <para>
+        This special TSC handling mode can be enabled on a per-VM basis,
+        and for best results must be used only in combination with
+        hardware virtualization. To enable this mode use the following
+        command:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution" 1</screen>
+
+      <para>
+        To revert to the default TSC handling mode use:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/TSCTiedToExecution"</screen>
+
+      <para>
+        Note that if you use the special TSC handling mode with a guest
+        operating system which is very strict about the consistency of
+        time sources you may get a warning or error message about the
+        timing inconsistency. It may also cause clocks to become
+        unreliable with some guest operating systems depending on how
+        they use the TSC.
+      </para>
+
     </sect2>
 
     <sect2 id="warpguest">
-      <title>Accelerate or slow down the guest clock</title>
-
-      <para>For certain purposes it can be useful to accelerate or to slow
-      down the (virtual) guest clock. This can be achieved as follows:</para>
-
-      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 200</screen>
-
-      <para>The above example will double the speed of the guest clock
-      while</para>
-
-      <screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 50</screen>
-
-      <para>will halve the speed of the guest clock. Note that changing the
-      rate of the virtual clock can confuse the guest and can even lead to
-      abnormal guest behavior. For instance, a higher clock rate means shorter
-      timeouts for virtual devices with the result that a slightly increased
-      response time of a virtual device due to an increased host load can
-      cause guest failures. Note further that any time synchronization
-      mechanism will frequently try to resynchronize the guest clock with the
-      reference clock (which is the host clock if the VirtualBox Guest
-      Additions are active). Therefore any time synchronization should be
-      disabled if the rate of the guest clock is changed as described above
-      (see <xref linkend="changetimesync" />).</para>
+
+      <title>Accelerate or Slow Down the Guest Clock</title>
+
+      <para>
+        For certain purposes it can be useful to accelerate or to slow
+        down the virtual guest clock. This can be achieved as follows:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 200</screen>
+
+      <para>
+        The above example will double the speed of the guest clock while
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/TM/WarpDrivePercentage" 50</screen>
+
+      <para>
+        will halve the speed of the guest clock. Note that changing the
+        rate of the virtual clock can confuse the guest and can even
+        lead to abnormal guest behavior. For instance, a higher clock
+        rate means shorter timeouts for virtual devices with the result
+        that a slightly increased response time of a virtual device due
+        to an increased host load can cause guest failures. Note further
+        that any time synchronization mechanism will frequently try to
+        resynchronize the guest clock with the reference clock, which is
+        the host clock if the VirtualBox Guest Additions are active.
+        Therefore any time synchronization should be disabled if the
+        rate of the guest clock is changed as described above. See
+        <xref linkend="changetimesync" />.
+      </para>
+
     </sect2>
 
     <sect2 id="changetimesync">
-      <title>Tuning the Guest Additions time synchronization
-      parameters</title>
-
-      <para>The VirtualBox Guest Additions ensure that the guest's system time
-      is synchronized with the host time. There are several parameters which
-      can be tuned. The parameters can be set for a specific VM using the
-      following command:</para>
-
-      <screen>VBoxManage guestproperty set "VM name" "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE</screen>
-
-      <para>where <computeroutput>PARAMETER</computeroutput> is one of the
-      following:</para>
-
-      <glosslist>
-        <glossentry>
-          <glossterm><computeroutput>--timesync-interval</computeroutput></glossterm>
-          <glossdef>
-            <para>Specifies the interval at which to synchronize the time
-            with the host. The default is 10000 ms (10 seconds).</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--timesync-min-adjust</computeroutput></glossterm>
-          <glossdef>
-            <para>The minimum absolute drift value measured in milliseconds
-            to make adjustments for. The default is 1000 ms on OS/2 and 100
-            ms elsewhere.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--timesync-latency-factor</computeroutput></glossterm>
-          <glossdef>
-            <para>The factor to multiply the time query latency with to
-            calculate the dynamic minimum adjust time. The default is 8
-            times, that means in detail: Measure the time it takes to
-            determine the host time (the guest has to contact the VM host
-            service which may take some time), multiply this value by 8 and
-            do an adjustment only if the time difference between host and
-            guest is bigger than this value. Don't do any time adjustment
-            otherwise.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--timesync-max-latency</computeroutput></glossterm>
-          <glossdef>
-            <para>The max host timer query latency to accept. The default is
-            250 ms.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--timesync-set-threshold</computeroutput></glossterm>
-          <glossdef>
-            <para>The absolute drift threshold, given as milliseconds where
-            to start setting the time instead of trying to smoothly adjust
-            it. The default is 20 minutes.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--timesync-set-start</computeroutput></glossterm>
-          <glossdef>
-            <para>Set the time when starting the time sync service.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--timesync-set-on-restore
-          0|1</computeroutput></glossterm>
-          <glossdef>
-            <para>Set the time after the VM was restored from a saved state
-            when passing 1 as parameter (default). Disable by passing 0. In
-            the latter case, the time will be adjusted smoothly which can
-            take a long time.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>All these parameters can be specified as command line parameters
-      to VBoxService as well.</para>
+
+      <title>Tuning the Guest Additions Time Synchronization Parameters</title>
+
+      <para>
+        The VirtualBox Guest Additions ensure that the guest's system
+        time is synchronized with the host time. There are several
+        parameters which can be tuned. The parameters can be set for a
+        specific VM using the following command:
+      </para>
+
+<screen>VBoxManage guestproperty set "VM name" "/VirtualBox/GuestAdd/VBoxService/PARAMETER" VALUE</screen>
+
+      <para>
+        where <computeroutput>PARAMETER</computeroutput> is one of the
+        following:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>--timesync-interval</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Specifies the interval at which to synchronize the time
+              with the host. The default is 10000 ms (10 seconds).
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>--timesync-min-adjust</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The minimum absolute drift value measured in milliseconds
+              to make adjustments for. The default is 1000 ms on OS/2
+              and 100 ms elsewhere.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>--timesync-latency-factor</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The factor to multiply the time query latency with to
+              calculate the dynamic minimum adjust time. The default is
+              8 times, which means as follows:
+            </para>
+
+            <para>
+              Measure the time it takes to determine the host time, the
+              guest has to contact the VM host service which may take
+              some time. Multiply this value by 8 and do an adjustment
+              only if the time difference between host and guest is
+              bigger than this value. Do not do any time adjustment
+              otherwise.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>--timesync-max-latency</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The max host timer query latency to accept. The default is
+              250 ms.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>--timesync-set-threshold</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The absolute drift threshold, given as milliseconds where
+              to start setting the time instead of trying to smoothly
+              adjust it. The default is 20 minutes.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>--timesync-set-start</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Set the time when starting the time sync service.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>--timesync-set-on-restore
+            0|1</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Set the time after the VM was restored from a saved state
+              when passing 1 as parameter (default). Disable by passing
+              0. In the latter case, the time will be adjusted smoothly
+              which can take a long time.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        All these parameters can be specified as command line parameters
+        to VBoxService as well.
+      </para>
+
     </sect2>
 
     <sect2 id="disabletimesync">
 
-      <title>Disabling the Guest Additions time synchronization</title>
-
-      <para>Once installed and started, the VirtualBox Guest Additions will
-        try to synchronize the guest time with the host time. This can be
-        prevented by forbidding the guest service from reading the host
-        clock:</para>
-
-      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen>
+      <title>Disabling the Guest Additions Time Synchronization</title>
+
+      <para>
+        Once installed and started, the VirtualBox Guest Additions will
+        try to synchronize the guest time with the host time. This can
+        be prevented by forbidding the guest service from reading the
+        host clock:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/VMMDev/0/Config/GetHostTimeDisabled" 1</screen>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="vboxbowsolaris11">
-    <title>Installing the alternate bridged networking driver on Solaris 11
-    hosts</title>
-
-    <para>Starting with VirtualBox 4.1, VirtualBox ships a new network filter
-    driver that utilizes Solaris 11's Crossbow functionality. By default, this
-    new driver is installed for Solaris 11 hosts (builds 159 and above) that
-    has support for it.</para>
-
-    <para>To force installation of the older STREAMS based network filter
-    driver, execute as root the following command before installing the
-    VirtualBox package:</para>
-
-    <screen>touch /etc/vboxinst_vboxflt</screen>
-
-    <para>To force installation of the Crossbow based network filter driver,
-    execute as root the following command before installing the VirtualBox
-    package:</para>
-
-    <screen>touch /etc/vboxinst_vboxbow</screen>
-
-    <para>To check which driver is currently being used by VirtualBox,
-    execute:</para>
-
-    <screen>modinfo | grep vbox</screen>
-
-    <para>If the output contains "vboxbow", it indicates VirtualBox is using
-    the Crossbow network filter driver, while the name "vboxflt" indicates
-    usage of the older STREAMS network filter.</para>
+
+    <title>Installing the Alternate Bridged Networking Driver on Solaris 11 hosts</title>
+
+    <para>
+      Starting with VirtualBox 4.1, VirtualBox ships a new network
+      filter driver that utilizes Solaris 11's Crossbow functionality.
+      By default, this new driver is installed for Solaris 11 hosts
+      (builds 159 and above) that has support for it.
+    </para>
+
+    <para>
+      To force installation of the older STREAMS based network filter
+      driver, execute as root the following command before installing
+      the VirtualBox package:
+    </para>
+
+<screen>touch /etc/vboxinst_vboxflt</screen>
+
+    <para>
+      To force installation of the Crossbow based network filter driver,
+      execute as root the following command before installing the
+      VirtualBox package:
+    </para>
+
+<screen>touch /etc/vboxinst_vboxbow</screen>
+
+    <para>
+      To check which driver is currently being used by VirtualBox,
+      execute:
+    </para>
+
+<screen>modinfo | grep vbox</screen>
+
+    <para>
+      If the output contains "vboxbow", it indicates VirtualBox is using
+      the Crossbow network filter driver, while the name "vboxflt"
+      indicates usage of the older STREAMS network filter.
+    </para>
+
   </sect1>
 
   <sect1 id="vboxbowvnictemplates">
-    <title>VirtualBox VNIC templates for VLANs on Solaris 11 hosts</title>
-
-    <para>VirtualBox supports VNIC (Virtual Network Interface) templates for
-    configuring VMs over VLANs.<footnote>
-        <para>Support for Crossbow based bridged networking was introduced
-        with VirtualBox 4.1 and requires Solaris 11 build 159 or above.</para>
-      </footnote> A VirtualBox VNIC template is a VNIC whose name starts with
-    "vboxvnic_template" (case-sensitive).</para>
-
-    <para>On Solaris 11 hosts<footnote><para>When Crossbow based bridged
-    networking is used.</para></footnote>, a VNIC template may be used to
-    specify the VLAN ID to use while bridging over a network link.</para>
-
-    <para>Here is an example of how to use a VNIC template to configure a VM
-    over a VLAN. Create a VirtualBox VNIC template, by executing as root:</para>
-
-    <screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0</screen>
-
-    <para>This will create a temporary VNIC template over interface "nge0"
-    with the VLAN ID 23. To create VNIC templates that are persistent across
-    host reboots, skip the <computeroutput>-t</computeroutput> parameter in the
-    above command. You may check the current state of links using:</para>
-
-    <para><screen>$ dladm show-link
+
+    <title>VirtualBox VNIC Templates for VLANs on Solaris 11 Hosts</title>
+
+    <para>
+      VirtualBox supports Virtual Network Interface (VNIC) templates for
+      configuring VMs over VLANs.
+
+      <footnote>
+
+        <para>
+          Support for Crossbow based bridged networking was introduced
+          with VirtualBox 4.1 and requires Solaris 11 build 159 or
+          above.
+        </para>
+
+      </footnote>
+
+      A VirtualBox VNIC template is a VNIC whose name starts with
+      "vboxvnic_template". The string is case-sensitive.
+    </para>
+
+    <para>
+      On Solaris 11 hosts, a VNIC template may be used to specify the
+      VLAN ID to use while bridging over a network link.
+
+      <footnote>
+
+        <para>
+          When Crossbow based bridged networking is used.
+        </para>
+
+      </footnote>
+    </para>
+
+    <para>
+      Here is an example of how to use a VNIC template to configure a VM
+      over a VLAN. Create a VirtualBox VNIC template, by executing as
+      root:
+    </para>
+
+<screen>dladm create-vnic -t -l nge0 -v 23 vboxvnic_template0</screen>
+
+    <para>
+      This will create a temporary VNIC template over interface "nge0"
+      with the VLAN ID 23. To create VNIC templates that are persistent
+      across host reboots, skip the <computeroutput>-t</computeroutput>
+      parameter in the above command. You may check the current state of
+      links using:
+    </para>
+
+    <para>
+<screen>$ dladm show-link
 LINK        CLASS     MTU    STATE    BRIDGE     OVER
 nge0        phys      1500   up       --         --
@@ -1841,59 +2734,86 @@
 $ dladm show-vnic
 LINK         OVER         SPEED  MACADDRESS        MACADDRTYPE         VID
-vboxvnic_template0 nge0   1000   2:8:20:25:12:75   random              23</screen></para>
-
-    <para>Once the VNIC template is created, any VMs that need to be on VLAN
-    23 over the interface "nge0" can be configured to bridge using this VNIC
-    template.</para>
-
-    <para>VNIC templates makes managing VMs on VLANs simpler and efficient.
-    The VLAN details are not stored as part of every VM's configuration but
-    rather inherited from the VNIC template while starting the VM. The VNIC
-    template itself can be modified anytime using <computeroutput>dladm</computeroutput>.</para>
-
-    <para>VNIC templates can be created with additional properties such as
-    bandwidth limits, CPU fanout etc. Refer to your Solaris network
-    documentation on how to accomplish this. These additional properties,
-    if any, are also applied to VMs which bridge using the VNIC template.</para>
+vboxvnic_template0 nge0   1000   2:8:20:25:12:75   random              23</screen>
+    </para>
+
+    <para>
+      Once the VNIC template is created, any VMs that need to be on VLAN
+      23 over the interface "nge0" can be configured to bridge using
+      this VNIC template.
+    </para>
+
+    <para>
+      VNIC templates makes managing VMs on VLANs simpler and efficient.
+      The VLAN details are not stored as part of every VM's
+      configuration but rather inherited from the VNIC template while
+      starting the VM. The VNIC template itself can be modified anytime
+      using <computeroutput>dladm</computeroutput>.
+    </para>
+
+    <para>
+      VNIC templates can be created with additional properties such as
+      bandwidth limits, CPU fanout etc. Refer to your Solaris network
+      documentation on how to accomplish this. These additional
+      properties, if any, are also applied to VMs which bridge using the
+      VNIC template.
+    </para>
+
   </sect1>
 
   <sect1 id="addhostonlysolaris">
-    <title>Configuring multiple host-only network interfaces on Solaris
-    hosts</title>
-
-    <para>By default VirtualBox provides you with one host-only network
-    interface. Adding more host-only network interfaces on Solaris hosts
-    requires manual configuration. Here's how to add another host-only
-    network interface.</para>
-
-    <para>Begin by stopping all running VMs. Then, unplumb the existing
-    "vboxnet0" interface by execute the following command as root:</para>
-
-    <screen>ifconfig vboxnet0 unplumb</screen>
-
-    <para>If you have several vboxnet interfaces, you will need to unplumb
-    all of them. Once all vboxnet interfaces are unplumbed, remove the
-    driver by executing the following command as root:</para>
-
-    <screen>rem_drv vboxnet</screen>
-
-    <para>Edit the file <computeroutput>/platform/i86pc/kernel/drv/vboxnet.conf</computeroutput>
-    and add a line for the new interface we want to add as shown below:</para>
-
-    <screen>name="vboxnet" parent="pseudo" instance=1;
+
+    <title>Configuring Multiple Host-Only Network Interfaces on Solaris Hosts</title>
+
+    <para>
+      By default VirtualBox provides you with one host-only network
+      interface. Adding more host-only network interfaces on Solaris
+      hosts requires manual configuration. Here is how to add another
+      host-only network interface.
+    </para>
+
+    <para>
+      Begin by stopping all running VMs. Then, unplumb the existing
+      "vboxnet0" interface by execute the following command as root:
+    </para>
+
+<screen>ifconfig vboxnet0 unplumb</screen>
+
+    <para>
+      If you have several vboxnet interfaces, you will need to unplumb
+      all of them. Once all vboxnet interfaces are unplumbed, remove the
+      driver by executing the following command as root:
+    </para>
+
+<screen>rem_drv vboxnet</screen>
+
+    <para>
+      Edit the file
+      <computeroutput>/platform/i86pc/kernel/drv/vboxnet.conf</computeroutput>
+      and add a line for the new interface we want to add as shown
+      below:
+    </para>
+
+<screen>name="vboxnet" parent="pseudo" instance=1;
 name="vboxnet" parent="pseudo" instance=2;</screen>
 
-    <para>Add as many of these lines as required with each line having a
-    unique instance number.</para>
-
-    <para>Next, reload the vboxnet driver by executing the following command
-    as root:</para>
-
-    <screen>add_drv vboxnet</screen>
-
-    <para>On Solaris 11.1 and newer hosts you may want to rename the default
-    vanity interface name. To check what name has been assigned, execute:</para>
-
-    <screen>dladm show-phys
+    <para>
+      Add as many of these lines as required with each line having a
+      unique instance number.
+    </para>
+
+    <para>
+      Next, reload the vboxnet driver by executing the following command
+      as root:
+    </para>
+
+<screen>add_drv vboxnet</screen>
+
+    <para>
+      On Solaris 11.1 and newer hosts you may want to rename the default
+      vanity interface name. To check what name has been assigned,
+      execute:
+    </para>
+
+<screen>dladm show-phys
 LINK              MEDIA                STATE      SPEED  DUPLEX    DEVICE
 net0              Ethernet             up         100    full      e1000g0
@@ -1901,816 +2821,1527 @@
 net1              Ethernet             up         1000   full      vboxnet0</screen>
 
-    <para>In the above example, we can rename "net2" to "vboxnet1" before
-    proceeding to plumb the interface. This can be done by executing as root:</para>
-
-    <screen>dladm rename-link net2 vboxnet1</screen>
-
-    <para>Now plumb all the interfaces using
-    <computeroutput>ifconfig vboxnetX plumb</computeroutput> (where 'X' would
-    be 1 in this case). Once the interface is plumbed, it may be configured
-    like any other network interface. Refer to the
-    <computeroutput>ifconfig</computeroutput> documentation for further details.</para>
-
-    <para>To make the newly added interfaces' settings persistent across
-    reboots, you will need to edit the files
-    <computeroutput>/etc/inet/netmasks</computeroutput>, and if you are using NWAM
-    <computeroutput>/etc/nwam/llp</computeroutput> and add the appropriate
-    entries to set the netmask and static IP for each of those interfaces. The
-    VirtualBox installer only updates these configuration files for the one
-    "vboxnet0" interface it creates by default.</para>
+    <para>
+      In the above example, we can rename "net2" to "vboxnet1" before
+      proceeding to plumb the interface. This can be done by executing
+      as root:
+    </para>
+
+<screen>dladm rename-link net2 vboxnet1</screen>
+
+    <para>
+      Now plumb all the interfaces using <computeroutput>ifconfig
+      vboxnetX plumb</computeroutput>, where 'X' would be 1 in this
+      case. Once the interface is plumbed, it may be configured like any
+      other network interface. Refer to the
+      <computeroutput>ifconfig</computeroutput> documentation for
+      further details.
+    </para>
+
+    <para>
+      To make the settings for the newly added interfaces persistent
+      across reboots, you will need to edit the files
+      <computeroutput>/etc/inet/netmasks</computeroutput>, and if you
+      are using NWAM <computeroutput>/etc/nwam/llp</computeroutput> and
+      add the appropriate entries to set the netmask and static IP for
+      each of those interfaces. The VirtualBox installer only updates
+      these configuration files for the one "vboxnet0" interface it
+      creates by default.
+    </para>
+
   </sect1>
 
   <sect1 id="solariscodedumper">
-    <title>Configuring the VirtualBox CoreDumper on Solaris hosts</title>
-
-    <para>VirtualBox is capable of producing its own core files for extensive
-    debugging when things go wrong. Currently this is only available on
-    Solaris hosts.</para>
-
-    <para>The VirtualBox CoreDumper can be enabled using the following
-    command:</para>
-
-    <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1</screen></para>
-
-    <para>You can specify which directory to use for core dumps with this
-    command:</para>
-
-    <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir &lt;path-to-directory&gt;</screen>Make
-    sure the directory you specify is on a volume with sufficient free space
-    and that the VirtualBox process has sufficient permissions to write files
-    to this directory. If you skip this command and don't specify any core
-    dump directory, the current directory of the VirtualBox executable will be
-    used (which would most likely fail when writing cores as they are
-    protected with root permissions). It is recommended you explicitly set a
-    core dump directory.</para>
-
-    <para>You must specify when the VirtualBox CoreDumper should be triggered.
-    This is done using the following commands:</para>
-
-    <para><screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1
-VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1</screen>At
-    least one of the above two commands will have to be provided if you have
-    enabled the VirtualBox CoreDumper.</para>
-
-    <para>Setting <computeroutput>CoreDumpReplaceSystemDump</computeroutput>
-    sets up the VM to override the host's core dumping mechanism and in the
-    event of any crash only the VirtualBox CoreDumper would produce the core
-    file.</para>
-
-    <para>Setting <computeroutput>CoreDumpLive</computeroutput> sets up the VM
-    to produce cores whenever the VM process receives a
-    <computeroutput>SIGUSR2</computeroutput> signal. After producing the core
-    file, the VM will not be terminated and will continue to run. You can thus
-    take cores of the VM process using:</para>
-
-    <para><screen>kill -s SIGUSR2 &lt;VM-process-id&gt;</screen></para>
-
-    <para>Core files produced by the VirtualBox CoreDumper are of the form
-    <computeroutput>core.vb.&lt;ProcessName&gt;.&lt;ProcessID&gt;</computeroutput>,
-    for example <computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.</para>
+
+    <title>Configuring the VirtualBox CoreDumper on Solaris Hosts</title>
+
+    <para>
+      VirtualBox is capable of producing its own core files for
+      extensive debugging when things go wrong. Currently this is only
+      available on Solaris hosts.
+    </para>
+
+    <para>
+      The VirtualBox CoreDumper can be enabled using the following
+      command:
+    </para>
+
+    <para>
+<screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpEnabled 1</screen>
+    </para>
+
+    <para>
+      You can specify which directory to use for core dumps with this
+      command:
+    </para>
+
+    <para>
+<screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpDir &lt;path-to-directory&gt;</screen>
+
+      Make sure the directory you specify is on a volume with sufficient
+      free space and that the VirtualBox process has sufficient
+      permissions to write files to this directory. If you skip this
+      command and do not specify any core dump directory, the current
+      directory of the VirtualBox executable will be used. This would
+      most likely fail when writing cores as they are protected with
+      root permissions. It is recommended you explicitly set a core dump
+      directory.
+    </para>
+
+    <para>
+      You must specify when the VirtualBox CoreDumper should be
+      triggered. This is done using the following commands:
+    </para>
+
+    <para>
+<screen>VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpReplaceSystemDump 1
+VBoxManage setextradata "VM name" VBoxInternal2/CoreDumpLive 1</screen>
+
+      At least one of the above two commands will have to be provided if
+      you have enabled the VirtualBox CoreDumper.
+    </para>
+
+    <para>
+      Setting <computeroutput>CoreDumpReplaceSystemDump</computeroutput>
+      sets up the VM to override the host's core dumping mechanism and
+      in the event of any crash only the VirtualBox CoreDumper would
+      produce the core file.
+    </para>
+
+    <para>
+      Setting <computeroutput>CoreDumpLive</computeroutput> sets up the
+      VM to produce cores whenever the VM process receives a
+      <computeroutput>SIGUSR2</computeroutput> signal. After producing
+      the core file, the VM will not be terminated and will continue to
+      run. You can thus take cores of the VM process using:
+    </para>
+
+    <para>
+<screen>kill -s SIGUSR2 &lt;VM-process-id&gt;</screen>
+    </para>
+
+    <para>
+      Core files produced by the VirtualBox CoreDumper are of the form
+      <computeroutput>core.vb.&lt;ProcessName&gt;.&lt;ProcessID&gt;</computeroutput>,
+      for example
+      <computeroutput>core.vb.VBoxHeadless.11321</computeroutput>.
+    </para>
+
   </sect1>
 
   <sect1 id="vboxandsolzvmm">
-    <title>VirtualBox and Solaris kernel zones</title>
-
-    <para>Solaris kernel zones on x86-based systems make use of hardware-assisted
-    virtualization features like VirtualBox does. However, for kernel zones and
-    VirtualBox to share this hardware resource, they need to co-operate.</para>
-
-    <para>By default, due to performance reasons, VirtualBox acquires the
-    hardware-assisted virtualization resource (VT-x/AMD-V) globally on the
-    host machine and uses it until the last VirtualBox VM that requires it is
-    powered off. This prevents other software from using VT-x/AMD-V during the
-    time VirtualBox has taken control of it.</para>
-
-    <para>VirtualBox can be instructed to relinquish use of hardware-assisted
-    virtualization features when not executing guest code, thereby allowing
-    kernel zones to make use of them. To do this, shutdown all VirtualBox VMs
-    and execute the following command:</para>
-
-    <screen>VBoxManage setproperty hwvirtexclusive off</screen>
-
-    <para>This command needs to be executed only once as the setting is stored
-    as part of the global VirtualBox settings which will continue to persist
-    across host-reboots and VirtualBox upgrades.</para>
+
+    <title>VirtualBox and Solaris Kernel Zones</title>
+
+    <para>
+      Solaris kernel zones on x86-based systems make use of
+      hardware-assisted virtualization features like VirtualBox does.
+      However, for kernel zones and VirtualBox to share this hardware
+      resource, they need to co-operate.
+    </para>
+
+    <para>
+      By default, due to performance reasons, VirtualBox acquires the
+      hardware-assisted virtualization resource (VT-x/AMD-V) globally on
+      the host machine and uses it until the last VirtualBox VM that
+      requires it is powered off. This prevents other software from
+      using VT-x/AMD-V during the time VirtualBox has taken control of
+      it.
+    </para>
+
+    <para>
+      VirtualBox can be instructed to relinquish use of
+      hardware-assisted virtualization features when not executing guest
+      code, thereby allowing kernel zones to make use of them. To do
+      this, shutdown all VirtualBox VMs and execute the following
+      command:
+    </para>
+
+<screen>VBoxManage setproperty hwvirtexclusive off</screen>
+
+    <para>
+      This command needs to be executed only once as the setting is
+      stored as part of the global VirtualBox settings which will
+      continue to persist across host-reboots and VirtualBox upgrades.
+    </para>
+
   </sect1>
 
   <sect1 id="guitweaks">
-    <title>Locking down the VirtualBox GUI</title>
-
-    <sect2>
-      <title>Customizing the VM manager</title>
-
-      <para>There are several advanced customization settings for locking down
-      the VirtualBox manager, that is, removing some features that the user
-      should not see.</para>
-
-      <para><screen>VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...]</screen></para>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-      following keywords:<glosslist>
-          <glossentry>
-            <glossterm><computeroutput>noSelector</computeroutput></glossterm>
-            <glossdef>
-              <para>Don't allow to start the VirtualBox manager. Trying to do so
-              will show a window containing a proper error message.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm><computeroutput>noMenuBar</computeroutput></glossterm>
-            <glossdef>
-              <para>VM windows will not contain a menu bar.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm><computeroutput>noStatusBar</computeroutput></glossterm>
-            <glossdef>
-              <para>VM windows will not contain a status bar.</para>
-            </glossdef>
-          </glossentry>
-        </glosslist></para>
-
-      <para>To disable any of these VM manager customizations do
-        <screen>VBoxManage setextradata global GUI/Customizations</screen></para>
+
+    <title>Locking Down the VirtualBox GUI</title>
+
+    <sect2 id="customize-vm-manager">
+
+      <title>Customizing the VM Manager</title>
+
+      <para>
+        There are several advanced customization settings for locking
+        down the VirtualBox manager. Locking down means removing some
+        features that the user should not see.
+      </para>
+
+      <para>
+<screen>VBoxManage setextradata global GUI/Customizations OPTION[,OPTION...]</screen>
+      </para>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>noSelector</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow users to start the VirtualBox manager. Trying
+              to do so will show a window containing a proper error
+              message.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>noMenuBar</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              VM windows will not contain a menu bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>noStatusBar</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              VM windows will not contain a status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        To disable any of these VM manager customizations do
+
+<screen>VBoxManage setextradata global GUI/Customizations</screen>
+      </para>
 
     </sect2>
-    <sect2>
-
-      <title>VM selector customization</title>
-      <para>The following per-machine VM extradata settings can be used to change the
-        behavior of the VM selector window in respect of certain VMs:</para>
-      <screen>VBoxManage setextradata "VM name" SETTING true</screen>
-      <para>where <computeroutput>SETTING</computeroutput> can be:</para>
-      <glosslist>
-        <glossentry>
-          <glossterm><computeroutput>GUI/HideDetails</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the VM configuration of a certain VM. The details
-              window will remain just empty if this VM is selected.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-         <glossterm><computeroutput>GUI/PreventReconfiguration</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't allow the user to open the settings dialog for a certain VM.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>GUI/PreventSnapshotOperations</computeroutput></glossterm>
-          <glossdef>
-            <para>Prevent snapshot operations for a VM from the GUI, either at runtime or when
-              the VM is powered off.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>GUI/HideFromManager</computeroutput></glossterm>
-          <glossdef>
-            <para>Hide a certain VM in the VM selector window.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>GUI/PreventApplicationUpdate</computeroutput></glossterm>
-          <glossdef>
-            <para>Disable the automatic update check and hide the corresponding menu item.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-      <para>Please note that these settings wouldn't prevent the user from
-        reconfiguring the VM by <computeroutput>VBoxManage modifyvm</computeroutput>.</para>
+
+    <sect2 id="customize-vm-selector">
+
+      <title>VM Selector Customization</title>
+
+      <para>
+        The following per-machine VM extradata settings can be used to
+        change the behavior of the VM selector window in respect of
+        certain VMs:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" SETTING true</screen>
+
+      <para>
+        where <computeroutput>SETTING</computeroutput> can be:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>GUI/HideDetails</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the VM configuration of a certain VM. The
+              details window will remain just empty if this VM is
+              selected.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>GUI/PreventReconfiguration</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow the user to open the settings dialog for a
+              certain VM.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>GUI/PreventSnapshotOperations</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Prevent snapshot operations for a VM from the GUI, either
+              at runtime or when the VM is powered off.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>GUI/HideFromManager</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Hide a certain VM in the VM selector window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>GUI/PreventApplicationUpdate</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Disable the automatic update check and hide the
+              corresponding menu item.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        Please note that these settings would not prevent the user from
+        reconfiguring the VM by <computeroutput>VBoxManage
+        modifyvm</computeroutput>.
+      </para>
 
     </sect2>
 
-    <sect2>
-      <title>Configure VM selector menu entries</title>
-      <para>You can disable (i.e. black-list) certain entries in the global settings
-        page of the VM selector:</para>
-      <screen>VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages OPTION[,OPTION...]</screen>
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>General</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>General</emphasis> settings pane.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Input</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Input</emphasis> settings pane.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Update</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Update</emphasis> settings pane.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Language</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Language</emphasis> settings pane.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Display</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Display</emphasis> settings pane.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Network</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Network</emphasis> settings pane.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Extensions</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Extensions</emphasis> settings pane.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Proxy</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Proxy</emphasis> settings pane.</para>
-          </glossdef>
-        </glossentry>
-
-      </glosslist>
-
-      <para>This is a global setting. Any combination of the above is allowed.
-         To restore the default behavior, use</para>
-      <screen>VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages</screen>
+    <sect2 id="config-vm-selector-menu">
+
+      <title>Configure VM Selector Menu Entries</title>
+
+      <para>
+        You can disable, or blacklist, certain entries in the global
+        settings page of the VM selector:
+      </para>
+
+<screen>VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages OPTION[,OPTION...]</screen>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>General</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>General</emphasis> settings
+              pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Input</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Input</emphasis> settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Update</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Update</emphasis> settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Language</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Language</emphasis> settings
+              pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Display</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Display</emphasis> settings
+              pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Network</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Network</emphasis> settings
+              pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Extensions</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Extensions</emphasis> settings
+              pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Proxy</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Proxy</emphasis> settings pane.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a global setting. Any combination of the above is
+        allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata global GUI/RestrictedGlobalSettingsPages</screen>
 
     </sect2>
 
-    <sect2>
-      <title>Configure VM window menu entries</title>
-      <para>You can disable (i.e. black-list) certain menu actions in the VM window:</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus OPTION[,OPTION...]</screen>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>All</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show any menu in the VM window.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Machine</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Machine</emphasis> menu in the VM window.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>View</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>View</emphasis> menu in the VM window.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Devices</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Devices</emphasis> menu in the VM window.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Help</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Help</emphasis> menu in the VM window.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Debug</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Debug</emphasis> menu in the VM window. The debug
-              menu is only visible if the GUI was started with special command line parameters
-              or environment variable settings.</para>
-          </glossdef>
-        </glossentry>
-
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
-      the default behavior, use</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus</screen>
-
-      <para>You can also disable (i.e. blacklist) certain menu actions of certain
-        menus. Use the following command to disable certain actions of the
-        <emphasis>Application</emphasis> menu (only available on Mac OS X hosts):</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>All</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show any menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>About</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>About</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
-      the default behavior, use</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus</screen>
-
-      <para>Use the following command to disable certain actions of the <emphasis>Machine</emphasis>
-        menu:</para>
-
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>All</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show any menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>SettingsDialog</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Settings</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>TakeSnapshot</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Take Snapshot</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>TakeScreenshot</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Take Screenshot</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>InformationDialog</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Session Information</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>MouseIntegration</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Disable Mouse Integration</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>TypeCAD</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Insert Ctrl+Alt+Del</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>TypeCABS</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Insert Ctrl+Alt+Backspace</emphasis> menu item in
-              this menu (available on X11 hosts only).</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Pause</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Pause</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Reset</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Reset</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>SaveState</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Save the machine state</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>ACPI Shutdown</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Power Off the machine</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
-      the default behavior, use</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions</screen>
-
-      <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
-        menu:</para>
-
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeViewMenuActions OPTION[,OPTION...]</screen>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>All</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show any menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Fullscreen</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Switch to Fullscreen</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Seamless</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Switch to Seamless Mode</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Scale</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Switch to Scaled Mode</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>GuestAutoresize</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Auto-resize Guest Display</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>AdjustWindow</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Adjust Window Size</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Multiscreen</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Multiscreen</emphasis> menu item in this menu (only visible in full screen / seamless mode).</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
-      the default behavior, use</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeViewMenuActions</screen>
-
-      <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
-        menu:</para>
-
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDevicesMenuActions OPTION[,OPTION...]</screen>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords to disable actions in the <emphasis>Devices</emphasis> menu:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>All</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show any menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>OpticalDevices</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>CD/DVD Devices</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>FloppyDevices</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>FLoppy Devices</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>USBDevices</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>USB Devices</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>SharedClipboard</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Shared Clipboard</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>DragAndDrop</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Drag and Drop</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>NetworkSettings</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Network Settings...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>SharedFoldersSettings</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Shared Folders Settings...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>VRDEServer</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Remove Display</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>InstallGuestTools</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Insert Guest Additions CD imnage...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
-      the default behavior, use</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDevicesMenuActions</screen>
-
-      <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
-        menu:</para>
-
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDebuggerMenuActions OPTION[,OPTION...]</screen>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords to disable actions in the <emphasis>Debug</emphasis> menu (normally completely disabled):</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>All</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show any menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Statistics</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Statistics...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>CommandLine</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Command Line...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Logging</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Logging...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>LogDialog</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Show Log...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
-      the default behavior, use</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDebuggerMenuActions</screen>
-
-      <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
-        menu:</para>
-
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeHelpMenuActions OPTION[,OPTION...]</screen>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords to disable actions in the <emphasis>Help</emphasis> menu (normally completely disabled):</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>All</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show any menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Contents</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Contents...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>WebSite</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>VirtualBox Web Site...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>ResetWarnings</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Reset All Warnings</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>NetworkAccessManager</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Network Operations Manager</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>About</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>About</emphasis> menu item in this menu (only on non Mac OS X hosts).</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Contents</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Contents...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Contents</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the <emphasis>Contents...</emphasis> menu item in this menu.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
-      the default behavior, use</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeHelpMenuActions</screen>
+    <sect2 id="config-vm-window-menu">
+
+      <title>Configure VM Window Menu Entries</title>
+
+      <para>
+        You can disable, or blacklist, certain menu actions in the VM
+        window:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus OPTION[,OPTION...]</screen>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>All</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu in the VM window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Machine</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Machine</emphasis> menu in the
+              VM window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>View</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>View</emphasis> menu in the VM
+              window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Devices</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Devices</emphasis> menu in the
+              VM window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Help</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Help</emphasis> menu in the VM
+              window.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Debug</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Debug</emphasis> menu in the VM
+              window. The debug menu is only visible if the GUI was
+              started with special command line parameters or
+              environment variable settings.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus</screen>
+
+      <para>
+        You can also disable, or blacklist, certain menu actions of
+        certain menus. Use the following command to disable certain
+        actions of the <emphasis>Application</emphasis> menu. This is
+        only available on Mac OS X hosts.
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>All</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>About</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>About</emphasis> menu item in
+              this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis>Machine</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>All</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>SettingsDialog</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Settings</emphasis> menu item in
+              this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>TakeSnapshot</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Take Snapshot</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>TakeScreenshot</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Take Screenshot</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>InformationDialog</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Session Information</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>MouseIntegration</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Disable Mouse
+              Integration</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>TypeCAD</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Insert Ctrl+Alt+Del</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>TypeCABS</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Insert
+              Ctrl+Alt+Backspace</emphasis> menu item in this menu.
+              Available on X11 hosts only.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Pause</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Pause</emphasis> menu item in
+              this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Reset</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Reset</emphasis> menu item in
+              this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>SaveState</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Save the machine
+              state</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Shutdown</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>ACPI Shutdown</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>PowerOff</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Power Off the machine</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis>View</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeViewMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>All</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Fullscreen</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Switch to Fullscreen</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Seamless</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Switch to Seamless
+              Mode</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Scale</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Switch to Scaled Mode</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>GuestAutoresize</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Auto-resize Guest
+              Display</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>AdjustWindow</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Adjust Window Size</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Multiscreen</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Multiscreen</emphasis> menu item
+              in this menu. Only visible in full screen/seamless mode.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeViewMenuActions</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis>View</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDevicesMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords to disable actions in the
+        <emphasis>Devices</emphasis> menu:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>All</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>OpticalDevices</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>CD/DVD Devices</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>FloppyDevices</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Floppy Devices</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>USBDevices</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>USB Devices</emphasis> menu item
+              in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>SharedClipboard</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Shared Clipboard</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>DragAndDrop</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Drag and Drop</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>NetworkSettings</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Network Settings...</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>SharedFoldersSettings</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Shared Folders
+              Settings...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>VRDEServer</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Remove Display</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>InstallGuestTools</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Insert Guest Additions CD
+              image...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDevicesMenuActions</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis>View</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDebuggerMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords to disable actions in the
+        <emphasis>Debug</emphasis> menu, which is normally completely
+        disabled:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>All</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Statistics</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Statistics...</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>CommandLine</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Command Line...</emphasis> menu
+              item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Logging</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Logging...</emphasis> menu item
+              in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>LogDialog</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Show Log...</emphasis> menu item
+              in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDebuggerMenuActions</screen>
+
+      <para>
+        Use the following command to disable certain actions of the
+        <emphasis>View</emphasis> menu:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeHelpMenuActions OPTION[,OPTION...]</screen>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords to disable actions in the
+        <emphasis>Help</emphasis> menu, which is normally completely
+        disabled:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>All</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show any menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Contents</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Contents...</emphasis> menu item
+              in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>WebSite</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>VirtualBox Web
+              Site...</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>ResetWarnings</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Reset All Warnings</emphasis>
+              menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>NetworkAccessManager</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Network Operations
+              Manager</emphasis> menu item in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>About</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>About</emphasis> menu item in
+              this menu. Only for non-Mac OS X hosts.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Contents</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Contents...</emphasis> menu item
+              in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Contents</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the <emphasis>Contents...</emphasis> menu item
+              in this menu.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeHelpMenuActions</screen>
 
     </sect2>
 
-    <sect2>
-
-      <title>Configure VM window status bar entries</title>
-
-      <para>You can disable (i.e. black-list) certain status bar items:</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedStatusBarIndicators OPTION[,OPTION...]</screen>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>HardDisks</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the hard disk icon in the VM window status bar. By default
-              the hard disk icon is only shown if the VM configuration contains one or
-              more hard disks.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>OpticalDisks</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the CD icon in the VM window status bar. By default the
-              CD icon is only shown if the VM configuration contains one or more CD
-            drives.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>FloppyDisks</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the floppy icon in the VM window status bar. By default the
-              floppy icon is only shown if the VM configuration contains one or more
-              floppy drives.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Network</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the network icon in the VM window status bar. By default
-              the network icon is only shown if the VM configuration contains one or more
-            active network adapters.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>USB</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the USB icon in the status bar. </para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>SharedFolders</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the shared folders icon in the status bar.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>VideoCapture</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the video capture icon in the status bar.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Features</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the CPU features icon in the status bar.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Mouse</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the mouse icon in the status bar.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Keyboard</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't show the keyboard icon in the status bar.</para>
-          </glossdef>
-        </glossentry>
-
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. If all options
-        are specified, no icons are displayed in the status bar of the VM window. To restore
-        the default behavior, use</para>
-
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedStatusBarIndicators</screen>
+    <sect2 id="config-vm-window-status-bar">
+
+      <title>Configure VM Window Status Bar Entries</title>
+
+      <para>
+        You can disable, or blacklist, certain status bar items:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedStatusBarIndicators OPTION[,OPTION...]</screen>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>HardDisks</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the hard disk icon in the VM window status
+              bar. By default the hard disk icon is only shown if the VM
+              configuration contains one or more hard disks.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>OpticalDisks</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the CD icon in the VM window status bar. By
+              default the CD icon is only shown if the VM configuration
+              contains one or more CD drives.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>FloppyDisks</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the floppy icon in the VM window status bar.
+              By default the floppy icon is only shown if the VM
+              configuration contains one or more floppy drives.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Network</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the network icon in the VM window status bar.
+              By default the network icon is only shown if the VM
+              configuration contains one or more active network
+              adapters.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>USB</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the USB icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>SharedFolders</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the shared folders icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>VideoCapture</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the video capture icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Features</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the CPU features icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Mouse</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the mouse icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Keyboard</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not show the keyboard icon in the status bar.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. If all options are specified, no icons are displayed in
+        the status bar of the VM window. To restore the default
+        behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedStatusBarIndicators</screen>
 
     </sect2>
 
-    <sect2>
-      <title>Configure VM window visual modes</title>
-
-      <para>You can disable (i.e. black-list) certain VM visual modes:</para>
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedVisualStates OPTION[,OPTION...]</screen>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>Fullscreen</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't allow to switch the VM into full screen mode.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Seamless</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't allow to switch the VM into seamless mode.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Scale</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't allow to switch the VM into scale mode.</para>
-          </glossdef>
-        </glossentry>
-
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. To restore
-        the default behavior, use</para>
-
-      <screen>VBoxManage setextradata "VM name" GUI/RestrictedVisualStates</screen>
+    <sect2 id="config-vm-window-visual-modes">
+
+      <title>Configure VM Window Visual Modes</title>
+
+      <para>
+        You can disable, or blacklist, certain VM visual modes:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedVisualStates OPTION[,OPTION...]</screen>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Fullscreen</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow to switch the VM into full screen mode.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Seamless</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow to switch the VM into seamless mode.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Scale</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow to switch the VM into scale mode.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. To restore the default behavior, use
+      </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedVisualStates</screen>
 
     </sect2>
 
-    <sect2>
-      <title>Host Key customization</title>
-
-      <para>To disable all host key combinations, open the preferences and
-        change the host key to <emphasis>None</emphasis>. This might be useful
-        when using VirtualBox in a kiosk mode.</para>
-
-      <para>To redefine or disable certain host key actions, use the following command:</para>
-
-      <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</screen>
-
-      <para>The following list shows the possible host key actions together with their default
-        host key shortcut. Setting an action to <emphasis>None</emphasis> will disable
-        that host key action.</para>
-      <table>
-        <title>Host Key customization</title>
+    <sect2 id="host-key-customize">
+
+      <title>Host Key Customization</title>
+
+      <para>
+        To disable all Host key combinations, open the preferences and
+        change the Host key to None. This might be useful when using
+        VirtualBox in a kiosk mode.
+      </para>
+
+      <para>
+        To redefine or disable certain Host key actions, use the
+        following command:
+      </para>
+
+<screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=F,...."</screen>
+
+      <para>
+        <xref linkend="table-host-key-customize"/> shows the possible
+        Host key actions, together with their default Host key shortcut.
+        Setting an action to None will disable that Host key action.
+      </para>
+
+      <table id="table-host-key-customize">
+        <title>Host Key Customization</title>
         <tgroup cols="3">
           <thead>
@@ -2725,25 +4356,25 @@
               <entry><computeroutput>TakeSnapshot</computeroutput></entry>
               <entry>T</entry>
-              <entry>take a snapshot</entry>
+              <entry>Take a snapshot</entry>
             </row>
             <row>
               <entry><computeroutput>TakeScreenshot</computeroutput></entry>
               <entry>E</entry>
-              <entry>take a screenshot</entry>
+              <entry>Take a screenshot</entry>
             </row>
             <row>
               <entry><computeroutput>MouseIntegration</computeroutput></entry>
               <entry>I</entry>
-              <entry>toggle mouse integration</entry>
+              <entry>Toggle mouse integration</entry>
             </row>
             <row>
               <entry><computeroutput>TypeCAD</computeroutput></entry>
               <entry>Del</entry>
-              <entry>inject Ctrl+Alt+Del</entry>
+              <entry>Inject Ctrl+Alt+Del</entry>
             </row>
             <row>
               <entry><computeroutput>TypeCABS</computeroutput></entry>
               <entry>Backspace</entry>
-              <entry>inject Ctrl+Alt+Backspace</entry>
+              <entry>Inject Ctrl+Alt+Backspace</entry>
             </row>
             <row>
@@ -2755,80 +4386,80 @@
               <entry><computeroutput>Reset</computeroutput></entry>
               <entry>R</entry>
-              <entry>(hard) reset the guest</entry>
+              <entry>Hard reset the guest</entry>
             </row>
             <row>
               <entry><computeroutput>SaveState</computeroutput></entry>
               <entry></entry>
-              <entry>save the VM state and terminate the VM</entry>
+              <entry>Save the VM state and terminate the VM</entry>
             </row>
             <row>
               <entry><computeroutput>Shutdown</computeroutput></entry>
               <entry>H</entry>
-              <entry>press the (virtual) ACPI power button</entry>
+              <entry>Press the (virtual) ACPI power button</entry>
             </row>
             <row>
               <entry><computeroutput>PowerOff</computeroutput></entry>
               <entry></entry>
-              <entry>power the VM off (without saving the state!)</entry>
+              <entry>Power the VM off, without saving the state</entry>
             </row>
             <row>
               <entry><computeroutput>Close</computeroutput></entry>
               <entry>Q</entry>
-              <entry>show the VM close dialog</entry>
+              <entry>Show the VM close dialog</entry>
             </row>
             <row>
               <entry><computeroutput>FullscreenMode</computeroutput></entry>
               <entry>F</entry>
-              <entry>switch the VM into full screen</entry>
+              <entry>Switch the VM into full screen</entry>
             </row>
             <row>
               <entry><computeroutput>SeamlessMode</computeroutput></entry>
               <entry>L</entry>
-              <entry>switch the VM into seamless mode</entry>
+              <entry>Switch the VM into seamless mode</entry>
             </row>
             <row>
               <entry><computeroutput>ScaleMode</computeroutput></entry>
               <entry>C</entry>
-              <entry>switch the VM into scale mode</entry>
+              <entry>Switch the VM into scale mode</entry>
             </row>
             <row>
               <entry><computeroutput>GuestAutoResize</computeroutput></entry>
               <entry>G</entry>
-              <entry>automatically resize the guest window</entry>
+              <entry>Automatically resize the guest window</entry>
             </row>
             <row>
               <entry><computeroutput>WindowAdjust</computeroutput></entry>
               <entry>A</entry>
-              <entry>immediately resize the guest window</entry>
+              <entry>Immediately resize the guest window</entry>
             </row>
             <row>
               <entry><computeroutput>PopupMenu</computeroutput></entry>
               <entry>Home</entry>
-              <entry>show popup menu in full screen / seaml. mode</entry>
+              <entry>Show popup menu in full screen / seaml. mode</entry>
             </row>
             <row>
               <entry><computeroutput>SettingsDialog</computeroutput></entry>
               <entry>S</entry>
-              <entry>open the VM settings dialog</entry>
+              <entry>Open the VM settings dialog</entry>
             </row>
             <row>
               <entry><computeroutput>InformationDialog</computeroutput></entry>
               <entry>N</entry>
-              <entry>show the VM information window</entry>
+              <entry>Show the VM information window</entry>
             </row>
             <row>
               <entry><computeroutput>NetworkAdaptersDialog</computeroutput></entry>
               <entry></entry>
-              <entry>show the VM network adapters dialog</entry>
+              <entry>Show the VM network adapters dialog</entry>
             </row>
             <row>
               <entry><computeroutput>SharedFoldersDialog</computeroutput></entry>
               <entry></entry>
-              <entry>show the VM shared folders dialog</entry>
+              <entry>Show the VM shared folders dialog</entry>
             </row>
             <row>
               <entry><computeroutput>InstallGuestAdditions</computeroutput></entry>
               <entry>D</entry>
-              <entry>mount the ISO containing the Guest Additions</entry>
+              <entry>Mount the ISO containing the Guest Additions</entry>
             </row>
           </tbody>
@@ -2836,746 +4467,1083 @@
       </table>
 
-      <para>To disable the full screen mode as well as the seamless mode, use the following command:
-        <screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen>
+      <para>
+        To disable the full screen mode as well as the seamless mode,
+        use the following command:
+
+<screen>VBoxManage setextradata global GUI/Input/MachineShortcuts "FullscreenMode=None,SeamlessMode=None"</screen>
       </para>
 
     </sect2>
 
-    <sect2>
-      <title>Action when terminating the VM</title>
-
-      <para>You can disallow (i.e. black-list) certain actions when terminating a VM.
-        To disallow specific actions, type:</para>
-
-      <para><screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen></para>
-
-      <para>where <computeroutput>OPTION</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>SaveState</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't allow the user to save the VM state when terminating
-            the VM.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't allow the user to shutdown the VM by sending the ACPI
-            power-off event to the guest.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't allow the user to power off the VM.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>PowerOffRestoringSnapshot</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't allow the user to return to the last snapshot when
-              powering off the VM.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Detach</computeroutput></glossterm>
-          <glossdef>
-            <para>Don't allow the user to detach from the VM process if the
-              VM was started in separate mode.</para>
-          </glossdef>
-        </glossentry>
-
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. If all
-        options are specified, the VM cannot be shut down at all.</para>
+    <sect2 id="terminate-vm-action">
+
+      <title>Action when Terminating the VM</title>
+
+      <para>
+        You can disallow, or blacklist, certain actions when terminating
+        a VM. To disallow specific actions, type:
+      </para>
+
+      <para>
+<screen>VBoxManage setextradata "VM name" GUI/RestrictedCloseActions OPTION[,OPTION...]</screen>
+      </para>
+
+      <para>
+        where <computeroutput>OPTION</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>SaveState</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow the user to save the VM state when
+              terminating the VM.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Shutdown</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow the user to shutdown the VM by sending the
+              ACPI power-off event to the guest.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>PowerOff</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow the user to power off the VM.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>PowerOffRestoringSnapshot</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow the user to return to the last snapshot when
+              powering off the VM.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Detach</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Do not allow the user to detach from the VM process if the
+              VM was started in separate mode.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. If all options are specified, the VM cannot be shut
+        down at all.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Default action when terminating the VM</title>
-
-      <para>You can define a specific action for terminating a VM. In contrast to
-        the setting decribed in the previous section, this setting allows only
-        one action when the user terminates the VM. No exit menu is shown.</para>
-
-      <para><screen>VBoxManage setextradata "VM name" GUI/DefaultCloseAction ACTION</screen></para>
-
-      <para>where <computeroutput>ACTION</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>SaveState</computeroutput></glossterm>
-          <glossdef>
-            <para>Save the VM state before terminating the VM process.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
-          <glossdef>
-            <para>The VM is shut down by sending the ACPI power-off event to the guest.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
-          <glossdef>
-            <para>The VM is powered off.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>PowerOffRestoringSnapshot</computeroutput></glossterm>
-          <glossdef>
-            <para>The VM is powered off and the saved state returns to the last snapshot.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Detach</computeroutput></glossterm>
-          <glossdef>
-            <para>Terminate the frontend but leave the VM process running.</para>
-          </glossdef>
-        </glossentry>
-
-      </glosslist>
-
-      <para>This is a per-VM setting. Any combination of the above is allowed. If all
-        options are specified, the VM cannot be shut down at all.</para>
+    <sect2 id="terminate-vm-default-action">
+
+      <title>Default Action when Terminating the VM</title>
+
+      <para>
+        You can define a specific action for terminating a VM. In
+        contrast to the setting decribed in the previous section, this
+        setting allows only one action when the user terminates the VM.
+        No exit menu is shown.
+      </para>
+
+      <para>
+<screen>VBoxManage setextradata "VM name" GUI/DefaultCloseAction ACTION</screen>
+      </para>
+
+      <para>
+        where <computeroutput>ACTION</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>SaveState</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Save the VM state before terminating the VM process.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Shutdown</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The VM is shut down by sending the ACPI power-off event to
+              the guest.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>PowerOff</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The VM is powered off.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>PowerOffRestoringSnapshot</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The VM is powered off and the saved state returns to the
+              last snapshot.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Detach</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              Terminate the frontend but leave the VM process running.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting. Any combination of the above is
+        allowed. If all options are specified, the VM cannot be shut
+        down at all.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Action for handling a Guru Meditation</title>
-
-      <para>A VM runs into a Guru Meditation if there is a problem which
+    <sect2 id="guru-meditation-action">
+
+      <title>Action for Handling a Guru Meditation</title>
+
+      <para>
+        A VM runs into a Guru Meditation if there is a problem which
         cannot be fixed by other means than terminating the process. The
         default is to show a message window which instructs the user to
-        open a bug report.</para>
-      <para>This behavior can be configured:</para>
-
-      <para><screen>VBoxManage setextradata "VM name" GUI/GuruMeditationHandler MODE</screen></para>
-
-      <para>where <computeroutput>MODE</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>Default</computeroutput></glossterm>
-          <glossdef>
-            <para>A message window is shown. After the user confirmed, the
-              VM is terminated.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
-          <glossdef>
-            <para>The VM is immediately powered-off without showing any message
-              window. The VM logfile will show information about what happened.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>Ignore</computeroutput></glossterm>
-          <glossdef>
-            <para>The VM is left in stuck mode. Execution is stopped but no
-            message window is shown. The VM has to be powered off manually.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>This is a per-VM setting.</para>
+        open a bug report.
+      </para>
+
+      <para>
+        This behavior can be configured:
+      </para>
+
+      <para>
+<screen>VBoxManage setextradata "VM name" GUI/GuruMeditationHandler MODE</screen>
+      </para>
+
+      <para>
+        where <computeroutput>MODE</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Default</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              A message window is shown. After the user confirmed, the
+              VM is terminated.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>PowerOff</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The VM is immediately powered-off without showing any
+              message window. The VM logfile will show information about
+              what happened.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Ignore</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The VM is left in stuck mode. Execution is stopped but no
+              message window is shown. The VM has to be powered off
+              manually.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Configuring automatic mouse capturing</title>
-
-      <para>
-        By default, the mouse is captured if the user clicks on the guest window
-        and the guest expects relative mouse coordinates at this time. This
-        happens if the pointing device is configured as PS/2 mouse and the guest did
-        not (yet) start the VirtualBox Guest Additions (for instance, the guest is
-        booting or no Guest Additions installed at all) or if the pointing device
-        is configured as USB tablet but the guest has no USB driver loaded yet.
-        Once the Guest Additions become active or the USB guest driver is started,
-        the mouse capture is automatically released.
-      </para>
-      <para>
-        The default behavior is sometimes not desired. Therefore it can be configured:
-      </para>
-      <para><screen>VBoxManage setextradata "VM name" GUI/MouseCapturePolicy MODE</screen></para>
-
-      <para>where <computeroutput>MODE</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>Default</computeroutput></glossterm>
-          <glossdef>
-            <para>The default behavior as described above.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>HostComboOnly</computeroutput></glossterm>
-          <glossdef>
-            <para>The mouse is only captured if the Host Key is toggled.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Disabled</computeroutput></glossterm>
-          <glossdef>
-            <para>The mouse is never captured, also not by toggling the Host Key</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>This is a per-VM setting.</para>
+    <sect2 id="mouse-capture">
+
+      <title>Configuring Automatic Mouse Capturing</title>
+
+      <para>
+        By default, the mouse is captured if the user clicks on the
+        guest window and the guest expects relative mouse coordinates at
+        this time. This happens if the pointing device is configured as
+        PS/2 mouse and the guest has not yet started the VirtualBox
+        Guest Additions. For instance, the guest is booting or the Guest
+        Additions are not installed, or if the pointing device is
+        configured as a USB tablet but the guest has no USB driver
+        loaded yet. Once the Guest Additions become active or the USB
+        guest driver is started, the mouse capture is automatically
+        released.
+      </para>
+
+      <para>
+        The default behavior is sometimes not desired. Therefore it can
+        be configured:
+      </para>
+
+      <para>
+<screen>VBoxManage setextradata "VM name" GUI/MouseCapturePolicy MODE</screen>
+      </para>
+
+      <para>
+        where <computeroutput>MODE</computeroutput> is one of the
+        following keywords:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Default</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The default behavior as described above.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>HostComboOnly</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The mouse is only captured if the Host Key is toggled.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <computeroutput>Disabled</computeroutput>
+          </term>
+
+          <listitem>
+            <para>
+              The mouse is never captured, also not by toggling the Host
+              Key
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        This is a per-VM setting.
+      </para>
 
     </sect2>
 
-    <sect2 id="mouse-capture">
-      <title>Configuring automatic mouse capturing</title>
-
-      <para>
-        By default, the mouse is captured if the user clicks on the guest window
-        and the guest expects relative mouse coordinates at this time. This
-        happens if the pointing device is configured as PS/2 mouse and the guest did
-        not (yet) start the VirtualBox Guest Additions (for instance, the guest is
-        booting or no Guest Additions installed at all) or if the pointing device
-        is configured as USB tablet but the guest has no USB driver loaded yet.
-        Once the Guest Additions become active or the USB guest driver is started,
-        the mouse capture is automatically released.
-      </para>
-      <para>
-        The default behavior is sometimes not desired. Therefore it can be configured:
-      </para>
-      <para><screen>VBoxManage setextradata "VM name" GUI/MouseCapturePolicy MODE</screen></para>
-
-      <para>where <computeroutput>MODE</computeroutput> is one of the
-        following keywords:</para><glosslist>
-        <glossentry>
-          <glossterm><computeroutput>Default</computeroutput></glossterm>
-          <glossdef>
-            <para>The default behavior as described above.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>HostComboOnly</computeroutput></glossterm>
-          <glossdef>
-            <para>The mouse is only captured if the Host Key is toggled.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>Disabled</computeroutput></glossterm>
-          <glossdef>
-            <para>The mouse is never captured, also not by toggling the Host Key</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>This is a per-VM setting.</para>
+    <sect2 id="legacy-fullscreen-mode">
+
+      <title>Requesting Legacy Full-Screen Mode</title>
+
+      <para>
+        As of version 4.3.16, VirtualBox uses special window manager
+        facilities to switch a multi-screen machine to full-screen on a
+        multi-monitor host system. However, not all window managers
+        provide these facilities correctly, so VirtualBox can be told to
+        use the old method of switching to full-screen mode instead
+        using the command:
+      </para>
+
+      <para>
+<screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode true</screen>
+      </para>
+
+      <para>
+        You can go back to the new method using the command:
+      </para>
+
+      <para>
+<screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode</screen>
+      </para>
+
+      <para>
+        This is a global setting.
+      </para>
 
     </sect2>
 
-    <sect2 id="legacy-fullscreen-mode">
-      <title>Requesting legacy full-screen mode</title>
-
-      <para>
-        As of version 4.3.16, VirtualBox uses special window manager facilities to switch
-        a multi-screen machine to full-screen on a multi-monitor host system. However,
-        not all window managers provide these facilities correctly, so VirtualBox can be
-        told to use the old method of switching to full-screen mode instead using the command:
-      </para>
-      <para><screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode true</screen></para>
-
-      <para>
-        You can go back to the new method using the command:
-      </para>
-      <para><screen>VBoxManage setextradata global GUI/Fullscreen/LegacyMode</screen></para>
-
-      <para>This is a global setting.</para>
+  </sect1>
+
+  <sect1 id="vboxwebsrv-daemon">
+
+    <title>Starting the VirtualBox Web Service Automatically</title>
+
+    <para>
+      The VirtualBox web service,
+      <computeroutput>vboxwebsrv</computeroutput>, is used for
+      controlling VirtualBox remotely. It is documented in detail in the
+      VirtualBox Software Development Kit (SDK). See
+      <xref linkend="VirtualBoxAPI" />. As the client base using this
+      interface is growing, we added start scripts for the various
+      operation systems we support. The following sections describe how
+      to use them. The VirtualBox web service is never started
+      automatically as a result of a standard installation.
+    </para>
+
+    <sect2 id="vboxwebsrv-linux">
+
+      <title>Linux: Starting the Web Service via init</title>
+
+      <para>
+        On Linux, the web service can be automatically started during
+        host boot by adding appropriate parameters to the file
+        <computeroutput>/etc/default/virtualbox</computeroutput>. There
+        is one mandatory parameter,
+        <computeroutput>VBOXWEB_USER</computeroutput>, which must be set
+        to the user which will later start the VMs. The parameters in
+        <xref linkend="table-websrv-config-params"/> all start with the
+        <computeroutput>VBOXWEB_</computeroutput> prefix string. For
+        example: <computeroutput>VBOXWEB_HOST</computeroutput> and
+        <computeroutput>VBOXWEB_PORT</computeroutput>.
+
+        <table id="table-websrv-config-params">
+          <title>Web Service Configuration Parameters</title>
+          <tgroup cols="3">
+            <thead>
+              <row>
+                <entry><emphasis role="bold">Parameter</emphasis></entry>
+                <entry><emphasis role="bold">Description</emphasis></entry>
+                <entry><emphasis role="bold">Default</emphasis></entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry><computeroutput>USER</computeroutput></entry>
+                <entry>The user as which the web service runs</entry>
+                <entry></entry>
+              </row>
+              <row>
+                <entry><computeroutput>HOST</computeroutput></entry>
+                <entry>The host to bind the web service to</entry>
+                <entry>localhost</entry>
+              </row>
+              <row>
+                <entry><computeroutput>PORT</computeroutput></entry>
+                <entry>The port to bind the web service to</entry>
+                <entry>18083</entry>
+              </row>
+              <row>
+                <entry><computeroutput>SSL_KEYFILE</computeroutput></entry>
+                <entry>Server key and certificate file, PEM format</entry>
+                <entry></entry>
+              </row>
+              <row>
+                <entry><computeroutput>SSL_PASSWORDFILE</computeroutput></entry>
+                <entry>File name for password to server key</entry>
+                <entry></entry>
+              </row>
+              <row>
+                <entry><computeroutput>SSL_CACERT</computeroutput></entry>
+                <entry>CA certificate file, PEM format</entry>
+                <entry></entry>
+              </row>
+              <row>
+                <entry><computeroutput>SSL_CAPATH</computeroutput></entry>
+                <entry>CA certificate path</entry>
+                <entry></entry>
+              </row>
+              <row>
+                <entry><computeroutput>SSL_DHFILE</computeroutput></entry>
+                <entry>DH file name or DH key length in bits</entry>
+                <entry></entry>
+              </row>
+              <row>
+                <entry><computeroutput>SSL_RANDFILE</computeroutput></entry>
+                <entry>File containing seed for random number generator</entry>
+                <entry></entry>
+              </row>
+              <row>
+                <entry><computeroutput>TIMEOUT</computeroutput></entry>
+                <entry>Session timeout in seconds; 0 disables timeouts</entry>
+                <entry>300</entry>
+              </row>
+              <row>
+                <entry><computeroutput>CHECK_INTERVAL</computeroutput></entry>
+                <entry>Frequency of timeout checks in seconds</entry>
+                <entry>5</entry>
+              </row>
+              <row>
+                <entry><computeroutput>THREADS</computeroutput></entry>
+                <entry>Maximum number of worker threads to run in parallel</entry>
+                <entry>100</entry>
+              </row>
+              <row>
+                <entry><computeroutput>KEEPALIVE</computeroutput></entry>
+                <entry>Maximum number of requests before a socket will be closed</entry>
+                <entry>100</entry>
+              </row>
+              <row>
+                <entry><computeroutput>ROTATE</computeroutput></entry>
+                <entry>Number of log files; 0 disables log rotation</entry>
+                <entry>10</entry>
+              </row>
+              <row>
+                <entry><computeroutput>LOGSIZE</computeroutput></entry>
+                <entry>Maximum size of a log file in bytes to trigger rotation</entry>
+                <entry>1MB</entry>
+              </row>
+              <row>
+                <entry><computeroutput>LOGINTERVAL</computeroutput></entry>
+                <entry>Maximum time interval in seconds to trigger log rotation</entry>
+                <entry>1 day</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table>
+      </para>
+
+      <para>
+        Setting the parameter
+        <computeroutput>SSL_KEYFILE</computeroutput> enables the SSL/TLS
+        support. Using encryption is strongly encouraged, as otherwise
+        everything (including passwords) is transferred in clear text.
+      </para>
+
     </sect2>
+
+    <sect2 id="vboxwebsrv-solaris">
+
+      <title>Solaris: Starting the Web Service via SMF</title>
+
+      <para>
+        On Solaris hosts, the VirtualBox web service daemon is
+        integrated into the SMF framework. You can change the
+        parameters, but do not have to if the defaults below already
+        match your needs:
+
+<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
+svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
+svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen>
+      </para>
+
+      <para>
+        <xref linkend="table-websrv-config-params"/> showing the
+        parameter names and defaults also applies for Solaris. The
+        parameter names must be changed to lowercase and a prefix of
+        <computeroutput>config/</computeroutput> has to be added. For
+        example: <computeroutput>config/user</computeroutput> or
+        <computeroutput>config/ssl_keyfile</computeroutput>. If you make
+        any change, do not forget to run the following command to put
+        the changes into effect immediately:
+
+<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen>
+      </para>
+
+      <para>
+        If you forget the above command then the previous settings are
+        used when enabling the service. Check the current property
+        settings with:
+
+<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen>
+      </para>
+
+      <para>
+        When everything is configured correctly you can start the
+        VirtualBox web service with the following command:
+
+<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen>
+      </para>
+
+      <para>
+        For more information about SMF, please refer to the Solaris
+        documentation.
+      </para>
+
+    </sect2>
+
+    <sect2 id="vboxwebsrv-osx">
+
+      <title>Mac OS X: Starting the Web Service via launchd</title>
+
+      <para>
+        On Mac OS X, launchd is used to start the VirtualBox webservice.
+        An example configuration file can be found in
+        <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
+        It can be enabled by changing the
+        <computeroutput>Disabled</computeroutput> key from
+        <computeroutput>true</computeroutput> to
+        <computeroutput>false</computeroutput>. To manually start the
+        service use the following command:
+
+<screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
+
+        For additional information on how launchd services could be
+        configured see:
+      </para>
+
+      <para>
+        <ulink
+      url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html</ulink>.
+      </para>
+
+    </sect2>
+
   </sect1>
 
-  <sect1 id="vboxwebsrv-daemon">
-    <title>Starting the VirtualBox web service automatically</title>
-
-    <para>The VirtualBox web service
-    (<computeroutput>vboxwebsrv</computeroutput>) is used for controlling
-    VirtualBox remotely. It is documented in detail in the VirtualBox Software
-    Development Kit (SDK); please see <xref linkend="VirtualBoxAPI" />. As the
-    client base using this interface is growing, we added start scripts for
-    the various operation systems we support. The following sections describe
-    how to use them. The VirtualBox web service is never started automatically
-    as a result of a standard installation.</para>
-
-    <sect2 id="vboxwebsrv-linux">
-      <title>Linux: starting the webservice via <computeroutput>init</computeroutput></title>
-
-      <para>On Linux, the web service can be automatically started during
-      host boot by adding appropriate parameters to the file
-      <computeroutput>/etc/default/virtualbox</computeroutput>.
-      There is one mandatory parameter, <computeroutput>VBOXWEB_USER</computeroutput>,
-      which must be set to the user which will later start the VMs. The
-      parameters in the table below all start with <computeroutput>VBOXWEB_</computeroutput>
-      (<computeroutput>VBOXWEB_HOST</computeroutput>,
-      <computeroutput>VBOXWEB_PORT</computeroutput> etc.):
-      <table>
-        <title>Web service configuration parameters</title>
-        <tgroup cols="3">
-          <thead>
-            <row>
-              <entry><emphasis role="bold">Parameter</emphasis></entry>
-              <entry><emphasis role="bold">Description</emphasis></entry>
-              <entry><emphasis role="bold">Default</emphasis></entry>
-            </row>
-          </thead>
-          <tbody>
-            <row>
-              <entry><computeroutput>USER</computeroutput></entry>
-              <entry>The user as which the web service runs</entry>
-              <entry></entry>
-            </row>
-            <row>
-              <entry><computeroutput>HOST</computeroutput></entry>
-              <entry>The host to bind the web service to</entry>
-              <entry>localhost</entry>
-            </row>
-            <row>
-              <entry><computeroutput>PORT</computeroutput></entry>
-              <entry>The port to bind the web service to</entry>
-              <entry>18083</entry>
-            </row>
-            <row>
-              <entry><computeroutput>SSL_KEYFILE</computeroutput></entry>
-              <entry>Server key and certificate file, PEM format</entry>
-              <entry></entry>
-            </row>
-            <row>
-              <entry><computeroutput>SSL_PASSWORDFILE</computeroutput></entry>
-              <entry>File name for password to server key</entry>
-              <entry></entry>
-            </row>
-            <row>
-              <entry><computeroutput>SSL_CACERT</computeroutput></entry>
-              <entry>CA certificate file, PEM format</entry>
-              <entry></entry>
-            </row>
-            <row>
-              <entry><computeroutput>SSL_CAPATH</computeroutput></entry>
-              <entry>CA certificate path</entry>
-              <entry></entry>
-            </row>
-            <row>
-              <entry><computeroutput>SSL_DHFILE</computeroutput></entry>
-              <entry>DH file name or DH key length in bits</entry>
-              <entry></entry>
-            </row>
-            <row>
-              <entry><computeroutput>SSL_RANDFILE</computeroutput></entry>
-              <entry>File containing seed for random number generator</entry>
-              <entry></entry>
-            </row>
-            <row>
-              <entry><computeroutput>TIMEOUT</computeroutput></entry>
-              <entry>Session timeout in seconds; 0 disables timeouts</entry>
-              <entry>300</entry>
-            </row>
-            <row>
-              <entry><computeroutput>CHECK_INTERVAL</computeroutput></entry>
-              <entry>Frequency of timeout checks in seconds</entry>
-              <entry>5</entry>
-            </row>
-            <row>
-              <entry><computeroutput>THREADS</computeroutput></entry>
-              <entry>Maximum number of worker threads to run in parallel</entry>
-              <entry>100</entry>
-            </row>
-            <row>
-              <entry><computeroutput>KEEPALIVE</computeroutput></entry>
-              <entry>Maximum number of requests before a socket will be closed</entry>
-              <entry>100</entry>
-            </row>
-            <row>
-              <entry><computeroutput>ROTATE</computeroutput></entry>
-              <entry>Number of log files; 0 disables log rotation</entry>
-              <entry>10</entry>
-            </row>
-            <row>
-              <entry><computeroutput>LOGSIZE</computeroutput></entry>
-              <entry>Maximum size of a log file in bytes to trigger rotation</entry>
-              <entry>1MB</entry>
-            </row>
-            <row>
-              <entry><computeroutput>LOGINTERVAL</computeroutput></entry>
-              <entry>Maximum time interval in seconds to trigger log rotation</entry>
-              <entry>1 day</entry>
-            </row>
-          </tbody>
-        </tgroup>
-      </table>
-      </para>
-
-      <para>Setting the parameter <computeroutput>SSL_KEYFILE</computeroutput>
-      enables the SSL/TLS support. Using encryption is strongly encouraged, as
-      otherwise everything (including passwords) is transferred in clear
-      text.</para>
+  <sect1 id="vboxwatchdog">
+
+    <title>VirtualBox Watchdog</title>
+
+    <para>
+      Starting with VirtualBox 4.2 the memory ballooning service
+      formerly known as <computeroutput>VBoxBalloonCtrl</computeroutput>
+      was renamed to VBoxWatchdog, which now incorporates several host
+      services that are meant to be run in a server environment.
+    </para>
+
+    <para>
+      These services are as follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Memory ballooning control, which automatically takes care of a
+          VM's configured memory balloon. See
+          <xref linkend="guestadd-balloon" />. This service is useful
+          for server environments where VMs may dynamically require more
+          or less memory during runtime.
+        </para>
+
+        <para>
+          The service periodically checks a VM's current memory balloon
+          and its free guest RAM and automatically adjusts the current
+          memory balloon by inflating or deflating it accordingly. This
+          handling only applies to running VMs having recent Guest
+          Additions installed.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Host isolation detection, which provides a way to detect
+          whether the host cannot reach the specific VirtualBox server
+          instance anymore and take appropriate actions, such as
+          shutting down, saving the current state or even powering down
+          certain VMs.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      All configuration values can be either specified via command line
+      or global extradata, whereas command line values always have a
+      higher priority when set. Some of the configuration values also be
+      specified on a per-VM basis. So the overall lookup order is:
+      command line, per-VM basis extradata (if available), global
+      extradata.
+    </para>
+
+    <sect2 id="vboxwatchdog-ballonctrl">
+
+      <title>Memory Ballooning Control</title>
+
+      <para>
+        The memory ballooning control inflates and deflates the memory
+        balloon of VMs based on the VMs free memory and the desired
+        maximum balloon size.
+      </para>
+
+      <para>
+        To set up the memory ballooning control the maximum ballooning
+        size a VM can reach needs to be set. This can be specified via
+        the command line with:
+
+<screen>--balloon-max &lt;Size in MB&gt;</screen>
+
+        or on a per-VM basis extradata value with:
+
+<screen>VBoxManage setextradata &lt;VM-Name&gt; VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
+
+        or using a global extradata value with:
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
+
+        <note>
+          <para>
+            If no maximum ballooning size is specified by at least one
+            of the parameters above, no ballooning will be performed at
+            all.
+          </para>
+        </note>
+      </para>
+
+      <para>
+        Setting the ballooning increment in MB can be either done via
+        command line with:
+
+<screen>--balloon-inc &lt;Size in MB&gt;</screen>
+
+        or using a global extradata value with:
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB &lt;Size in MB&gt;</screen>
+
+        The default ballooning increment is 256 MB if not specified.
+      </para>
+
+      <para>
+        The same options apply for a ballooning decrement. Using the
+        command line with:
+
+<screen>--balloon-dec &lt;Size in MB&gt;</screen>
+
+        or using a global extradata value with:
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB &lt;Size in MB&gt;</screen>
+
+        The default ballooning decrement is 128 MB if not specified.
+      </para>
+
+      <para>
+        To define the lower limit in MB a balloon can be the command
+        line with:
+
+<screen>--balloon-lower-limit &lt;Size in MB&gt;</screen>
+
+        can be used or using a global extradata value with:
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB &lt;Size in MB&gt;</screen>
+
+        is available. Default lower limit is 128 if not specified.
+      </para>
+
     </sect2>
 
-    <sect2 id="vboxwebsrv-solaris">
-      <title>Solaris: starting the web service via SMF</title>
-
-      <para>On Solaris hosts, the VirtualBox web service daemon is
-      integrated into the SMF framework. You can change the parameters, but
-      don't have to if the defaults below already match your needs:<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
-svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
-svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen></para>
-
-      <para>The table in the previous section showing the parameter names and
-      defaults also applies to Solaris. The parameter names must be changed
-      to lowercase and a prefix of <computeroutput>config/</computeroutput>
-      has to be added, e.g. <computeroutput>config/user</computeroutput> or
-      <computeroutput>config/ssl_keyfile</computeroutput>. If you made any
-      change, don't forget to run the following command to put the changes into
-      effect immediately:<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen></para>
-
-      <para>If you forget the above command then the previous settings will
-      be used when enabling the service. Check the current property settings
-      with:<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen></para>
-
-      <para>When everything is configured correctly you can start the
-      VirtualBox web service with the following command:<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen></para>
-
-      <para>For more information about SMF, please refer to the Solaris
-      documentation.</para>
+    <sect2 id="vboxwatchdog-hostisln">
+
+      <title>Host Isolation Detection</title>
+
+      <para>
+        To detect whether a host is being isolated, that is, the host
+        cannot reach the VirtualBox server instance anymore, the host
+        needs to set an alternating value to a global extradata value
+        within a time period. If this value is not set within that time
+        period a timeout occurred and the so-called host isolation
+        response will be performed to the VMs handled. Which VMs are
+        handled can be controlled by defining VM groups and assigning
+        VMs to those groups. By default no groups are set, meaning that
+        all VMs on the server will be handled when no host response is
+        received within 30 seconds.
+      </para>
+
+      <para>
+        To set the groups handled by the host isolation detection via
+        command line:
+
+<screen>--apimon-groups=&lt;string[,stringN]&gt;</screen>
+
+        or using a global extradata value with:
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups &lt;string[,stringN]&gt;</screen>
+      </para>
+
+      <para>
+        To set the host isolation timeout via command line:
+
+<screen>--apimon-isln-timeout=&lt;ms&gt;</screen>
+
+        or using a global extradata value with:
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS &lt;ms&gt;</screen>
+      </para>
+
+      <para>
+        To set the actual host isolation response via command line:
+
+<screen>--apimon-isln-response=&lt;cmd&gt;</screen>
+
+        or using a global extradata value with:
+
+<screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse &lt;cmd&gt;</screen>
+
+        The following response commands are available:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <computeroutput>none</computeroutput>. This has no effect.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>pause</computeroutput>. Pauses the execution
+            of a VM.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>poweroff</computeroutput>. Shuts down the VM
+            by pressing the virtual power button. The VM will not have
+            the chance of saving any data or veto the shutdown process.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>save</computeroutput>. Saves the current
+            machine state and powers off the VM afterwards. If saving
+            the machine state fails the VM will be paused.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>shutdown</computeroutput>. Shuts down the VM
+            in a gentle way by sending an
+            <computeroutput>ACPI</computeroutput> shutdown event to the
+            VM's operating system. The OS then has the chance of doing a
+            clean shutdown.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </sect2>
 
-    <sect2 id="vboxwebsrv-osx">
-      <title>Mac OS X: starting the webservice via launchd</title>
-
-      <para>On Mac OS X, launchd is used to start the VirtualBox webservice. An
-      example configuration file can be found in
-      <computeroutput>$HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</computeroutput>.
-      It can be enabled by changing the
-      <computeroutput>Disabled</computeroutput> key from
-      <computeroutput>true</computeroutput> to
-      <computeroutput>false</computeroutput>. To manually start the
-      service use the following command: <screen>launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist</screen>
-      For additional information on how launchd services could be
-      configured see <literal><ulink
-      url="https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html">https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html</ulink></literal>.</para>
+    <sect2 id="vboxwatchdog-moreinfo">
+
+      <title>More Information</title>
+
+      <para>
+        For more advanced options and parameters like verbose logging
+        check the built-in command line help accessible with
+        <computeroutput>--help</computeroutput>.
+      </para>
+
     </sect2>
+
+    <sect2 id="vboxwatchdog-linux">
+
+      <title>Linux: Starting the Watchdog Service via init</title>
+
+      <para>
+        On Linux, the watchdog service can be automatically started
+        during host boot by adding appropriate parameters to the file
+        <computeroutput>/etc/default/virtualbox</computeroutput>. There
+        is one mandatory parameter,
+        <computeroutput>VBOXWATCHDOG_USER</computeroutput>, which must
+        be set to the user which will later start the VMs. For backward
+        compatibility you can also specify
+        <computeroutput>VBOXBALLOONCTRL_USER</computeroutput>.
+      </para>
+
+      <para>
+        The parameters in
+        <xref linkend="table-vboxwatchdog-config-params"/> all start
+        with the <computeroutput>VBOXWATCHDOG_</computeroutput> prefix
+        string. For example:
+        <computeroutput>VBOXWATCHDOG_BALLOON_INTERVAL</computeroutput>
+        and <computeroutput>VBOXWATCHDOG_LOGSIZE</computeroutput>.
+        Legacy parameters such as
+        <computeroutput>VBOXBALLOONCTRL_INTERVAL</computeroutput> can
+        still be used.
+
+        <table id="table-vboxwatchdog-config-params">
+          <title>VirtualBox Watchdog Configuration Parameters</title>
+          <tgroup cols="3">
+            <thead>
+              <row>
+                <entry><emphasis role="bold">Parameter</emphasis></entry>
+                <entry><emphasis role="bold">Description</emphasis></entry>
+                <entry><emphasis role="bold">Default</emphasis></entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry><computeroutput>USER</computeroutput></entry>
+                <entry>The user as which the watchdog service runs</entry>
+                <entry></entry>
+              </row>
+              <row>
+                <entry><computeroutput>ROTATE</computeroutput></entry>
+                <entry>Number of log files; 0 disables log rotation</entry>
+                <entry>10</entry>
+              </row>
+              <row>
+                <entry><computeroutput>LOGSIZE</computeroutput></entry>
+                <entry>Maximum size of a log file in bytes to trigger rotation</entry>
+                <entry>1MB</entry>
+              </row>
+              <row>
+                <entry><computeroutput>LOGINTERVAL</computeroutput></entry>
+                <entry>Maximum time interval in seconds to trigger log rotation</entry>
+                <entry>1 day</entry>
+              </row>
+              <row>
+                <entry><computeroutput>BALLOON_INTERVAL</computeroutput></entry>
+                <entry>Interval for checking the balloon size (msec)</entry>
+                <entry>30000</entry>
+              </row>
+              <row>
+                <entry><computeroutput>BALLOON_INCREMENT</computeroutput></entry>
+                <entry>Balloon size increment (MByte)</entry>
+                <entry>256</entry>
+              </row>
+              <row>
+                <entry><computeroutput>BALLOON_DECREMENT</computeroutput></entry>
+                <entry>Balloon size decrement (MByte)</entry>
+                <entry>128</entry>
+              </row>
+              <row>
+                <entry><computeroutput>BALLOON_LOWERLIMIT</computeroutput></entry>
+                <entry>Balloon size lower limit (MByte)</entry>
+                <entry>64</entry>
+              </row>
+              <row>
+                <entry><computeroutput>BALLOON_SAFETYMARGIN</computeroutput></entry>
+                <entry>Free memory required for decreasing the balloon size (MByte)</entry>
+                <entry>1024</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </table>
+      </para>
+
+    </sect2>
+
+    <sect2 id="vboxwatchdog-solaris">
+
+      <title>Solaris: Starting the Watchdog Service via SMF</title>
+
+      <para>
+        On Solaris hosts, the VirtualBox watchdog service daemon is
+        integrated into the SMF framework. You can change the
+        parameters, but do not have to if the defaults already match
+        your needs:
+      </para>
+
+<screen>svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \
+  config/balloon_interval=10000
+svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \
+config/balloon_safetymargin=134217728</screen>
+
+      <para>
+        <xref linkend="table-vboxwatchdog-config-params"/> also applies
+        for Solaris. The parameter names must be changed to lowercase
+        and a prefix of <computeroutput>config/</computeroutput> has to
+        be added. For example:
+        <computeroutput>config/user</computeroutput> or
+        <computeroutput>config/balloon_safetymargin</computeroutput>. If
+        you made any change, do not forget to run the following command
+        to put the changes into effect immediately:
+
+<screen>svcadm refresh svc:/application/virtualbox/balloonctrl:default</screen>
+      </para>
+
+      <para>
+        If you forget the above command then the previous settings will
+        be used when enabling the service. Check the current property
+        settings with:
+
+<screen>svcprop -p config svc:/application/virtualbox/balloonctrl:default</screen>
+      </para>
+
+      <para>
+        When everything is configured correctly you can start the
+        VirtualBox watchdog service with the following command:
+
+<screen>svcadm enable svc:/application/virtualbox/balloonctrl:default</screen>
+      </para>
+
+      <para>
+        For more information about SMF, please refer to the Solaris
+        documentation.
+      </para>
+
+    </sect2>
+
   </sect1>
 
-  <sect1 id="vboxwatchdog">
-    <title>VirtualBox Watchdog</title>
-    <para>Starting with VirtualBox 4.2 the memory ballooning service formerly
-    known as <computeroutput>VBoxBalloonCtrl</computeroutput> was renamed to
-    VBoxWatchdog, which now incorporates several host services that are meant
-    to be run in a server environment.</para>
-
-    <para>These services are: <itemizedlist>
-        <listitem>
-            <para>Memory ballooning control, which automatically takes care of
-            a VM's configured memory balloon (see <xref linkend="guestadd-balloon" />
-            for an introduction to memory ballooning). This especially is useful
-            for server environments where VMs may dynamically require more or
-            less memory during runtime.</para>
-
-            <para>The service periodically checks a VM's current memory balloon
-            and its free guest RAM and automatically adjusts the current memory
-            balloon by inflating or deflating it accordingly. This handling only
-            applies to running VMs having recent Guest Additions installed.</para>
-        </listitem>
-        <listitem>
-            <para>Host isolation detection, which provides a way to detect whether
-            the host cannot reach the specific VirtualBox server instance anymore
-            and take appropriate actions, such as shutting down, saving the
-            current state or even powering down certain VMs.</para>
-        </listitem>
-    </itemizedlist></para>
-
-    <para>
-    All configuration values can be either specified via command line or global
-    extradata, whereas command line values always have a higher priority when set.
-    Some of the configuration values also be specified on a per-VM basis. So
-    the overall lookup order is: command line, per-VM basis extradata (if available),
-    global extradata.
-    </para>
-
-    <sect2 id="vboxwatchdog-ballonctrl">
-        <title>Memory ballooning control</title>
-        <para>The memory ballooning control inflates and deflates the memory balloon
-        of VMs based on the VMs free memory and the desired maximum balloon size.</para>
-
-        <para>To set up the memory ballooning control the maximum ballooning size a
-        VM can reach needs to be set. This can be specified via command line with
-        <screen>--balloon-max &lt;Size in MB&gt;</screen>, on a per-VM basis extradata value with
-        <screen>VBoxManage setextradata &lt;VM-Name&gt; VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
-        or using a global extradata value with
-        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax &lt;Size in MB&gt;</screen>
-        <note><para>If no maximum ballooning size is specified by at least one of
-            the parameters above, no ballooning will be performed at all.</para></note>
-        </para>
-
-        <para>Setting the ballooning increment in MB can be either done via
-        command line with
-        <screen>--balloon-inc &lt;Size in MB&gt;</screen> or using a global
-        extradata value with
-        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB &lt;Size in MB&gt;</screen>
-        Default ballooning increment is 256 MB if not specified.</para>
-
-        <para>Same goes with the ballooning decrement: Via command line with
-        <screen>--balloon-dec &lt;Size in MB&gt;</screen> or using a global
-        extradata value with
-        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB &lt;Size in MB&gt;</screen>
-        Default ballooning decrement is 128 MB if not specified.</para>
-
-        <para>To define the lower limit in MB a balloon can be the command line with
-        <screen>--balloon-lower-limit &lt;Size in MB&gt;</screen> can be used or using a global
-        extradata value with
-        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB &lt;Size in MB&gt;</screen>
-        is available. Default lower limit is 128 if not specified.</para>
-    </sect2>
-
-    <sect2 id="vboxwatchdog-hostisln">
-        <title>Host isolation detection</title>
-        <para>To detect whether a host is being isolated, that is, the host cannot
-        reach the VirtualBox server instance anymore, the host needs to set an
-        alternating value to a global extradata value within a time period. If
-        this value is not set within that time period a timeout occurred and the
-        so-called host isolation response will be performed to the VMs handled.
-        Which VMs are handled can be controlled by defining VM groups and assigning
-        VMs to those groups. By default no groups are set, meaning that all VMs
-        on the server will be handled when no host response is received within
-        30 seconds.</para>
-
-        <para>To set the groups handled by the host isolation detection via
-        command line:
-        <screen>--apimon-groups=&lt;string[,stringN]&gt;</screen> or using a global
-        extradata value with
-        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups &lt;string[,stringN]&gt;</screen>
-        </para>
-
-        <para>To set the host isolation timeout via command line:
-        <screen>--apimon-isln-timeout=&lt;ms&gt;</screen> or using a global
-        extradata value with
-        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS &lt;ms&gt;</screen>
-        </para>
-
-        <para>To set the actual host isolation response via command line:
-        <screen>--apimon-isln-response=&lt;cmd&gt;</screen> or using a global
-        extradata value with
-        <screen>VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse &lt;cmd&gt;</screen>
-        The following response commands are available:
-        <itemizedlist>
-            <listitem>
-                <para><computeroutput>none</computeroutput>, which does nothing.</para>
-            </listitem>
-            <listitem>
-                <para><computeroutput>pause</computeroutput>, which pauses the
-                execution of a VM.</para>
-            </listitem>
-            <listitem>
-                <para><computeroutput>poweroff</computeroutput>, which shuts down
-                the VM by pressing the virtual power button. The VM will not have
-                the chance of saving any data or veto the shutdown process.</para>
-            </listitem>
-            <listitem>
-                <para><computeroutput>save</computeroutput>, which saves the current
-                machine state and powers off the VM afterwards. If saving the machine
-                state fails the VM will be paused.</para>
-            </listitem>
-            <listitem>
-                <para><computeroutput>shutdown</computeroutput>, which shuts down
-                the VM in a gentle way by sending an <computeroutput>ACPI</computeroutput>
-                shutdown event to the VM's operating system. The OS then has the
-                chance of doing a clean shutdown.</para>
-            </listitem>
-        </itemizedlist>
-        </para>
-    </sect2>
-
-    <sect2 id="vboxwatchdog-moreinfo">
-        <title>More information</title>
-        <para>For more advanced options and parameters like verbose logging check
-        the built-in command line help accessible with
-        <computeroutput>--help</computeroutput>.</para>
-    </sect2>
-
-    <sect2 id="vboxwatchdog-linux">
-      <title>Linux: starting the watchdog service via <computeroutput>init</computeroutput></title>
-
-      <para>On Linux, the watchdog service can be automatically started during
-      host boot by adding appropriate parameters to the file
-      <computeroutput>/etc/default/virtualbox</computeroutput>.
-      There is one mandatory parameter, <computeroutput>VBOXWATCHDOG_USER</computeroutput>,
-      which must be set to the user which will later start the VMs. For backward
-      compatibility you can also specify <computeroutput>VBOXBALLOONCTRL_USER</computeroutput>The
-      parameters in the table below all start with <computeroutput>VBOXWATCHDOG_</computeroutput>
-      (<computeroutput>VBOXWATCHDOG_BALLOON_INTERVAL</computeroutput>,
-      <computeroutput>VBOXWATCHDOG_LOGSIZE</computeroutput> etc., and for
-      previously existing parameters the
-      <computeroutput>VBOXBALLOONCTRL_INTERVAL</computeroutput> etc. parameters
-      can still be used):
-      <table>
-        <title>VirtualBox watchdog configuration parameters</title>
-        <tgroup cols="3">
-          <thead>
-            <row>
-              <entry><emphasis role="bold">Parameter</emphasis></entry>
-              <entry><emphasis role="bold">Description</emphasis></entry>
-              <entry><emphasis role="bold">Default</emphasis></entry>
-            </row>
-          </thead>
-          <tbody>
-            <row>
-              <entry><computeroutput>USER</computeroutput></entry>
-              <entry>The user as which the watchdog service runs</entry>
-              <entry></entry>
-            </row>
-            <row>
-              <entry><computeroutput>ROTATE</computeroutput></entry>
-              <entry>Number of log files; 0 disables log rotation</entry>
-              <entry>10</entry>
-            </row>
-            <row>
-              <entry><computeroutput>LOGSIZE</computeroutput></entry>
-              <entry>Maximum size of a log file in bytes to trigger rotation</entry>
-              <entry>1MB</entry>
-            </row>
-            <row>
-              <entry><computeroutput>LOGINTERVAL</computeroutput></entry>
-              <entry>Maximum time interval in seconds to trigger log rotation</entry>
-              <entry>1 day</entry>
-            </row>
-            <row>
-              <entry><computeroutput>BALLOON_INTERVAL</computeroutput></entry>
-              <entry>Interval for checking the balloon size (msec)</entry>
-              <entry>30000</entry>
-            </row>
-            <row>
-              <entry><computeroutput>BALLOON_INCREMENT</computeroutput></entry>
-              <entry>Balloon size increment (MByte)</entry>
-              <entry>256</entry>
-            </row>
-            <row>
-              <entry><computeroutput>BALLOON_DECREMENT</computeroutput></entry>
-              <entry>Balloon size decrement (MByte)</entry>
-              <entry>128</entry>
-            </row>
-            <row>
-              <entry><computeroutput>BALLOON_LOWERLIMIT</computeroutput></entry>
-              <entry>Balloon size lower limit (MByte)</entry>
-              <entry>64</entry>
-            </row>
-            <row>
-              <entry><computeroutput>BALLOON_SAFETYMARGIN</computeroutput></entry>
-              <entry>Free memory required for decreasing the balloon size (MByte)</entry>
-              <entry>1024</entry>
-            </row>
-          </tbody>
-        </tgroup>
-      </table>
-      </para>
-    </sect2>
-
-    <sect2 id="vboxwatchdog-solaris">
-      <title>Solaris: starting the watchdog service via SMF</title>
-
-      <para>On Solaris hosts, the VirtualBox watchdog service daemon is
-      integrated into the SMF framework. You can change the parameters, but
-      don't have to if the defaults already match your needs:<screen>svccfg -s svc:/application/virtualbox/balloonctrl:default setprop config/balloon_interval=10000
-svccfg -s svc:/application/virtualbox/balloonctrl:default setprop config/balloon_safetymargin=134217728</screen></para>
-
-      <para>The table in the previous section showing the parameter names and
-      defaults also applies to Solaris. The parameter names must be changed
-      to lowercase and a prefix of <computeroutput>config/</computeroutput>
-      has to be added, e.g. <computeroutput>config/user</computeroutput> or
-      <computeroutput>config/balloon_safetymargin</computeroutput>. If you made any
-      change, don't forget to run the following command to put the changes into
-      effect immediately:<screen>svcadm refresh svc:/application/virtualbox/balloonctrl:default</screen></para>
-
-      <para>If you forget the above command then the previous settings will
-      be used when enabling the service. Check the current property settings
-      with:<screen>svcprop -p config svc:/application/virtualbox/balloonctrl:default</screen></para>
-
-      <para>When everything is configured correctly you can start the
-      VirtualBox watchdog service with the following command:<screen>svcadm enable svc:/application/virtualbox/balloonctrl:default</screen></para>
-
-      <para>For more information about SMF, please refer to the Solaris
-      documentation.</para>
-    </sect2>
+  <sect1 id="otherextpacks">
+
+    <title>Other Extension Packs</title>
+
+    <para>
+      Starting with VirtualBox 4.2.0 there is another extension pack,
+      <code>VNC</code>, which is open source and replaces the previous
+      integration of the VNC remote access protocol. This is
+      experimental code, and will be initially available in the
+      VirtualBox source code package only. It is to a large portion code
+      contributed by users, and is not supported in any way by Oracle.
+    </para>
+
+    <para>
+      The keyboard handling is severely limited, and only the US
+      keyboard layout works. Other keyboard layouts will have at least
+      some keys which produce the wrong results, often with quite
+      surprising effects, and for layouts which have significant
+      differences to the US keyboard layout it is most likely unusable.
+    </para>
+
+    <para>
+      It is possible to install both the Oracle VM VirtualBox Extension
+      Pack and VNC, but only one VRDE module can be active at any time.
+      The following command switches to the VNC VRDE module in VNC:
+
+<screen>VBoxManage setproperty vrdeextpack VNC</screen>
+    </para>
+
+    <para>
+      Configuring the remote access works very similarly to VRDP, see
+      <xref linkend="vrde" />, with some limitations. VNC does not
+      support specifying several port numbers, and the authentication is
+      done differently. VNC can only deal with password authentication,
+      and there is no option to use password hashes. This leaves no
+      other choice than having a clear-text password in the VM
+      configuration, which can be set with the following command:
+
+<screen>VBoxManage modifyvm "VM name" --vrdeproperty VNCPassword=secret</screen>
+    </para>
+
+    <para>
+      The user is responsible for keeping this password secret, and it
+      should be removed when a VM configuration is passed to another
+      person, for whatever purpose. Some VNC servers claim to have
+      "encrypted" passwords in the configuration. This is not true
+      encryption, it is only concealing the passwords, which is exactly
+      as secure as clear-text passwords.
+    </para>
+
+    <para>
+      The following command switches back to VRDP, if installed:
+
+<screen>VBoxManage setproperty vrdeextpack "Oracle VM VirtualBox Extension Pack"</screen>
+    </para>
+
   </sect1>
 
-  <sect1 id="otherextpacks">
-    <title>Other extension packs</title>
-
-    <para>Starting with VirtualBox 4.2.0 there is another extension pack,
-    <code>VNC</code>, which is open source and replaces the previous
-    integration of the VNC remote access protocol. This is experimental code,
-    and will be initially available in the VirtualBox source code package only.
-    It is to a large portion code contributed by users, and is not supported
-    in any way by Oracle.</para>
-
-    <para>The keyboard handling is severely limited, and only the US keyboard
-    layout works. Other keyboard layouts will have at least some keys which
-    produce the wrong results (often quite surprising effects), and for layouts
-    which have significant differences to the US keyboard layout it is most
-    likely unusable.</para>
-
-    <para>It is possible to install both the Oracle VM VirtualBox Extension
-    Pack and VNC, but only one VRDE module can be active at any time. The
-    following command switches to the VNC VRDE module in
-    VNC:<screen>VBoxManage setproperty vrdeextpack VNC</screen></para>
-
-    <para>Configuring the remote access works very similarly to VRDP (see
-    <xref linkend="vrde" />), with some limitations: VNC does not
-    support specifying several port numbers, and the authentication is done
-    differently. VNC can only deal with password authentication, and there
-    is no option to use password hashes. This leaves no other choice than
-    having a clear-text password in the VM configuration, which can be set with
-    the following command:<screen>VBoxManage modifyvm "VM name" --vrdeproperty VNCPassword=secret</screen></para>
-
-    <para>The user is responsible for keeping this password secret, and it
-    should be removed when a VM configuration is passed to another person,
-    for whatever purpose. Some VNC servers claim to have "encrypted" passwords
-    in the configuration. This is not true encryption, it is only concealing
-    the passwords, which is exactly as secure as clear-text passwords.</para>
-
-    <para>The following command switches back to VRDP (if
-    installed):<screen>VBoxManage setproperty vrdeextpack "Oracle VM VirtualBox Extension Pack"</screen></para>
-  </sect1>
-
   <sect1 id="autostart">
-    <title>Starting virtual machines during system boot</title>
-
-    <para>Starting with VirtualBox 4.2.0 it is possible to start VMs automatically during
-    system boot on Linux, Solaris and Mac OS X for all users. </para>
+
+    <title>Starting Virtual Machines During System Boot</title>
+
+    <para>
+      Starting with VirtualBox 4.2.0 it is possible to start VMs
+      automatically during system boot on Linux, Solaris and Mac OS X
+      for all users.
+    </para>
 
     <sect2 id="autostart-linux">
-      <title>Linux: starting the autostart service via <computeroutput>init</computeroutput></title>
-
-      <para>On Linux, the autostart service is activated by setting two variables in
-      <computeroutput>/etc/default/virtualbox</computeroutput>.
-      The first one is <computeroutput>VBOXAUTOSTART_DB</computeroutput> which
-      contains an absolute path to the autostart database directory.
-      The directory should have write access for every user who should be able to
-      start virtual machines automatically. Furthermore the directory should have the
-      sticky bit set.
-      The second variable is <computeroutput>VBOXAUTOSTART_CONFIG</computeroutput>
-      which points the service to the autostart configuration file which is used
-      during boot to determine whether to allow individual users to start a VM
-      automatically and configure startup delays.
-      The configuration file can be placed in <computeroutput>/etc/vbox</computeroutput>
-      and contains several options. One is <computeroutput>default_policy</computeroutput>
-      which controls whether the autostart service allows or denies to start a VM
-      for users which are not in the exception list.
-      The exception list starts with <computeroutput>exception_list</computeroutput>
-      and contains a comma separated list with usernames. Furthermore a separate
-      startup delay can be configured for every user to avoid overloading the host.
-      A sample configuration is given below:</para>
-
-      <para><screen>
+
+      <title>Linux: Starting the Autostart Service via init</title>
+
+      <para>
+        On Linux, the autostart service is activated by setting two
+        variables in
+        <computeroutput>/etc/default/virtualbox</computeroutput>. The
+        first one is <computeroutput>VBOXAUTOSTART_DB</computeroutput>
+        which contains an absolute path to the autostart database
+        directory. The directory should have write access for every user
+        who should be able to start virtual machines automatically.
+        Furthermore the directory should have the sticky bit set. The
+        second variable is
+        <computeroutput>VBOXAUTOSTART_CONFIG</computeroutput> which
+        points the service to the autostart configuration file which is
+        used during boot to determine whether to allow individual users
+        to start a VM automatically and configure startup delays. The
+        configuration file can be placed in
+        <computeroutput>/etc/vbox</computeroutput> and contains several
+        options. One is <computeroutput>default_policy</computeroutput>
+        which controls whether the autostart service allows or denies to
+        start a VM for users which are not in the exception list. The
+        exception list starts with
+        <computeroutput>exception_list</computeroutput> and contains a
+        comma separated list with usernames. Furthermore a separate
+        startup delay can be configured for every user to avoid
+        overloading the host. A sample configuration is given below:
+      </para>
+
+      <para>
+<screen>
 # Default policy is to deny starting a VM, the other option is "allow".
 default_policy = deny
@@ -3593,252 +5561,337 @@
     allow = false
 }
-      </screen></para>
-
-      <para>Every user who wants to enable autostart for individual machines
-      has to set the path to the autostart database directory with
-      <screen>VBoxManage setproperty autostartdbpath &lt;Autostart directory&gt;</screen>
-      </para>
+      </screen>
+      </para>
+
+      <para>
+        Every user who wants to enable autostart for individual machines
+        has to set the path to the autostart database directory with
+
+<screen>VBoxManage setproperty autostartdbpath &lt;Autostart directory&gt;</screen>
+      </para>
+
     </sect2>
 
     <sect2 id="autostart-solaris">
-      <title>Solaris: starting the autostart service via SMF</title>
-
-      <para>On Solaris hosts, the VirtualBox autostart daemon is
-      integrated into the SMF framework. To enable it you have to point the service
-      to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />):
-      <screen>svccfg -s svc:/application/virtualbox/autostart:default setprop config/config=/etc/vbox/autostart.cfg</screen>
-      </para>
-
-      <para>When everything is configured correctly you can start the
-      VirtualBox autostart service with the following command:<screen>svcadm enable svc:/application/virtualbox/autostart:default</screen></para>
-
-      <para>For more information about SMF, please refer to the Solaris
-      documentation.</para>
+
+      <title>Solaris: Starting the Autostart Service via SMF</title>
+
+      <para>
+        On Solaris hosts, the VirtualBox autostart daemon is integrated
+        into the SMF framework. To enable it you have to point the
+        service to an existing configuration file which has the same
+        format as on Linux, see <xref linkend="autostart-linux" />. For
+        example:
+
+<screen>svccfg -s svc:/application/virtualbox/autostart:default setprop \
+  config/config=/etc/vbox/autostart.cfg</screen>
+      </para>
+
+      <para>
+        When everything is configured correctly you can start the
+        VirtualBox autostart service with the following command:
+
+<screen>svcadm enable svc:/application/virtualbox/autostart:default</screen>
+      </para>
+
+      <para>
+        For more information about SMF, please refer to the Solaris
+        documentation.
+      </para>
+
     </sect2>
 
     <sect2 id="autostart-osx">
-      <title>Mac OS X: starting the autostart service via launchd</title>
-
-      <para>On Mac OS X, launchd is used to start the VirtualBox autostart service. An
-      example configuration file can be found in
-      <computeroutput>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</computeroutput>.
-      To enable the service copy the file to <computeroutput>/Library/LaunchDaemons</computeroutput> and change the
-      <computeroutput>Disabled</computeroutput> key from
-      <computeroutput>true</computeroutput> to
-      <computeroutput>false</computeroutput>. Furthermore replace the second parameter
-      to an existing configuration file which has the same format as on Linux (see <xref linkend="autostart-linux" />).
-      To manually start the service use the following command:
-      <screen>launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen>
-      For additional information on how launchd services could be
-      configured see <literal><ulink
-      url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html">http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ulink></literal>.</para>
+
+      <title>Mac OS X: Starting the Autostart Service via launchd</title>
+
+      <para>
+        On Mac OS X, launchd is used to start the VirtualBox autostart
+        service. An example configuration file can be found in
+        <computeroutput>/Applications/VirtualBox.app/Contents/MacOS/org.virtualbox.vboxautostart.plist</computeroutput>.
+        To enable the service copy the file to
+        <computeroutput>/Library/LaunchDaemons</computeroutput> and
+        change the <computeroutput>Disabled</computeroutput> key from
+        <computeroutput>true</computeroutput> to
+        <computeroutput>false</computeroutput>. Furthermore replace the
+        second parameter to an existing configuration file which has the
+        same format as on Linux, see <xref linkend="autostart-linux" />.
+        To manually start the service use the following command:
+
+<screen>launchctl load /Library/LaunchDaemons/org.virtualbox.vboxautostart.plist</screen>
+
+        For additional information on how launchd services could be
+        configured see:
+      </para>
+
+      <para>
+        <ulink
+      url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html">http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html</ulink>.
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="vboxexpertstoragemgmt">
-    <title>VirtualBox expert storage management</title>
-
-    <para>In case the snapshot model of VirtualBox is not sufficient
-    it is possible to enable a special mode which makes it possible to
-    reconfigure storage attachments while the VM is paused.
-    The user has to make sure that the disk data stays consistent to the guest
-    because unlike with hotplugging the guest is not informed about detached
-    or newly attached media.</para>
-
-    <para>The expert storage management mode can be enabled per VM executing:</para>
-
-    <screen>VBoxManage setextradata "VM name" "VBoxInternal2/SilentReconfigureWhilePaused" 1</screen>
-
-    <para>Storage attachments can be reconfigured while the VM is paused afterwards using:</para>
-    <screen>VBoxManage storageattach ...</screen>
+
+    <title>VirtualBox Expert Storage Management</title>
+
+    <para>
+      In case the snapshot model of VirtualBox is not sufficient it is
+      possible to enable a special mode which makes it possible to
+      reconfigure storage attachments while the VM is paused. The user
+      has to make sure that the disk data stays consistent to the guest
+      because unlike with hotplugging the guest is not informed about
+      detached or newly attached media.
+    </para>
+
+    <para>
+      The expert storage management mode can be enabled per VM
+      executing:
+    </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal2/SilentReconfigureWhilePaused" 1</screen>
+
+    <para>
+      Storage attachments can be reconfigured while the VM is paused
+      afterwards using:
+    </para>
+
+<screen>VBoxManage storageattach ...</screen>
+
   </sect1>
 
   <sect1 id="hostpowertweaks">
-    <title>Handling of host power management events</title>
-
-    <para>Some host power management events are handled by VirtualBox. The
-    actual behavior depends on the platform:</para>
-
-    <para>
-      <glosslist>
-        <glossentry>
-          <glossterm>Host Suspends</glossterm>
-           <glossdef>
-             <para>
-               This event is generated when the host is about to suspend, that is,
-               the host saves the state to some non-volatile storage and powers off.
-             </para>
-             <para>
-               This event is currently only handled on Windows hosts and Mac OS X hosts.
-               When this event is generated, VirtualBox will pause all running VMs.
-             </para>
-           </glossdef>
-         </glossentry>
-         <glossentry>
-           <glossterm>Host Resumes</glossterm>
-           <glossdef>
-             <para>
-               This event is generated when the host woke up from the suspended
-               state.
-             </para>
-             <para>
-               This event is currently only handled on Windows hosts and Mac OS X hosts.
-               When this event is generated, VirtualBox will resume all VMs which
-               are where paused before.
-             </para>
-           </glossdef>
-         </glossentry>
-         <glossentry>
-           <glossterm>Battery Low</glossterm>
-           <glossdef>
-             <para>
-               The battery level reached a critical level (usually less than 5
-               percent charged).
-             </para>
-             <para>
-               This event is currently only handled on Windows hosts and Mac OS X hosts.
-               When this event is generated, VirtualBox will save the state and
-               terminate all VMs in preparation of a potential host powerdown.
-             </para>
-             <para>The behavior can be configured. By executing the following command,
-             no VM is saved:</para>
-             <screen>VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 0</screen>
-             <para>This is a global setting as well as a per-VM setting. The per-VM
-               value has higher precedence than the global value. The following command
-               will save the state of all VMs but will not save the state of VM "foo":</para>
-             <screen>VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 1
+
+    <title>Handling of Host Power Management Events</title>
+
+    <para>
+      Some host power management events are handled by VirtualBox. The
+      actual behavior depends on the platform:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Host Suspends.</emphasis> This event is
+          generated when the host is about to suspend, that is, the host
+          saves the state to some non-volatile storage and powers off.
+        </para>
+
+        <para>
+          This event is currently only handled on Windows hosts and Mac
+          OS X hosts. When this event is generated, VirtualBox will
+          pause all running VMs.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Host Resumes.</emphasis> This event is
+          generated when the host woke up from the suspended state.
+        </para>
+
+        <para>
+          This event is currently only handled on Windows hosts and Mac
+          OS X hosts. When this event is generated, VirtualBox will
+          resume all VMs which are where paused before.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Battery Low.</emphasis> The battery
+          level reached a critical level, usually less than 5 percent
+          charged.
+        </para>
+
+        <para>
+          This event is currently only handled on Windows hosts and Mac
+          OS X hosts. When this event is generated, VirtualBox will save
+          the state and terminate all VMs in preparation of a potential
+          host powerdown.
+        </para>
+
+        <para>
+          The behavior can be configured. By executing the following
+          command, no VM is saved:
+        </para>
+
+<screen>VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 0</screen>
+
+        <para>
+          This is a global setting as well as a per-VM setting. The
+          per-VM value has higher precedence than the global value. The
+          following command will save the state of all VMs but will not
+          save the state of VM "foo":
+        </para>
+
+<screen>VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 1
 VBoxManage setextradata "foo" "VBoxInternal2/SavestateOnBatteryLow" 0</screen>
-             <para>The first line is actually not required as by default the savestate
-             action is performed.</para>
-           </glossdef>
-         </glossentry>
-       </glosslist>
-     </para>
-   </sect1>
-
-   <sect1 id="sse412passthrough">
-     <title>Passing through SSE4.1 / SSE4.2 instructions</title>
-     <para>
-       To provide SSE 4.1 / SSE 4.2 support to guests, the host CPU has to
-       implement these instruction sets. The instruction sets are exposed
-       to guests by default, but it is possible to disable the instructions
-       for certain guests using the following commands:</para>
+
+        <para>
+          The first line is actually not required as by default the
+          savestate action is performed.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="sse412passthrough">
+
+    <title>Passing Through SSE4.1/SSE4.2 Instructions</title>
+
+    <para>
+      To provide SSE 4.1/SSE 4.2 support to guests, the host CPU has to
+      implement these instruction sets. The instruction sets are exposed
+      to guests by default, but it is possible to disable the instructions
+      for certain guests using the following commands:</para>
 <screen>VBoxManage setextradata "VM name" VBoxInternal/CPUM/IsaExts/SSE4.1 0
 VBoxManage setextradata "VM name" VBoxInternal/CPUM/IsaExts/SSE4.2 0</screen>
-     <para>
-       These are a per-VM settings which are turned on by default.
-     </para>
-   </sect1>
+
+    <para>
+      These are a per-VM settings which are turned on by default.
+    </para>
+
+  </sect1>
 
   <sect1 id="hidledssync">
-    <title>Support for keyboard indicator synchronization</title>
-
-    <para>
-      This feature makes the host keyboard indicators (LEDs) match those of the virtual machine's emulated
-      keyboard when the machine window is active. It is currently implemented for Mac OS X and
-      Windows hosts. The feature is enabled by default (on a supported host OS), but can be disabled
-      using the following command:
-    </para>
-
-    <screen>VBoxManage setextradata "VM name" GUI/HidLedsSync 0</screen>
+
+    <title>Support for Keyboard Indicators Synchronization</title>
+
+    <para>
+      This feature makes the host keyboard lights match those of the
+      virtual machine's emulated keyboard when the machine window is
+      selected. It is currently implemented for Mac OS X and Windows
+      hosts. The feature is enabled by default (on a supported host OS),
+      but can be disabled using the following command:
+    </para>
+
+<screen>VBoxManage setextradata "VM name" GUI/HidLedsSync "0"</screen>
 
     <para>
       This is a per-VM setting and it is enabled by default.
     </para>
+
   </sect1>
 
   <sect1 id="usbtrafficcapturing">
-    <title>Capturing USB traffic for selected devices</title>
-
-    <para>
-      Starting with VirtualBox 5.0 it is possible to capture USB traffic for
-      single USB devices or on the root hub level which captures the traffic of
-      all USB devices attached to the root hub. VirtualBox stores the traffic
-      in a format which is compatible with Wireshark. To capture the traffic
-      of a specific USB device it must be attached to the VM with VBoxManage
-      using the following command:
-    </para>
-
-    <screen>VBoxManage controlvm "VM name" usbattach "device uuid|address" --capturefile "filename"</screen>
-
-    <para>
-      In order to enable capturing on the root hub use the following command
-      while the VM is not running:
-    </para>
-
-    <screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/usb-ehci/0/LUN#0/Config/CaptureFilename "filename"</screen>
-
-    <para>The command above enables capturing on the root hub attached to the EHCI controller.
-    To enable it for the OHCI or XHCI controller replace <computeroutput>usb-ehci</computeroutput>
-    with <computeroutput>usb-ohci</computeroutput> or <computeroutput>usb-xhci</computeroutput> respectively.</para>
+
+    <title>Capturing USB Traffic for Selected Devices</title>
+
+    <para>
+      Starting with VirtualBox 5.0 it is possible to capture USB traffic
+      for single USB devices or on the root hub level which captures the
+      traffic of all USB devices attached to the root hub. VirtualBox
+      stores the traffic in a format which is compatible with Wireshark.
+      To capture the traffic of a specific USB device it must be
+      attached to the VM with VBoxManage using the following command:
+    </para>
+
+<screen>VBoxManage controlvm "VM name" usbattach "device uuid|address" --capturefile "filename"</screen>
+
+    <para>
+      In order to enable capturing on the root hub use the following
+      command while the VM is not running:
+    </para>
+
+<screen>VBoxManage setextradata "VM name" \
+  VBoxInternal/Devices/usb-ehci/0/LUN#0/Config/CaptureFilename "filename"</screen>
+
+    <para>
+      The command above enables capturing on the root hub attached to
+      the EHCI controller. To enable it for the OHCI or XHCI controller
+      replace <computeroutput>usb-ehci</computeroutput> with
+      <computeroutput>usb-ohci</computeroutput> or
+      <computeroutput>usb-xhci</computeroutput> respectively.
+    </para>
+
   </sect1>
 
   <sect1 id="heartbeatservice">
-    <title>Configuring the heartbeat service</title>
-    <para>
-      VirtualBox ships a simple heartbeat service. Once the Guest Additions are
-      active, the guest sends frequent heartbeat pings to the host. If the guest
-      stops sending the heartbeat pings without properly terminating the service,
-      the VM process will log this event in the VBox.log file. In the future it
-      might be possible to configure dedicated actions but for now there is only a
-      warning in the log file.</para>
-
-    <para>
-      There are two parameters to configure. The <emphasis>heartbeat interval</emphasis>
-      defines the time between two heartbeat pings. The default value is 2 seconds, that
-      is, the heartbeat service of the VirtualBox Guest Additions will send a heartbeat
-      ping every two seconds. The value in nanoseconds can be configured like this:
-    </para>
-    <screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/VMMDev/0/Config/HeartbeatInterval 2000000000</screen>
-    <para>
-      The <emphasis>heartbeat timeout</emphasis> defines the time the host waits
-      starting from the last heartbeat ping before it defines the guest as unresponsive.
-      The default value is 2 times the heartbeat interval (4 seconds) and can be configured
-      as following (in nanoseconds):
-    </para>
-
-    <screen>VBoxManage setextradata "VM name" VBoxInternal/Devices/VMMDev/0/Config/HeartbeatTimeout 4000000000</screen>
+
+    <title>Configuring the Heartbeat Service</title>
+
+    <para>
+      VirtualBox ships a simple heartbeat service. Once the Guest
+      Additions are active, the guest sends frequent heartbeat pings to
+      the host. If the guest stops sending the heartbeat pings without
+      properly terminating the service, the VM process will log this
+      event in the VBox.log file. In the future it might be possible to
+      configure dedicated actions but for now there is only a warning in
+      the log file.
+    </para>
+
+    <para>
+      There are two parameters to configure. The <emphasis>heartbeat
+      interval</emphasis> defines the time between two heartbeat pings.
+      The default value is 2 seconds, that is, the heartbeat service of
+      the VirtualBox Guest Additions will send a heartbeat ping every
+      two seconds. The value in nanoseconds can be configured like this:
+    </para>
+
+<screen>VBoxManage setextradata "VM name"\
+  VBoxInternal/Devices/VMMDev/0/Config/HeartbeatInterval 2000000000</screen>
+
+    <para>
+      The <emphasis>heartbeat timeout</emphasis> defines the time the
+      host waits starting from the last heartbeat ping before it defines
+      the guest as unresponsive. The default value is 2 times the
+      heartbeat interval (4 seconds) and can be configured as following,
+      in nanoseconds:
+    </para>
+
+<screen>VBoxManage setextradata "VM name" \
+  VBoxInternal/Devices/VMMDev/0/Config/HeartbeatTimeout 4000000000</screen>
 
     <para>
       If the heartbeat timeout expires, there will be a log message like
-      <emphasis>VMMDev: HeartBeatCheckTimer: Guest seems to be unresponsive. Last heartbeat
-        received 5 seconds ago.</emphasis>
-      If another heartbeat ping arrives after this warning, there will be a log
-      message like
-      <emphasis>VMMDev: GuestHeartBeat: Guest is alive.</emphasis>
-    </para>
+      <emphasis>VMMDev: HeartBeatCheckTimer: Guest seems to be
+      unresponsive. Last heartbeat received 5 seconds ago.</emphasis> If
+      another heartbeat ping arrives after this warning, there will be a
+      log message like <emphasis>VMMDev: GuestHeartBeat: Guest is
+      alive.</emphasis>
+    </para>
+
   </sect1>
 
   <sect1 id="diskencryption">
-    <title>Encryption of disk images</title>
-
-    <para>
-      Starting with VirtualBox 5.0, it is possible to encrypt the data stored in
-      hard disk images transparently for the guest. It does not depend on a specific
-      image format to be used. Images which have the data encrypted are not portable
-      between VirtualBox and other virtualization software.
-    </para>
-
-    <para>
-      VirtualBox uses the AES algorithm in XTS mode and supports 128 or 256 bit
-      data encryption keys (DEK).
-      The DEK is stored encrypted in the medium properties and is decrypted during
-      VM startup by entering a password which was chosen when the image was encrypted.
-    </para>
-
-    <para>
-      Since the DEK is stored as part of the VM configuration file, it is
-      important that it is kept safe. Losing the DEK means that the data stored
-      in the disk images is lost irrecoverably. Having complete and up to
-      date backups of all data related to the VM is the responsibility of the
-      user.
+
+    <title>Encryption of Disk Images</title>
+
+    <para>
+      Starting with VirtualBox 5.0, it is possible to encrypt the data
+      stored in hard disk images transparently for the guest. It does
+      not depend on a specific image format to be used. Images which
+      have the data encrypted are not portable between VirtualBox and
+      other virtualization software.
+    </para>
+
+    <para>
+      VirtualBox uses the AES algorithm in XTS mode and supports 128-bit
+      or 256-bit data encryption keys (DEK). The DEK is stored encrypted
+      in the medium properties and is decrypted during VM startup by
+      entering a password which was chosen when the image was encrypted.
+    </para>
+
+    <para>
+      Since the DEK is stored as part of the VM configuration file, it
+      is important that it is kept safe. Losing the DEK means that the
+      data stored in the disk images is lost irrecoverably. Having
+      complete and up to date backups of all data related to the VM is
+      the responsibility of the user.
     </para>
 
     <sect2 id="diskencryption-limitations">
-      <title>Limitations</title>
-
-      <para>
-        There are some limitations the user needs to be aware of when using this
-        feature:
+
+      <title>Limitations of Disk Encryption</title>
+
+      <para>
+        There are some limitations the user needs to be aware of when
+        using this feature:
       </para>
 
@@ -3846,45 +5899,59 @@
 
         <listitem>
-          <para>This feature is part of the Oracle VM VirtualBox Extension
+          <para>
+            This feature is part of the Oracle VM VirtualBox Extension
             Pack, which needs to be installed. Otherwise disk encryption
-            is unavailable.</para>
-        </listitem>
-
-        <listitem>
-          <para>Since encryption works only on the stored user data,
-            it is currently not possible to check for metadata integrity of the disk image.
-            Attackers might destroy data by removing or changing blocks of data
-            in the image or change metadata items such as the disk size.
+            is unavailable.
           </para>
         </listitem>
 
         <listitem>
-          <para>Exporting appliances which contain encrypted disk images is not
-            possible because the OVF specification doesn't support this.
-            All images are therefore decrypted during export.</para>
-        </listitem>
-
-        <listitem>
-          <para>The DEK is kept in memory while the VM is running to be able to
-            decrypt data read and encrypt data written by the guest. While this should
-            be obvious the user needs to be aware of this because an attacker might be able
-            to extract the key on a compromised host and decrypt the data.</para>
-        </listitem>
-
-        <listitem>
-          <para>When encrypting or decrypting the images, the password is
-            passed in clear text via the VirtualBox API. This needs to be kept
-            in mind, especially when using third party API clients which make
-            use of the webservice where the password might be transmitted
-            over the network. The use of HTTPS is mandatory in such a case.
+          <para>
+            Since encryption works only on the stored user data, it is
+            currently not possible to check for metadata integrity of
+            the disk image. Attackers might destroy data by removing or
+            changing blocks of data in the image or change metadata
+            items such as the disk size.
           </para>
         </listitem>
 
         <listitem>
-          <para>Encrypting images with differencing images is only possible if
-            there are no snapshots or a linear chain of snapshots. This
-            limitation may be addressed in a future VirtualBox version.</para>
+          <para>
+            Exporting appliances which contain encrypted disk images is
+            not possible because the OVF specification does not support
+            this. All images are therefore decrypted during export.
+          </para>
         </listitem>
 
+        <listitem>
+          <para>
+            The DEK is kept in memory while the VM is running to be able
+            to decrypt data read and encrypt data written by the guest.
+            While this should be obvious the user needs to be aware of
+            this because an attacker might be able to extract the key on
+            a compromised host and decrypt the data.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            When encrypting or decrypting the images, the password is
+            passed in clear text via the VirtualBox API. This needs to
+            be kept in mind, especially when using third party API
+            clients which make use of the webservice where the password
+            might be transmitted over the network. The use of HTTPS is
+            mandatory in such a case.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Encrypting images with differencing images is only possible
+            if there are no snapshots or a linear chain of snapshots.
+            This limitation may be addressed in a future VirtualBox
+            version.
+          </para>
+        </listitem>
+
       </itemizedlist>
 
@@ -3892,442 +5959,734 @@
 
     <sect2 id="diskencryption-encryption">
-      <title>Encrypting disk images</title>
-
-      <para>
-        Encrypting disk images can be done either using the GUI or VBoxManage.
-        While the GUI is easier to use, it works on a per VM basis and encrypts
-        all disk images attached to the specific VM.
-        With VBoxManage one can encrypt individual images (including all differencing
-        images). To encrypt an unencrypted medium with VBoxManage, use:
-      </para>
-
-      <screen>VBoxManage encryptmedium "uuid|filename" --newpassword "file|-" --cipher "cipher id" --newpasswordid "id"</screen>
-
-      <para>
-        To supply the encryption password point VBoxManage to the file where the
-        password is stored or specify <computeroutput>-</computeroutput> to let VBoxManage
-        ask you for the password on the command line.
-      </para>
-      <para>
-        The cipher parameter specifies the cipher to use for encryption and can be either
-        <computeroutput>AES-XTS128-PLAIN64</computeroutput> or <computeroutput>AES-XTS256-PLAIN64</computeroutput>.
-        The specified password identifier can be freely chosen by the user and is
-        used for correct identification when supplying multiple passwords during
-        VM startup.
-      </para>
-      <para>
-        If the user uses the same password when encrypting multiple images and also the
-        same password identifier, the user needs to supply the password only once during
-        VM startup.
-      </para>
+
+      <title>Encrypting Disk Images</title>
+
+      <para>
+        Encrypting disk images can be done either using the GUI or
+        VBoxManage. While the GUI is easier to use, it works on a per VM
+        basis and encrypts all disk images attached to the specific VM.
+        With VBoxManage one can encrypt individual images, including all
+        differencing images. To encrypt an unencrypted medium with
+        VBoxManage, use:
+      </para>
+
+<screen>VBoxManage encryptmedium "uuid|filename" \
+  --newpassword "file|-" --cipher "cipher id" --newpasswordid "id"</screen>
+
+      <para>
+        To supply the encryption password point VBoxManage to the file
+        where the password is stored or specify
+        <computeroutput>-</computeroutput> to let VBoxManage ask you for
+        the password on the command line.
+      </para>
+
+      <para>
+        The cipher parameter specifies the cipher to use for encryption
+        and can be either
+        <computeroutput>AES-XTS128-PLAIN64</computeroutput> or
+        <computeroutput>AES-XTS256-PLAIN64</computeroutput>. The
+        specified password identifier can be freely chosen by the user
+        and is used for correct identification when supplying multiple
+        passwords during VM startup.
+      </para>
+
+      <para>
+        If the user uses the same password when encrypting multiple
+        images and also the same password identifier, the user needs to
+        supply the password only once during VM startup.
+      </para>
+
     </sect2>
 
     <sect2 id="diskencryption-startvm">
-      <title>Starting a VM with encrypted images</title>
-
-      <para>
-        When a VM is started using the GUI, a dialog will open where the user
-        needs to enter all passwords for all encrypted images attached to the VM.
-        If another frontend like VBoxHeadless is used, the VM will be paused as soon
-        as the guest tries to access an encrypted disk.
-        The user needs to provide the passwords through VBoxManage using the following
-        command:
-      </para>
-
-      <screen>VBoxManage controlvm "uuid|vmname" addencpassword "id" "password" [--removeonsuspend "yes|no"]</screen>
-
-      <para>
-        The <computeroutput>id</computeroutput> parameter must be the same as the password identifier
-        supplied when encrypting the images. <computeroutput>password</computeroutput> is the password
-        used when encrypting the images. The user can optionally specify
-        <computeroutput>--removeonsuspend "yes|no"</computeroutput> to specify whether
-        to remove the password from VM memory when the VM is suspended. Before the VM can be
-        resumed, the user needs to supply the passwords again. This is useful when
-        a VM is suspended by a host suspend event and the user doesn't want
-        the password to remain in memory.
-      </para>
+
+      <title>Starting a VM with Encrypted Images</title>
+
+      <para>
+        When a VM is started using the GUI, a dialog will open where the
+        user needs to enter all passwords for all encrypted images
+        attached to the VM. If another frontend like VBoxHeadless is
+        used, the VM will be paused as soon as the guest tries to access
+        an encrypted disk. The user needs to provide the passwords
+        through VBoxManage using the following command:
+      </para>
+
+<screen>VBoxManage controlvm "uuid|vmname" addencpassword "id" "password" [--removeonsuspend "yes|no"]</screen>
+
+      <para>
+        The <computeroutput>id</computeroutput> parameter must be the
+        same as the password identifier supplied when encrypting the
+        images. <computeroutput>password</computeroutput> is the
+        password used when encrypting the images. The user can
+        optionally specify <computeroutput>--removeonsuspend
+        "yes|no"</computeroutput> to specify whether to remove the
+        password from VM memory when the VM is suspended. Before the VM
+        can be resumed, the user needs to supply the passwords again.
+        This is useful when a VM is suspended by a host suspend event
+        and the user does not want the password to remain in memory.
+      </para>
+
     </sect2>
 
     <sect2 id="diskencryption-decryption">
-      <title>Decrypting encrypted images</title>
-
-      <para>
-        In some circumstances it might be required to decrypt previously encrypted
-        images. This can be done in the GUI for a complete VM or using VBoxManage
-        with the following command:
-      </para>
-
-      <screen>VBoxManage encryptmedium "uuid|filename" --oldpassword "file|-"</screen>
-
-      <para>
-        The only required parameter is the password the image was encrypted with.
-        The options are the same as for encrypting images.
-      </para>
+
+      <title>Decrypting Encrypted Images</title>
+
+      <para>
+        In some circumstances it might be required to decrypt previously
+        encrypted images. This can be done in the GUI for a complete VM
+        or using VBoxManage with the following command:
+      </para>
+
+<screen>VBoxManage encryptmedium "uuid|filename" --oldpassword "file|-"</screen>
+
+      <para>
+        The only required parameter is the password the image was
+        encrypted with. The options are the same as for encrypting
+        images.
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="gimdebug">
-    <title>Paravirtualized debugging</title>
-
-    <para>In this section we cover debugging of guest operating systems using interfaces
-    supported by paravirtualization providers.</para>
+
+    <title>Paravirtualized Debugging</title>
+
+    <para>
+      In this section we cover debugging of guest operating systems
+      using interfaces supported by paravirtualization providers.
+    </para>
 
     <note>
-      <para>Paravirtualized debugging significantly alter guest operating system behaviour
-      and should only be used by expert users for debugging and diagnostics.</para>
+      <para>
+        Paravirtualized debugging significantly alter guest operating
+        system behaviour and should only be used by expert users for
+        debugging and diagnostics.
+      </para>
     </note>
 
-    <para>These debug options are specified as a string of key-value pairs separated by
-    commas. An empty string disables paravirtualized debugging.</para>
+    <para>
+      These debug options are specified as a string of key-value pairs
+      separated by commas. An empty string disables paravirtualized
+      debugging.
+    </para>
 
     <sect2 id="gimdebughyperv">
-      <title>Hyper-V debug options</title>
-
-      <para>All of the options listed below are optional, and thus the default value
-      specified will be used when the corresponding key-value pair is not
-      specified.</para>
+
+      <title>Hyper-V Debug Options</title>
+
+      <para>
+        All of the options listed below are optional, and thus the
+        default value specified will be used when the corresponding
+        key-value pair is not specified.
+      </para>
 
       <itemizedlist>
+
         <listitem>
-          <para>Key: <emphasis role="bold"><computeroutput>enabled</computeroutput></emphasis></para>
-          <para>Value: <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput></para>
-          <para>Default: <computeroutput>0</computeroutput></para>
-          <para>Specify <computeroutput>1</computeroutput> to enable the Hyper-V debug
-            interface. If this key-value pair is not specified or the value is not
-            <computeroutput>1</computeroutput>, the Hyper-V debug interface is disabled
-            regardless of other key-value pairs being present.</para>
+          <para>
+            Key:
+            <emphasis role="bold"><computeroutput>enabled</computeroutput></emphasis>
+          </para>
+
+          <para>
+            Value: <computeroutput>0</computeroutput> or
+            <computeroutput>1</computeroutput>
+          </para>
+
+          <para>
+            Default: <computeroutput>0</computeroutput>
+          </para>
+
+          <para>
+            Specify <computeroutput>1</computeroutput> to enable the
+            Hyper-V debug interface. If this key-value pair is not
+            specified or the value is not
+            <computeroutput>1</computeroutput>, the Hyper-V debug
+            interface is disabled regardless of other key-value pairs
+            being present.
+          </para>
         </listitem>
+
         <listitem>
-          <para>Key: <emphasis role="bold"><computeroutput>address</computeroutput></emphasis></para>
-          <para>Value: IPv4 address</para>
-          <para>Default: 127.0.0.1</para>
-          <para>Specify the IPv4 address where the remote debugger is connected.</para>
+          <para>
+            Key:
+            <emphasis role="bold"><computeroutput>address</computeroutput></emphasis>
+          </para>
+
+          <para>
+            Value: IPv4 address
+          </para>
+
+          <para>
+            Default: 127.0.0.1
+          </para>
+
+          <para>
+            Specify the IPv4 address where the remote debugger is
+            connected.
+          </para>
         </listitem>
+
         <listitem>
-          <para>Key: <emphasis role="bold"><computeroutput>port</computeroutput></emphasis></para>
-          <para>Value: UDP port number</para>
-          <para>Default: 50000</para>
-          <para>Specify the UDP port number where the remote debugger is connected.</para>
+          <para>
+            Key:
+            <emphasis role="bold"><computeroutput>port</computeroutput></emphasis>
+          </para>
+
+          <para>
+            Value: UDP port number
+          </para>
+
+          <para>
+            Default: 50000
+          </para>
+
+          <para>
+            Specify the UDP port number where the remote debugger is
+            connected.
+          </para>
         </listitem>
+
         <listitem>
-          <para>Key: <emphasis role="bold"><computeroutput>vendor</computeroutput></emphasis></para>
-          <para>Value: Hyper-V vendor signature reported via CPUID to the guest</para>
-          <para>Default: When debugging is enabled: <computeroutput>Microsoft Hv</computeroutput>,
-          otherwise: <computeroutput>VBoxVBoxVBox</computeroutput></para>
-          <para>Specify the Hyper-V vendor signature which is exposed to the guest via CPUID.
-          For debugging Microsoft Windows guests, it is required the hypervisor reports
-          the Microsoft vendor.</para>
+          <para>
+            Key:
+            <emphasis role="bold"><computeroutput>vendor</computeroutput></emphasis>
+          </para>
+
+          <para>
+            Value: Hyper-V vendor signature reported via CPUID to the
+            guest
+          </para>
+
+          <para>
+            Default: When debugging is enabled:
+            <computeroutput>Microsoft Hv</computeroutput>, otherwise:
+            <computeroutput>VBoxVBoxVBox</computeroutput>
+          </para>
+
+          <para>
+            Specify the Hyper-V vendor signature which is exposed to the
+            guest via CPUID. For debugging Microsoft Windows guests, it
+            is required the hypervisor reports the Microsoft vendor.
+          </para>
         </listitem>
+
         <listitem>
-          <para>Key: <emphasis role="bold"><computeroutput>hypercallinterface</computeroutput>
-          </emphasis></para>
-          <para>Value: <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput></para>
-          <para>Default: <computeroutput>0</computeroutput></para>
-          <para>Specify whether hypercalls should be suggested for initiating debug data
-          transfers between host and guest rather than MSRs when requested by the guest.</para>
+          <para>
+            Key:
+            <emphasis role="bold"><computeroutput>hypercallinterface</computeroutput>
+            </emphasis>
+          </para>
+
+          <para>
+            Value: <computeroutput>0</computeroutput> or
+            <computeroutput>1</computeroutput>
+          </para>
+
+          <para>
+            Default: <computeroutput>0</computeroutput>
+          </para>
+
+          <para>
+            Specify whether hypercalls should be suggested for
+            initiating debug data transfers between host and guest
+            rather than MSRs when requested by the guest.
+          </para>
         </listitem>
+
         <listitem>
-          <para>Key: <emphasis role="bold"><computeroutput>vsinterface</computeroutput>
-          </emphasis></para>
-          <para>Value: <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput></para>
-          <para>Default: When debugging is enabled, <computeroutput>1</computeroutput>,
-          otherwise <computeroutput>0</computeroutput></para>
-          <para>Specify whether to expose the "VS#1" (virtualization service) interface to the
-          guest. This interface is required for debugging Microsoft Windows 10 32-bit guests, but
-          is optional for other Windows versions.</para>
+          <para>
+            Key:
+            <emphasis role="bold"><computeroutput>vsinterface</computeroutput>
+            </emphasis>
+          </para>
+
+          <para>
+            Value: <computeroutput>0</computeroutput> or
+            <computeroutput>1</computeroutput>
+          </para>
+
+          <para>
+            Default: When debugging is enabled,
+            <computeroutput>1</computeroutput>, otherwise
+            <computeroutput>0</computeroutput>
+          </para>
+
+          <para>
+            Specify whether to expose the "VS#1" (virtualization
+            service) interface to the guest. This interface is required
+            for debugging Microsoft Windows 10 32-bit guests, but is
+            optional for other Windows versions.
+          </para>
         </listitem>
+
       </itemizedlist>
 
       <sect3 id="gimdebughyperv-windows-setup">
-        <title>Setting up Windows guests for debugging with the Hyper-V paravirtualization provider</title>
-
-        <para>Windows supports debugging over a serial cable, USB, IEEE 1394 Firewire, and Ethernet
-        (only Windows 8 and later). USB and IEEE 1394 are not applicable for virtual machines, and
-        Ethernet requires Windows 8 or later. While serial connection is universally usable, it is
-        slow.</para>
-
-        <para>Debugging using the Hyper-V debug transport, supported on Windows Vista and later,
-        offers significant benefits. It provides excellent performance due to direct host-to-guest
-        transfers, it is easy to set up and requires minimal support from the hypervisor. It can be
-        used with the debugger running on the same host as the VM or with the debugger and VM on
-        separate machines connected over a network.</para>
-
-        <sect4><title>Prerequisites</title>
-          <itemizedlist>
-            <listitem>
-              <para>A VM configured for Hyper-V paravirtualization running a Windows Vista or newer
-              Windows guest. You may check the effective paravirtualization provider for your VM from
-              the output of the following VBoxManage command:</para>
-              <para><screen>VBoxManage showvminfo "VM name"</screen></para>
-            </listitem>
-
-            <listitem>
-              <para>A sufficiently up-to-date version of the Microsoft WinDbg debugger required
-              to debug the version of Windows in your VM.</para>
-            </listitem>
-
-            <listitem>
-              <para>While Windows 8 and newer Windows guests ship with Hyper-V debug support,
-              Windows 7 and Vista do not. To use Hyper-V debugging with a Windows 7 or Vista
-              guest, copy the file
-              <computeroutput>kdvm.dll</computeroutput> from a Windows 8.0 installation<footnote>
-              <para>Only Windows 8.0 ships <computeroutput>kdvm.dll</computeroutput>. Windows 8.1
-              and newer Windows versions do not.</para></footnote>. This file is
-              typically located in <computeroutput>C:\Windows\System32</computeroutput>. Copy it
-              to the same location in your Windows 7/Vista guest. Make sure you copy the 32-bit or
-              64-bit version of the DLL which matches your guest OS.</para>
-            </listitem>
-          </itemizedlist>
-        </sect4>
-
-        <sect4><title>VM and guest configuration</title>
-          <orderedlist>
-            <listitem>
-              <para>Power off the VM.</para>
-            </listitem>
-
-            <listitem>
-              <para>Enable the debug options by executing the following VBoxManage command:</para>
-              <para><screen>VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1"</screen></para>
-              <para>The above command assumes your debugger will connect to your host machine
-              on UDP port 50000. However, if you need to run the debugger on a remote machine
-              you may specify the remote address and port here, e.g. using:</para>
-              <para>
-              <screen>VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1,address=192.168.32.1,port=55000"</screen>
-              </para>
-              <para>Refer <xref linkend="gimdebughyperv" /> for the complete set of options.</para>
-            </listitem>
-
-            <listitem>
-              <para>Start the VM.</para>
-            </listitem>
-
-            <listitem>
-              <para>In the guest, start an elevated command prompt and execute the
-              following commands:</para>
-              <itemizedlist>
-                <listitem><para>For a Windows 8 or newer Windows guest:</para>
-                  <para>
-                  <screen>bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4</screen>
-                  </para>
-                </listitem>
-                <listitem><para>For a Windows 7 or Vista guest:</para>
-                  <para>
-                  <screen>bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4</screen>
-                  <screen>bcdedit /set dbgtransport kdvm.dll</screen>
-                  </para>
-                  <para>The IP address and port in the <computeroutput>bcdedit</computeroutput> command
-                  are ignored when using the Hyper-V debug transport. Any valid IP and a port number greater
-                  than 49151 and lower than 65536 can be entered.</para>
-
-                  <para>The encryption key in the <computeroutput>bcdedit</computeroutput> command is
-                  relevant and must be valid. The key "1.2.3.4" used in the above example is valid
-                  and may be used if security is not a concern. If you do not specify any encryption key,
-                  <computeroutput>bcdedit</computeroutput> will generate one for you and you will need to copy
-                  this key to later enter in Microsoft WinDbg on the remote end. This encryption key is used
-                  to encrypt the debug data exchanged between Windows and the debugger.</para>
-                </listitem>
-                <listitem>
-                  <para>Execute one or more of the following commands to enable debugging for
-                  the appropriate phase or component of your Windows guest: </para>
-                  <para>
-                    <screen>bcdedit /set debug on</screen>
-                    <screen>bcdedit /set bootdebug on</screen>
-                    <screen>bcdedit /set {bootmgr} bootdebug on</screen>
-                  </para>
-                  <para>Please note that the <computeroutput>bootdebug</computeroutput> options are only
-                  effective on Windows 8 or newer when using the Hyper-V debug transport. Refer to Microsoft
-                  Windows documentation for detailed explanation of <computeroutput>bcdedit</computeroutput>
-                  options.</para>
-                </listitem>
-              </itemizedlist>
-            </listitem>
-
-            <listitem>
-              <para>Start Microsoft WinDbg on your host machine or remote host.</para>
-
-              <para>From the "File" menu, select "Kernel debug". Under the "NET" tab, specify the UDP port
-              number you used in the <computeroutput>paravirtdebug</computeroutput> options. If you didn't
-              specify any, leave it as 50000. Ensure that the UDP port is not blocked by a firewall or other
-              security software.</para>
-
-              <para>In the "Key" field, enter <computeroutput>1.2.3.4</computeroutput> or the encryption
-              key from the <computeroutput>bcdedit</computeroutput> command in your Windows guest.</para>
-
-              <para>Now press "OK" to start listening for connections. Microsoft WinDbg typically shows
-              a "Waiting to reconnect" message during this phase.</para>
-
-              <para>Alternatively, launch WinDbg from the command line to directly start a debug session:
-                <screen>windbg.exe -k net:port=50000,key=1.2.3.4</screen>
-              Please refer to the WinDbg documentation for complete command line syntax.
-              </para>
-
-            </listitem>
-
-            <listitem>
-              <para>Reboot your Windows guest and it should then connect as a debuggee with Microsoft
-              WinDbg.</para>
-            </listitem>
-          </orderedlist>
-        </sect4>
+
+        <title>Setting up Windows Guests for Debugging with the Hyper-V
+          Paravirtualization Provider</title>
+
+        <para>
+          Windows supports debugging over a serial cable, USB, IEEE 1394
+          Firewire, and Ethernet (only Windows 8 and later). USB and
+          IEEE 1394 are not applicable for virtual machines, and
+          Ethernet requires Windows 8 or later. While serial connection
+          is universally usable, it is slow.
+        </para>
+
+        <para>
+          Debugging using the Hyper-V debug transport, supported on
+          Windows Vista and later, offers significant benefits. It
+          provides excellent performance due to direct host-to-guest
+          transfers, it is easy to set up and requires minimal support
+          from the hypervisor. It can be used with the debugger running
+          on the same host as the VM or with the debugger and VM on
+          separate machines connected over a network.
+        </para>
+
+        <para>
+          <emphasis role="bold">Prerequisites</emphasis>
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              A VM configured for Hyper-V paravirtualization running a
+              Windows Vista or newer Windows guest. You may check the
+              effective paravirtualization provider for your VM from the
+              output of the following VBoxManage command:
+            </para>
+
+            <para>
+<screen>VBoxManage showvminfo "VM name"</screen>
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              A sufficiently up-to-date version of the Microsoft WinDbg
+              debugger required to debug the version of Windows in your
+              VM.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              While Windows 8 and newer Windows guests ship with Hyper-V
+              debug support, Windows 7 and Vista do not. To use Hyper-V
+              debugging with a Windows 7 or Vista guest, copy the file
+              <computeroutput>kdvm.dll</computeroutput> from a Windows
+              8.0 installation
+
+              <footnote>
+
+                <para>
+                  Only Windows 8.0 ships
+                  <computeroutput>kdvm.dll</computeroutput>. Windows 8.1
+                  and newer Windows versions do not.
+                </para>
+
+              </footnote>
+
+              . This file is typically located in
+              <computeroutput>C:\Windows\System32</computeroutput>. Copy
+              it to the same location in your Windows 7/Vista guest.
+              Make sure you copy the 32-bit or 64-bit version of the DLL
+              which matches your guest OS.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          <emphasis role="bold">VM and Guest Configuration</emphasis>
+        </para>
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              Power off the VM.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Enable the debug options by executing the following
+              VBoxManage command:
+            </para>
+
+            <para>
+<screen>VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1"</screen>
+            </para>
+
+            <para>
+              The above command assumes your debugger will connect to
+              your host machine on UDP port 50000. However, if you need
+              to run the debugger on a remote machine you may specify
+              the remote address and port here. For example::
+            </para>
+
+            <para>
+<screen>VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1,address=192.168.32.1,port=55000"</screen>
+            </para>
+
+            <para>
+              See <xref linkend="gimdebughyperv" /> for the complete set
+              of options.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Start the VM.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              In the guest, start an elevated command prompt and execute
+              the following commands:
+            </para>
+
+            <itemizedlist>
+
+              <listitem>
+                <para>
+                  For a Windows 8 or newer Windows guest:
+                </para>
+
+                <para>
+<screen>bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4</screen>
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  For a Windows 7 or Vista guest:
+                </para>
+
+                <para>
+<screen>bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4</screen>
+
+<screen>bcdedit /set dbgtransport kdvm.dll</screen>
+                </para>
+
+                <para>
+                  The IP address and port in the
+                  <computeroutput>bcdedit</computeroutput> command are
+                  ignored when using the Hyper-V debug transport. Any
+                  valid IP and a port number greater than 49151 and
+                  lower than 65536 can be entered.
+                </para>
+
+                <para>
+                  The encryption key in the
+                  <computeroutput>bcdedit</computeroutput> command is
+                  relevant and must be valid. The key "1.2.3.4" used in
+                  the above example is valid and may be used if security
+                  is not a concern. If you do not specify any encryption
+                  key, <computeroutput>bcdedit</computeroutput> will
+                  generate one for you and you will need to copy this
+                  key to later enter in Microsoft WinDbg on the remote
+                  end. This encryption key is used to encrypt the debug
+                  data exchanged between Windows and the debugger.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  Execute one or more of the following commands to
+                  enable debugging for the appropriate phase or
+                  component of your Windows guest:
+                </para>
+
+                <para>
+<screen>bcdedit /set debug on</screen>
+
+<screen>bcdedit /set bootdebug on</screen>
+
+<screen>bcdedit /set {bootmgr} bootdebug on</screen>
+                </para>
+
+                <para>
+                  Please note that the
+                  <computeroutput>bootdebug</computeroutput> options are
+                  only effective on Windows 8 or newer when using the
+                  Hyper-V debug transport. Refer to Microsoft Windows
+                  documentation for detailed explanation of
+                  <computeroutput>bcdedit</computeroutput> options.
+                </para>
+              </listitem>
+
+            </itemizedlist>
+          </listitem>
+
+          <listitem>
+            <para>
+              Start Microsoft WinDbg on your host machine or remote
+              host.
+            </para>
+
+            <para>
+              From the <emphasis role="bold">File</emphasis> menu,
+              select <emphasis role="bold">Kernel Debug</emphasis>. On
+              the NET tab, specify the UDP port number you used in the
+              <computeroutput>paravirtdebug</computeroutput> options. If
+              you did not specify any, leave it as 50000. Ensure that
+              the UDP port is not blocked by a firewall or other
+              security software.
+            </para>
+
+            <para>
+              In the Key field, enter
+              <computeroutput>1.2.3.4</computeroutput> or the encryption
+              key from the <computeroutput>bcdedit</computeroutput>
+              command in your Windows guest.
+            </para>
+
+            <para>
+              Click <emphasis role="bold">OK</emphasis> to start
+              listening for connections. Microsoft WinDbg typically
+              shows a "Waiting to reconnect" message during this phase.
+            </para>
+
+            <para>
+              Alternatively, launch WinDbg from the command line to
+              directly start a debug session:
+
+<screen>windbg.exe -k net:port=50000,key=1.2.3.4</screen>
+
+              Please refer to the WinDbg documentation for complete
+              command line syntax.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Reboot your Windows guest and it should then connect as a
+              debuggee with Microsoft WinDbg.
+            </para>
+          </listitem>
+
+        </orderedlist>
+
       </sect3>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="pcspeaker_passthrough">
-    <title>PC speaker passthrough</title>
-
-    <para>As an experimental feature (primarily due to being limited to Linux
-    host only and unknown Linux distribution coverage) VirtualBox supports
-    passing through the PC speaker to the host. The PC speaker (sometimes
-    called system speaker) is a way to produce audible feedback such as beeps
-    without the need for regular audio/sound card support.</para>
-
-    <para>The PC speaker passthrough feature in VirtualBox handles beeps only.
-    Advanced PC speaker use by the VM (such as PCM audio) will not work,
-    resulting in undefined host behavior.</para>
-
-    <para>Producing beeps on Linux is unfortunately a very complex topic.
-    VirtualBox offers a collection of options, in an attempt to make this work
-    deterministically and reliably on as many Linux distributions and system
-    configurations as possible:
-      <table>
-        <title>PC speaker configuration options</title>
-        <tgroup cols="3">
-          <thead>
-            <row>
-              <entry><emphasis role="bold">Code</emphasis></entry>
-              <entry><emphasis role="bold">Device</emphasis></entry>
-              <entry><emphasis role="bold">Notes</emphasis></entry>
-            </row>
-          </thead>
-          <tbody>
-            <row>
-              <entry>1</entry>
-              <entry><computeroutput>/dev/input/ by-path/platform- pcspkr-event-spkr</computeroutput></entry>
-              <entry>Direct host PC speaker use.</entry>
-            </row>
-            <row>
-              <entry>2</entry>
-              <entry><computeroutput>/dev/tty</computeroutput></entry>
-              <entry>Uses the terminal association of the VM process. VM needs
-              to be started on a virtual console.</entry>
-            </row>
-            <row>
-              <entry>3</entry>
-              <entry><computeroutput>/dev/tty0</computeroutput> or
+
+    <title>PC Speaker Passthrough</title>
+
+    <para>
+      As an experimental feature, primarily due to being limited to
+      Linux host only and unknown Linux distribution coverage,
+      VirtualBox supports passing through the PC speaker to the host.
+      The PC speaker, sometimes called the system speaker, is a way to
+      produce audible feedback such as beeps without the need for
+      regular audio and sound card support.
+    </para>
+
+    <para>
+      The PC speaker passthrough feature in VirtualBox handles beeps
+      only. Advanced PC speaker use by the VM, such as PCM audio, will
+      not work, resulting in undefined host behavior.
+    </para>
+
+    <para>
+      Producing beeps on Linux is a very complex topic. VirtualBox
+      offers a collection of options, in an attempt to make this work
+      deterministically and reliably on as many Linux distributions and
+      system configurations as possible. These are summarized in
+      <xref linkend="table-pcspeaker-config"/>.
+    </para>
+
+    <table id="table-pcspeaker-config">
+      <title>PC Speaker Configuration Options</title>
+      <tgroup cols="3">
+        <thead>
+          <row>
+            <entry><emphasis role="bold">Code</emphasis></entry>
+            <entry><emphasis role="bold">Device</emphasis></entry>
+            <entry><emphasis role="bold">Notes</emphasis></entry>
+          </row>
+        </thead>
+        <tbody>
+          <row>
+            <entry>1</entry>
+            <entry><computeroutput>/dev/input/ by-path/platform-
+              pcspkr-event-spkr</computeroutput></entry>
+            <entry>Direct host PC speaker use.</entry>
+          </row>
+          <row>
+            <entry>2</entry>
+            <entry><computeroutput>/dev/tty</computeroutput></entry>
+            <entry>Uses the terminal association of the VM process. VM needs to be started
+              on a virtual console.</entry>
+          </row>
+          <row>
+            <entry>3</entry>
+            <entry><computeroutput>/dev/tty0</computeroutput> or
               <computeroutput>/dev/vc/0</computeroutput></entry>
-              <entry>Can only be used by user <computeroutput>root</computeroutput>
-              or users with capability <computeroutput>cap_sys_tty_config</computeroutput></entry>
-            </row>
-            <row>
-              <entry>9</entry>
-              <entry>user specified console or evdev device path</entry>
-              <entry>Like 1-3, just with a custom device path.</entry>
-            </row>
-            <row>
-              <entry>70</entry>
-              <entry><computeroutput>/dev/tty</computeroutput></entry>
-              <entry>Standard beep only. Loses frequency and length. See code
-              2.</entry>
-            </row>
-            <row>
-              <entry>79</entry>
-              <entry>user specified terminal device path</entry>
-              <entry>Like 70, just with a custom device path.</entry>
-            </row>
-            <row>
-              <entry>100</entry>
-              <entry>all of the above</entry>
-              <entry>Tries all above codes.</entry>
-            </row>
-          </tbody>
-        </tgroup>
-      </table>
-    </para>
-
-    <para>To enable PC speaker passthrough use the following command:
-      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" N</screen>
-    Replace <computeroutput>N</computeroutput> with the code representing the
-    case you want to use. Changing this setting will take effect when the VM is
-    started next. It is safe to enable PC speaker passthrough on all host OSes.
-    It will only have an effect on Linux.</para>
-
-    <para>The VM log file, <computeroutput>VBox.log</computeroutput>, will
-    contain lines with the prefix <computeroutput>PIT: speaker:</computeroutput>
-    showing the PC speaker passthrough setup activities. It gives hints which
-    device it picked or why it failed.</para>
-
-    <para>Enabling PC speaker passthrough for the VM is usually the simple
-    part. The real difficulty is making sure that VirtualBox can access the
-    necessary device, because in a typical Linux install most of them can only
-    be accessed by user <computeroutput>root</computeroutput>. You should
-    follow the preferred way to persistently change this, e.g. by referring to
-    your distribution's documentation. Since there are countless Linux
-    distribution variants, we can only give the general hints that there is
-    often a way to give the X11 session user access to additional devices, or
-    you need to find a working solution using a udev configuration file. If
-    everything fails you might try setting the permissions using a script
-    which is run late enough in the host system startup.</para>
-
-    <para>Sometimes additional rules are applied by the kernel to limit access
-    (e.g. that the VM process must have the same controlling terminal as the
-    device configured to be used for beeping, something which is often very
-    difficult to achieve for GUI applications such as VirtualBox). The table
-    above contains some hints, but generally refer to the Linux
-    documentation.</para>
-
-    <para>If you have trouble getting any beeps even if the device permissions
-    are set up and VBox.log confirms that it uses evdev or console for the
-    PC speaker control, check if your system has a PC speaker. Some systems do
-    not have one. Other complications can arise from Linux rerouting the PC
-    speaker output to a sound card. Check if the beeps are audible if you
-    connect speakers to your sound card. Today almost all systems have one.
-    Finally, check if the audio mixer control has a channel named "beep"
-    (could be hidden in the mixer settings) and that it isn't muted.</para>
+            <entry>Can only be used by user <computeroutput>root</computeroutput> or users
+              with capability
+              <computeroutput>cap_sys_tty_config</computeroutput></entry>
+          </row>
+          <row>
+            <entry>9</entry>
+            <entry>user specified console or evdev device path</entry>
+            <entry>Like 1-3, just with a custom device path.</entry>
+          </row>
+          <row>
+            <entry>70</entry>
+            <entry><computeroutput>/dev/tty</computeroutput></entry>
+            <entry>Standard beep only. Loses frequency and length. See code 2.</entry>
+          </row>
+          <row>
+            <entry>79</entry>
+            <entry>user specified terminal device path</entry>
+            <entry>Like 70, just with a custom device path.</entry>
+          </row>
+          <row>
+            <entry>100</entry>
+            <entry>all of the above</entry>
+            <entry>Tries all above codes.</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+
+    <para>
+      To enable PC speaker passthrough use the following command:
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/i8254/0/Config/PassthroughSpeaker" N</screen>
+
+      Replace <computeroutput>N</computeroutput> with the code
+      representing the case you want to use. Changing this setting will
+      take effect when the VM is started next. It is safe to enable PC
+      speaker passthrough on all host OSes. It will only have an effect
+      on Linux.
+    </para>
+
+    <para>
+      The VM log file, <computeroutput>VBox.log</computeroutput>, will
+      contain lines with the prefix <computeroutput>PIT:
+      speaker:</computeroutput> showing the PC speaker passthrough setup
+      activities. It gives hints which device it picked or why it
+      failed.
+    </para>
+
+    <para>
+      Enabling PC speaker passthrough for the VM is usually the simple
+      part. The real difficulty is making sure that VirtualBox can
+      access the necessary device, because in a typical Linux install
+      most of them can only be accessed by user
+      <computeroutput>root</computeroutput>. You should follow the
+      preferred way to persistently change this, e.g. by referring to
+      your distribution's documentation. Since there are countless Linux
+      distribution variants, we can only give the general hints that
+      there is often a way to give the X11 session user access to
+      additional devices, or you need to find a working solution using a
+      udev configuration file. If everything fails you might try setting
+      the permissions using a script which is run late enough in the
+      host system startup.
+    </para>
+
+    <para>
+      Sometimes additional rules are applied by the kernel to limit
+      access (e.g. that the VM process must have the same controlling
+      terminal as the device configured to be used for beeping,
+      something which is often very difficult to achieve for GUI
+      applications such as VirtualBox). The table above contains some
+      hints, but generally refer to the Linux documentation.
+    </para>
+
+    <para>
+      If you have trouble getting any beeps even if the device
+      permissions are set up and VBox.log confirms that it uses evdev or
+      console for the PC speaker control, check if your system has a PC
+      speaker. Some systems do not have one. Other complications can
+      arise from Linux rerouting the PC speaker output to a sound card.
+      Check if the beeps are audible if you connect speakers to your
+      sound card. Today almost all systems have one. Finally, check if
+      the audio mixer control has a channel named "beep" (could be
+      hidden in the mixer settings) and that it is not muted.
+    </para>
+
   </sect1>
 
   <sect1 id="usbip">
-    <title>Accessing USB devices exposed over the network with USB/IP</title>
-
-    <para>Starting with 5.1.0, VirtualBox supports passing through USB
-    devices which are exposed over the network using the USB over IP protocol
-    without the need to configure the client side provided by the kernel and
-    usbip tools. Furthermore, this feature works with VirtualBox running on any
-    supported host, rather than just Linux alone - as is the case with the official
-    client.</para>
-
-    <para>To enable support for passing through USB/IP devices, the device server exporting
-    the devices must be added with the following command:
-    <screen>VBoxManage usbdevsource add "Unique name" --backend "USBIP" --address "Device server[:port]"</screen>
-    USB devices exported on the device server are then accessible through the GUI
-    or VBoxManage, like any USB devices attached locally. This can be used multiple times
-    to access different device servers.</para>
-
-    <para>To remove a device server, the following command can be used:
-      <screen>VBoxManage usbdevsource remove "Unique name"</screen>
+
+    <title>Accessing USB devices Exposed Over the Network with USB/IP</title>
+
+    <para>
+      Starting with 5.1.0, VirtualBox supports passing through USB
+      devices which are exposed over the network using the USB over IP
+      protocol without the need to configure the client side provided by
+      the kernel and usbip tools. Furthermore, this feature works with
+      VirtualBox running on any supported host, rather than just Linux
+      alone, as is the case with the official client.
+    </para>
+
+    <para>
+      To enable support for passing through USB/IP devices, the device
+      server exporting the devices must be added with the following
+      command:
+
+<screen>VBoxManage usbdevsource add "Unique name" --backend "USBIP" --address "Device server[:port]"</screen>
+
+      USB devices exported on the device server are then accessible
+      through the GUI or VBoxManage, like any USB devices attached
+      locally. This can be used multiple times to access different
+      device servers.
+    </para>
+
+    <para>
+      To remove a device server, the following command can be used:
+
+<screen>VBoxManage usbdevsource remove "Unique name"</screen>
     </para>
 
     <sect2 id="usbip-setup-server">
-      <title>Setting up USB/IP support on a Linux system</title>
-
-      <para>This section gives a brief overview on how to set up a Linux based system
-      to act as a USB device server. The system on the server requires that the
-      <computeroutput>usbip-core.ko</computeroutput> and
-      <computeroutput>usbip-host.ko</computeroutput> kernel drivers
-      are available, and that the USB/IP tools package is installed.
-      The particular installation method for the necessary tools depends on which
-      distribution is used.
-      For example, for Debian based systems - the following command should be used to
-      install the required tools:
-      <screen>apt-get install usbip-utils</screen></para>
-      <para>To check whether the necessary tools are already installed use
-      the following command:
-      <screen>
+
+      <title>Setting up USB/IP Support on a Linux System</title>
+
+      <para>
+        This section gives a brief overview on how to set up a Linux
+        based system to act as a USB device server. The system on the
+        server requires that the
+        <computeroutput>usbip-core.ko</computeroutput> and
+        <computeroutput>usbip-host.ko</computeroutput> kernel drivers
+        are available, and that the USB/IP tools package is installed.
+        The particular installation method for the necessary tools
+        depends on which distribution is used. For example, for Debian
+        based systems - the following command should be used to install
+        the required tools:
+
+<screen>apt-get install usbip-utils</screen>
+      </para>
+
+      <para>
+        To check whether the necessary tools are already installed use
+        the following command:
+
+<screen>
 $ usbip list -l
-      </screen></para>
-      <para>
-      which should produce output similar to that shown in the example below:
-      <screen>
+      </screen>
+      </para>
+
+      <para>
+        This should produce output similar to that shown in the example
+        below:
+
+<screen>
  - busid 4-2 (0bda:0301)
    Realtek Semiconductor Corp. : multicard reader (0bda:0301)
@@ -4335,33 +6694,51 @@
  - busid 5-1 (046d:c52b)
    Logitech, Inc. : Unifying Receiver (046d:c52b)
-      </screen></para>
-
-      <para>If everything is installed, the USB/IP server needs to be started as
-      <computeroutput>root</computeroutput> using the following command:
-      <screen>usbipd -D</screen>
-      Refer to the documentation for the installed distribution to determine how to start the
-      service when the system boots.</para>
-
-      <para>By default, no device on the server is exported - and this must be done manually
-      for each device. To export a device use:
-      <screen>usbip bind -b "bus identifier"</screen>
-      To export the multicard reader from above, for example  - use:
-      <screen>usbip bind -b 4-2</screen></para>
+      </screen>
+      </para>
+
+      <para>
+        If everything is installed, the USB/IP server needs to be
+        started as <computeroutput>root</computeroutput> using the
+        following command:
+
+<screen>usbipd -D</screen>
+
+        Refer to the documentation for the installed distribution to
+        determine how to start the service when the system boots.
+      </para>
+
+      <para>
+        By default, no device on the server is exported. This must be
+        done manually for each device. To export a device use:
+
+<screen>usbip bind -b "bus identifier"</screen>
+
+        To export the multicard reader from above, for example - use:
+
+<screen>usbip bind -b 4-2</screen>
+      </para>
+
     </sect2>
 
     <sect2 id="usbip-security">
-      <title>Security considerations</title>
-
-      <para>The communication between the server and client is unencrypted and
-      there is no authorization required to access exported devices. An attacker
-      might sniff sensitive data or gain control over a device. To mitigate this
-      risk, the device should be exposed over a local network to which only trusted
-      clients have access. To access the device remotely over a public network,
-      a VPN solution should be used to provide the required level of security protection.</para>
+
+      <title>Security Considerations</title>
+
+      <para>
+        The communication between the server and client is unencrypted
+        and there is no authorization required to access exported
+        devices. An attacker might sniff sensitive data or gain control
+        over a device. To mitigate this risk, the device should be
+        exposed over a local network to which only trusted clients have
+        access. To access the device remotely over a public network, a
+        VPN solution should be used to provide the required level of
+        security protection.
+      </para>
+
     </sect2>
+
   </sect1>
 
-  <xi:include href="user_isomakercmd-man.xml"    xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="user_isomakercmd-man.xml"    xmlns:xi="http://www.w3.org/2001/XInclude" />
 
 </chapter>
-
Index: /trunk/doc/manual/en_US/user_BasicConcepts.xml
===================================================================
--- /trunk/doc/manual/en_US/user_BasicConcepts.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_BasicConcepts.xml	(revision 73276)
@@ -1,1729 +1,2506 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="BasicConcepts">
-  <title>Configuring virtual machines</title>
-
-  <para>Whereas <xref linkend="Introduction" /> gave you a quick introduction
-  to VirtualBox and how to get your first virtual machine running, the
-  following chapter describes in detail how to configure virtual
-  machines.</para>
-
-  <para>You have considerable latitude in deciding what virtual hardware will
-  be provided to the guest. The virtual hardware can be used for communicating
-  with the host system or with other guests. For instance, if you provide
-  VirtualBox with the image of a CD-ROM in an ISO file, VirtualBox can present
-  this image to a guest system as if it were a physical CD-ROM. Similarly, you
-  can give a guest system access to the real network via its virtual network
-  card, and, if you so choose, give the host system, other guests, or
-  computers on the Internet access to the guest system.</para>
+
+  <title>Configuring Virtual Machines</title>
+
+  <para>
+    Whereas <xref linkend="Introduction" /> gave you a quick
+    introduction to VirtualBox and how to get your first virtual machine
+    running, the following chapter describes in detail how to configure
+    virtual machines.
+  </para>
+
+  <para>
+    You have considerable latitude in deciding what virtual hardware
+    will be provided to the guest. The virtual hardware can be used for
+    communicating with the host system or with other guests. For
+    instance, if you provide VirtualBox with the image of a CD-ROM in an
+    ISO file, VirtualBox can present this image to a guest system as if
+    it were a physical CD-ROM. Similarly, you can give a guest system
+    access to the real network via its virtual network card, and, if you
+    so choose, give the host system, other guests, or computers on the
+    Internet access to the guest system.
+  </para>
 
   <sect1 id="guestossupport">
-    <title>Supported guest operating systems</title>
-
-    <para>Since VirtualBox is designed to provide a generic virtualization
-    environment for x86 systems, it may run operating systems of any kind,
-    even those not listed here. However, the focus is to optimize VirtualBox
-    for the following guest systems:</para>
-
-    <para><glosslist>
-        <glossentry>
-          <glossterm>Windows NT 4.0</glossterm>
-
-          <glossdef>
-            <para>All versions, editions and service packs are fully
-            supported; however, there are some issues with older service
-            packs. We recommend to install service pack 6a. Guest Additions
-            are available with a limited feature set.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Windows 2000 / XP / Server 2003 / Vista / Server 2008 /
-            7 / 8 / 8.1 / 10 RTM 10240 / Server 2012</glossterm>
-
-          <glossdef>
-            <para>All versions, editions and service packs are fully supported
-            (including 64-bit versions, under the preconditions listed below).
-            Guest Additions are available. Windows 8 and later requires hardware
-            virtualization to be enabled.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>DOS / Windows 3.x / 95 / 98 / ME</glossterm>
-
-          <glossdef>
-            <para>Limited testing has been performed. Use beyond legacy
-            installation mechanisms not recommended. No Guest Additions
-            available.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Linux 2.4</glossterm>
-
-          <glossdef>
-            <para>Limited support.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Linux 2.6</glossterm>
-
-          <glossdef>
-            <para>All versions/editions are fully supported (32 bits and 64
-            bits). Guest Additions are available.</para>
-
-            <para>We strongly recommend using a Linux kernel version 2.6.13 or
-            higher for better performance.<note>
-                <para>Certain Linux kernel releases have bugs that prevent
-                them from executing in a virtual environment; please see <xref
-                linkend="ts_linux-buggy" /> for details.</para>
-              </note></para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Linux 3.x and later</glossterm>
-
-          <glossdef>
-            <para>All versions/editions are fully supported (32 bits and 64
-            bits). Guest Additions are available.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Solaris 10 (u6 and higher), Solaris 11 (including Solaris
-          11 Express)</glossterm>
-
-          <glossdef>
-            <para>Fully supported (64 bits, prior to Solaris 11 11/11 also 32 bits).
-            Guest Additions are available.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>FreeBSD</glossterm>
-
-          <glossdef>
-            <para>Requires hardware virtualization to be enabled. Limited
-            support. Guest Additions are not available yet.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>OpenBSD</glossterm>
-
-          <glossdef>
-            <para>Requires hardware virtualization to be enabled. Versions 3.7
-            and later are supported. Guest Additions are not available
-            yet.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>OS/2 Warp 4.5</glossterm>
-
-          <glossdef>
-            <para>Requires hardware virtualization to be enabled. We
-            officially support MCP2 only; other OS/2 versions may or may not
-            work. Guest Additions are available with a limited feature
-            set.<footnote>
-                <para>See <xref linkend="KnownIssues" />.</para>
-              </footnote></para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Mac OS X</glossterm>
-
-          <glossdef>
-            <para>VirtualBox 3.2 added experimental support for Mac OS X
-            guests, but this comes with restrictions. Please see the following
-            section as well as <xref linkend="KnownIssues" />.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist></para>
+
+    <title>Supported Guest Operating Systems</title>
+
+    <para>
+      Since VirtualBox is designed to provide a generic virtualization
+      environment for x86 systems, it may run operating systems of any
+      kind, even those not listed here. However, the focus is to
+      optimize VirtualBox for the following guest systems:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Windows NT 4.0:</emphasis>
+        </para>
+
+        <para>
+          All versions, editions and service packs are fully supported.
+          However, there are some issues with older service packs. We
+          recommend that you install service pack 6a. Guest Additions
+          are available with a limited feature set.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Windows 2000/XP/Server 2003/Vista/Server
+          2008/7/8/8.1/10 RTM 10240/Server 2012:</emphasis>
+        </para>
+
+        <para>
+          All versions, editions and service packs are fully supported,
+          including 64-bit versions, under the preconditions listed
+          below. Guest Additions are available. Windows 8 and later
+          requires hardware virtualization to be enabled.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">DOS/Windows 3.x/95/98/ME:</emphasis>
+        </para>
+
+        <para>
+          Limited testing has been performed. Use beyond legacy
+          installation mechanisms is not recommended. Guest Additions
+          are not available.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Linux 2.4:</emphasis>
+        </para>
+
+        <para>
+          Limited support.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Linux 2.6:</emphasis>
+        </para>
+
+        <para>
+          All versions and editions are fully supported, both 32-bit and
+          64-bit. Guest Additions are available.
+        </para>
+
+        <para>
+          We strongly recommend using a Linux kernel version of 2.6.13
+          or later for best performance.
+        </para>
+
+        <note>
+          <para>
+            Certain Linux kernel releases have bugs that prevent them
+            from executing in a virtual environment. See
+            <xref
+                linkend="ts_linux-buggy" />.
+          </para>
+        </note>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Linux 3.x and later:</emphasis>
+        </para>
+
+        <para>
+          All versions and editions are fully supported, both 32-bit and
+          64-bit. Guest Additions are available.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"> Solaris 10u6 and higher, Solaris 11,
+          including Solaris 11 Express:</emphasis>
+        </para>
+
+        <para>
+          Fully supported. 64-bit, prior to Solaris 11 11/11, and also
+          32 32-bit. Guest Additions are available.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">FreeBSD:</emphasis>
+        </para>
+
+        <para>
+          Requires hardware virtualization to be enabled. Limited
+          support. Guest Additions are not available yet.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"> OpenBSD:</emphasis>
+        </para>
+
+        <para>
+          Requires hardware virtualization to be enabled. Versions 3.7
+          and later are supported. Guest Additions are not available
+          yet.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">OS/2 Warp 4.5:</emphasis>
+        </para>
+
+        <para>
+          Requires hardware virtualization to be enabled. We officially
+          support MCP2 only. Other OS/2 versions may or may not work.
+          Guest Additions are available with a limited feature set. See
+          <xref linkend="KnownIssues" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Mac OS X:</emphasis>
+        </para>
+
+        <para>
+          VirtualBox 3.2 added experimental support for Mac OS X guests,
+          but this comes with restrictions. See
+          <xref linkend="intro-macosxguests"/> and also
+          <xref linkend="KnownIssues" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
 
     <sect2 id="intro-macosxguests">
-      <title>Mac OS X guests</title>
-
-      <para>Starting with version 3.2, VirtualBox has experimental support for
-      Mac OS X guests. This allows you to install and execute unmodified
-      versions of Mac OS X on supported host hardware.</para>
-
-      <para>Whereas competing solutions perform modifications to the Mac OS X
-      install DVDs (e.g. different boot loader and replaced files), VirtualBox
-      is the first product to provide the modern PC architecture expected by
-      OS X without requiring any "hacks".</para>
-
-      <para>You should be aware of a number of <emphasis role="bold">important
-      issues</emphasis> before attempting to install a Mac OS X guest:<orderedlist>
-          <listitem>
-            <para>Mac OS X is commercial, licensed software and contains
-            <emphasis role="bold">both license and technical restrictions</emphasis>
-            that limit its use to certain hardware and usage scenarios. It is
-            important that you understand and obey these restrictions.</para>
-
-            <para>In particular, for most versions of Mac OS X, Apple prohibits
-            installing them on non-Apple hardware.</para>
-
-            <para>These license restrictions are also enforced on a technical
-            level. Mac OS X verifies whether it is running on Apple hardware,
-            and most DVDs that come with Apple hardware even check for an
-            exact model. These restrictions are <emphasis>not</emphasis>
-            circumvented by VirtualBox and continue to apply.</para>
-          </listitem>
-
-          <listitem>
-            <para>Only <emphasis role="bold">CPUs</emphasis> known and tested
-            by Apple are supported. As a result, if your Intel CPU is newer
-            than the build of Mac OS X, or if you have a non-Intel CPU, it will
-            most likely panic during bootup with an "Unsupported CPU"
-            exception. It is generally best to use the Mac OS X DVD that came
-            with your Apple hardware.</para>
-          </listitem>
-
-          <listitem>
-            <para>The Mac OS X installer expects the harddisk to be
-            <emphasis role="bold">partitioned</emphasis> so when it does not
-            offer a selection, you have to launch the Disk Utility from the
-            "Tools" menu and partition the hard disk. Then close the Disk
-            Utility and proceed with the installation.</para>
-          </listitem>
-
-          <listitem>
-            <para>In addition, as Mac OS X support in VirtualBox is currently
-            still experimental, please refer also to <xref linkend="KnownIssues" />.</para>
-          </listitem>
-        </orderedlist></para>
+
+      <title>Mac OS X Guests</title>
+
+      <para>
+        Starting with version 3.2, VirtualBox has experimental support
+        for Mac OS X guests. This allows you to install and execute
+        unmodified versions of Mac OS X on supported host hardware.
+      </para>
+
+      <para>
+        Whereas competing solutions perform modifications to the Mac OS
+        X install DVDs, such as a different boot loader and replaced
+        files, VirtualBox is the first product to provide the modern PC
+        architecture expected by OS X without requiring any "hacks".
+      </para>
+
+      <para>
+        You should be aware of a number of important issues before
+        attempting to install a Mac OS X guest:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Mac OS X is commercial, licensed software and contains
+            <emphasis role="bold">both license and technical
+            restrictions</emphasis> that limit its use to certain
+            hardware and usage scenarios. It is important that you
+            understand and obey these restrictions.
+          </para>
+
+          <para>
+            In particular, for most versions of Mac OS X, Apple
+            prohibits installing them on non-Apple hardware.
+          </para>
+
+          <para>
+            These license restrictions are also enforced on a technical
+            level. Mac OS X verifies whether it is running on Apple
+            hardware, and most DVDs that come with Apple hardware even
+            check for an exact model. These restrictions are
+            <emphasis>not</emphasis> circumvented by VirtualBox and
+            continue to apply.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Only <emphasis role="bold">CPUs</emphasis> known and tested
+            by Apple are supported. As a result, if your Intel CPU is
+            newer than the build of Mac OS X, or if you have a non-Intel
+            CPU, it will most likely panic during bootup with an
+            "Unsupported CPU" exception. It is generally best to use the
+            Mac OS X DVD that came with your Apple hardware.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            The Mac OS X installer expects the harddisk to be
+            <emphasis role="bold">partitioned</emphasis> so when it does
+            not offer a selection, you have to start the Disk Utility
+            from the Tools menu and partition the hard disk. Then close
+            the Disk Utility and proceed with the installation.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            In addition, as Mac OS X support in VirtualBox is currently
+            still experimental, see also <xref linkend="KnownIssues" />.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </sect2>
 
     <sect2 id="intro-64bitguests">
-      <title>64-bit guests</title>
-
-      <para>VirtualBox supports 64-bit guest operating systems, even on 32-bit
-      host operating systems,<footnote>
-          <para>64-bit guest support was added with VirtualBox 2.0; support
-          for 64-bit guests on 32-bit hosts was added with VirtualBox
-          2.1.</para>
-        </footnote> provided that the following conditions are
-      met:<orderedlist>
-          <listitem>
-            <para>You need a 64-bit processor with hardware virtualization
-            support (see <xref linkend="hwvirt" />).</para>
-          </listitem>
-
-          <listitem>
-            <para>You must enable hardware virtualization for the particular
-            VM for which you want 64-bit support; software virtualization is
-            not supported for 64-bit VMs.</para>
-          </listitem>
-
-          <listitem>
-            <para>If you want to use 64-bit guest support on a 32-bit host
-            operating system, you must also select a 64-bit operating system
-            for the particular VM. Since supporting 64 bits on 32-bit hosts
-            incurs additional overhead, VirtualBox only enables this support
-            upon explicit request.</para>
-
-            <para>On 64-bit hosts (which typically come with hardware
-            virtualization support), 64-bit guest operating systems are always
-            supported regardless of settings, so you can simply install a
-            64-bit operating system in the guest.</para>
-          </listitem>
-        </orderedlist></para>
-
-      <para><warning>
-          <para>On any host, you should enable the <emphasis role="bold">I/O
-          APIC</emphasis> for virtual machines that you intend to use in
-          64-bit mode. This is especially true for 64-bit Windows VMs. See
-          <xref linkend="settings-general-advanced" />. In addition, for
-          64-bit Windows guests, you should make sure that the VM uses the
-          <emphasis role="bold">Intel networking device</emphasis>, since
-          there is no 64-bit driver support for the AMD PCNet card; see <xref
-          linkend="nichardware" />.</para>
-        </warning></para>
-
-      <para>If you use the "Create VM" wizard of the VirtualBox graphical user
-      interface (see <xref linkend="gui-createvm" />), VirtualBox will
-      automatically use the correct settings for each selected 64-bit
-      operating system type.</para>
+
+      <title>64-bit Guests</title>
+
+      <para>
+        VirtualBox supports 64-bit guest operating systems, even on
+        32-bit host operating systems,
+
+        <footnote>
+
+          <para>
+            64-bit guest support was added with VirtualBox 2.0; support
+            for 64-bit guests on 32-bit hosts was added with VirtualBox
+            2.1.
+          </para>
+
+        </footnote>
+
+        provided that the following conditions are met:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            You need a 64-bit processor with hardware virtualization
+            support. See <xref linkend="hwvirt" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            You must enable hardware virtualization for the particular
+            VM for which you want 64-bit support. Software
+            virtualization is not supported for 64-bit VMs.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            If you want to use 64-bit guest support on a 32-bit host
+            operating system, you must also select a 64-bit operating
+            system for the particular VM. Since supporting 64 bits on
+            32-bit hosts incurs additional overhead, VirtualBox only
+            enables this support upon explicit request.
+          </para>
+
+          <para>
+            On 64-bit hosts, which typically come with hardware
+            virtualization support, 64-bit guest operating systems are
+            always supported regardless of settings. So you can simply
+            install a 64-bit operating system in the guest.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        <warning>
+          <para>
+            On any host, you should enable <emphasis role="bold">I/O
+            APIC</emphasis> for virtual machines that you intend to use
+            in 64-bit mode. This is especially true for 64-bit Windows
+            VMs. See <xref linkend="settings-general-advanced" />. In
+            addition, for 64-bit Windows guests, you should make sure
+            that the VM uses the <emphasis role="bold">Intel networking
+            device</emphasis>, since there is no 64-bit driver support
+            for the AMD PCNet card. See
+            <xref
+          linkend="nichardware" />.
+          </para>
+        </warning>
+      </para>
+
+      <para>
+        If you use the <emphasis role="bold">Create VM </emphasis>
+        wizard of the VirtualBox graphical user interface, see
+        <xref linkend="gui-createvm" />, VirtualBox will automatically
+        use the correct settings for each selected 64-bit operating
+        system type.
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="basic-unattended">
-    <title>Unattended guest installation</title>
-    <para>VirtualBox is able to automatically install a guest by providing
-    the installation medium as well as a few parameters like the name of
-    the default user.</para>
-    <para>To perform an unattended guest installation, a VM has to be
-    prepared. A VM can be created using the GUI as described in <xref
-    linkend="gui-createvm" /> or by using VBoxManage as described in
-    <xref linkend="vboxmanage-createvm" />. In general it's sufficient to
-    chose the type of the guest operating system and to use the proposed
-    defaults for that operating system. See the following sections on how
-    to change the VM settings for certain needs.</para>
-    <para>After the VM was created, the VM has to be prepared for unattended
-    guest execution use VBoxManage, see <xref
-    linkend="vboxmanage-unattended" />. During this step VirtualBox scans
-    the installation medium and changes certain parameters for a seamless
-    installation as a guest running on VirtualBox.</para>
-    <para>Once the preparation phase was successfully finished, the VM can
-    be started either from the GUI or from VBoxManage, see <xref
-    linkend="vboxmanage-startvm" />. The VM will now perform the automatic
-    installation. Please note that the boot order was changed during the
-    preparation phase by giving the virtual hard disk the highest priority.
-    As the disk is normally empty before an automatic installation is started,
-    the VM will boot from the virtual DVD drive as next available boot medium
-    and the installation will start. If, for some reason, the virtual hard
-    disk contains a bootable operating system then the installation will not
-    start unless the boot order was manually changed by pressing F12 during
-    the BIOS splash screen.</para>
+
+    <title>Unattended Guest Installation</title>
+
+    <para>
+      VirtualBox is able to automatically install a guest by providing
+      the installation medium as well as a few parameters like the name
+      of the default user.
+    </para>
+
+    <para>
+      To perform an unattended guest installation, a VM has to be
+      prepared. A VM can be created using the GUI as described in
+      <xref
+    linkend="gui-createvm" /> or by using VBoxManage as
+      described in <xref linkend="vboxmanage-createvm" />. In general
+      it's sufficient to chose the type of the guest operating system
+      and to use the proposed defaults for that operating system. See
+      the following sections on how to change the VM settings for
+      certain needs.
+    </para>
+
+    <para>
+      After the VM was created, the VM has to be prepared for unattended
+      guest execution use VBoxManage, see
+      <xref
+    linkend="vboxmanage-unattended" />. During this step
+      VirtualBox scans the installation medium and changes certain
+      parameters for a seamless installation as a guest running on
+      VirtualBox.
+    </para>
+
+    <para>
+      Once the preparation phase was successfully finished, the VM can
+      be started either from the GUI or from VBoxManage, see
+      <xref
+    linkend="vboxmanage-startvm" />. The VM will now perform
+      the automatic installation. Please note that the boot order was
+      changed during the preparation phase by giving the virtual hard
+      disk the highest priority. As the disk is normally empty before an
+      automatic installation is started, the VM will boot from the
+      virtual DVD drive as next available boot medium and the
+      installation will start. If, for some reason, the virtual hard
+      disk contains a bootable operating system then the installation
+      will not start unless the boot order was manually changed by
+      pressing F12 during the BIOS splash screen.
+    </para>
+
   </sect1>
 
-  <sect1>
-    <title>Emulated hardware</title>
-
-    <para>VirtualBox virtualizes nearly all hardware of the host. Depending on
-    a VM's configuration, the guest will see the following virtual
-    hardware:<itemizedlist>
-        <listitem>
-          <para><emphasis role="bold">Input devices.</emphasis> By default,
+  <sect1 id="emul-hardware">
+
+    <title>Emulated Hardware</title>
+
+    <para>
+      VirtualBox virtualizes nearly all hardware of the host. Depending
+      on a VM's configuration, the guest will see the following virtual
+      hardware:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Input devices.</emphasis> By default,
           VirtualBox emulates a standard PS/2 keyboard and mouse. These
           devices are supported by almost all past and present operating
-          systems.</para>
-
-          <para>In addition, VirtualBox can provide virtual USB input devices
-          to avoid having to capture mouse and keyboard, as described in <xref
-          linkend="keyb_mouse_normal" />.</para>
+          systems.
+        </para>
+
+        <para>
+          In addition, VirtualBox can provide virtual USB input devices
+          to avoid having to capture mouse and keyboard, as described in
+          <xref
+          linkend="keyb_mouse_normal" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Graphics.</emphasis> The VirtualBox
+          graphics device (sometimes referred to as VGA device) is,
+          unlike nearly all other emulated devices, not based on any
+          physical counterpart. It is a simple, synthetic device which
+          provides compatibility with standard VGA and several extended
+          registers used by the VESA BIOS Extensions (VBE).
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Storage.</emphasis> VirtualBox currently
+          emulates the standard ATA interface found on Intel PIIX3/PIIX4
+          chips, the SATA (AHCI) interface, and two SCSI adapters (LSI
+          Logic and BusLogic). See
+          <xref linkend="harddiskcontrollers" /> for details. Whereas
+          providing one of these would be enough for VirtualBox by
+          itself, this multitude of storage adapters is required for
+          compatibility with other hypervisors. Windows is particularly
+          picky about its boot devices, and migrating VMs between
+          hypervisors is very difficult or impossible if the storage
+          controllers are different.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Networking.</emphasis> See
+          <xref
+          linkend="nichardware" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">USB.</emphasis> VirtualBox emulates
+          three USB host controllers: xHCI, EHCI, and OHCI. While xHCI
+          handles all USB transfer speeds, only guest operating systems
+          released approximately after 2011 support xHCI. Note that for
+          Windows 7 guests, 3rd party drivers must be installed for xHCI
+          support.
+        </para>
+
+        <para>
+          Older operating systems typically support OHCI and EHCI. The
+          two controllers are needed because OHCI only handles USB low-
+          and full-speed devices (both USB 1.x and 2.0), while EHCI only
+          handles high-speed devices (USB 2.0 only).
+        </para>
+
+        <para>
+          The emulated USB controllers do not communicate directly with
+          devices on the host but rather with a virtual USB layer which
+          abstracts the USB protocol and allows the use of remote USB
+          devices.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Audio.</emphasis> See
+          <xref
+          linkend="settings-audio" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="generalsettings">
+
+    <title>General Settings</title>
+
+    <para>
+      In the Settings window, under
+      <emphasis role="bold">General</emphasis>, you can configure the
+      most fundamental aspects of the virtual machine such as memory and
+      essential hardware. There are three tabs: Basic, Advanced and
+      Description.
+    </para>
+
+    <sect2 id="settings-basic">
+
+      <title>Basic Tab</title>
+
+      <para>
+        In the Basic tab of the General settings category, you can find
+        these settings:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Name:</emphasis> The name under which
+            the VM is shown in the list of VMs in the main window. Under
+            this name, VirtualBox also saves the VM's configuration
+            files. By changing the name, VirtualBox renames these files
+            as well. As a result, you can only use characters which are
+            allowed in your host operating system's file names.
+          </para>
+
+          <para>
+            Note that internally, VirtualBox uses unique identifiers
+            (UUIDs) to identify virtual machines. You can display these
+            with <computeroutput>VBoxManage</computeroutput>.
+          </para>
         </listitem>
 
         <listitem>
-          <para><emphasis role="bold">Graphics.</emphasis> The VirtualBox
-          graphics device (sometimes referred to as VGA device) is, unlike
-          nearly all other emulated devices, not based on any physical
-          counterpart. It is a simple, synthetic device which provides
-          compatibility with standard VGA and several extended registers used
-          by the VESA BIOS Extensions (VBE).</para>
+          <para>
+            <emphasis role="bold">Operating system/version:</emphasis>
+            The type of the guest operating system that is, or will be,
+            installed in the VM. This is the same setting that was
+            specified in the "New Virtual Machine" wizard. See
+            <xref
+            linkend="gui-createvm" />.
+          </para>
+
+          <para>
+            Whereas the default settings of a newly created VM depend on
+            the selected operating system type, changing the type later
+            has no effect on VM settings. This value is purely
+            informational and decorative.
+          </para>
         </listitem>
 
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="settings-general-advanced">
+
+      <title>Advanced Tab</title>
+
+      <para>
+        The following settings are available in the Advanced tab:
+      </para>
+
+      <itemizedlist>
+
         <listitem>
-          <para><emphasis role="bold">Storage.</emphasis> VirtualBox currently
-          emulates the standard ATA interface found on Intel PIIX3/PIIX4
-          chips, the SATA (AHCI) interface, and two SCSI adapters (LSI Logic
-          and BusLogic); see <xref linkend="harddiskcontrollers" /> for
-          details. Whereas providing one of these would be enough for
-          VirtualBox by itself, this multitude of storage adapters is required
-          for compatibility with other hypervisors. Windows is particularly
-          picky about its boot devices, and migrating VMs between hypervisors
-          is very difficult or impossible if the storage controllers are
-          different.</para>
+          <para>
+            <emphasis role="bold">Snapshot Folder:</emphasis> By
+            default, VirtualBox saves snapshot data together with your
+            other VirtualBox configuration data. See
+            <xref
+              linkend="vboxconfigdata" />. With this
+            setting, you can specify any other folder for each VM.
+          </para>
         </listitem>
 
         <listitem>
-          <para><emphasis role="bold">Networking.</emphasis> See <xref
-          linkend="nichardware" />.</para>
+          <para>
+            <emphasis role="bold">Shared Clipboard:</emphasis> You can
+            select here whether the clipboard of the guest operating
+            system should be shared with that of your host. If you
+            select <emphasis role="bold">Bidirectional</emphasis>, then
+            VirtualBox will always make sure that both clipboards
+            contain the same data. If you select
+            <emphasis role="bold">Host to Guest</emphasis> or
+            <emphasis role="bold">Guest to Host</emphasis>, then
+            VirtualBox will only ever copy clipboard data in one
+            direction.
+          </para>
+
+          <para>
+            Clipboard sharing requires that the VirtualBox Guest
+            Additions be installed. In such a case, this setting has no
+            effect. See <xref linkend="guestadditions" />.
+          </para>
+
+          <para>
+            The shared clipboard is disabled by default. See
+            <xref linkend="security_clipboard"/> for an explanation.
+            This setting can be changed at any time using the "Shared
+            Clipboard" menu item in the "Devices" menu of the virtual
+            machine.
+          </para>
         </listitem>
 
         <listitem>
-          <para><emphasis role="bold">USB.</emphasis> VirtualBox emulates three
-          USB host controllers: xHCI, EHCI, and OHCI. While xHCI handles all USB
-          transfer speeds, only guest operating systems released approximately
-          after 2011 support xHCI. Note that for Windows 7 guests, 3rd party
-          drivers must be installed for xHCI support.</para>
-          <para>
-          Older operating systems typically support OHCI and EHCI. The two
-          controllers are needed because OHCI only handles USB low- and full-speed
-          devices (both USB 1.x and 2.0), while EHCI only handles high-speed
-          devices (USB 2.0 only).</para>
-          <para>
-          The emulated USB controllers do not
-          communicate directly with devices on the host but rather with a
-          virtual USB layer which abstracts the USB protocol and allows the
-          use of remote USB devices.</para>
+          <para>
+            <emphasis role="bold">Drag and Drop:</emphasis> This setting
+            enables support for drag and drop. Select an object, such as
+            a file, from the host or guest and directly copy or open it
+            on the guest or host. Multiple per-VM drag and drop modes
+            allow restricting access in either direction.
+          </para>
+
+          <para>
+            For drag and drop to work the Guest Additions need to be
+            installed on the guest.
+          </para>
+
+          <note>
+            <para>
+              Drag and drop is disabled by default. This setting can be
+              changed at any time using the <emphasis role="bold">Drag
+              and Drop</emphasis> menu item in the Devices menu of the
+              virtual machine.
+            </para>
+          </note>
+
+          <para>
+            See <xref linkend="guestadd-dnd"/>.
+
+            <footnote>
+
+              <para>
+                Experimental support for drag and drop was added with
+                VirtualBox 4.2.
+              </para>
+
+            </footnote>
+          </para>
         </listitem>
 
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="settings-description">
+
+      <title>Description Tab</title>
+
+      <para>
+        Here you can enter any description for your virtual machine, if
+        you want. This has no effect on the functionality of the
+        machine, but you may find this space useful to note down things
+        like the configuration of a virtual machine and the software
+        that has been installed into it.
+      </para>
+
+      <para>
+        To insert a line break into the description text field, press
+        <emphasis>Shift+Enter</emphasis>.
+      </para>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="settings-system">
+
+    <title>System Settings</title>
+
+    <para>
+      The System category groups various settings that are related to
+      the basic hardware that is presented to the virtual machine.
+    </para>
+
+    <note>
+      <para>
+        As the activation mechanism of Microsoft Windows is sensitive to
+        hardware changes, if you are changing hardware settings for a
+        Windows guest, some of these changes may trigger a request for
+        another activation with Microsoft.
+      </para>
+    </note>
+
+    <sect2 id="settings-motherboard">
+
+      <title>Motherboard Tab</title>
+
+      <para>
+        On the Motherboard tab, you can influence virtual hardware that
+        would normally be on the motherboard of a real computer.
+      </para>
+
+      <itemizedlist>
+
         <listitem>
-          <para><emphasis role="bold">Audio.</emphasis> See <xref
-          linkend="settings-audio" />.</para>
+          <para>
+            <emphasis role="bold">Base memory:</emphasis> Sets the
+            amount of RAM that is allocated and given to the VM when it
+            is running. The specified amount of memory will be requested
+            from the host operating system, so it must be available or
+            made available as free memory on the host when attempting to
+            start the VM and will not be available to the host while the
+            VM is running. This is the same setting that was specified
+            in the "New Virtual Machine" wizard, as described in
+            <xref linkend="gui-createvm" />.
+          </para>
+
+          <para>
+            Generally, it is possible to change the memory size after
+            installing the guest operating system. But you must not
+            reduce the memory to an amount where the operating system
+            would no longer boot.
+          </para>
         </listitem>
-      </itemizedlist></para>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Boot order:</emphasis> Determines the
+            order in which the guest operating system will attempt to
+            boot from the various virtual boot devices. Analogous to a
+            real PC's BIOS setting, VirtualBox can tell a guest OS to
+            start from the virtual floppy, the virtual CD/DVD drive, the
+            virtual hard drive (each of these as defined by the other VM
+            settings), the network, or none of these.
+          </para>
+
+          <para>
+            If you select <emphasis role="bold">Network</emphasis>, the
+            VM will attempt to boot from a network via the PXE
+            mechanism. This needs to be configured in detail on the
+            command line. See
+            <xref
+              linkend="vboxmanage-modifyvm" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Chipset:</emphasis> You can select
+            which chipset will be presented to the virtual machine.
+            Before VirtualBox 4.0, PIIX3 was the only available option
+            here. For modern guest operating systems such as Mac OS X,
+            that old chipset is no longer well supported. As a result,
+            VirtualBox 4.0 introduced an emulation of the more modern
+            ICH9 chipset, which supports PCI express, three PCI buses,
+            PCI-to-PCI bridges and Message Signaled Interrupts (MSI).
+            This allows modern operating systems to address more PCI
+            devices and no longer requires IRQ sharing. Using the ICH9
+            chipset it is also possible to configure up to 36 network
+            cards, up to 8 network adapters with PIIX3. Note that the
+            ICH9 support is experimental and not recommended for guest
+            operating systems which do not require it.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Pointing Device:</emphasis> The
+            default virtual pointing devices for older guests is the
+            traditional PS/2 mouse. If set to <emphasis>USB
+            tablet</emphasis>, VirtualBox reports to the virtual machine
+            that a USB tablet device is present and communicates mouse
+            events to the virtual machine through this device. The third
+            setting is a <emphasis>USB Multi-Touch Tablet</emphasis>
+            which is suited for recent Windows guests.
+          </para>
+
+          <para>
+            Using the virtual USB tablet has the advantage that
+            movements are reported in absolute coordinates, instead of
+            as relative position changes. This allows VirtualBox to
+            translate mouse events over the VM window into tablet events
+            without having to "capture" the mouse in the guest as
+            described in
+            <xref
+              linkend="keyb_mouse_normal" />. This
+            makes using the VM less tedious even if Guest Additions are
+            not installed.
+
+            <footnote>
+
+              <para>
+                The virtual USB tablet was added with VirtualBox 3.2.
+                Depending on the guest operating system selected, this
+                is now enabled by default for new virtual machines.
+              </para>
+
+            </footnote>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Enable I/O APIC:</emphasis> Advanced
+            Programmable Interrupt Controllers (APICs) are a newer x86
+            hardware feature that have replaced old-style Programmable
+            Interrupt Controllers (PICs) in recent years. With an I/O
+            APIC, operating systems can use more than 16 interrupt
+            requests (IRQs) and therefore avoid IRQ sharing for improved
+            reliability.
+          </para>
+
+          <note>
+            <para>
+              Enabling the I/O APIC is <emphasis>required</emphasis> for
+              64-bit guest operating systems, especially Windows Vista.
+              It is also required if you want to use more than one
+              virtual CPU in a virtual machine.
+            </para>
+          </note>
+
+          <para>
+            However, software support for I/O APICs has been unreliable
+            with some operating systems other than Windows. Also, the
+            use of an I/O APIC slightly increases the overhead of
+            virtualization and therefore slows down the guest OS a
+            little.
+          </para>
+
+          <warning>
+            <para>
+              All Windows operating systems starting with Windows 2000
+              install different kernels depending on whether an I/O APIC
+              is available. As with ACPI, the I/O APIC therefore
+              <emphasis>must not be turned off after
+              installation</emphasis> of a Windows guest OS. Turning it
+              on after installation will have no effect however.
+            </para>
+          </warning>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Enable EFI:</emphasis> Enables
+            Extensible Firmware Interface (EFI), which replaces the
+            legacy BIOS and may be useful for certain advanced use
+            cases. See <xref linkend="efi" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Hardware clock in UTC time:</emphasis>
+            If checked, VirtualBox will report the system time in UTC
+            format to the guest instead of local (host) time. This
+            affects how the virtual real-time clock (RTC) operates and
+            may be useful for Unix-like guest operating systems, which
+            typically expect the hardware clock to be set to UTC.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        In addition, you can turn off the <emphasis role="bold">Advanced
+        Configuration and Power Interface (ACPI)</emphasis> which
+        VirtualBox presents to the guest operating system by default.
+        ACPI is the current industry standard to allow operating systems
+        to recognize hardware, configure motherboards and other devices
+        and manage power. As all modern PCs contain this feature and
+        Windows and Linux have been supporting it for years, it is also
+        enabled by default in VirtualBox. It can only be turned off on
+        the command line. See
+        <xref
+      linkend="vboxmanage-modifyvm" />.
+      </para>
+
+      <warning>
+        <para>
+          All Windows operating systems starting with Windows 2000
+          install different kernels depending on whether ACPI is
+          available, so ACPI <emphasis>must not be turned off</emphasis>
+          after installation of a Windows guest OS. Turning it on after
+          installation will have no effect however.
+        </para>
+      </warning>
+
+    </sect2>
+
+    <sect2 id="settings-processor">
+
+      <title>Processor Tab</title>
+
+      <para>
+        On the Processor tab, you can set how many virtual
+        <emphasis role="bold">CPU cores</emphasis> the guest operating
+        systems should see. Starting with version 3.0, VirtualBox
+        supports symmetrical multiprocessing (SMP) and can present up to
+        32 virtual CPU cores to each virtual machine.
+      </para>
+
+      <para>
+        You should not, however, configure virtual machines to use more
+        CPU cores than are available physically (real cores, no
+        hyperthreads).
+      </para>
+
+      <para>
+        On this tab you can also set the <emphasis role="bold">CPU
+        execution cap</emphasis>. This setting limits the amount of time
+        a host CPU spends to emulate a virtual CPU. The default setting
+        is 100% meaning that there is no limitation. A setting of 50%
+        implies a single virtual CPU can use up to 50% of a single host
+        CPU. Note that limiting the execution time of the virtual CPUs
+        may induce guest timing problems.
+      </para>
+
+      <para>
+        In addition, the <emphasis role="bold">Enable PAE/NX</emphasis>
+        setting determines whether the PAE and NX capabilities of the
+        host CPU will be exposed to the virtual machine. PAE stands for
+        "Physical Address Extension". Normally, if enabled and supported
+        by the operating system, then even a 32-bit x86 CPU can access
+        more than 4 GB of RAM. This is made possible by adding another 4
+        bits to memory addresses, so that with 36 bits, up to 64 GB can
+        be addressed. Some operating systems, such as Ubuntu Server,
+        require PAE support from the CPU and cannot be run in a virtual
+        machine without it.
+      </para>
+
+      <para>
+        With virtual machines running modern server operating systems,
+        VirtualBox also supports CPU hot-plugging. For details, see
+        <xref linkend="cpuhotplug" />.
+      </para>
+
+    </sect2>
+
+    <sect2 id="settings-acceleration">
+
+      <title>Acceleration Tab</title>
+
+      <para>
+        On this page, you can determine whether and how VirtualBox
+        should use hardware virtualization extensions that your host CPU
+        may support. This is the case with most CPUs built after 2006.
+      </para>
+
+      <para>
+        You can select for each virtual machine individually whether
+        VirtualBox should use software or hardware virtualization.
+
+        <footnote>
+
+          <para>
+            Prior to VirtualBox version 2.2, software virtualization was
+            the default; starting with version 2.2, VirtualBox will
+            enable hardware virtualization by default for new virtual
+            machines that you create. Existing virtual machines are not
+            automatically changed for compatibility reasons, and the
+            default can of course be changed for each virtual machine.
+          </para>
+
+        </footnote>
+      </para>
+
+      <para>
+        In most cases, the default settings will be fine; VirtualBox
+        will have picked sensible defaults depending on the operating
+        system that you selected when you created the virtual machine.
+        In certain situations, however, you may want to change these
+        preconfigured defaults.
+      </para>
+
+      <para>
+        Advanced users may be interested in technical details about
+        software vs. hardware virtualization. See
+        <xref
+      linkend="hwvirt" />.
+      </para>
+
+      <para>
+        If your host's CPU supports the <emphasis role="bold">nested
+        paging</emphasis> (AMD-V) or
+        <emphasis role="bold">EPT</emphasis> (Intel VT-x) features, then
+        you can expect a significant performance increase by enabling
+        nested paging in addition to hardware virtualization. For
+        technical details, see <xref linkend="nestedpaging" />.
+      </para>
+
+      <para>
+        Starting with version 5.0, VirtualBox provides
+        paravirtualization interfaces to improve time-keeping accuracy
+        and performance of guest operating systems. The options
+        available are documented under the
+        <computeroutput>paravirtprovider</computeroutput> option in
+        <xref linkend="vboxmanage-modifyvm" />. For further details on
+        the paravirtualization providers, see
+        <xref linkend="gimproviders" />.
+      </para>
+
+    </sect2>
+
   </sect1>
 
-  <sect1 id="generalsettings">
-    <title>General settings</title>
-
-    <para>In the Settings window, under "General", you can configure the most
-    fundamental aspects of the virtual machine such as memory and essential
-    hardware. There are three tabs, "Basic", "Advanced" and
-    "Description".</para>
-
-    <sect2>
-      <title>"Basic" tab</title>
-
-      <para>Under the "Basic" tab of the "General" settings category, you can
-      find these settings:</para>
-
-      <glosslist>
-        <glossentry>
-          <glossterm>Name</glossterm>
-
-          <glossdef>
-            <para>The name under which the VM is shown in the list of VMs in
-            the main window. Under this name, VirtualBox also saves the VM's
-            configuration files. By changing the name, VirtualBox renames
-            these files as well. As a result, you can only use characters
-            which are allowed in your host operating system's file
-            names.</para>
-
-            <para>Note that internally, VirtualBox uses unique identifiers
-            (UUIDs) to identify virtual machines. You can display these with
-            <computeroutput>VBoxManage</computeroutput>.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Operating system / version</glossterm>
-
-          <glossdef>
-            <para>The type of the guest operating system that is (or will be)
-            installed in the VM. This is the same setting that was specified
-            in the "New Virtual Machine" wizard, as described in <xref
-            linkend="gui-createvm" />.</para>
-
-            <para>Whereas the default settings of a newly created VM depend on
-            the selected operating system type, changing the type later has no
-            effect on VM settings; this value is then purely informational and
-            decorative.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-    </sect2>
-
-    <sect2 id="settings-general-advanced">
-      <title>"Advanced" tab</title>
-
-      <para><glosslist>
-          <glossentry>
-            <glossterm>Snapshot Folder</glossterm>
-
-            <glossdef>
-              <para>By default, VirtualBox saves snapshot data together with
-              your other VirtualBox configuration data; see <xref
-              linkend="vboxconfigdata" />. With this setting, you can specify
-              any other folder for each VM.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>Shared Clipboard</glossterm>
-
-            <glossdef>
-              <para>You can select here whether the clipboard of the guest
-              operating system should be shared with that of your host. If you
-              select "Bidirectional", then VirtualBox will always make sure
-              that both clipboards contain the same data. If you select "Host
-              to guest" or "Guest to host", then VirtualBox will only ever
-              copy clipboard data in one direction.</para>
-
-              <para>Clipboard sharing requires that the VirtualBox Guest
-              Additions be installed. As a result, this setting has no effect
-              otherwise; see <xref linkend="guestadditions" /> for
-              details.</para>
-
-              <para>The shared clipboard is disabled by default. See
-              <xref linkend="security_clipboard"/> for an explanation. This
-              setting can be changed at any time using the "Shared Clipboard"
-              menu item in the "Devices" menu of the virtual machine.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>Drag and Drop</glossterm>
-            <glossdef>
-              <para>This setting allows to enable support for drag and drop: Select
-              an object (e.g. a file) from the host or guest and directly copy
-              or open it on the guest or host. Multiple per-VM drag and drop modes
-              allow restricting access in either direction.</para>
-
-              <para>For drag and drop to work the Guest Additions need to be
-              installed on the guest.</para>
-
-              <para><note><para>Drag and drop is disabled by default. This setting can be
-              changed at any time using the "Drag and Drop" menu item in the
-              "Devices" menu of the virtual machine.</para></note></para>
-
-              <para>See <xref linkend="guestadd-dnd"/> for more information.
-              <footnote><para>Experimental support for drag and drop was added
-              with VirtualBox 4.2.</para></footnote></para>
-            </glossdef>
-          </glossentry>
-
-        </glosslist></para>
-    </sect2>
-
-    <sect2>
-      <title>"Description" tab</title>
-
-      <para>Here you can enter any description for your virtual machine, if
-      you want. This has no effect on the functionality of the machine, but
-      you may find this space useful to note down things like the
-      configuration of a virtual machine and the software that has been
-      installed into it.</para>
-      <para>To insert a line break into the description text field, press
-      <emphasis>Shift+Enter</emphasis>.</para>
-    </sect2>
+  <sect1 id="settings-display">
+
+    <title>Display Settings</title>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Video memory size:</emphasis> Sets the
+          size of the memory provided by the virtual graphics card
+          available to the guest, in MB. As with the main memory, the
+          specified amount will be allocated from the host's resident
+          memory. Based on the amount of video memory, higher
+          resolutions and color depths may be available.
+        </para>
+
+        <para>
+          The GUI will show a warning if the amount of video memory is
+          too small to be able to switch the VM into full screen mode.
+          The minimum value depends on the number of virtual monitors,
+          the screen resolution and the color depth of the host display
+          as well as of the activation of <emphasis>3D
+          acceleration</emphasis> and <emphasis>2D video
+          acceleration</emphasis>. A rough estimate is (<emphasis>color
+          depth</emphasis> / 8) x <emphasis>vertical pixels</emphasis> x
+          <emphasis>horizontal pixels</emphasis> x <emphasis>number of
+          screens</emphasis> = <emphasis>number of bytes</emphasis>.
+          Like said above, there might be extra memory required for any
+          activated display acceleration setting.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Monitor count:</emphasis> With this
+          setting VirtualBox can provide more than one virtual monitor
+          to a virtual machine. If a guest operating system, such as
+          Windows, supports multiple attached monitors, VirtualBox can
+          pretend that multiple virtual monitors are present.
+
+          <footnote>
+
+            <para>
+              Multiple monitor support was added with VirtualBox 3.2.
+            </para>
+
+          </footnote>
+
+          Up to eight such virtual monitors are supported.
+        </para>
+
+        <para>
+          The output of the multiple monitors are displayed on the host
+          in multiple VM windows which are running side by side.
+        </para>
+
+        <para>
+          However, in full screen and seamless mode, they use the
+          available physical monitors attached to the host. As a result,
+          for full screen and seamless modes to work with multiple
+          monitors, you will need at least as many physical monitors as
+          you have virtual monitors configured, or VirtualBox will
+          report an error. You can configure the relationship between
+          guest and host monitors using the view menu by pressing Host
+          key + Home when you are in full screen or seamless mode.
+        </para>
+
+        <para>
+          See also <xref linkend="KnownIssues" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Enable 3D acceleration:</emphasis> If a
+          virtual machine has Guest Additions installed, you can select
+          here whether the guest should support accelerated 3D graphics.
+          See <xref linkend="guestadd-3d" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Enable 2D video acceleration:</emphasis>
+          If a virtual machine with Microsoft Windows has Guest
+          Additions installed, you can select here whether the guest
+          should support accelerated 2D video graphics. See
+          <xref
+          linkend="guestadd-2d" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Remote display:</emphasis> On the
+          <emphasis role="bold">Remote Display</emphasis> tab, if the
+          VirtualBox Remote Display Extension (VRDE) is installed, you
+          can enable the VRDP server that is built into VirtualBox. This
+          enables you to connect to the console of the virtual machine
+          remotely with any standard RDP viewer, such as
+          <computeroutput>mstsc.exe</computeroutput> that comes with
+          Microsoft Windows. On Linux and Solaris systems you can use
+          the standard open source
+          <computeroutput>rdesktop</computeroutput> program. These
+          features are described in <xref linkend="vrde" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Video Capture:</emphasis> On the
+          <emphasis role="bold">Video Capture</emphasis> tab you can
+          enable video capturing for this VM. Note that this feature can
+          also be enabled/disabled while the VM is executed.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
-  <sect1 id="settings-system">
-    <title>System settings</title>
-
-    <para>The "System" category groups various settings that are related to
-    the basic hardware that is presented to the virtual machine.<note>
-        <para>As the activation mechanism of Microsoft Windows is sensitive to
-        hardware changes, if you are changing hardware settings for a Windows
-        guest, some of these changes may trigger a request for another
-        activation with Microsoft.</para>
-      </note></para>
-
-    <sect2 id="settings-motherboard">
-      <title>"Motherboard" tab</title>
-
-      <para>On the "Motherboard" tab, you can influence virtual hardware that
-      would normally be on the motherboard of a real computer.<glosslist>
-          <glossentry>
-            <glossterm>Base memory</glossterm>
-
-            <glossdef>
-              <para>This sets the amount of RAM that is allocated and given to
-              the VM when it is running. The specified amount of memory will
-              be requested from the host operating system, so it must be
-              available or made available as free memory on the host when
-              attempting to start the VM and will not be available to the host
-              while the VM is running. This is the same setting that was
-              specified in the "New Virtual Machine" wizard, as described with
-              guidelines under <xref linkend="gui-createvm" /> above.</para>
-
-              <para>Generally, it is possible to change the memory size after
-              installing the guest operating system (provided you do not
-              reduce the memory to an amount where the operating system would
-              no longer boot).</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>Boot order</glossterm>
-
-            <glossdef>
-              <para>This setting determines the order in which the guest
-              operating system will attempt to boot from the various virtual
-              boot devices. Analogous to a real PC's BIOS setting, VirtualBox
-              can tell a guest OS to start from the virtual floppy, the
-              virtual CD/DVD drive, the virtual hard drive (each of these as
-              defined by the other VM settings), the network, or none of
-              these.</para>
-
-              <para>If you select "Network", the VM will attempt to boot from
-              a network via the PXE mechanism. This needs to be configured in
-              detail on the command line; please see <xref
-              linkend="vboxmanage-modifyvm" />.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>Chipset</glossterm>
-
-            <glossdef>
-              <para>Here you can select which chipset will be presented to the
-              virtual machine. Before VirtualBox 4.0, PIIX3 was the only
-              available option here. For modern guest operating systems such
-              as Mac OS X, that old chipset is no longer well supported. As a
-              result, VirtualBox 4.0 introduced an emulation of the more
-              modern ICH9 chipset, which supports PCI express, three PCI
-              buses, PCI-to-PCI bridges and Message Signaled Interrupts
-              (MSI). This allows modern operating systems to address more PCI
-              devices and no longer requires IRQ sharing. Using the ICH9 chipset
-              it is also possible to configure up to 36 network cards (up to 8
-              network adapters with PIIX3). Note that the ICH9 support is
-              experimental and not recommended for guest operating systems which
-              do not require it.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>Pointing Device</glossterm>
-
-            <glossdef>
-              <para>The default virtual pointing devices for older guests is the
-              traditional PS/2 mouse. If set to <emphasis>USB tablet</emphasis>,
-              VirtualBox reports to the virtual machine that a USB tablet
-              device is present and communicates mouse events to
-              the virtual machine through this device. The third setting is
-              a <emphasis>USB Multi-Touch Tablet</emphasis> which is suited
-              for recent Windows guests.</para>
-
-              <para>Using the virtual USB tablet has the advantage that
-              movements are reported in absolute coordinates (instead of as
-              relative position changes), which allows VirtualBox to translate
-              mouse events over the VM window into tablet events without
-              having to "capture" the mouse in the guest as described in <xref
-              linkend="keyb_mouse_normal" />. This makes using the VM less
-              tedious even if Guest Additions are not installed.<footnote>
-                  <para>The virtual USB tablet was added with VirtualBox 3.2.
-                  Depending on the guest operating system selected, this is
-                  now enabled by default for new virtual machines.</para>
-                </footnote></para>
-            </glossdef>
-          </glossentry>
-          <glossentry>
-            <glossterm>Enable I/O APIC</glossterm>
-
-            <glossdef>
-              <para>Advanced Programmable Interrupt Controllers (APICs) are a
-              newer x86 hardware feature that have replaced old-style
-              Programmable Interrupt Controllers (PICs) in recent years. With
-              an I/O APIC, operating systems can use more than 16 interrupt
-              requests (IRQs) and therefore avoid IRQ sharing for improved
-              reliability.<note>
-                  <para>Enabling the I/O APIC is <emphasis>required</emphasis>
-                  for 64-bit guest operating systems, especially Windows
-                  Vista; it is also required if you want to use more than one
-                  virtual CPU in a virtual machine.</para>
-                </note></para>
-
-              <para>However, software support for I/O APICs has been
-              unreliable with some operating systems other than Windows. Also,
-              the use of an I/O APIC slightly increases the overhead of
-              virtualization and therefore slows down the guest OS a
-              little.<warning>
-                  <para>All Windows operating systems starting with Windows
-                  2000 install different kernels depending on whether an I/O
-                  APIC is available. As with ACPI, the I/O APIC therefore
-                  <emphasis>must not be turned off after
-                  installation</emphasis> of a Windows guest OS. Turning it on
-                  after installation will have no effect however.</para>
-                </warning></para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>Enable EFI</glossterm>
-
-            <glossdef>
-              <para>This enables Extensible Firmware Interface (EFI), which
-              replaces the legacy BIOS and may be useful for certain
-              advanced use cases. Please refer to <xref linkend="efi" /> for
-              details.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>Hardware clock in UTC time</glossterm>
-
-            <glossdef>
-              <para>If checked, VirtualBox will report the system time in UTC
-              format to the guest instead of local (host) time. This affects
-              how the virtual real-time clock (RTC) operates and may be useful
-              for Unix-like guest operating systems, which typically expect
-              the hardware clock to be set to UTC.</para>
-            </glossdef>
-          </glossentry>
-
-        </glosslist></para>
-
-      <para>In addition, you can turn off the <emphasis role="bold">Advanced
-      Configuration and Power Interface (ACPI)</emphasis> which VirtualBox
-      presents to the guest operating system by default. ACPI is the current
-      industry standard to allow operating systems to recognize hardware,
-      configure motherboards and other devices and manage power. As all modern
-      PCs contain this feature and Windows and Linux have been supporting it
-      for years, it is also enabled by default in VirtualBox. It can only be
-      turned off on the command line; see <xref
-      linkend="vboxmanage-modifyvm" />.<warning>
-          <para>All Windows operating systems starting with Windows 2000
-          install different kernels depending on whether ACPI is available, so
-          ACPI <emphasis>must not be turned off</emphasis> after installation
-          of a Windows guest OS. Turning it on after installation will have no
-          effect however.</para>
-        </warning></para>
-    </sect2>
-
-    <sect2 id="settings-processor">
-      <title>"Processor" tab</title>
-
-      <para>On the "Processor" tab, you can set how many virtual <emphasis
-      role="bold">CPU cores</emphasis> the guest operating systems should see.
-      Starting with version 3.0, VirtualBox supports symmetrical
-      multiprocessing (SMP) and can present up to 32 virtual CPU cores to each
-      virtual machine.</para>
-
-      <para>You should not, however, configure virtual machines to use more
-      CPU cores than you have available physically (real cores, no hyperthreads).</para>
-
-      <para>On this tab you can also set the <emphasis role="bold">"CPU execution
-      cap"</emphasis>. This setting
-      limits the amount of time a host CPU spends to emulate a virtual CPU.
-      The default setting is 100% meaning that there is no limitation. A setting
-      of 50% implies a single virtual CPU can use up to 50% of a single host
-      CPU. Note that limiting the execution time of the virtual CPUs may induce
-      guest timing problems.</para>
-
-      <para>In addition, the <emphasis role="bold">"Enable PAE/NX"</emphasis>
-      setting determines whether the PAE and NX capabilities of the host CPU
-      will be exposed to the virtual machine. PAE stands for "Physical Address
-      Extension". Normally, if enabled and supported by the operating system,
-      then even a 32-bit x86 CPU can access more than 4 GB of RAM. This is
-      made possible by adding another 4 bits to memory addresses, so that with
-      36 bits, up to 64 GB can be addressed. Some operating systems (such as
-      Ubuntu Server) require PAE support from the CPU and cannot be run in a
-      virtual machine without it.</para>
-
-      <para>With virtual machines running modern server operating systems,
-      VirtualBox also supports CPU hot-plugging. For details about this,
-      please refer to <xref linkend="cpuhotplug" />.</para>
-    </sect2>
-
-    <sect2>
-      <title>"Acceleration" tab</title>
-
-      <para>On this page, you can determine whether and how VirtualBox should
-      use hardware virtualization extensions that your host CPU may support.
-      This is the case with most CPUs built after 2006.</para>
-
-      <para>You can select for each virtual machine individually whether
-      VirtualBox should use software or hardware virtualization.<footnote>
-          <para>Prior to VirtualBox version 2.2, software virtualization was
-          the default; starting with version 2.2, VirtualBox will enable
-          hardware virtualization by default for new virtual machines that you
-          create. (Existing virtual machines are not automatically changed for
-          compatibility reasons, and the default can of course be changed for
-          each virtual machine.)</para>
-        </footnote></para>
-
-      <para>In most cases, the default settings will be fine; VirtualBox will
-      have picked sensible defaults depending on the operating system that you
-      selected when you created the virtual machine. In certain situations,
-      however, you may want to change these preconfigured defaults.</para>
-
-      <para>Advanced users may be interested in technical details about
-      software vs. hardware virtualization; please see <xref
-      linkend="hwvirt" />.</para>
-
-      <para>If your host's CPU supports the <emphasis role="bold">nested
-      paging</emphasis> (AMD-V) or <emphasis role="bold">EPT</emphasis> (Intel
-      VT-x) features, then you can expect a significant performance increase
-      by enabling nested paging in addition to hardware virtualization. For
-      technical details, see <xref linkend="nestedpaging" />.</para>
-
-      <para>Starting with version 5.0, VirtualBox provides paravirtualization
-      interfaces to improve time-keeping accuracy and performance of guest
-      operating systems. The options available are documented under the
-      <computeroutput>paravirtprovider</computeroutput> option
-      in <xref linkend="vboxmanage-modifyvm" />. For further details on
-      the paravirtualization providers, please refer to
-      <xref linkend="gimproviders" />.</para>
-    </sect2>
-  </sect1>
-
-  <sect1 id="settings-display">
-    <title>Display settings</title>
-
-    <glosslist>
-      <glossentry>
-        <glossterm>Video memory size</glossterm>
-
-        <glossdef>
-          <para>This sets the size of the memory provided by the virtual
-          graphics card available to the guest, in MB. As with the main
-          memory, the specified amount will be allocated from the host's
-          resident memory. Based on the amount of video memory, higher
-          resolutions and color depths may be available.</para>
-          <para>The GUI will show a warning if the amount of video memory
-          is too small to be able to switch the VM into full screen mode.
-          The minimum value depends on the number of virtual monitors, the
-          screen resolution and the color depth of the host display as well
-          as of the activation of <emphasis>3D acceleration</emphasis> and
-          <emphasis>2D video acceleration</emphasis>. A rough estimate
-          is (<emphasis>color depth</emphasis> / 8) x
-          <emphasis>vertical pixels</emphasis> x
-          <emphasis>horizontal pixels</emphasis> x
-          <emphasis>number of screens</emphasis> = <emphasis>number of bytes</emphasis>.
-          Like said above, there might be extra memory required for any
-          activated display acceleration setting.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>Monitor count</glossterm>
-
-        <glossdef>
-          <para>With this setting VirtualBox can provide more than one virtual
-          monitor to a virtual machine. If a guest operating system (such as
-          Windows) supports multiple attached monitors, VirtualBox can pretend
-          that multiple virtual monitors are present.<footnote>
-              <para>Multiple monitor support was added with VirtualBox
-              3.2.</para>
-            </footnote> Up to 8 such virtual monitors are supported.</para>
-
-          <para>The output of the multiple monitors will be displayed on the
-          host in multiple VM windows which are running side by side.</para>
-
-          <para>However, in full screen and seamless mode, they will use the
-          available physical monitors attached to the host. As a result, for
-          full screen and seamless modes to work with multiple monitors, you
-          will need at least as many physical monitors as you have virtual
-          monitors configured, or VirtualBox will report an error. You can
-          configure the relationship between guest and host monitors using the
-          view menu by pressing Host key + Home when you are in full screen or
-          seamless mode.</para>
-
-          <para>Please see <xref linkend="KnownIssues" /> also.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>Enable 3D acceleration</glossterm>
-
-        <glossdef>
-          <para>If a virtual machine has Guest Additions installed, you can
-          select here whether the guest should support accelerated 3D
-          graphics. Please refer to <xref linkend="guestadd-3d" /> for
-          details.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>Enable 2D video acceleration</glossterm>
-
-        <glossdef>
-          <para>If a virtual machine with Microsoft Windows has Guest
-          Additions installed, you can select here whether the guest should
-          support accelerated 2D video graphics. Please refer to <xref
-          linkend="guestadd-2d" /> for details.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>Remote display</glossterm>
-
-        <glossdef>
-          <para>Under the "Remote display" tab, if the VirtualBox Remote
-          Display Extension (VRDE) is installed, you can enable the VRDP server
-          that is built into VirtualBox. This allows you to connect to the
-          console of the virtual machine remotely with any standard RDP viewer,
-          such as <computeroutput>mstsc.exe</computeroutput> that comes with
-          Microsoft Windows. On Linux and Solaris systems you can use the
-          standard open-source <computeroutput>rdesktop</computeroutput>
-          program. These features are described in detail in
-          <xref linkend="vrde" />.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>Video Capture</glossterm>
-
-        <glossdef>
-          <para>Under the "Video Capture" tab you can enable video capturing
-          for this VM. Note that this feature can also be enabled/disabled
-          while the VM is executed.</para>
-        </glossdef>
-      </glossentry>
-    </glosslist>
-  </sect1>
-
   <sect1 id="settings-storage">
-    <title>Storage settings</title>
-
-    <para>The "Storage" category in the VM settings allows you to connect
-    virtual hard disk, CD/DVD and floppy images and drives to your virtual
-    machine.</para>
-
-    <para>In a real PC, so-called "storage controllers" connect physical disk
-    drives to the rest of the computer. Similarly, VirtualBox presents virtual
-    storage controllers to a virtual machine. Under each controller, the
-    virtual devices (hard disks, CD/DVD or floppy drives) attached to the
-    controller are shown.<note>
-        <para>This section can only give you a quick introduction to the
-        VirtualBox storage settings. Since VirtualBox gives you an enormous
-        wealth of options in this area, we have dedicated an entire chapter of
-        this User Manual to explaining all the details: please see <xref
-        linkend="storage" />.</para>
-      </note></para>
-
-    <para>If you have used the "Create VM" wizard to create a machine, you
-    will normally see something like the following:</para>
-
-    <para><mediaobject>
+
+    <title>Storage Settings</title>
+
+    <para>
+      The Storage category in the VM settings enables you to connect
+      virtual hard disk, CD/DVD, and floppy images and drives to your
+      virtual machine.
+    </para>
+
+    <para>
+      In a real PC, so-called "storage controllers" connect physical
+      disk drives to the rest of the computer. Similarly, VirtualBox
+      presents virtual storage controllers to a virtual machine. Under
+      each controller, the virtual devices, such as hard disks, CD/DVD
+      or floppy drives, attached to the controller are shown.
+
+      <note>
+        <para>
+          This section can only give you a quick introduction to the
+          VirtualBox storage settings. Since VirtualBox gives you an
+          enormous wealth of options in this area, we have dedicated an
+          entire chapter of this User Manual to explaining all the
+          details. See <xref
+        linkend="storage" />.
+        </para>
+      </note>
+    </para>
+
+    <para>
+      If you have used the <emphasis role="bold">Create VM</emphasis>
+      wizard to create a machine, you will normally see something like
+      the following:
+    </para>
+
+    <para>
+      <mediaobject>
         <imageobject>
           <imagedata align="center" fileref="images/vm-settings-harddisk.png"
                      width="10cm" />
         </imageobject>
-      </mediaobject></para>
-
-    <para>Depending on the guest operating system type that you selected when
-    you created the VM, the typical layout of storage devices in a new VM is
-    as follows:<itemizedlist>
-        <listitem>
-          <para>You will see an <emphasis role="bold">IDE
-          controller,</emphasis> to which a virtual CD/DVD drive has been
-          attached (to the "secondary master" port of the IDE
-          controller).</para>
-        </listitem>
-
-        <listitem>
-          <para>You will also see a <emphasis role="bold">SATA
-          controller,</emphasis> which is a more modern type of storage
+      </mediaobject>
+    </para>
+
+    <para>
+      Depending on the guest operating system type that you selected
+      when you created the VM, the typical layout of storage devices in
+      a new VM is as follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          You will see an <emphasis role="bold">IDE
+          controller</emphasis>, to which a virtual CD/DVD drive has
+          been attached to the "secondary master" port of the IDE
+          controller.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          You will also see a <emphasis role="bold">SATA
+          controller</emphasis>, which is a more modern type of storage
           controller for higher hard disk data throughput, to which the
-          virtual hard disks are attached. Initially you will normally have
-          one such virtual disk, but as you can see in the above screenshot,
-          you can have more than one, each represented by a disk image file
-          (VDI files, in this case).</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>If you created your VM with an older version of VirtualBox, the
-    default storage layout may differ. You might then only have an IDE
-    controller to which both the CD/DVD drive and the hard disks have been
-    attached. This might also apply if you selected an older operating system
-    type when you created the VM. Since older operating systems do not support
-    SATA without additional drivers, VirtualBox will make sure that no such
-    devices are present initially. Please see <xref
-    linkend="harddiskcontrollers" /> for additional information.</para>
-
-    <para>VirtualBox also provides a <emphasis role="bold">floppy
-    controller</emphasis>, which is special: you cannot add devices other than
-    floppy drives to it. Virtual floppy drives, like virtual CD/DVD drives,
-    can be connected to either a host floppy drive (if you have one) or a disk
-    image, which in this case must be in RAW format.</para>
-
-    <para>You can modify these media attachments freely. For example, if you
-    wish to copy some files from another virtual disk that you created, you
-    can connect that disk as a second hard disk, as in the above screenshot.
-    You could also add a second virtual CD/DVD drive, or change where these
-    items are attached. The following options are available:<itemizedlist>
-        <listitem>
-          <para>To <emphasis role="bold">add another virtual hard disk, or a
-          CD/DVD or floppy drive,</emphasis> select the storage controller to
-          which it should be added (IDE, SATA, SCSI, SAS, floppy controller)
-          and then click on the "add disk" button below the tree. You can then
-          either select "Add CD/DVD device" or "Add Hard Disk". (If you
-          clicked on a floppy controller, you can add a floppy drive instead.)
-          Alternatively, right-click on the storage controller and select a
-          menu item there.</para>
-
-          <para>On the right part of the window, you can then set the
-          following:<orderedlist>
+          virtual hard disks are attached. Initially you will normally
+          have one such virtual disk, but as you can see in the above
+          screenshot, you can have more than one. Each is represented by
+          a disk image file, VDI files in this case.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      If you created your VM with an older version of VirtualBox, the
+      default storage layout may differ. You might then only have an IDE
+      controller to which both the CD/DVD drive and the hard disks have
+      been attached. This might also apply if you selected an older
+      operating system type when you created the VM. Since older
+      operating systems do not support SATA without additional drivers,
+      VirtualBox will make sure that no such devices are present
+      initially. See <xref
+    linkend="harddiskcontrollers" />.
+    </para>
+
+    <para>
+      VirtualBox also provides a <emphasis role="bold">floppy
+      controller</emphasis>. You cannot add devices other than floppy
+      drives to this controller. Virtual floppy drives, like virtual
+      CD/DVD drives, can be connected to either a host floppy drive, if
+      you have one, or a disk image, which in this case must be in RAW
+      format.
+    </para>
+
+    <para>
+      You can modify these media attachments freely. For example, if you
+      wish to copy some files from another virtual disk that you
+      created, you can connect that disk as a second hard disk, as in
+      the above screenshot. You could also add a second virtual CD/DVD
+      drive, or change where these items are attached. The following
+      options are available:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          To <emphasis role="bold">add another virtual hard disk, or a
+          CD/DVD or floppy drive</emphasis>, select the storage
+          controller to which it should be added (IDE, SATA, SCSI, SAS,
+          floppy controller) and then click on the
+          <emphasis role="bold">Add Disk</emphasis> button below the
+          tree. You can then either select <emphasis role="bold">Add
+          CD/DVD Device</emphasis> or <emphasis role="bold">Add Hard
+          Disk</emphasis>. If you clicked on a floppy controller, you
+          can add a floppy drive instead. Alternatively, right-click on
+          the storage controller and select a menu item there.
+        </para>
+
+        <para>
+          On the right part of the window, you can then set the
+          following:
+        </para>
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              You can then select to which
+              <emphasis
+                role="bold">device
+              slot</emphasis> of the controller the virtual disk should
+              be connected to. IDE controllers have four slots which
+              have traditionally been called "primary master", "primary
+              slave", "secondary master" and "secondary slave". By
+              contrast, SATA and SCSI controllers offer you up to 30
+              slots to which virtual devices can be attached.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You can select which <emphasis role="bold">image
+              file</emphasis> to use.
+            </para>
+
+            <itemizedlist>
+
               <listitem>
-                <para>You can then select to which <emphasis
-                role="bold">device slot</emphasis> of the controller the
-                virtual disk should be connected to. IDE controllers have four
-                slots which have traditionally been called "primary master",
-                "primary slave", "secondary master" and "secondary slave". By
-                contrast, SATA and SCSI controllers offer you up to 30 slots
-                to which virtual devices can be attached.</para>
-              </listitem>
-
-              <listitem>
-                <para>You can select which <emphasis role="bold">image
-                file</emphasis> to use.<itemizedlist>
-                    <listitem>
-                      <para>For virtual hard disks, a button with a drop-down
-                      list appears on the right, offering you to either select
-                      a <emphasis role="bold">virtual hard disk
-                      file</emphasis> using a standard file dialog or to
-                      <emphasis role="bold">create a new hard disk</emphasis>
-                      (image file), which will bring up the "Create new disk"
-                      wizard, which was described in <xref
-                      linkend="gui-createvm" />.</para>
-
-                      <para>For details on the image file types that are
-                      supported, please see <xref
-                      linkend="vdidetails" />.</para>
-                    </listitem>
-
-                    <listitem>
-                      <para>For virtual CD/DVD drives, the image files will
-                      typically be in the standard ISO format instead. Most
-                      commonly, you will select this option when installing an
-                      operating system from an ISO file that you have obtained
-                      from the Internet. For example, most Linux distributions
-                      are available in this way.</para>
-
-                      <para>For virtual CD/DVD drives, the following
-                      additional options are available:</para>
-
-                      <para><itemizedlist>
-                          <listitem>
-                            <para>If you select <emphasis role="bold">"Host
-                            drive"</emphasis> from the list, then the physical
-                            device of the host computer is connected to the VM,
-                            so that the guest operating system can read from and
-                            write to your physical device. This is, for
-                            instance, useful if you want to install Windows from
-                            a real installation CD. In this case, select your
-                            host drive from the drop-down list presented.</para>
-
-                            <para>If you want to write (burn) CDs or DVDs using
-                            the host drive, you need to also enable the
-                            <emphasis role="bold">"Passthrough"</emphasis>
-                            option; see <xref linkend="storage-cds" />.</para>
-                          </listitem>
-
-                          <listitem>
-                            <para>If you select <emphasis role="bold">"Remove
-                            disk from virtual drive",</emphasis> VirtualBox will
-                            present an empty CD/DVD drive to the guest into
-                            which no media has been inserted.</para>
-                          </listitem>
-                        </itemizedlist></para>
-                    </listitem>
-                  </itemizedlist></para>
-              </listitem>
-            </orderedlist></para>
-        </listitem>
-
-        <listitem>
-          <para>To <emphasis role="bold">remove an attachment,</emphasis>
-          select it and click on the "remove" icon at the bottom (or
-          right-click on it and select the menu item).</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>Removable media (CD/DVDs and floppies) can be changed while the
-    guest is running. Since the "Settings" dialog is not available at that
-    time, you can also access these settings from the "Devices" menu of your
-    virtual machine window.</para>
-  </sect1>
-
-  <sect1 id="settings-audio">
-    <title>Audio settings</title>
-
-    <para>The "Audio" section in a virtual machine's Settings window
-    determines whether the VM will see a sound card connected, and whether the
-    audio output should be heard on the host system.</para>
-
-    <para>If audio is enabled for a guest, you can choose between the
-    emulation of an Intel AC'97 controller, an Intel HD Audio
-    controller<footnote>
-        <para>Intel HD Audio support was added with VirtualBox 4.0 because
-        Windows 7 and later (as well as 64-bit Windows Vista) do not support
-        the Intel AC'97 controller out of the box.</para>
-      </footnote> or a SoundBlaster 16 card. In any case, you can select what
-    audio driver VirtualBox will use on the host.</para>
-
-    <para>On a Linux host, depending on your host configuration, you can also
-    select between the OSS, ALSA or the PulseAudio subsystem. On newer Linux
-    distributions, the PulseAudio subsystem should be preferred.</para>
-
-    <para>Since VirtualBox 5.0 only OSS is supported on Solaris hosts - the "Solaris Audio"
-    audio backend is no longer supported on Solaris hosts.</para>
-  </sect1>
-
-  <sect1 id="settings-network">
-    <title>Network settings</title>
-
-    <para>The "Network" section in a virtual machine's Settings window allows
-    you to configure how VirtualBox presents virtual network cards to your VM,
-    and how they operate.</para>
-
-    <para>When you first create a virtual machine, VirtualBox by default
-    enables one virtual network card and selects the "Network Address
-    Translation" (NAT) mode for it. This way the guest can connect to the
-    outside world using the host's networking and the outside world can
-    connect to services on the guest which you choose to make visible outside
-    of the virtual machine.</para>
-
-    <para>This default setup is good for probably 95% of VirtualBox users.
-    However, VirtualBox is extremely flexible in how it can virtualize
-    networking. It supports many virtual network cards per virtual machine,
-    the first four of which can be configured in detail in the Manager window.
-    Additional network cards can be configured on the command line with
-    VBoxManage. </para>
-
-    <para>Because of the vast array of options available, we have dedicated an
-    entire chapter of this manual to discussing networking configuration;
-    please see <xref linkend="networkingdetails" />.</para>
-  </sect1>
-
-  <sect1 id="serialports">
-    <title>Serial ports</title>
-
-    <para>VirtualBox fully supports virtual serial ports in a virtual machine
-    in an easy-to-use manner.<footnote>
-        <para>Serial port support was added with VirtualBox 1.5.</para>
-      </footnote></para>
-
-    <para>Ever since the original IBM PC, personal computers have been
-    equipped with one or two serial ports (also called COM ports by DOS and
-    Windows). Serial ports were commonly used with modems, and some
-    computer mice used to be connected to serial ports before USB became
-    commonplace.
-    </para>
-
-    <para>While serial ports are no longer as ubiquitous as they used to be,
-    there are still some important uses left for them. For example, serial
-    ports can be used to set up a primitive network over a null-modem cable,
-    in case Ethernet is not available. Also, serial ports are indispensable
-    for system programmers needing to do kernel debugging, since kernel
-    debugging software usually interacts with developers over a serial port.
-    With virtual serial ports, system programmers can do kernel debugging on a
-    virtual machine instead of needing a real computer to connect to.</para>
-
-    <para>If a virtual serial port is enabled, the guest operating system sees
-    a standard 16550A compatible UART device. Both receiving and transmitting
-    data is supported. How this virtual serial port is then connected to the
-    host is configurable, and the details depend on your host operating system.
-    </para>
-
-    <para>You can use either the graphical user interface or the command-line
-    <computeroutput>VBoxManage</computeroutput> tool to set up virtual serial
-    ports. For the latter, please refer to <xref
-    linkend="vboxmanage-modifyvm" />; in that section, look for the
-    <computeroutput>--uart</computeroutput> and
-    <computeroutput>--uartmode</computeroutput> options.</para>
-
-    <para>In either case, you can configure up to four virtual serial ports per
-    virtual machine. For each such device, you will need to
-    determine<orderedlist>
-        <listitem>
-          <para>what kind of serial port the virtual machine should see by
-          selecting an I/O base address and interrupt (IRQ). For these, we
-          recommend to use the traditional values<footnote>
-              <para>See, for example, <ulink
-              url="http://en.wikipedia.org/wiki/COM_(hardware_interface)">http://en.wikipedia.org/wiki/COM_(hardware_interface)</ulink>.</para>
-            </footnote>, which are:</para>
-
-          <para><orderedlist>
-              <listitem>
-                <para>COM1: I/O base 0x3F8, IRQ 4</para>
-              </listitem>
-
-              <listitem>
-                <para>COM2: I/O base 0x2F8, IRQ 3</para>
-              </listitem>
-
-              <listitem>
-                <para>COM3: I/O base 0x3E8, IRQ 4</para>
-              </listitem>
-
-              <listitem>
-                <para>COM4: I/O base 0x2E8, IRQ 3</para>
-              </listitem>
-            </orderedlist></para>
-        </listitem>
-
-        <listitem>
-          <para>Then, you will need to determine what this virtual port should
-          be connected to. For each virtual serial port, you have the
-          following options:</para>
-
-          <para><itemizedlist>
-              <listitem>
-                <para>You can elect to have the virtual serial port
-                "disconnected", which means that the guest will see the
-                device, but it will behave as if no cable had been connected
-                to it.</para>
-              </listitem>
-
-              <listitem>
-                <para>You can connect the virtual serial port to a physical
-                serial port on your host. (On a Windows host, this will be a
-                name like <computeroutput>COM1</computeroutput>; on Linux or
-                Solaris hosts, it will be a device node like
-                <computeroutput>/dev/ttyS0</computeroutput>). VirtualBox will
-                then simply redirect all data received from and sent to the
-                virtual serial port to the physical device.</para>
-              </listitem>
-
-              <listitem>
-                <para>You can tell VirtualBox to connect the virtual serial
-                port to a software pipe on the host. This depends on your host
-                operating system:<itemizedlist>
-                    <listitem>
-                      <para>On a Windows host, data will be sent and received
-                      through a named pipe. The pipe name must be in the format
-                      <computeroutput>\\.\pipe\&lt;name&gt;</computeroutput>
-                      where <computeroutput>&lt;name&gt;</computeroutput> should
-                      identify the virtual machine but may be freely
-                      chosen.</para>
-                    </listitem>
-
-                    <listitem>
-                      <para>On a Mac, Linux or Solaris host, a local
-                      domain socket is used instead. The socket filename must be
-                      chosen such that the user running VirtualBox has
-                      sufficient privileges to create and write to it. The
-                      <computeroutput>/tmp</computeroutput> directory is often a
-                      good candidate.</para>
-                      <para>On Linux there are various tools which can connect
-                      to a local domain socket or create one in server mode. The
-                      most flexible tool is
-                      <computeroutput>socat</computeroutput> and is available
-                      as part of many distributions.</para>
-                    </listitem>
-                  </itemizedlist></para>
-
-                <para>In this case, you can configure whether VirtualBox
-                should create the named pipe (or, on non-Windows hosts, the
-                local domain socket) itself or whether VirtualBox should
-                assume that the pipe (or socket) exists already. With the
-                <computeroutput>VBoxManage</computeroutput> command-line
-                options, this is referred to as "server" or "client" mode,
-                respectively.</para>
-
-                <para>For a direct connection between two virtual machines
-                (corresponding to a null-modem cable), simply configure one VM
-                to create a pipe/socket and another to attach to it.
+                <para>
+                  For virtual hard disks, a button with a drop-down list
+                  appears on the right, offering you to either select a
+                  <emphasis role="bold">virtual hard disk
+                  file</emphasis> using a standard file dialog or to
+                  <emphasis role="bold">create a new hard
+                  disk</emphasis> (image file). The latter option
+                  displays the <emphasis role="bold">Create New
+                  Disk</emphasis> wizard, described in
+                  <xref
+                      linkend="gui-createvm" />.
+                </para>
+
+                <para>
+                  For details on the image file types that are
+                  supported, see
+                  <xref
+                      linkend="vdidetails" />.
                 </para>
               </listitem>
 
               <listitem>
-                <para>You can send the virtual serial port output to a file.
-                This option is very useful for capturing diagnostic output from
-                a guest. Any file may be used for this purpose, as long as the
-                user running VirtualBox has sufficient privileges to create and
-                write to the file.
+                <para>
+                  For virtual CD/DVD drives, the image files will
+                  typically be in the standard ISO format instead. Most
+                  commonly, you will select this option when installing
+                  an operating system from an ISO file that you have
+                  obtained from the Internet. For example, most Linux
+                  distributions are available in this way.
+                </para>
+
+                <para>
+                  For virtual CD/DVD drives, the following additional
+                  options are available:
+                </para>
+
+                <itemizedlist>
+
+                  <listitem>
+                    <para>
+                      If you select <emphasis role="bold">Host
+                      Drive</emphasis> from the list, then the physical
+                      device of the host computer is connected to the
+                      VM, so that the guest operating system can read
+                      from and write to your physical device. This is,
+                      for instance, useful if you want to install
+                      Windows from a real installation CD. In this case,
+                      select your host drive from the drop-down list
+                      presented.
+                    </para>
+
+                    <para>
+                      If you want to write (burn) CDs or DVDs using the
+                      host drive, you need to also enable the
+                      <emphasis role="bold">Passthrough</emphasis>
+                      option. See <xref linkend="storage-cds" />.
+                    </para>
+                  </listitem>
+
+                  <listitem>
+                    <para>
+                      If you select <emphasis role="bold">Remove Disk
+                      from Virtual Drive</emphasis>, VirtualBox will
+                      present an empty CD/DVD drive to the guest into
+                      which no media has been inserted.
+                    </para>
+                  </listitem>
+
+                </itemizedlist>
+              </listitem>
+
+            </itemizedlist>
+          </listitem>
+
+        </orderedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          To <emphasis role="bold">remove an attachment</emphasis>,
+          either select it and click on the
+          <emphasis role="bold">Remove</emphasis> icon at the bottom, or
+          right-click on it and select the menu item.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Removable media, such as CD/DVDs and floppies, can be changed
+      while the guest is running. Since the Settings dialog is not
+      available at that time, you can also access these settings from
+      the <emphasis role="bold">Devices</emphasis> menu of your virtual
+      machine window.
+    </para>
+
+  </sect1>
+
+  <sect1 id="settings-audio">
+
+    <title>Audio Settings</title>
+
+    <para>
+      The Audio section in a virtual machine's Settings window
+      determines whether the VM will see a sound card connected, and
+      whether the audio output should be heard on the host system.
+    </para>
+
+    <para>
+      If audio is enabled for a guest, you can choose between the
+      emulation of an Intel AC'97 controller, an Intel HD Audio
+      controller
+
+      <footnote>
+
+        <para>
+          Intel HD Audio support was added with VirtualBox 4.0 because
+          Windows 7 and later (as well as 64-bit Windows Vista) do not
+          support the Intel AC'97 controller out of the box.
+        </para>
+
+      </footnote>
+
+      or a SoundBlaster 16 card. In any case, you can select what audio
+      driver VirtualBox will use on the host.
+    </para>
+
+    <para>
+      On a Linux host, depending on your host configuration, you can
+      also select between the OSS, ALSA, or the PulseAudio subsystem. On
+      newer Linux distributions, the PulseAudio subsystem should be
+      preferred.
+    </para>
+
+    <para>
+      Since VirtualBox 5.0 only OSS is supported on Solaris hosts. The
+      "Solaris Audio" audio backend is no longer supported on Solaris
+      hosts.
+    </para>
+
+  </sect1>
+
+  <sect1 id="settings-network">
+
+    <title>Network Settings</title>
+
+    <para>
+      The Network section in a virtual machine's Settings window enables
+      you to configure how VirtualBox presents virtual network cards to
+      your VM, and how they operate.
+    </para>
+
+    <para>
+      When you first create a virtual machine, VirtualBox by default
+      enables one virtual network card and selects the Network Address
+      Translation (NAT) mode for it. This way the guest can connect to
+      the outside world using the host's networking and the outside
+      world can connect to services on the guest which you choose to
+      make visible outside of the virtual machine.
+    </para>
+
+    <para>
+      This default setup is good for the majority of VirtualBox users.
+      However, VirtualBox is extremely flexible in how it can virtualize
+      networking. It supports many virtual network cards per virtual
+      machine, the first four of which can be configured in detail in
+      the Manager window. Additional network cards can be configured on
+      the command line with VBoxManage.
+    </para>
+
+    <para>
+      Because of the vast array of options available, we have dedicated
+      an entire chapter of this manual to discussing networking
+      configuration. See <xref linkend="networkingdetails" />.
+    </para>
+
+  </sect1>
+
+  <sect1 id="serialports">
+
+    <title>Serial Ports</title>
+
+    <para>
+      VirtualBox fully supports virtual serial ports in a virtual
+      machine in an easy-to-use manner.
+
+      <footnote>
+
+        <para>
+          Serial port support was added with VirtualBox 1.5.
+        </para>
+
+      </footnote>
+    </para>
+
+    <para>
+      Ever since the original IBM PC, personal computers have been
+      equipped with one or two serial ports, also called COM ports by
+      DOS and Windows. Serial ports were commonly used with modems, and
+      some computer mice used to be connected to serial ports before USB
+      became commonplace.
+    </para>
+
+    <para>
+      While serial ports are no longer as ubiquitous as they used to be,
+      there are still some important uses left for them. For example,
+      serial ports can be used to set up a primitive network over a
+      null-modem cable, in case Ethernet is not available. Also, serial
+      ports are indispensable for system programmers needing to do
+      kernel debugging, since kernel debugging software usually
+      interacts with developers over a serial port. With virtual serial
+      ports, system programmers can do kernel debugging on a virtual
+      machine instead of needing a real computer to connect to.
+    </para>
+
+    <para>
+      If a virtual serial port is enabled, the guest operating system
+      sees a standard 16550A compatible UART device. Both receiving and
+      transmitting data is supported. How this virtual serial port is
+      then connected to the host is configurable, and the details depend
+      on your host operating system.
+    </para>
+
+    <para>
+      You can use either the graphical user interface or the
+      command-line <computeroutput>VBoxManage</computeroutput> tool to
+      set up virtual serial ports. For the latter, see
+      <xref
+    linkend="vboxmanage-modifyvm" /> for information on the
+      <computeroutput>--uart</computeroutput> and
+      <computeroutput>--uartmode</computeroutput> options.
+    </para>
+
+    <para>
+      In either case, you can configure up to four virtual serial ports
+      per virtual machine. For each such device, you will need to
+      determine the following:
+    </para>
+
+    <orderedlist>
+
+      <listitem>
+        <para>
+          What kind of serial port the virtual machine should see, by
+          selecting an I/O base address and interrupt (IRQ). For these,
+          we recommend you use the traditional values, as follows:
+
+          <footnote>
+
+            <para>
+              See, for example,
+              <ulink
+              url="http://en.wikipedia.org/wiki/COM_(hardware_interface)">http://en.wikipedia.org/wiki/COM_(hardware_interface)</ulink>.
+            </para>
+
+          </footnote>
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              COM1: I/O base 0x3F8, IRQ 4
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              COM2: I/O base 0x2F8, IRQ 3
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              COM3: I/O base 0x3E8, IRQ 4
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              COM4: I/O base 0x2E8, IRQ 3
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          Then, you will need to determine what this virtual port should
+          be connected to. For each virtual serial port, you have the
+          following options:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              You can configure the virtual serial port to be
+              "disconnected". This means that the guest will see the
+              device, but it will behave as if no cable had been
+              connected to it.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You can connect the virtual serial port to a physical
+              serial port on your host. On a Windows host, this will be
+              a name like <computeroutput>COM1</computeroutput>. On
+              Linux or Solaris hosts, it will be a device node like
+              <computeroutput>/dev/ttyS0</computeroutput>. VirtualBox
+              will then simply redirect all data received from and sent
+              to the virtual serial port to the physical device.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You can tell VirtualBox to connect the virtual serial port
+              to a software pipe on the host. This depends on your host
+              operating system, as follows:
+            </para>
+
+            <itemizedlist>
+
+              <listitem>
+                <para>
+                  On a Windows host, data will be sent and received
+                  through a named pipe. The pipe name must be in the
+                  format
+                  <computeroutput>\\.\pipe\&lt;name&gt;</computeroutput>
+                  where <computeroutput>&lt;name&gt;</computeroutput>
+                  should identify the virtual machine but may be freely
+                  chosen.
                 </para>
               </listitem>
 
               <listitem>
-                <para>TCP Socket: Useful for forwarding serial traffic over TCP/IP,
-                  acting as a server, or it can act as a TCP client connecting to other
-                  servers. It allows a remote machine to directly connect to the guest's
-                  serial port via TCP.
+                <para>
+                  On a Mac, Linux, or Solaris host, a local domain
+                  socket is used instead. The socket filename must be
+                  chosen such that the user running VirtualBox has
+                  sufficient privileges to create and write to it. The
+                  <computeroutput>/tmp</computeroutput> directory is
+                  often a good candidate.
                 </para>
-                <itemizedlist>
-                  <listitem>
-                    <para>TCP Server: Uncheck the
-                      <emphasis>Connect to existing pipe/socket</emphasis> checkbox and specify
-                      the <emphasis role="bold"><computeroutput>port</computeroutput></emphasis>
-                      number. Typically 23 or 2023. Note that on UNIX-like systems you will
-                      have to use a port a number greater than 1024 for regular users.
-                    </para>
-                    <para>
-                      The client can use software such as <computeroutput>PuTTY</computeroutput>
-                      or the <computeroutput>telnet</computeroutput> command line
-                      tool to access the TCP Server.
-                    </para>
-                  </listitem>
-                  <listitem>
-                    <para>TCP Client: To create a virtual null-modem cable over the Internet or
-                      LAN, the other side can connect via TCP by specifying <emphasis role="bold">
-                      <computeroutput>hostname:port</computeroutput></emphasis>. The TCP socket
-                    will act in client mode if check the <emphasis>Connect to existing pipe/socket</emphasis>
-                    checkbox.
-                    </para>
-                  </listitem>
-                </itemizedlist>
+
+                <para>
+                  On Linux there are various tools which can connect to
+                  a local domain socket or create one in server mode.
+                  The most flexible tool is
+                  <computeroutput>socat</computeroutput> and is
+                  available as part of many distributions.
+                </para>
               </listitem>
 
-            </itemizedlist></para>
+            </itemizedlist>
+
+            <para>
+              In this case, you can configure whether VirtualBox should
+              create the named pipe (or, on non-Windows hosts, the local
+              domain socket) itself or whether VirtualBox should assume
+              that the pipe or socket exists already. With the
+              <computeroutput>VBoxManage</computeroutput> command-line
+              options, this is referred to as "server" or "client" mode,
+              respectively.
+            </para>
+
+            <para>
+              For a direct connection between two virtual machines,
+              corresponding to a null-modem cable, simply configure one
+              VM to create a pipe/socket and another to attach to it.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You can send the virtual serial port output to a file.
+              This option is very useful for capturing diagnostic output
+              from a guest. Any file may be used for this purpose, as
+              long as the user running VirtualBox has sufficient
+              privileges to create and write to the file.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              TCP Socket: Useful for forwarding serial traffic over
+              TCP/IP, acting as a server, or it can act as a TCP client
+              connecting to other servers. It allows a remote machine to
+              directly connect to the guest's serial port via TCP.
+            </para>
+
+            <itemizedlist>
+
+              <listitem>
+                <para>
+                  TCP Server: Uncheck the <emphasis>Connect to existing
+                  pipe/socket</emphasis> checkbox and specify the
+                  <emphasis role="bold"><computeroutput>port</computeroutput></emphasis>
+                  number. Typically 23 or 2023. Note that on UNIX-like
+                  systems you will have to use a port a number greater
+                  than 1024 for regular users.
+                </para>
+
+                <para>
+                  The client can use software such as
+                  <computeroutput>PuTTY</computeroutput> or the
+                  <computeroutput>telnet</computeroutput> command line
+                  tool to access the TCP Server.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  TCP Client: To create a virtual null-modem cable over
+                  the Internet or LAN, the other side can connect via
+                  TCP by specifying
+                  <computeroutput>hostname:port</computeroutput>. The
+                  TCP socket will act in client mode if you check the
+                  <emphasis role="bold">Connect to existing
+                  pipe/socket</emphasis> checkbox.
+                </para>
+              </listitem>
+
+            </itemizedlist>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+    </orderedlist>
+
+    <para>
+      Up to four serial ports can be configured per virtual machine, but
+      you can pick any port numbers out of the above. However, serial
+      ports cannot reliably share interrupts; if both ports are to be
+      used at the same time, they must use different interrupt levels,
+      for example COM1 and COM2, but not COM1 and COM3.
+    </para>
+
+  </sect1>
+
+  <sect1 id="usb-support">
+
+    <title>USB Support</title>
+
+    <sect2 id="settings-usb">
+
+      <title>USB Settings</title>
+
+      <para>
+        The USB section in a virtual machine's Settings window enables
+        you to configure VirtualBox's sophisticated USB support.
+      </para>
+
+      <para>
+        VirtualBox can enable virtual machines to access the USB devices
+        on your host directly. To achieve this, VirtualBox presents the
+        guest operating system with a virtual USB controller. As soon as
+        the guest system starts using a USB device, it will appear as
+        unavailable on the host.
+      </para>
+
+      <note>
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              Be careful with USB devices that are currently in use on
+              the host! For example, if you allow your guest to connect
+              to your USB hard disk that is currently mounted on the
+              host, when the guest is activated, it will be disconnected
+              from the host without a proper shutdown. This may cause
+              data loss.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Solaris hosts have a few known limitations regarding USB
+              support. See <xref linkend="KnownIssues" />.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </note>
+
+      <para>
+        In addition to allowing a guest access to your local USB
+        devices, VirtualBox even allows your guests to connect to remote
+        USB devices by use of the VirtualBox Remote Desktop Extension
+        (VRDE). See <xref linkend="usb-over-rdp" />.
+      </para>
+
+      <para>
+        In the Settings dialog, you can first configure whether USB is
+        available in the guest at all, and then choose the level of USB
+        support: OHCI for USB 1.1, EHCI (which will also enable OHCI)
+        for USB 2.0, or xHCI for all USB speeds.
+      </para>
+
+      <note>
+        <para>
+          The xHCI and EHCI controllers are shipped as a VirtualBox
+          extension package, which must be installed separately. See
+          <xref
+          linkend="intro-installing" />.
+        </para>
+      </note>
+
+      <para>
+        When USB support is enabled for a VM, you can determine in
+        detail which devices will be automatically attached to the
+        guest. For this, you can create so-called "filters" by
+        specifying certain properties of the USB device. USB devices
+        with a matching filter will be automatically passed to the guest
+        once they are attached to the host. USB devices without a
+        matching filter can be passed manually to the guest, for example
+        by using the <emphasis role="bold">Devices</emphasis>,
+        <emphasis role="bold">USB</emphasis> menu.
+      </para>
+
+      <para>
+        Clicking on the <emphasis role="bold">+</emphasis> button to the
+        right of the <emphasis role="bold">USB Device Filters</emphasis>
+        window creates a new filter. You can give the filter a name, for
+        later reference, and specify the filter criteria. The more
+        criteria you specify, the more precisely devices will be
+        selected. For instance, if you specify only a vendor ID of 046d,
+        all devices produced by Logitech will be available to the guest.
+        If you fill in all fields, on the other hand, the filter will
+        only apply to a particular device model from a particular
+        vendor, and not even to other devices of the same type with a
+        different revision and serial number.
+      </para>
+
+      <para>
+        In detail, the following criteria are available:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Vendor and product ID</emphasis>. With
+            USB, each vendor of USB products carries an identification
+            number that is unique world-wide, called the
+            <emphasis>vendor ID</emphasis>. Similarly, each line of
+            products is assigned a <emphasis>product ID</emphasis>
+            number. Both numbers are commonly written in hexadecimal
+            (that is, they are composed of the numbers 0-9 and the
+            letters A-F), and a colon separates the vendor from the
+            product ID. For example,
+            <computeroutput>046d:c016</computeroutput> stands for
+            Logitech as a vendor, and the M-UV69a Optical Wheel Mouse
+            product.
+          </para>
+
+          <para>
+            Alternatively, you can also specify
+            <emphasis
+          role="bold">Manufacturer</emphasis> and
+            <emphasis
+          role="bold">Product</emphasis> by name.
+          </para>
+
+          <para>
+            To list all the USB devices that are connected to your host
+            machine with their respective vendor IDs and product IDs,
+            use the following command:
+
+<screen>VBoxManage list usbhost</screen>
+          </para>
+
+          <para>
+            On Windows, you can also see all USB devices that are
+            attached to your system in the Device Manager. On Linux, you
+            can use the <computeroutput>lsusb</computeroutput> command.
+          </para>
         </listitem>
-      </orderedlist>Up to four serial ports can be configured per virtual
-      machine, but you can pick any port numbers out of the above. However,
-      serial ports cannot reliably share interrupts; if both ports are to be
-      used at the same time, they must use different interrupt levels, for
-      example COM1 and COM2, but not COM1 and COM3.
-    </para>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Serial number</emphasis>. While vendor
+            ID and product ID are quite specific to identify USB
+            devices, if you have two identical devices of the same brand
+            and product line, you will also need their serial numbers to
+            filter them out correctly.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Remote</emphasis>. This setting
+            specifies whether the device will be local only, remote only
+            (such as over VRDP), or either.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        On a Windows host, you will need to unplug and reconnect a USB
+        device to use it after creating a filter for it.
+      </para>
+
+      <para>
+        As an example, you could create a new USB filter and specify a
+        vendor ID of 046d (Logitech, Inc), a manufacturer index of 1,
+        and "not remote". Then any USB devices on the host system
+        produced by Logitech, Inc with a manufacturer index of 1 will be
+        visible to the guest system.
+      </para>
+
+      <para>
+        Several filters can select a single device. For example, a
+        filter which selects all Logitech devices, and one which selects
+        a particular webcam.
+      </para>
+
+      <para>
+        You can deactivate filters without deleting them by clicking in
+        the checkbox next to the filter name.
+      </para>
+
+    </sect2>
+
+    <sect2 id="usb-implementation-notes">
+
+      <title>Implementation Notes for Windows and Linux Hosts</title>
+
+      <para>
+        On Windows hosts, a kernel mode device driver provides USB proxy
+        support. It implements both a USB monitor, which allows
+        VirtualBox to capture devices when they are plugged in, and a
+        USB device driver to claim USB devices for a particular virtual
+        machine. As opposed to VirtualBox versions before 1.4.0, system
+        reboots are no longer necessary after installing the driver.
+        Also, you no longer need to replug devices for VirtualBox to
+        claim them.
+      </para>
+
+      <para>
+        On newer Linux hosts, VirtualBox accesses USB devices through
+        special files in the file system. When VirtualBox is installed,
+        these are made available to all users in the
+        <computeroutput>vboxusers</computeroutput> system group. In
+        order to be able to access USB from guest systems, make sure
+        that you are a member of this group.
+      </para>
+
+      <para>
+        On older Linux hosts, USB devices are accessed using the
+        <computeroutput>usbfs</computeroutput> file system. Therefore,
+        the user executing VirtualBox needs read and write permission to
+        the USB file system. Most distributions provide a group (e.g.
+        <computeroutput>usbusers</computeroutput>) which the VirtualBox
+        user needs to be added to. Also, VirtualBox can only proxy to
+        virtual machines USB devices which are not claimed by a Linux
+        host USB driver. The <computeroutput>Driver=</computeroutput>
+        entry in <computeroutput>/proc/bus/usb/devices</computeroutput>
+        will show you which devices are currently claimed. See also
+        <xref
+      linkend="ts_usb-linux" /> for details about
+        <computeroutput>usbfs</computeroutput>.
+      </para>
+
+    </sect2>
+
   </sect1>
 
-  <sect1>
-    <title>USB support</title>
-
-    <sect2 id="settings-usb">
-      <title>USB settings</title>
-
-      <para>The "USB" section in a virtual machine's Settings window allows
-      you to configure VirtualBox's sophisticated USB support.</para>
-
-      <para>VirtualBox can allow virtual machines to access the USB devices on
-      your host directly. To achieve this, VirtualBox presents the guest
-      operating system with a virtual USB controller. As soon as the guest
-      system starts using a USB device, it will appear as unavailable on the
-      host.<note>
-          <orderedlist>
-            <listitem>
-              <para>Be careful with USB devices that are currently in use on
-              the host! For example, if you allow your guest to connect to
-              your USB hard disk that is currently mounted on the host, when
-              the guest is activated, it will be disconnected from the host
-              without a proper shutdown. This may cause data loss.</para>
-            </listitem>
-
-            <listitem>
-              <para>Solaris hosts have a few known limitations regarding USB
-              support; please see <xref linkend="KnownIssues" />.</para>
-            </listitem>
-          </orderedlist>
-        </note></para>
-
-      <para>In addition to allowing a guest access to your local USB devices,
-      VirtualBox even allows your guests to connect to remote USB devices by
-      use of the VirtualBox Remote Desktop Extension (VRDE). For details about
-      this, see <xref linkend="usb-over-rdp" />.</para>
-
-      <para>In the Settings dialog, you can first configure whether USB is
-      available in the guest at all, and then choose the level of USB support:
-      OHCI for USB 1.1, EHCI (which will also enable OHCI) for USB 2.0,
-      or xHCI for all USB speeds. <note>
-          <para>The xHCI and EHCI controllers are shipped as a VirtualBox extension
-          package, which must be installed separately. See <xref
-          linkend="intro-installing" /> for more information.</para>
-        </note></para>
-
-      <para>When USB support is enabled for a VM, you can determine in detail
-      which devices will be automatically attached to the guest. For this, you
-      can create so-called "filters" by specifying certain properties of
-      the USB device. USB devices with a matching filter will be automatically
-      passed to the guest once they are attached to the host. USB devices
-      without a matching filter can be passed manually to the guest, for
-      example by using the Devices / USB devices menu.</para>
-
-      <para>Clicking on the "+" button to the right of the "USB Device
-      Filters" window creates a <emphasis role="bold">new filter.</emphasis>
-      You can give the filter a name (for referencing it later) and specify
-      the filter criteria. The more criteria you specify, the more precisely
-      devices will be selected. For instance, if you specify only a vendor ID
-      of 046d, all devices produced by Logitech will be available to the
-      guest. If you fill in all fields, on the other hand, the filter will
-      only apply to a particular device model from a particular vendor, and
-      not even to other devices of the same type with a different revision and
-      serial number.</para>
-
-      <para>In detail, the following criteria are available:</para>
-
-      <orderedlist>
-        <listitem>
-          <para><emphasis role="bold">Vendor and product ID.</emphasis> With
-          USB, each vendor of USB products carries an identification number
-          that is unique world-wide, the "vendor ID". Similarly, each line of
-          products is assigned a "product ID" number. Both numbers are
-          commonly written in hexadecimal (that is, they are composed of the
-          numbers 0-9 and the letters A-F), and a colon separates the vendor
-          from the product ID. For example,
-          <computeroutput>046d:c016</computeroutput> stands for Logitech as a
-          vendor, and the "M-UV69a Optical Wheel Mouse" product.</para>
-
-          <para>Alternatively, you can also specify <emphasis
-          role="bold">"Manufacturer"</emphasis> and <emphasis
-          role="bold">"Product"</emphasis> by name.</para>
-
-          <para>To list all the USB devices that are connected to your host
-          machine with their respective vendor and product IDs, you can use
-          the following command (see <xref linkend="vboxmanage" />): <screen>VBoxManage list usbhost</screen></para>
-
-          <para>On Windows, you can also see all USB devices that are attached
-          to your system in the Device Manager. On Linux, you can use the
-          <computeroutput>lsusb</computeroutput> command.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Serial number.</emphasis> While vendor
-          and product ID are already quite specific to identify USB devices,
-          if you have two identical devices of the same brand and product
-          line, you will also need their serial numbers to filter them out
-          correctly.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Remote.</emphasis> This setting
-          specifies whether the device will be local only, or remote only
-          (over VRDP), or either.</para>
-        </listitem>
-      </orderedlist>
-
-      <para>On a Windows host, you will need to unplug and reconnect a USB
-      device to use it after creating a filter for it.</para>
-
-      <para>As an example, you could create a new USB filter and specify a
-      vendor ID of 046d (Logitech, Inc), a manufacturer index of 1, and "not
-      remote". Then any USB devices on the host system produced by Logitech,
-      Inc with a manufacturer index of 1 will be visible to the guest
-      system.</para>
-
-      <para>Several filters can select a single device -- for example, a
-      filter which selects all Logitech devices, and one which selects a
-      particular webcam.</para>
-
-      <para>You can <emphasis role="bold">deactivate</emphasis> filters
-      without deleting them by clicking in the checkbox next to the filter
-      name.</para>
+  <sect1 id="shared-folders">
+
+    <title>Shared Folders</title>
+
+    <para>
+      Shared folders enable you to easily exchange data between a
+      virtual machine and your host. This feature requires that the
+      VirtualBox Guest Additions be installed in a virtual machine and
+      is described in detail in <xref linkend="sharedfolders" />.
+    </para>
+
+  </sect1>
+
+  <sect1 id="user-interface">
+
+    <title>User Interface</title>
+
+    <para>
+      The User Interface section allows you to change certain aspects of
+      the user interface of this VM.
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Menu Bar:</emphasis> This widget enables
+          you to disable menus by clicking on the menu to release it,
+          menu entries by unchecking the checkbox of the entry to
+          disable it and the complete menu bar by unchecking the
+          rightmost checkbox.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Mini ToolBar:</emphasis> In full screen
+          or seamless mode, VirtualBox can display a small toolbar that
+          contains some of the items that are normally available from
+          the virtual machine's menu bar. This toolbar reduces itself to
+          a small gray line unless you move the mouse over it. With the
+          toolbar, you can return from full screen or seamless mode,
+          control machine execution or enable certain devices. If you do
+          not want to see the toolbar, disable this setting.
+        </para>
+
+        <para>
+          The second setting enables you to show the toolbar at the top
+          of the screen, instead of showing it at the bottom.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Status Bar:</emphasis> This widget
+          allows you to disable icons on the status bar by unchecking
+          the checkbox of an icon to disable it, to rearrange icons by
+          dragging and dropping the icon, and to disable the complete
+          status bar by unchecking the leftmost checkbox.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="efi">
+
+    <title>Alternative Firmware (EFI)</title>
+
+    <para>
+      Starting with release 3.1, VirtualBox includes experimental
+      support for the Extensible Firmware Interface (EFI), which is a
+      new industry standard intended to eventually replace the legacy
+      BIOS as the primary interface for bootstrapping computers and
+      certain system services later.
+    </para>
+
+    <para>
+      By default, VirtualBox uses the BIOS firmware for virtual
+      machines. To use EFI for a given virtual machine, you can enable
+      EFI in the machine's Settings dialog. See
+      <xref linkend="settings-motherboard" />. Alternatively, use the
+      <computeroutput>VBoxManage</computeroutput> command line interface
+      as follows:
+    </para>
+
+<screen>VBoxManage modifyvm "VM name" --firmware efi</screen>
+
+    <para>
+      To switch back to using the BIOS:
+    </para>
+
+<screen>VBoxManage modifyvm "VM name" --firmware bios</screen>
+
+    <para>
+      One notable user of EFI is Apple's Mac OS X, but more recent
+      Linuxes and Windows, starting with Vista, offer special versions
+      that can be booted using EFI as well.
+    </para>
+
+    <para>
+      Another possible use of EFI in VirtualBox is development and
+      testing of EFI applications, without booting any OS.
+    </para>
+
+    <para>
+      Note that the VirtualBox EFI support is experimental and will be
+      enhanced as EFI matures and becomes more widespread. Mac OS X,
+      Linux, and newer Windows guests are known to work fine. Windows 7
+      guests are unable to boot with the VirtualBox EFI implementation.
+    </para>
+
+    <sect2 id="efividmode">
+
+      <title>Video Modes in EFI</title>
+
+      <para>
+        EFI provides two distinct video interfaces: GOP (Graphics Output
+        Protocol) and UGA (Universal Graphics Adapter). Modern operating
+        systems, such as Mac OS X, generally use GOP, while some older
+        ones still use UGA. VirtualBox provides a configuration option
+        to control the graphics resolution for both interfaces, making
+        the difference mostly irrelevant for users.
+      </para>
+
+      <para>
+        The default resolution is 1024x768. To select a graphics
+        resolution for EFI, use the following
+        <computeroutput>VBoxManage</computeroutput> command:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiGraphicsResolution HxV</screen>
+
+      <para>
+        Determine the horizontal resolution H and the vertical
+        resolution V from the following list of default resolutions:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            VGA
+          </term>
+
+          <listitem>
+            <para>
+              640x480, 32bpp, 4:3
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            SVGA
+          </term>
+
+          <listitem>
+            <para>
+              800x600, 32bpp, 4:3
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            XGA
+          </term>
+
+          <listitem>
+            <para>
+              1024x768, 32bpp, 4:3
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            XGA+
+          </term>
+
+          <listitem>
+            <para>
+              1152x864, 32bpp, 4:3
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            HD
+          </term>
+
+          <listitem>
+            <para>
+              1280x720, 32bpp, 16:9
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            WXGA
+          </term>
+
+          <listitem>
+            <para>
+              1280x800, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            SXGA
+          </term>
+
+          <listitem>
+            <para>
+              1280x1024, 32bpp, 5:4
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            SXGA+
+          </term>
+
+          <listitem>
+            <para>
+              1400x1050, 32bpp, 4:3
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            WXGA+
+          </term>
+
+          <listitem>
+            <para>
+              1440x900, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            HD+
+          </term>
+
+          <listitem>
+            <para>
+              1600x900, 32bpp, 16:9
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            UXGA
+          </term>
+
+          <listitem>
+            <para>
+              1600x1200, 32bpp, 4:3
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            WSXGA+
+          </term>
+
+          <listitem>
+            <para>
+              1680x1050, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            Full HD
+          </term>
+
+          <listitem>
+            <para>
+              1920x1080, 32bpp, 16:9
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            WUXGA
+          </term>
+
+          <listitem>
+            <para>
+              1920x1200, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            DCI 2K
+          </term>
+
+          <listitem>
+            <para>
+              2048x1080, 32bpp, 19:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            Full HD+
+          </term>
+
+          <listitem>
+            <para>
+              2160x1440, 32bpp, 3:2
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            Unnamed
+          </term>
+
+          <listitem>
+            <para>
+              2304x1440, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            QHD
+          </term>
+
+          <listitem>
+            <para>
+              2560x1440, 32bpp, 16:9
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            WQXGA
+          </term>
+
+          <listitem>
+            <para>
+              2560x1600, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            QWXGA+
+          </term>
+
+          <listitem>
+            <para>
+              2880x1800, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            QHD+
+          </term>
+
+          <listitem>
+            <para>
+              3200x1800, 32bpp, 16:9
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            WQSXGA
+          </term>
+
+          <listitem>
+            <para>
+              3200x2048, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            4K UHD
+          </term>
+
+          <listitem>
+            <para>
+              3840x2160, 32bpp, 16:9
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            WQUXGA
+          </term>
+
+          <listitem>
+            <para>
+              3840x2400, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            DCI 4K
+          </term>
+
+          <listitem>
+            <para>
+              4096x2160, 32bpp, 19:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            HXGA
+          </term>
+
+          <listitem>
+            <para>
+              4096x3072, 32bpp, 4:3
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            UHD+
+          </term>
+
+          <listitem>
+            <para>
+              5120x2880, 32bpp, 16:9
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            WHXGA
+          </term>
+
+          <listitem>
+            <para>
+              5120x3200, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            WHSXGA
+          </term>
+
+          <listitem>
+            <para>
+              6400x4096, 32bpp, 16:10
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            HUXGA
+          </term>
+
+          <listitem>
+            <para>
+              6400x4800, 32bpp, 4:3
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            8K UHD2
+          </term>
+
+          <listitem>
+            <para>
+              7680x4320, 32bpp, 16:9
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        If this list of default resolution does not cover your needs,
+        see <xref linkend="customvesa" />. Note that the color depth
+        value specified in a custom video mode must be specified (8, 16,
+        24 and 32 are accepted), but it is silently assumed to be 32 by
+        EFI.
+      </para>
+
+      <para>
+        The EFI default video resolution settings can only be changed
+        when the VM is powered off.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Implementation notes for Windows and Linux hosts</title>
-
-      <para>On Windows hosts, a kernel mode device driver provides USB proxy
-      support. It implements both a USB monitor, which allows VirtualBox to
-      capture devices when they are plugged in, and a USB device driver to
-      claim USB devices for a particular virtual machine. As opposed to
-      VirtualBox versions before 1.4.0, system reboots are no longer necessary
-      after installing the driver. Also, you no longer need to replug devices
-      for VirtualBox to claim them.</para>
-
-      <para>On newer Linux hosts, VirtualBox accesses USB devices through
-      special files in the file system. When VirtualBox is installed, these
-      are made available to all users in the
-      <computeroutput>vboxusers</computeroutput> system group. In order to be
-      able to access USB from guest systems, make sure that you are a member
-      of this group.</para>
-
-      <para>On older Linux hosts, USB devices are accessed using the
-      <computeroutput>usbfs</computeroutput> file system. Therefore, the user
-      executing VirtualBox needs read and write permission to the USB file
-      system. Most distributions provide a group (e.g.
-      <computeroutput>usbusers</computeroutput>) which the VirtualBox user
-      needs to be added to. Also, VirtualBox can only proxy to virtual
-      machines USB devices which are not claimed by a Linux host USB driver.
-      The <computeroutput>Driver=</computeroutput> entry in
-      <computeroutput>/proc/bus/usb/devices</computeroutput> will show you
-      which devices are currently claimed. Please refer to <xref
-      linkend="ts_usb-linux" /> also for details about
-      <computeroutput>usbfs</computeroutput>.</para>
+    <sect2 id="efibootargs">
+
+      <title>Specifying Boot Arguments</title>
+
+      <para>
+        It is currently not possible to manipulate EFI variables from
+        within a running guest. For example, setting the "boot-args"
+        variable by running the <computeroutput>nvram</computeroutput>
+        tool in a Mac OS X guest will not work. As an alternative way,
+        "VBoxInternal2/EfiBootArgs" extradata can be passed to a VM in
+        order to set the "boot-args" variable. To change the "boot-args"
+        EFI variable:
+
+<screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiBootArgs &lt;value&gt;</screen>
+      </para>
+
     </sect2>
+
   </sect1>
 
-  <sect1>
-    <title>Shared folders</title>
-
-    <para>Shared folders allow you to easily exchange data between a virtual
-    machine and your host. This feature requires that the VirtualBox Guest
-    Additions be installed in a virtual machine and is described in detail in
-    <xref linkend="sharedfolders" />.</para>
-  </sect1>
-
-  <sect1>
-    <title>User Interface</title>
-
-    <para>The "User Interface" section allows you to change certain aspects of
-      the user interface of this VM.</para>
-
-    <para><glosslist>
-      <glossentry>
-        <glossterm>Menu Bar</glossterm>
-        <glossdef>
-          <para>This widget allows you to disable certain menus (click at
-            the menu to release it), certain menu entries (uncheck the
-            checkbox of the entry to disable it) and the complete menu bar
-            (uncheck the rightmost checkbox).
-          </para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>Mini ToolBar</glossterm>
-        <glossdef>
-          <para>In full screen or seamless mode, VirtualBox can display a
-          small toolbar that contains some of the items that are normally
-          available from the virtual machine's menu bar. This toolbar
-          reduces itself to a small gray line unless you move the mouse
-          over it. With the toolbar, you can return from full screen or
-          seamless mode, control machine execution or enable certain
-          devices. If you don't want to see the toolbar, disable this
-          setting.</para>
-          <para>The second setting allows to show the toolbar at the top
-          of the screen instead of showing it at the bottom.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>Status Bar</glossterm>
-        <glossdef>
-          <para>This widget allows you to disable certain icons of the
-          status bar (uncheck the checkbox of an icon to disable it),
-          to re-arrange icons (drag and drop the icon) and to disable the
-          complete status bar (uncheck the leftmost checkbox).</para>
-        </glossdef>
-      </glossentry>
-    </glosslist></para>
-
-  </sect1>
-
-  <sect1 id="efi">
-    <title>Alternative firmware (EFI)</title>
-
-    <para>Starting with release 3.1, VirtualBox includes experimental support
-    for the Extensible Firmware Interface (EFI), which is a new industry
-    standard intended to eventually replace the legacy BIOS as the primary
-    interface for bootstrapping computers and certain system services
-    later.</para>
-
-    <para>By default, VirtualBox uses the BIOS firmware for virtual machines.
-    To use EFI for a given virtual machine, you can enable EFI in the
-    machine's "Settings" dialog (see <xref linkend="settings-motherboard" />).
-    Alternatively, use the <computeroutput>VBoxManage</computeroutput> command
-    line interface like this: <screen>VBoxManage modifyvm "VM name" --firmware efi</screen>
-    To switch back to using the BIOS, use: <screen>VBoxManage modifyvm "VM name" --firmware bios</screen>One
-    notable user of EFI is Apple's Mac OS X, but more recent Linuxes
-    and Windows (starting with Vista) offer special versions that can be
-    booted using EFI as well.</para>
-
-    <para>Another possible use of EFI in VirtualBox is development and testing
-    of EFI applications, without booting any OS.</para>
-
-    <para>Note that the VirtualBox EFI support is experimental and will be
-      enhanced as EFI matures and becomes more widespread. Mac OS X, Linux
-      and newer Windows guests are known to work fine. Windows 7 guests are
-      unable to boot with the VirtualBox EFI implementation.</para>
-
-    <sect2 id="efividmode">
-      <title>Video modes in EFI</title>
-
-      <para>EFI provides two distinct video interfaces: GOP (Graphics Output
-      Protocol) and UGA (Universal Graphics Adapter). Modern operating systems
-      (such as Mac OS X) generally use GOP, while some older ones still use
-      UGA. VirtualBox provides a configuration option to control the
-      graphics resolution for both interfaces, making the difference mostly
-      irrelevant for users.</para>
-
-      <para>The default resolution is 1024x768. To select a graphics resolution
-      for EFI, use the following <computeroutput>VBoxManage</computeroutput>
-      command:
-      <screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiGraphicsResolution HxV</screen>
-      Determine the horizontal resolution H and the vertical resolution V from
-      the following list of default resolutions:</para>
-
-      <glosslist>
-        <glossentry>
-          <glossterm>VGA</glossterm>
-          <glossdef>
-            <para>640x480, 32bpp, 4:3</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>SVGA</glossterm>
-          <glossdef>
-            <para>800x600, 32bpp, 4:3</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>XGA</glossterm>
-          <glossdef>
-            <para>1024x768, 32bpp, 4:3</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>XGA+</glossterm>
-          <glossdef>
-            <para>1152x864, 32bpp, 4:3</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>HD</glossterm>
-          <glossdef>
-            <para>1280x720, 32bpp, 16:9</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>WXGA</glossterm>
-          <glossdef>
-            <para>1280x800, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>SXGA</glossterm>
-          <glossdef>
-            <para>1280x1024, 32bpp, 5:4</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>SXGA+</glossterm>
-          <glossdef>
-            <para>1400x1050, 32bpp, 4:3</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>WXGA+</glossterm>
-          <glossdef>
-            <para>1440x900, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>HD+</glossterm>
-          <glossdef>
-            <para>1600x900, 32bpp, 16:9</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>UXGA</glossterm>
-          <glossdef>
-            <para>1600x1200, 32bpp, 4:3</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>WSXGA+</glossterm>
-          <glossdef>
-            <para>1680x1050, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Full HD</glossterm>
-          <glossdef>
-            <para>1920x1080, 32bpp, 16:9</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>WUXGA</glossterm>
-          <glossdef>
-            <para>1920x1200, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>DCI 2K</glossterm>
-          <glossdef>
-            <para>2048x1080, 32bpp, 19:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Full HD+</glossterm>
-          <glossdef>
-            <para>2160x1440, 32bpp, 3:2</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Unnamed</glossterm>
-          <glossdef>
-            <para>2304x1440, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>QHD</glossterm>
-          <glossdef>
-            <para>2560x1440, 32bpp, 16:9</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>WQXGA</glossterm>
-          <glossdef>
-            <para>2560x1600, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>QWXGA+</glossterm>
-          <glossdef>
-            <para>2880x1800, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>QHD+</glossterm>
-          <glossdef>
-            <para>3200x1800, 32bpp, 16:9</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>WQSXGA</glossterm>
-          <glossdef>
-            <para>3200x2048, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>4K UHD</glossterm>
-          <glossdef>
-            <para>3840x2160, 32bpp, 16:9</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>WQUXGA</glossterm>
-          <glossdef>
-            <para>3840x2400, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>DCI 4K</glossterm>
-          <glossdef>
-            <para>4096x2160, 32bpp, 19:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>HXGA</glossterm>
-          <glossdef>
-            <para>4096x3072, 32bpp, 4:3</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>UHD+</glossterm>
-          <glossdef>
-            <para>5120x2880, 32bpp, 16:9</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>WHXGA</glossterm>
-          <glossdef>
-            <para>5120x3200, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>WHSXGA</glossterm>
-          <glossdef>
-            <para>6400x4096, 32bpp, 16:10</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>HUXGA</glossterm>
-          <glossdef>
-            <para>6400x4800, 32bpp, 4:3</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>8K UHD2</glossterm>
-          <glossdef>
-            <para>7680x4320, 32bpp, 16:9</para>
-          </glossdef>
-        </glossentry>
-
-      </glosslist>
-
-      <para>If this list of default resolution does not cover your needs, see
-      <xref linkend="customvesa" />. Note that the color depth value specified
-      in a custom video mode must be specified (8, 16, 24 and 32 are accepted),
-      but it is silently assumed to be 32 by EFI.</para>
-
-      <para>The EFI default video resolution settings can only be changed when
-      the VM is powered off.</para>
-    </sect2>
-
-    <sect2 id="efibootargs">
-      <title>Specifying boot arguments</title>
-
-      <para>It is currently not possible to manipulate EFI variables from within a running guest
-      (e.g., setting the "boot-args" variable by running the <computeroutput>nvram</computeroutput> tool in a Mac OS X guest will not work).
-      As an alternative way, "VBoxInternal2/EfiBootArgs" extradata can be passed to a VM in order to set
-      the "boot-args" variable. To change the "boot-args" EFI variable:
-      <screen>VBoxManage setextradata "VM name" VBoxInternal2/EfiBootArgs &lt;value&gt;</screen>
-      </para>
-    </sect2>
-
-  </sect1>
 </chapter>
Index: /trunk/doc/manual/en_US/user_ChangeLog.xml
===================================================================
--- /trunk/doc/manual/en_US/user_ChangeLog.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_ChangeLog.xml	(revision 73276)
@@ -1,10 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
+
 <chapter id="ChangeLog">
-  <title>Change log</title>
+  <title>Change Log</title>
 
   <para>This section summarizes the changes between VirtualBox versions. Note
-  that this change log is not exhaustive; not all changes are listed.</para>
+  that this change log is not exhaustive and not all changes are listed.</para>
 
   <para>VirtualBox version numbers consist of three numbers separated by dots
@@ -14,9 +18,9 @@
   In addition, each build contains a revision number.</para>
 
-  <xi:include href="@VBOX_PATH_MANUAL_SRC@/user_ChangeLogImpl.xml" xpointer="xpointer(/chapter/*)"
+  <xi:include href="user_ChangeLogImpl.xml" xpointer="xpointer(/chapter/*)"
     xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <sect1>
-    <title>Older Change log details</title>
+  <sect1 id="change-log-older">
+    <title>Older Change Log Details</title>
     <para>With VirtualBox 5.0, changelog information for versions before 4.3
     was removed in order to save space. To access this information, please
Index: /trunk/doc/manual/en_US/user_Frontends.xml
===================================================================
--- /trunk/doc/manual/en_US/user_Frontends.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_Frontends.xml	(revision 73276)
@@ -1,557 +1,152 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="remotevm">
-  <title>Remote virtual machines</title>
+
+  <title>Remote Virtual Machines</title>
 
   <sect1 id="vrde">
-    <title>Remote display (VRDP support)</title>
-
-    <para>VirtualBox can display virtual machines remotely, meaning that a
-    virtual machine can execute on one computer even though the machine will be
-    displayed on a second computer, and the machine will be controlled from
-    there as well, as if the virtual machine was running on that second
-    computer.</para>
-
-    <para>For maximum flexibility, starting with VirtualBox 4.0, VirtualBox
-    implements remote machine display through a generic extension interface,
-    the VirtualBox Remote Desktop Extension (VRDE). The base open-source
-    VirtualBox package only provides this interface, while implementations can
-    be supplied by third parties with VirtualBox extension packages, which
-    must be installed separately from the base package. See <xref
-    linkend="intro-installing" /> for more information.</para>
-
-    <para>Oracle provides support for the <emphasis role="bold">VirtualBox
-    Remote Display Protocol (VRDP)</emphasis> in such a VirtualBox extension
-    package. When this package is installed, VirtualBox versions 4.0 and later
-    support VRDP the same way as binary (non-open-source) versions of
-    VirtualBox before 4.0 did.</para>
-
-    <para>VRDP is a backwards-compatible extension to Microsoft's Remote
-    Desktop Protocol (RDP). As a result, you can use any standard RDP client
-    to control the remote VM.</para>
-
-    <para>Even when the extension is installed, the VRDP server is disabled by
-    default. It can easily be enabled on a per-VM basis either in the
-    VirtualBox Manager in the "Display" settings (see <xref
-    linkend="settings-display" />) or with
-    <computeroutput>VBoxManage</computeroutput>:<screen>VBoxManage modifyvm "VM name" --vrde on</screen></para>
-
-    <para>By default, the VRDP server uses TCP port
-    <computeroutput>3389</computeroutput>. You will need to change the
-    default port if you run more than one VRDP server, since the port can
-    only be used by one server at a time; you might also need to change it
-    on Windows hosts since the default port might already be used by the RDP
-    server that is built into Windows itself. Ports 5000 through 5050 are
-    typically not used and might be a good choice.</para>
-
-    <para>The port can be changed either in the "Display" settings of the
-    graphical user interface or with
-    <computeroutput>--vrdeport</computeroutput> option of the
-    <computeroutput>VBoxManage modifyvm</computeroutput> command. You can
-    specify a comma-separated list of ports or ranges of ports. Use a dash
-    between two port numbers to specify a range. The VRDP server will bind
-    to <emphasis role="bold">one</emphasis> of available ports from the
-    specified list. For example, <computeroutput>VBoxManage modifyvm "VM
-    name" --vrdeport 5000,5010-5012</computeroutput> will configure the
-    server to bind to one of the ports 5000, 5010, 5011 or 5012. See <xref
-    linkend="vboxmanage-modifyvm-vrde" /> for details.</para>
-
-    <para>The actual port used by a running VM can be either queried with
-    <computeroutput>VBoxManage showvminfo</computeroutput> command or seen
-    in the GUI on the "Runtime" tab of the "Session Information Dialog",
-    which is accessible via the "Machine" menu of the VM window.</para>
-
-    <para>Support for IPv6 has been implemented in VirtualBox 4.3.
-    If the host OS supports IPv6 the VRDP server will automatically
-    listen for IPv6 connections in addition to IPv4.</para>
+
+    <title>Remote Display (VRDP Support)</title>
+
+    <para>
+      VirtualBox can display virtual machines remotely, meaning that a
+      virtual machine can execute on one computer even though the
+      machine will be displayed on a second computer, and the machine
+      will be controlled from there as well, as if the virtual machine
+      was running on that second computer.
+    </para>
+
+    <para>
+      For maximum flexibility, starting with VirtualBox 4.0, VirtualBox
+      implements remote machine display through a generic extension
+      interface, the VirtualBox Remote Desktop Extension (VRDE). The
+      base open source VirtualBox package only provides this interface,
+      while implementations can be supplied by third parties with
+      VirtualBox extension packages, which must be installed separately
+      from the base package. See
+      <xref
+    linkend="intro-installing" />.
+    </para>
+
+    <para>
+      Oracle provides support for the VirtualBox Remote Display Protocol
+      (VRDP) in such a VirtualBox extension package. When this package
+      is installed, VirtualBox versions 4.0 and later support VRDP the
+      same way as binary (non-open source) versions of VirtualBox before
+      4.0 did.
+    </para>
+
+    <para>
+      VRDP is a backwards-compatible extension to Microsoft's Remote
+      Desktop Protocol (RDP). As a result, you can use any standard RDP
+      client to control the remote VM.
+    </para>
+
+    <para>
+      Even when the extension is installed, the VRDP server is disabled
+      by default. It can easily be enabled on a per-VM basis either in
+      the VirtualBox Manager in the Display settings, see
+      <xref
+    linkend="settings-display" />, or with
+      <computeroutput>VBoxManage</computeroutput>:
+    </para>
+
+<screen>VBoxManage modifyvm "VM name" --vrde on</screen>
+
+    <para>
+      By default, the VRDP server uses TCP port
+      <computeroutput>3389</computeroutput>. You will need to change the
+      default port if you run more than one VRDP server, since the port
+      can only be used by one server at a time. You might also need to
+      change it on Windows hosts since the default port might already be
+      used by the RDP server that is built into Windows itself. Ports
+      5000 through 5050 are typically not used and might be a good
+      choice.
+    </para>
+
+    <para>
+      The port can be changed either in the Display settings of the
+      graphical user interface or with
+      <computeroutput>--vrdeport</computeroutput> option of the
+      <computeroutput>VBoxManage modifyvm</computeroutput> command. You
+      can specify a comma-separated list of ports or ranges of ports.
+      Use a dash between two port numbers to specify a range. The VRDP
+      server will bind to <emphasis>one</emphasis> of the available
+      ports from the specified list. For example,
+      <computeroutput>VBoxManage modifyvm "VM name" --vrdeport
+      5000,5010-5012</computeroutput> will configure the server to bind
+      to one of the ports 5000, 5010, 5011, or 5012. See
+      <xref
+    linkend="vboxmanage-modifyvm-vrde" />.
+    </para>
+
+    <para>
+      The actual port used by a running VM can be either queried with
+      the <computeroutput>VBoxManage showvminfo</computeroutput> command
+      or seen in the GUI on the Runtime tab of the Session Information
+      dialog, which is accessible via the Machine menu of the VM window.
+    </para>
+
+    <para>
+      Support for IPv6 has been implemented in VirtualBox 4.3. If the
+      host OS supports IPv6 the VRDP server will automatically listen
+      for IPv6 connections in addition to IPv4.
+    </para>
 
     <sect2 id="rdp-viewers">
-      <title>Common third-party RDP viewers</title>
-
-      <para>Since VRDP is backwards-compatible to RDP, you can use any
-      standard RDP viewer to connect to such a remote virtual machine
-      (examples follow below). For this to work, you must specify the
-      <emphasis role="bold">IP address</emphasis> of your
-      <emphasis>host</emphasis> system (not of the virtual machine!) as the
-      server address to connect to, as well as the <emphasis role="bold">port
-      number</emphasis> that the VRDP server is using.</para>
-
-      <para>Here follow examples for the most common RDP viewers:<itemizedlist>
-          <listitem>
-            <para>On Windows, you can use the Microsoft Terminal Services
-            Connector (<computeroutput>mstsc.exe</computeroutput>) that ships
-            with Windows. You can start it by bringing up the "Run" dialog
-            (press the Windows key and "R") and typing "mstsc". You can also
-            find it under "Start" &rarr; "All Programs" &rarr; "Accessories"
-            &rarr; "Remote Desktop Connection". If you use the "Run" dialog,
-            you can type in options directly:<screen>mstsc 1.2.3.4:3389</screen></para>
-
-            <para>Replace <computeroutput>1.2.3.4</computeroutput> with the host IP address,
-            and <computeroutput>3389</computeroutput> with a different port if necessary.</para>
-
-            <note>
-              <para>IPv6 address must be enclosed in square brackets to specify a port.
-              For example: <computeroutput>mstsc [fe80::1:2:3:4]:3389</computeroutput></para>
-            </note>
-
-            <note>
-              <para>When connecting to localhost in order to test the
-              connection, the addresses
-              <computeroutput>localhost</computeroutput> and
-              <computeroutput>127.0.0.1</computeroutput> might not work using
-              <computeroutput>mstsc.exe</computeroutput>. Instead, the address
-              <computeroutput>127.0.0.2[:3389]</computeroutput> has to be
-              used.</para>
-            </note>
-          </listitem>
-
-          <listitem>
-            <para>On other systems, you can use the standard open-source
-            <computeroutput>rdesktop</computeroutput> program. This ships with
-            most Linux distributions, but VirtualBox also comes with a
-            modified variant of rdesktop for remote USB support (see <xref
-            linkend="usb-over-rdp" /> below).</para>
-
-            <para>With rdesktop, use a command line such as the
-            following:<screen>rdesktop -a 16 -N 1.2.3.4:3389</screen></para>
-
-            <para>As said for the Microsoft viewer above, replace <computeroutput>1.2.3.4</computeroutput>
-            with the host IP address, and <computeroutput>3389</computeroutput> with a different port if
-            necessary. The <computeroutput>-a 16</computeroutput> option
-            requests a color depth of 16 bits per pixel, which we recommend.
-            (For best performance, after installation of the guest operating
-            system, you should set its display color depth to the same value).
-            The <computeroutput>-N</computeroutput> option enables use of the
-            NumPad keys.</para>
-          </listitem>
-
-          <listitem>
-            <para>If you run the KDE desktop, you might prefer
-            <computeroutput>krdc</computeroutput>, the KDE RDP viewer. The
-            command line would look like this:<screen>krdc rdp://1.2.3.4:3389</screen></para>
-
-            <para>Again, replace <computeroutput>1.2.3.4</computeroutput> with the host IP address,
-            and <computeroutput>3389</computeroutput> with a different port if necessary.
-            The "rdp://" bit is required with krdc to switch it into RDP mode.</para>
-          </listitem>
-
-          <listitem>
-            <para>With Sun Ray thin clients you can use
-            <computeroutput>uttsc</computeroutput>, which is part of the
-            Sun Ray Windows Connector package. See the corresponding
-            documentation for details.</para>
-          </listitem>
-        </itemizedlist></para>
-    </sect2>
-
-    <sect2 id="vboxheadless">
-      <title>VBoxHeadless, the remote desktop server</title>
-
-      <para>While any VM started from the VirtualBox Manager is capable of
-      running virtual machines remotely, it is not convenient to have to run
-      the full-fledged GUI if you never want to have VMs displayed locally in
-      the first place. In particular, if you are running server hardware whose
-      only purpose is to host VMs, and all your VMs are supposed to run
-      remotely over VRDP, then it is pointless to have a graphical user
-      interface on the server at all -- especially since, on a Linux or
-      Solaris host, the VirtualBox manager comes with dependencies on the Qt
-      and SDL libraries. This is inconvenient if you would rather not have the
-      X Window system on your server at all.</para>
-
-      <para>VirtualBox therefore comes with yet another front-end called
-      <computeroutput>VBoxHeadless</computeroutput>, which produces no visible
-      output on the host at all, but still can deliver VRDP data. This
-      front-end has no dependencies on the X Window system on Linux and
-      Solaris hosts.<footnote>
-          <para>Before VirtualBox 1.6, the headless server was called
-          <computeroutput>VBoxVRDP</computeroutput>. For the sake of backwards
-          compatibility, the VirtualBox installation still installs an
-          executable with that name as well.</para>
-        </footnote></para>
-
-      <para>To start a virtual machine with
-      <computeroutput>VBoxHeadless</computeroutput>, you have three
-      options:</para>
+
+      <title>Common Third-Party RDP Viewers</title>
+
+      <para>
+        Since VRDP is backwards-compatible to RDP, you can use any
+        standard RDP viewer to connect to such a remote virtual machine.
+        For this to work, you must specify the IP address of your
+        <emphasis>host</emphasis> system, not of the virtual machine, as
+        the server address to connect to. You must also specify the port
+        number that the VRDP server is using.
+      </para>
+
+      <para>
+        The following examples are for the most common RDP viewers:
+      </para>
 
       <itemizedlist>
-        <listitem>
-          <para>You can use <screen>VBoxManage startvm "VM name" --type headless</screen>The
-          extra <computeroutput>--type</computeroutput> option causes
-          VirtualBox to use <computeroutput>VBoxHeadless</computeroutput> as
-          the front-end to the internal virtualization engine instead of the
-          Qt front-end.</para>
-        </listitem>
-
-        <listitem>
-          <para>One alternative is to use
-          <computeroutput>VBoxHeadless</computeroutput> directly, as
-          follows:<screen>VBoxHeadless --startvm &lt;uuid|name&gt;</screen></para>
-
-          <para>This way of starting the VM helps troubleshooting problems
-          reported by <computeroutput>VBoxManage startvm ...</computeroutput>
-          because you can see sometimes more detailed error messages,
-          especially for early failures before the VM execution is started.
-          In normal situations <computeroutput>VBoxManage startvm</computeroutput>
-          is preferred since it runs the VM directly as a background process
-          which has to be done explicitly when directly starting
-          <computeroutput>VBoxHeadless</computeroutput>.</para>
-        </listitem>
-
-        <listitem>
-          <para>The other alternative is to start
-          <computeroutput>VBoxHeadless</computeroutput> from the VirtualBox
-          Manager GUI, by holding the Shift key when starting a virtual
-          machine or selecting <computeroutput>Headless Start</computeroutput>
-          from the <computeroutput>Machine</computeroutput> menu.
-          </para>
-        </listitem>
-      </itemizedlist>
-
-      <para>Since VirtualBox version 5.0, when you use
-      <computeroutput>VBoxHeadless</computeroutput> to start a VM,
-      the VRDP server will be enabled according to the VM configuration.
-      You can override the VM's setting using <computeroutput>--vrde</computeroutput>
-      command line parameter. To enable the VRDP server start the VM like
-      this:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde on</screen>
-      and to disable it:<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde off</screen>
-      To have the VRDP server enabled depending on the VM configuration, as the
-      other front-ends would, you can still use:
-      <screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde config</screen>
-      but this is the same as <screen>VBoxHeadless --startvm &lt;uuid|name&gt;</screen></para>
-
-      <para>If you start the VM with <computeroutput>VBoxManage startvm ...</computeroutput>
-      then the configuration settings of the VM are always used.</para>
-    </sect2>
-
-    <sect2>
-      <title>Step by step: creating a virtual machine on a headless
-      server</title>
-
-      <para>The following instructions may give you an idea how to create a
-      virtual machine on a headless server over a network connection. We will
-      create a virtual machine, establish an RDP connection and install a
-      guest operating system -- all without having to touch the headless
-      server. All you need is the following:</para>
-
-      <para><orderedlist>
-          <listitem>
-            <para>VirtualBox on a server machine with a supported host
-            operating system. The VirtualBox extension pack for the VRDP
-            server must be installed (see the previous section). For the
-            following example, we will assume a Linux server.</para>
-          </listitem>
-
-          <listitem>
-            <para>An ISO file accessible from the server, containing the
-            installation data for the guest operating system to install (we
-            will assume Windows XP in the following example).</para>
-          </listitem>
-
-          <listitem>
-            <para>A terminal connection to that host through which you can
-            access a command line (e.g. via
-            <computeroutput>ssh</computeroutput>).</para>
-          </listitem>
-
-          <listitem>
-            <para>An RDP viewer on the remote client; see <xref
-            linkend="rdp-viewers" /> above for examples.</para>
-          </listitem>
-        </orderedlist>Note again that on the server machine, since we will
-      only use the headless server, neither Qt nor SDL nor the X Window system
-      will be needed.</para>
-
-      <para><orderedlist>
-          <listitem>
-            <para>On the headless server, create a new virtual machine:</para>
-
-            <screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen>
-
-            <para>Note that if you do not specify
-            <computeroutput>--register</computeroutput>, you will have to
-            manually use the <computeroutput>registervm</computeroutput>
-            command later.</para>
-
-            <para>Note further that you do not need to specify
-            <computeroutput>--ostype</computeroutput>, but doing so selects
-            some sane default values for certain VM parameters, for example
-            the RAM size and the type of the virtual network device. To get a
-            complete list of supported operating systems you can use</para>
-
-            <screen>VBoxManage list ostypes</screen>
-          </listitem>
-
-          <listitem>
-            <para>Make sure the settings for this VM are appropriate for the
-            guest operating system that we will install. For example:<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen></para>
-          </listitem>
-
-          <listitem>
-            <para>Create a virtual hard disk for the VM (in this case, 10 GB in
-            size):<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</screen></para>
-          </listitem>
-
-          <listitem>
-            <para>Add an IDE Controller to the new VM:<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller"
-      --add ide --controller PIIX4</screen></para>
-          </listitem>
-
-          <listitem>
-            <para>Set the VDI file created above as the first virtual hard
-            disk of the new VM:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
-      --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen></para>
-          </listitem>
-
-          <listitem>
-            <para>Attach the ISO file that contains the operating system
-            installation that you want to install later to the virtual
-            machine, so the machine can boot from it:<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
-      --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen></para>
-          </listitem>
-
-          <listitem>
-            <para>Enable VirtualBox remote desktop extension (the VRDP server):
-            <screen>VBoxManage modifyvm "Windows XP" --vrde on</screen></para>
-          </listitem>
-
-          <listitem>
-            <para>Start the virtual machine using VBoxHeadless:<screen>VBoxHeadless --startvm "Windows XP"</screen></para>
-
-            <para>If everything worked, you should see a copyright notice. If,
-            instead, you are returned to the command line, then something went
-            wrong.</para>
-          </listitem>
-
-          <listitem>
-            <para>On the client machine, fire up the RDP viewer and try to
-            connect to the server (see <xref linkend="rdp-viewers" /> above
-            for how to use various common RDP viewers).</para>
-
-            <para>You should now be seeing the installation routine of your
-            guest operating system remotely in the RDP viewer.</para>
-          </listitem>
-        </orderedlist></para>
-    </sect2>
-
-    <sect2 id="usb-over-rdp">
-      <title>Remote USB</title>
-
-      <para>As a special feature on top of the VRDP support, VirtualBox
-      supports remote USB devices over the wire as well. That is, the
-      VirtualBox guest that runs on one computer can access the USB devices of
-      the remote computer on which the VRDP data is being displayed the same
-      way as USB devices that are connected to the actual host. This allows
-      for running virtual machines on a VirtualBox host that acts as a server,
-      where a client can connect from elsewhere that needs only a network
-      adapter and a display capable of running an RDP viewer. When USB devices
-      are plugged into the client, the remote VirtualBox server can access
-      them.</para>
-
-      <para>For these remote USB devices, the same filter rules apply as for
-      other USB devices, as described with <xref linkend="settings-usb" />.
-      All you have to do is specify "Remote" (or "Any") when setting up these
-      rules.</para>
-
-      <para>Accessing remote USB devices is only possible if the RDP client
-      supports this extension. On Linux and Solaris hosts, the VirtualBox
-      installation provides a suitable VRDP client called
-      <computeroutput>rdesktop-vrdp</computeroutput>. Recent versions of
-      <computeroutput>uttsc</computeroutput>, a client tailored for the use
-      with Sun Ray thin clients, also support accessing remote USB devices.
-      RDP clients for other platforms will be provided in future VirtualBox
-      versions.</para>
-
-      <para>To make a remote USB device available to a VM,
-      <computeroutput>rdesktop-vrdp</computeroutput> should be started as
-      follows:<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen>
-      Please refer to <xref linkend="ts_usb-linux" /> for further details on how
-      to properly set up the permissions for USB devices. Furthermore it is
-      advisable to
-      disable automatic loading of any host driver on the remote host which
-      might work on USB devices to ensure that the devices are accessible by
-      the RDP client. If the setup was properly done on the remote host,
-      plug/unplug events are visible on the VBox.log file of the VM.</para>
-    </sect2>
-
-    <sect2 id="vbox-auth">
-      <title>RDP authentication</title>
-
-      <para>For each virtual machine that is remotely accessible via RDP, you
-      can individually determine if and how client connections are
-      authenticated. For this, use <computeroutput>VBoxManage
-      modifyvm</computeroutput> command with the
-      <computeroutput>--vrdeauthtype</computeroutput> option; see <xref
-      linkend="vboxmanage-modifyvm" /> for a general introduction. Three
-      methods of authentication are available:<itemizedlist>
-          <listitem>
-            <para>The "null" method means that there is no authentication at
-            all; any client can connect to the VRDP server and thus the
-            virtual machine. This is, of course, very insecure and only to be
-            recommended for private networks.</para>
-          </listitem>
-
-          <listitem>
-            <para>The "external" method provides external authentication
-            through a special authentication library. VirtualBox ships with
-            two such authentication libraries:<orderedlist>
-                <listitem>
-                  <para>The default authentication library,
-                  <computeroutput>VBoxAuth</computeroutput>, authenticates
-                  against user credentials of the hosts. Depending on the host
-                  platform, this means:<itemizedlist>
-                      <listitem>
-                        <para>On Linux hosts,
-                        <computeroutput>VBoxAuth.so</computeroutput>
-                        authenticates users against the host's PAM
-                        system.</para>
-                      </listitem>
-
-                      <listitem>
-                        <para>On Windows hosts,
-                        <computeroutput>VBoxAuth.dll</computeroutput>
-                        authenticates users against the host's WinLogon
-                        system.</para>
-                      </listitem>
-
-                      <listitem>
-                        <para>On Mac OS X hosts,
-                        <computeroutput>VBoxAuth.dylib</computeroutput>
-                        authenticates users against the host's directory
-                        service.<footnote>
-                            <para>Support for Mac OS X was added in version
-                            3.2.</para>
-                          </footnote></para>
-                      </listitem>
-                    </itemizedlist></para>
-
-                  <para>In other words, the "external" method per default
-                  performs authentication with the user accounts that exist on
-                  the host system. Any user with valid authentication
-                  credentials is accepted, i.e. the username does not have to
-                  correspond to the user running the VM.</para>
-                </listitem>
-
-                <listitem>
-                  <para>An additional library called
-                  <computeroutput>VBoxAuthSimple</computeroutput> performs
-                  authentication against credentials configured in the
-                  "extradata" section of a virtual machine's XML settings
-                  file. This is probably the simplest way to get
-                  authentication that does not depend on a running and
-                  supported guest (see below). The following steps are
-                  required:<orderedlist>
-                      <listitem>
-                        <para>Enable
-                        <computeroutput>VBoxAuthSimple</computeroutput> with
-                        the following command:</para>
-
-                        <para><screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen></para>
-                      </listitem>
-
-                      <listitem>
-                        <para>To enable the library for a particular VM, you
-                        must then switch authentication to external:<screen>VBoxManage modifyvm "VM name" --vrdeauthtype external</screen></para>
-
-                        <para>Replace
-                        <computeroutput>&lt;vm&gt;</computeroutput> with the
-                        VM name or UUID.</para>
-                      </listitem>
-
-                      <listitem>
-                        <para>You will then need to configure users and
-                        passwords by writing items into the machine's
-                        extradata. Since the XML machine settings file, into
-                        whose "extradata" section the password needs to be
-                        written, is a plain text file, VirtualBox uses hashes
-                        to encrypt passwords. The following command must be
-                        used:<screen>VBoxManage setextradata "VM name" "VBoxAuthSimple/users/&lt;user&gt;" &lt;hash&gt;</screen></para>
-
-                        <para>Replace
-                        <computeroutput>&lt;vm&gt;</computeroutput> with the
-                        VM name or UUID,
-                        <computeroutput>&lt;user&gt;</computeroutput> with the
-                        user name who should be allowed to log in and
-                        <computeroutput>&lt;hash&gt;</computeroutput> with the
-                        encrypted password. As an example, to obtain the hash
-                        value for the password "secret", you can use the
-                        following command:<screen>VBoxManage internalcommands passwordhash "secret"</screen></para>
-
-                        <para>This will print
-                        <screen>2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen>
-                        You can then use VBoxManage setextradata to store this
-                        value in the machine's "extradata" section.</para>
-
-                        <para>As example, combined together, to set the
-                        password for the user "john" and the machine "My VM"
-                        to "secret", use this command:<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john"
-    2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen></para>
-                      </listitem>
-                    </orderedlist></para>
-                </listitem>
-              </orderedlist></para>
-          </listitem>
-
-          <listitem>
-            <para>Finally, the "guest" authentication method performs
-            authentication with a special component that comes with the Guest
-            Additions; as a result, authentication is not performed on the
-            host, but with the <emphasis>guest</emphasis> user
-            accounts.</para>
-
-            <para>This method is currently still in testing and not yet
-            supported.</para>
-          </listitem>
-        </itemizedlist></para>
-
-      <para>In addition to the methods described above, you can replace the
-      default "external" authentication module with any other module. For
-      this, VirtualBox provides a well-defined interface that allows you to
-      write your own authentication module. This is described in detail in the
-      VirtualBox Software Development Kit (SDK) reference; please see <xref
-      linkend="VirtualBoxAPI" /> for details.</para>
-    </sect2>
-
-    <sect2 id="vrde-crypt">
-      <title>RDP encryption</title>
-
-      <para>RDP features data stream encryption, which is based on the RC4
-      symmetric cipher (with keys up to 128bit). The RC4 keys are being
-      replaced in regular intervals (every 4096 packets).</para>
-
-      <para>RDP provides different authentication methods:<orderedlist>
-          <listitem>
-            <para>Historically, RDP4 authentication was used, with which the
-            RDP client does not perform any checks in order to verify the
-            identity of the server it connects to. Since user credentials can
-            be obtained using a "man in the middle" (MITM) attack, RDP4
-            authentication is insecure and should generally not be
-            used.</para>
-          </listitem>
-
-          <listitem>
-            <para>RDP5.1 authentication employs a server certificate for which
-            the client possesses the public key. This way it is guaranteed
-            that the server possess the corresponding private key. However, as
-            this hard-coded private key became public some years ago, RDP5.1
-            authentication is also insecure.</para>
-          </listitem>
-
-          <listitem>
-            <para>RDP5.2 authentication uses the Enhanced RDP Security, which
-            means that an external security protocol is used to secure the
-            connection. RDP4 and RDP5.1 use Standard RDP Security.
-            The VRDP server supports Enhanced RDP Security with TLS protocol and,
-            as a part of TLS handshake, sends the server certificate to the
-            client.</para>
-
-            <para>The <computeroutput>Security/Method</computeroutput> VRDE
-            property sets the desired security method, which is used for a
-            connection. Valid values are:<itemizedlist>
+
+        <listitem>
+          <para>
+            On Windows, you can use the Microsoft Terminal Services
+            Connector, <computeroutput>mstsc.exe</computeroutput>, that
+            is included with Windows. Press the
+            <emphasis role="bold">Windows key + R</emphasis>, to display
+            the Run dialog. Enter <command>mstsc</command> to start the
+            program. You can also find the program in
+            <emphasis role="bold">Start</emphasis>,
+            <emphasis role="bold">All Programs</emphasis>,
+            <emphasis role="bold">Accessories</emphasis>,
+            <emphasis role="bold">Remote Desktop Connection</emphasis>.
+            If you use the Run dialog, you can type in options directly.
+            For example:
+          </para>
+
+<screen>mstsc 1.2.3.4:3389</screen>
+
+          <para>
+            Replace <computeroutput>1.2.3.4</computeroutput> with the
+            host IP address, and <computeroutput>3389</computeroutput>
+            with a different port, if necessary.
+          </para>
+
+          <note>
+            <itemizedlist>
+
               <listitem>
                 <para>
-                  <computeroutput>Negotiate</computeroutput> - both Enhanced (TLS)
-                  and Standard RDP Security connections are allowed. The security
-                  method is negotiated with the client. This is the default setting.
+                  IPv6 addresses must be enclosed in square brackets to
+                  specify a port. For example: <computeroutput>mstsc
+                  [fe80::1:2:3:4]:3389</computeroutput>
                 </para>
               </listitem>
@@ -559,137 +154,920 @@
               <listitem>
                 <para>
-                  <computeroutput>RDP</computeroutput> - only Standard RDP Security
-                  is accepted.</para>
+                  When connecting to localhost in order to test the
+                  connection, the addresses
+                  <computeroutput>localhost</computeroutput> and
+                  <computeroutput>127.0.0.1</computeroutput> might not
+                  work using <computeroutput>mstsc.exe</computeroutput>.
+                  Instead, the address
+                  <computeroutput>127.0.0.2[:3389]</computeroutput> has
+                  to be used.
+                </para>
               </listitem>
 
-              <listitem>
-                <para>
-                  <computeroutput>TLS</computeroutput> - only Enhanced RDP Security
-                  is accepted. The client must support TLS.</para>
+            </itemizedlist>
+          </note>
+        </listitem>
+
+        <listitem>
+          <para>
+            On other systems, you can use the standard open source
+            <computeroutput>rdesktop</computeroutput> program. This
+            ships with most Linux distributions, but VirtualBox also
+            comes with a modified variant of rdesktop for remote USB
+            support. See <xref
+            linkend="usb-over-rdp" />.
+          </para>
+
+          <para>
+            With rdesktop, use a command line such as the following:
+          </para>
+
+<screen>rdesktop -a 16 -N 1.2.3.4:3389</screen>
+
+          <para>
+            Replace <computeroutput>1.2.3.4</computeroutput> with the
+            host IP address, and <computeroutput>3389</computeroutput>
+            with a different port, if necessary. The <computeroutput>-a
+            16</computeroutput> option requests a color depth of 16 bits
+            per pixel, which we recommend. For best performance, after
+            installation of the guest operating system, you should set
+            its display color depth to the same value. The
+            <computeroutput>-N</computeroutput> option enables use of
+            the NumPad keys.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            If you run the KDE desktop, you can use
+            <computeroutput>krdc</computeroutput>, the KDE RDP viewer. A
+            typical command line is as follows:
+          </para>
+
+<screen>krdc rdp://1.2.3.4:3389</screen>
+
+          <para>
+            Replace <computeroutput>1.2.3.4</computeroutput> with the
+            host IP address, and <computeroutput>3389</computeroutput>
+            with a different port, if necessary. The "rdp://" prefix is
+            required with krdc to switch it into RDP mode.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            With Sun Ray thin clients you can use
+            <computeroutput>uttsc</computeroutput>, which is part of the
+            Sun Ray Windows Connector package. See the Sun Ray
+            documentation for details.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="vboxheadless">
+
+      <title>VBoxHeadless, the Remote Desktop Server</title>
+
+      <para>
+        While any VM started from the VirtualBox Manager is capable of
+        running virtual machines remotely, it is not convenient to have
+        to run the full-fledged GUI if you never want to have VMs
+        displayed locally in the first place. In particular, if you are
+        running server hardware whose only purpose is to host VMs, and
+        all your VMs are supposed to run remotely over VRDP, then it is
+        pointless to have a graphical user interface on the server at
+        all. This is especially true for Linux or Solaris hosts, as the
+        VirtualBox manager comes with dependencies on the Qt and SDL
+        libraries. This is inconvenient if you would rather not have the
+        X Window system on your server at all.
+      </para>
+
+      <para>
+        VirtualBox therefore comes with a front-end called
+        <computeroutput>VBoxHeadless</computeroutput>, which produces no
+        visible output on the host at all, but still can deliver VRDP
+        data. This front-end has no dependencies on the X Window system
+        on Linux and Solaris hosts.
+
+        <footnote>
+
+          <para>
+            Before VirtualBox 1.6, the headless server was called
+            <computeroutput>VBoxVRDP</computeroutput>. For the sake of
+            backwards compatibility, the VirtualBox installation still
+            installs an executable with that name as well.
+          </para>
+
+        </footnote>
+      </para>
+
+      <para>
+        To start a virtual machine with
+        <computeroutput>VBoxHeadless</computeroutput>, you have the
+        following options:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Use the <computeroutput>VBoxManage</computeroutput> command,
+            as follows:
+          </para>
+
+<screen>VBoxManage startvm "VM name" --type headless</screen>
+
+          <para>
+            The <computeroutput>--type</computeroutput> option causes
+            VirtualBox to use
+            <computeroutput>VBoxHeadless</computeroutput> as the
+            front-end to the internal virtualization engine, instead of
+            the Qt front-end.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Use the <computeroutput>VBoxHeadless</computeroutput>
+            command, as follows:
+          </para>
+
+<screen>VBoxHeadless --startvm &lt;uuid|name&gt;</screen>
+
+          <para>
+            This way of starting the VM helps troubleshooting problems
+            reported by <computeroutput>VBoxManage startvm
+            </computeroutput>, because you can sometimes see more
+            detailed error messages, especially for early failures
+            before the VM execution is started. In normal situations
+            <computeroutput>VBoxManage startvm</computeroutput> is
+            preferred, since it runs the VM directly as a background
+            process which has to be done explicitly when directly
+            starting <computeroutput>VBoxHeadless</computeroutput>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Start <computeroutput>VBoxHeadless</computeroutput> from the
+            VirtualBox Manager GUI, by holding the Shift key when
+            starting a virtual machine or by selecting
+            <emphasis role="bold">Headless Start</emphasis> from the
+            <emphasis role="bold">Machine</emphasis> menu.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Since VirtualBox version 5.0, when you use
+        <computeroutput>VBoxHeadless</computeroutput> to start a VM, the
+        VRDP server will be enabled according to the VM configuration.
+        You can override the VM's setting using
+        <computeroutput>--vrde</computeroutput> command line parameter.
+        To enable the VRDP server start the VM like this:
+
+<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde on</screen>
+
+        To disable the VRDP server:
+
+<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde off</screen>
+
+        To have the VRDP server enabled depending on the VM
+        configuration, as the other front-ends would, you can use:
+
+<screen>VBoxHeadless --startvm &lt;uuid|name&gt; --vrde config</screen>
+
+        This command is the same as:
+
+<screen>VBoxHeadless --startvm &lt;uuid|name&gt;</screen>
+      </para>
+
+      <para>
+        If you start the VM with <computeroutput>VBoxManage
+        startvm</computeroutput> then the configuration settings of the
+        VM are always used.
+      </para>
+
+    </sect2>
+
+    <sect2 id="headless-vm-steps">
+
+      <title>Step by Step: Creating a Virtual Machine on a Headless Server</title>
+
+      <para>
+        The following instructions describe how to create a virtual
+        machine on a headless server over a network connection. This
+        example creates a virtual machine, establishes an RDP connection
+        and installs a guest operating system. All of these tasks are
+        done without having to touch the headless server. You need the
+        following prerequisites:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            VirtualBox on a server machine with a supported host
+            operating system. The VirtualBox extension pack for the VRDP
+            server must be installed, see <xref linkend="vrde"/>. The
+            procedures assume a Linux server is used.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            An ISO file accessible from the server, containing the
+            installation data for the guest operating system to install.
+            Windows XP is used in the example.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            A terminal connection to that host through which you can
+            access a command line, such as
+            <computeroutput>ssh</computeroutput>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            An RDP viewer on the remote client. See
+            <xref
+            linkend="rdp-viewers" /> for examples.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Note that on the server machine, since we will only use the
+        headless server, Qt, SDL, and the X Window system are not
+        required.
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+          <para>
+            On the headless server, create a new virtual machine. For
+            example:
+          </para>
+
+<screen>VBoxManage createvm --name "Windows XP" --ostype WindowsXP --register</screen>
+
+          <para>
+            If you do not specify
+            <computeroutput>--register</computeroutput>, you will have
+            to manually use the
+            <computeroutput>registervm</computeroutput> command later.
+          </para>
+
+          <para>
+            You do not need to specify
+            <computeroutput>--ostype</computeroutput>, but doing so
+            selects some sensible default values for certain VM
+            parameters. For example, the RAM size and the type of the
+            virtual network device. To get a complete list of supported
+            operating systems you can use the following command:
+          </para>
+
+<screen>VBoxManage list ostypes</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Make sure the settings for the VM are appropriate for the
+            guest operating system that we will install. For example:
+          </para>
+
+<screen>VBoxManage modifyvm "Windows XP" --memory 256 --acpi on --boot1 dvd --nic1 nat</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Create a virtual hard disk for the VM. For example, to
+            create a 10 GB virtual hard disk:
+          </para>
+
+<screen>VBoxManage createhd --filename "WinXP.vdi" --size 10000</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Add an IDE Controller to the new VM. For example:
+          </para>
+
+<screen>VBoxManage storagectl "Windows XP" --name "IDE Controller"
+      --add ide --controller PIIX4</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Set the VDI file you created as the first virtual hard disk
+            of the new VM. For example:
+          </para>
+
+<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
+      --port 0 --device 0 --type hdd --medium "WinXP.vdi"</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Attach the ISO file that contains the operating system
+            installation that you want to install later to the virtual
+            machine. This is done so that the VM can boot from it.
+          </para>
+
+<screen>VBoxManage storageattach "Windows XP" --storagectl "IDE Controller"
+      --port 0 --device 1 --type dvddrive --medium /full/path/to/iso.iso</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Enable the VirtualBox Remote Desktop Extension, the VRDP
+            server, as follows:
+          </para>
+
+<screen>VBoxManage modifyvm "Windows XP" --vrde on</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            Start the virtual machine using the
+            <computeroutput>VBoxHeadless</computeroutput> command:
+          </para>
+
+<screen>VBoxHeadless --startvm "Windows XP"</screen>
+
+          <para>
+            If the configuration steps worked, you should see a
+            copyright notice. If you are returned to the command line,
+            then something did not work correctly.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            On the client machine, start the RDP viewer and connect to
+            the server. See <xref linkend="rdp-viewers" /> for details
+            of how to use various common RDP viewers.
+          </para>
+
+          <para>
+            The installation routine of your guest operating system
+            should be displayed in the RDP viewer.
+          </para>
+        </listitem>
+
+      </orderedlist>
+
+    </sect2>
+
+    <sect2 id="usb-over-rdp">
+
+      <title>Remote USB</title>
+
+      <para>
+        As a special feature additional to the VRDP support, VirtualBox
+        also supports remote USB devices over the wire. That is, the
+        VirtualBox guest that runs on one computer can access the USB
+        devices of the remote computer on which the VRDP data is being
+        displayed the same way as USB devices that are connected to the
+        actual host. This allows for running virtual machines on a
+        VirtualBox host that acts as a server, where a client can
+        connect from elsewhere that needs only a network adapter and a
+        display capable of running an RDP viewer. When USB devices are
+        plugged into the client, the remote VirtualBox server can access
+        them.
+      </para>
+
+      <para>
+        For these remote USB devices, the same filter rules apply as for
+        other USB devices. See <xref linkend="settings-usb" />. All you
+        have to do is specify Remote, or Any, when setting up these
+        rules.
+      </para>
+
+      <para>
+        Accessing remote USB devices is only possible if the RDP client
+        supports this extension. On Linux and Solaris hosts, the
+        VirtualBox installation provides a suitable VRDP client called
+        <computeroutput>rdesktop-vrdp</computeroutput>. Recent versions
+        of <computeroutput>uttsc</computeroutput>, a client tailored for
+        the use with Sun Ray thin clients, also support accessing remote
+        USB devices. RDP clients for other platforms will be provided in
+        future VirtualBox versions.
+      </para>
+
+      <para>
+        To make a remote USB device available to a VM,
+        <computeroutput>rdesktop-vrdp</computeroutput> should be started
+        as follows:
+
+<screen>rdesktop-vrdp -r usb -a 16 -N my.host.address</screen>
+
+        Please refer to <xref linkend="ts_usb-linux" /> for further
+        details on how to properly set up the permissions for USB
+        devices. Furthermore it is advisable to disable automatic
+        loading of any host driver on the remote host which might work
+        on USB devices to ensure that the devices are accessible by the
+        RDP client. If the setup was properly done on the remote host,
+        plug/unplug events are visible on the VBox.log file of the VM.
+      </para>
+
+    </sect2>
+
+    <sect2 id="vbox-auth">
+
+      <title>RDP Authentication</title>
+
+      <para>
+        For each virtual machine that is remotely accessible via RDP,
+        you can individually determine if and how client connections are
+        authenticated. For this, use <computeroutput>VBoxManage
+        modifyvm</computeroutput> command with the
+        <computeroutput>--vrdeauthtype</computeroutput> option. See
+        <xref
+      linkend="vboxmanage-modifyvm" />. The following
+        methods of authentication are available:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            The <emphasis role="bold">null</emphasis> method means that
+            there is no authentication at all. Any client can connect to
+            the VRDP server and thus the virtual machine. This is very
+            insecure and only to be recommended for private networks.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            The <emphasis role="bold">external</emphasis> method
+            provides external authentication through a special
+            authentication library. VirtualBox ships with two special
+            authentication libraries:
+          </para>
+
+          <orderedlist>
+
+            <listitem>
+              <para>
+                The default authentication library,
+                <computeroutput>VBoxAuth</computeroutput>, authenticates
+                against user credentials of the hosts. Depending on the
+                host platform, this means the following:
+              </para>
+
+              <itemizedlist>
+
+                <listitem>
+                  <para>
+                    On Linux hosts,
+                    <computeroutput>VBoxAuth.so</computeroutput>
+                    authenticates users against the host's PAM system.
+                  </para>
                 </listitem>
-            </itemizedlist>
-            For example the following command allows a client to use either Standard
-            or Enhanced RDP Security connection:
-            <screen>vboxmanage modifyvm "VM name" --vrdeproperty "Security/Method=negotiate"</screen>
-            </para>
-
-            <para>If the <computeroutput>Security/Method</computeroutput> property is
-            set to either <computeroutput>Negotiate</computeroutput> or
-            <computeroutput>TLS</computeroutput>, the TLS protocol will be automatically
-            used by the server, if the client supports TLS. However, in order to use TLS
-            the server must possess the Server Certificate, the Server Private Key and the
-            Certificate Authority (CA) Certificate. The following example shows how to
-            generate a server certificate.<orderedlist>
+
                 <listitem>
-                <para>Create a CA self signed certificate:
-                <screen>openssl req -new -x509 -days 365 -extensions v3_ca \
-  -keyout ca_key_private.pem -out ca_cert.pem</screen></para>
+                  <para>
+                    On Windows hosts,
+                    <computeroutput>VBoxAuth.dll</computeroutput>
+                    authenticates users against the host's WinLogon
+                    system.
+                  </para>
                 </listitem>
 
                 <listitem>
-                <para>Generate a server private key and a request for signing:
-                <screen>openssl genrsa -out server_key_private.pem
-openssl req -new -key server_key_private.pem -out server_req.pem</screen></para>
+                  <para>
+                    On Mac OS X hosts,
+                    <computeroutput>VBoxAuth.dylib</computeroutput>
+                    authenticates users against the host's directory
+                    service.
+
+                    <footnote>
+
+                      <para>
+                        Support for Mac OS X was added in version 3.2.
+                      </para>
+
+                    </footnote>
+                  </para>
                 </listitem>
 
+              </itemizedlist>
+
+              <para>
+                In other words, the external method by default performs
+                authentication with the user accounts that exist on the
+                host system. Any user with valid authentication
+                credentials is accepted. For example, the username does
+                not have to correspond to the user running the VM.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                An additional library called
+                <computeroutput>VBoxAuthSimple</computeroutput> performs
+                authentication against credentials configured in the
+                "extradata" section of a virtual machine's XML settings
+                file. This is probably the simplest way to get
+                authentication that does not depend on a running and
+                supported guest. The following steps are required:
+              </para>
+
+              <orderedlist>
+
                 <listitem>
-                <para>Generate the server certificate:
-                <screen>openssl x509 -req -days 365 -in server_req.pem \
-  -CA ca_cert.pem -CAkey ca_key_private.pem -set_serial 01 -out server_cert.pem</screen></para>
+                  <para>
+                    Enable
+                    <computeroutput>VBoxAuthSimple</computeroutput> with
+                    the following command:
+                  </para>
+
+<screen>VBoxManage setproperty vrdeauthlibrary "VBoxAuthSimple"</screen>
                 </listitem>
-            </orderedlist>
-            The server must be configured to access the required files:
-            <screen>vboxmanage modifyvm "VM name" \
+
+                <listitem>
+                  <para>
+                    To enable the library for a particular VM, you must
+                    switch authentication to external, as follows:
+                  </para>
+
+<screen>VBoxManage modifyvm "VM name" --vrdeauthtype external</screen>
+
+                  <para>
+                    Replace <computeroutput>&lt;vm&gt;</computeroutput>
+                    with the VM name or UUID.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    You then need to configure users and passwords by
+                    writing items into the machine's extradata. Since
+                    the XML machine settings file, into whose
+                    <computeroutput>extradata</computeroutput> section
+                    the password needs to be written, is a plain text
+                    file, VirtualBox uses hashes to encrypt passwords.
+                    The following command must be used:
+                  </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxAuthSimple/users/&lt;user&gt;" &lt;hash&gt;</screen>
+
+                  <para>
+                    Replace <computeroutput>&lt;vm&gt;</computeroutput>
+                    with the VM name or UUID,
+                    <computeroutput>&lt;user&gt;</computeroutput> with
+                    the user name who should be allowed to log in and
+                    <computeroutput>&lt;hash&gt;</computeroutput> with
+                    the encrypted password. As an example, to obtain the
+                    hash value for the password
+                    <computeroutput>secret</computeroutput>, you can use
+                    the following command:
+                  </para>
+
+<screen>VBoxManage internalcommands passwordhash "secret"</screen>
+
+                  <para>
+                    This command will generate output similar to the
+                    following:
+                  </para>
+
+<screen>2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen>
+
+                  <para>
+                    You then use VBoxManage setextradata to store this
+                    value in the machine's
+                    <computeroutput>extradata</computeroutput> section.
+                  </para>
+
+                  <para>
+                    As a combined example, to set the password for the
+                    user <computeroutput>john</computeroutput> and the
+                    machine <computeroutput>My VM</computeroutput> to
+                    <computeroutput>secret</computeroutput>, use this
+                    command:
+                  </para>
+
+<screen>VBoxManage setextradata "My VM" "VBoxAuthSimple/users/john"
+    2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b</screen>
+                </listitem>
+
+              </orderedlist>
+            </listitem>
+
+          </orderedlist>
+        </listitem>
+
+        <listitem>
+          <para>
+            The <emphasis role="bold">guest</emphasis> authentication
+            method performs authentication with a special component that
+            comes with the Guest Additions. As a result, authentication
+            is not performed on the host, but with the guest user
+            accounts.
+          </para>
+
+          <para>
+            This method is currently still in testing and not yet
+            supported.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        In addition to the methods described above, you can replace the
+        default external authentication module with any other module.
+        For this, VirtualBox provides a well-defined interface that
+        allows you to write your own authentication module. This is
+        described in detail in the VirtualBox Software Development Kit
+        (SDK) reference. See <xref
+      linkend="VirtualBoxAPI" />.
+      </para>
+
+    </sect2>
+
+    <sect2 id="vrde-crypt">
+
+      <title>RDP Encryption</title>
+
+      <para>
+        RDP features data stream encryption, which is based on the RC4
+        symmetric cipher, with keys up to 128-bit. The RC4 keys are
+        replaced at regular intervals, every 4096 packets.
+      </para>
+
+      <para>
+        RDP provides the following different authentication methods:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">RDP4</emphasis> authentication was
+            used historically. With RDP4, the RDP client does not
+            perform any checks in order to verify the identity of the
+            server it connects to. Since user credentials can be
+            obtained using a "man in the middle" (MITM) attack, RDP4
+            authentication is insecure and should generally not be used.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">RDP5.1</emphasis> authentication
+            employs a server certificate for which the client possesses
+            the public key. This way it is guaranteed that the server
+            possess the corresponding private key. However, as this
+            hard-coded private key became public some years ago, RDP5.1
+            authentication is also insecure.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">RDP5.2</emphasis> authentication uses
+            Enhanced RDP Security, which means that an external security
+            protocol is used to secure the connection. RDP4 and RDP5.1
+            use Standard RDP Security. The VRDP server supports Enhanced
+            RDP Security with TLS protocol and, as a part of TLS
+            handshake, sends the server certificate to the client.
+          </para>
+
+          <para>
+            The <computeroutput>Security/Method</computeroutput> VRDE
+            property sets the desired security method, which is used for
+            a connection. Valid values are as follows:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <emphasis role="bold">Negotiate.</emphasis> Both
+                Enhanced (TLS) and Standard RDP Security connections are
+                allowed. The security method is negotiated with the
+                client. This is the default setting.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <emphasis role="bold">RDP.</emphasis> Only Standard RDP
+                Security is accepted.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <emphasis role="bold">TLS.</emphasis> Only Enhanced RDP
+                Security is accepted. The client must support TLS.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
+          <para>
+            For example, the following command allows a client to use
+            either Standard or Enhanced RDP Security connection:
+          </para>
+
+<screen>vboxmanage modifyvm "VM name" --vrdeproperty "Security/Method=negotiate"</screen>
+
+          <para>
+            If the <computeroutput>Security/Method</computeroutput>
+            property is set to either Negotiate or TLS, the TLS protocol
+            will be automatically used by the server, if the client
+            supports TLS. However, in order to use TLS the server must
+            possess the Server Certificate, the Server Private Key and
+            the Certificate Authority (CA) Certificate. The following
+            example shows how to generate a server certificate.
+          </para>
+
+          <orderedlist>
+
+            <listitem>
+              <para>
+                Create a CA self signed certificate.
+              </para>
+
+<screen>openssl req -new -x509 -days 365 -extensions v3_ca \
+  -keyout ca_key_private.pem -out ca_cert.pem</screen>
+            </listitem>
+
+            <listitem>
+              <para>
+                Generate a server private key and a request for signing.
+              </para>
+
+<screen>openssl genrsa -out server_key_private.pem
+openssl req -new -key server_key_private.pem -out server_req.pem</screen>
+            </listitem>
+
+            <listitem>
+              <para>
+                Generate the server certificate.
+              </para>
+
+<screen>openssl x509 -req -days 365 -in server_req.pem \
+  -CA ca_cert.pem -CAkey ca_key_private.pem -set_serial 01 -out server_cert.pem</screen>
+            </listitem>
+
+          </orderedlist>
+
+          <para>
+            The server must be configured to access the required files.
+            For example:
+          </para>
+
+<screen>vboxmanage modifyvm "VM name" \
   --vrdeproperty "Security/CACertificate=path/ca_cert.pem"</screen>
-            <screen>vboxmanage modifyvm "VM name" \
+
+<screen>vboxmanage modifyvm "VM name" \
   --vrdeproperty "Security/ServerCertificate=path/server_cert.pem"</screen>
-            <screen>vboxmanage modifyvm "VM name" \
+
+<screen>vboxmanage modifyvm "VM name" \
   --vrdeproperty "Security/ServerPrivateKey=path/server_key_private.pem"</screen>
-            </para>
-          </listitem>
-        </orderedlist></para>
-
-      <para>As the client that connects to the server determines what type
-      of encryption will be used, with rdesktop, the Linux RDP viewer, use the
-      <computeroutput>-4</computeroutput> or
-      <computeroutput>-5</computeroutput> options.</para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        As the client that connects to the server determines what type
+        of encryption will be used, with rdesktop, the Linux RDP viewer,
+        use the <computeroutput>-4</computeroutput> or
+        <computeroutput>-5</computeroutput> options.
+      </para>
+
     </sect2>
 
     <sect2 id="vrde-multiconnection">
-      <title>Multiple connections to the VRDP server</title>
-
-      <para>The VRDP server of VirtualBox supports multiple simultaneous
-      connections to the same running VM from different clients. All connected
-      clients see the same screen output and share a mouse pointer and
-      keyboard focus. This is similar to several people using the same
-      computer at the same time, taking turns at the keyboard.</para>
-
-      <para>The following command enables multiple connection mode: <screen>VBoxManage modifyvm "VM name" --vrdemulticon on</screen></para>
+
+      <title>Multiple Connections to the VRDP Server</title>
+
+      <para>
+        The VRDP server of VirtualBox supports multiple simultaneous
+        connections to the same running VM from different clients. All
+        connected clients see the same screen output and share a mouse
+        pointer and keyboard focus. This is similar to several people
+        using the same computer at the same time, taking turns at the
+        keyboard.
+      </para>
+
+      <para>
+        The following command enables multiple connection mode:
+
+<screen>VBoxManage modifyvm "VM name" --vrdemulticon on</screen>
+      </para>
+
     </sect2>
 
     <sect2 id="vrde-multimonitor">
-      <title>Multiple remote monitors</title>
-
-      <para>To access two or more remote VM displays you have to enable the
-      VRDP multiconnection mode (see <xref
-      linkend="vrde-multiconnection" />).</para>
-
-      <para>The RDP client can select the virtual monitor number to connect to
-      using the <computeroutput>domain</computeroutput> logon parameter
-      (<computeroutput>-d</computeroutput>). If the parameter ends with
-      <computeroutput>@</computeroutput> followed by a number, VirtualBox
-      interprets this number as the screen index. The primary guest screen is
-      selected with <computeroutput>@1</computeroutput>, the first secondary
-      screen is <computeroutput>@2</computeroutput>, etc.</para>
-
-      <para>The Microsoft RDP6 client does not let you specify a separate
-      domain name. Instead, use
-      <computeroutput>domain\username</computeroutput> in the
-      <computeroutput>Username:</computeroutput> field -- for example,
-      <computeroutput>@2\name</computeroutput>.
-      <computeroutput>name</computeroutput> must be supplied, and must be the
-      name used to log in if the VRDP server is set up to require credentials.
-      If it is not, you may use any text as the username.</para>
+
+      <title>Multiple Remote Monitors</title>
+
+      <para>
+        To access two or more remote VM displays you have to enable the
+        VRDP multiconnection mode. See
+        <xref
+      linkend="vrde-multiconnection" />.
+      </para>
+
+      <para>
+        The RDP client can select the virtual monitor number to connect
+        to using the <computeroutput>domain</computeroutput> logon
+        parameter (<computeroutput>-d</computeroutput>). If the
+        parameter ends with <computeroutput>@</computeroutput> followed
+        by a number, VirtualBox interprets this number as the screen
+        index. The primary guest screen is selected with
+        <computeroutput>@1</computeroutput>, the first secondary screen
+        is <computeroutput>@2</computeroutput>, and so on.
+      </para>
+
+      <para>
+        The Microsoft RDP6 client does not let you specify a separate
+        domain name. Instead, use
+        <computeroutput>domain\username</computeroutput> in the
+        <computeroutput>Username:</computeroutput> field. For example,
+        <computeroutput>@2\name</computeroutput>.
+        <computeroutput>name</computeroutput> must be supplied, and must
+        be the name used to log in if the VRDP server is set up to
+        require credentials. If it is not, you may use any text as the
+        username.
+      </para>
+
     </sect2>
 
     <sect2 id="vrde-videochannel">
-      <title>VRDP video redirection</title>
-
-      <para>Starting with VirtualBox 3.2, the VRDP server can redirect video
-      streams from the guest to the RDP client. Video frames are compressed
-      using the JPEG algorithm allowing a higher compression ratio than
-      standard RDP bitmap compression methods. It is possible to increase the
-      compression ratio by lowering the video quality.</para>
-
-      <para>The VRDP server automatically detects video streams in a guest as
-      frequently updated rectangular areas. As a result, this method works
-      with any guest operating system without having to install additional
-      software in the guest; in particular, the Guest Additions are not
-      required.</para>
-
-      <para>On the client side, however, currently only the Windows 7 Remote
-      Desktop Connection client supports this feature. If a client does not
-      support video redirection, the VRDP server falls back to regular bitmap
-      updates.</para>
-
-      <para>The following command enables video redirection: <screen>VBoxManage modifyvm "VM name" --vrdevideochannel on</screen></para>
-
-      <para>The quality of the video is defined as a value from 10 to 100
-      percent, representing a JPEG compression level (where lower numbers mean
-      lower quality but higher compression). The quality can be changed using
-      the following command: <screen>VBoxManage modifyvm "VM name" --vrdevideochannelquality 75</screen></para>
+
+      <title>VRDP Video Redirection</title>
+
+      <para>
+        Starting with VirtualBox 3.2, the VRDP server can redirect video
+        streams from the guest to the RDP client. Video frames are
+        compressed using the JPEG algorithm allowing a higher
+        compression ratio than standard RDP bitmap compression methods.
+        It is possible to increase the compression ratio by lowering the
+        video quality.
+      </para>
+
+      <para>
+        The VRDP server automatically detects video streams in a guest
+        as frequently updated rectangular areas. As a result, this
+        method works with any guest operating system without having to
+        install additional software in the guest. In particular, the
+        Guest Additions are not required.
+      </para>
+
+      <para>
+        On the client side, however, currently only the Windows 7 Remote
+        Desktop Connection client supports this feature. If a client
+        does not support video redirection, the VRDP server falls back
+        to regular bitmap updates.
+      </para>
+
+      <para>
+        The following command enables video redirection:
+
+<screen>VBoxManage modifyvm "VM name" --vrdevideochannel on</screen>
+      </para>
+
+      <para>
+        The quality of the video is defined as a value from 10 to 100
+        percent, representing a JPEG compression level, where lower
+        numbers mean lower quality but higher compression. The quality
+        can be changed using the following command:
+
+<screen>VBoxManage modifyvm "VM name" --vrdevideochannelquality 75</screen>
+      </para>
+
     </sect2>
 
     <sect2 id="vrde-customization">
-      <title>VRDP customization</title>
-
-      <para>With VirtualBox 4.0 it is possible to disable display output,
-      mouse and keyboard input, audio, remote USB or clipboard individually in
-      the VRDP server.</para>
-
-      <para>The following commands change corresponding server
-      settings:</para>
-
-      <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=1
+
+      <title>VRDP Customization</title>
+
+      <para>
+        With VirtualBox 4.0 it is possible to disable display output,
+        mouse and keyboard input, audio, remote USB, or clipboard
+        individually in the VRDP server.
+      </para>
+
+      <para>
+        The following commands change corresponding server settings:
+      </para>
+
+<screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=1
 VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableInput=1
 VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUSB=1
@@ -698,12 +1076,18 @@
 VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableUpstreamAudio=1</screen>
 
-      <para>To reenable a feature use a similar command without the trailing
-      1. For example: <screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=</screen></para>
-
-      <para>These properties were introduced with VirtualBox 3.2.10. However,
-      in the 3.2.x series, it was necessary to use the following commands to
-      alter these settings instead:</para>
-
-      <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1
+      <para>
+        To reenable a feature use a similar command without the trailing
+        1. For example:
+
+<screen>VBoxManage modifyvm "VM name" --vrdeproperty Client/DisableDisplay=</screen>
+      </para>
+
+      <para>
+        These properties were introduced with VirtualBox 3.2.10.
+        However, in the 3.2.x series, it was necessary to use the
+        following commands to alter these settings instead:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay" 1
 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableInput" 1
 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableUSB" 1
@@ -711,106 +1095,165 @@
 VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableClipboard" 1</screen>
 
-      <para>To reenable a feature use a similar command without the trailing
-      1. For example: <screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen></para>
+      <para>
+        To reenable a feature use a similar command without the trailing
+        1. For example:
+
+<screen>VBoxManage setextradata "VM name" "VRDP/Feature/Client/DisableDisplay"</screen>
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="teleporting">
+
     <title>Teleporting</title>
 
-    <para>Starting with version 3.1, VirtualBox supports "teleporting" -- that
-    is, moving a virtual machine over a network from one VirtualBox host to
-    another, while the virtual machine is running. This works regardless of
-    the host operating system that is running on the hosts: you can teleport
-    virtual machines between Solaris and Mac hosts, for example.</para>
-
-    <para>Teleporting requires that a machine be currently running on one
-    host, which is then called the <emphasis role="bold">"source"</emphasis>.
-    The host to which the virtual machine will be teleported will then be
-    called the <emphasis role="bold">"target"</emphasis>; the machine on the
-    target is then configured to wait for the source to contact the target.
-    The machine's running state will then be transferred from the source to
-    the target with minimal downtime.</para>
-
-    <para>Teleporting happens over any TCP/IP network; the source and the
-    target only need to agree on a TCP/IP port which is specified in the
-    teleporting settings.</para>
-
-    <para>At this time, there are a few prerequisites for this to work,
-    however:<orderedlist>
-        <listitem>
-          <para>On the target host, you must configure a virtual machine in
-          VirtualBox with exactly the same hardware settings as the machine on
-          the source that you want to teleport. This does not apply to
-          settings which are merely descriptive, such as the VM name, but
-          obviously for teleporting to work, the target machine must have the
-          same amount of memory and other hardware settings. Otherwise
-          teleporting will fail with an error message.</para>
-        </listitem>
-
-        <listitem>
-          <para>The two virtual machines on the source and the target must
-          share the same storage (hard disks as well as floppy and CD/DVD
-          images). This means that they either use the same iSCSI targets or
-          that the storage resides somewhere on the network and both hosts
-          have access to it via NFS or SMB/CIFS.</para>
-
-          <para>This also means that neither the source nor the target machine
-          can have any snapshots.</para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>Then perform the following steps:<orderedlist>
-        <listitem>
-          <para>On the <emphasis>target</emphasis> host, configure the virtual
-          machine to wait for a teleport request to arrive when it is started,
-          instead of actually attempting to start the machine. This is done
-          with the following VBoxManage command:<screen>VBoxManage modifyvm &lt;targetvmname&gt; --teleporter on --teleporterport &lt;port&gt;</screen></para>
-
-          <para>where <computeroutput>&lt;targetvmname&gt;</computeroutput> is
+    <para>
+      Starting with version 3.1, VirtualBox supports
+      <emphasis>teleporting</emphasis>. Teleporting is moving a virtual
+      machine over a network from one VirtualBox host to another, while
+      the virtual machine is running. This works regardless of the host
+      operating system that is running on the hosts. You can teleport
+      virtual machines between Solaris and Mac hosts, for example.
+    </para>
+
+    <para>
+      Teleporting requires that a machine be currently running on one
+      host, which is called the <emphasis>source</emphasis>. The host to
+      which the virtual machine will be teleported is called the
+      <emphasis>target</emphasis>. The machine on the target is then
+      configured to wait for the source to contact the target. The
+      machine's running state will then be transferred from the source
+      to the target with minimal downtime.
+    </para>
+
+    <para>
+      Teleporting happens over any TCP/IP network. The source and the
+      target only need to agree on a TCP/IP port which is specified in
+      the teleporting settings.
+    </para>
+
+    <para>
+      At this time, there are a few prerequisites for this to work, as
+      follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          On the target host, you must configure a virtual machine in
+          VirtualBox with exactly the same hardware settings as the
+          machine on the source that you want to teleport. This does not
+          apply to settings which are merely descriptive, such as the VM
+          name, but obviously for teleporting to work, the target
+          machine must have the same amount of memory and other hardware
+          settings. Otherwise teleporting will fail with an error
+          message.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The two virtual machines on the source and the target must
+          share the same storage, hard disks as well as floppy disks and
+          CD/DVD images. This means that they either use the same iSCSI
+          targets or that the storage resides somewhere on the network
+          and both hosts have access to it via NFS or SMB/CIFS.
+        </para>
+
+        <para>
+          This also means that neither the source nor the target machine
+          can have any snapshots.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      To configure teleporting, perform the following steps:
+    </para>
+
+    <orderedlist>
+
+      <listitem>
+        <para>
+          On the <emphasis>target</emphasis> host, configure the virtual
+          machine to wait for a teleport request to arrive when it is
+          started, instead of actually attempting to start the machine.
+          This is done with the following VBoxManage command:
+        </para>
+
+<screen>VBoxManage modifyvm &lt;targetvmname&gt; --teleporter on --teleporterport &lt;port&gt;</screen>
+
+        <para>
+          where <computeroutput>&lt;targetvmname&gt;</computeroutput> is
           the name of the virtual machine on the target host and
           <computeroutput>&lt;port&gt;</computeroutput> is a TCP/IP port
           number to be used on both the source and the target hosts. For
-          example, use 6000. For details, see <xref
-          linkend="vboxmanage-modifyvm-teleport" />.</para>
-        </listitem>
-
-        <listitem>
-          <para>Start the VM on the target host. You will see that instead of
-          actually running, it will show a progress dialog. indicating that it
-          is waiting for a teleport request to arrive.</para>
-        </listitem>
-
-        <listitem>
-          <para>Start the machine on the <emphasis>source</emphasis> host as
-          usual. When it is running and you want it to be teleported, issue
-          the following command on the source host:<screen>VBoxManage controlvm &lt;sourcevmname&gt; teleport --host &lt;targethost&gt; --port &lt;port&gt;</screen></para>
-
-          <para>where <computeroutput>&lt;sourcevmname&gt;</computeroutput> is
-          the name of the virtual machine on the source host (the machine that
-          is currently running),
-          <computeroutput>&lt;targethost&gt;</computeroutput> is the host or
-          IP name of the target host on which the machine is waiting for the
-          teleport request, and <computeroutput>&lt;port&gt;</computeroutput>
-          must be the same number as specified in the command on the target
-          host. For details, see <xref
-          linkend="vboxmanage-controlvm" />.</para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>For testing, you can also teleport machines on the same host; in
-    that case, use "localhost" as the hostname on both the source and the
-    target host.<note>
-        <para>In rare cases, if the CPUs of the source and the target are very
-        different, teleporting can fail with an error message, or the target
-        may hang. This may happen especially if the VM is running application
-        software that is highly optimized to run on a particular CPU without
-        correctly checking that certain CPU features are actually present.
-        VirtualBox filters what CPU capabilities are presented to the guest
-        operating system. Advanced users can attempt to restrict these virtual
-        CPU capabilities with the <computeroutput>VBoxManage --modifyvm
-        --cpuid</computeroutput> command; see <xref
-        linkend="vboxmanage-modifyvm-teleport" />.</para>
-      </note></para>
+          example, use 6000. See
+          <xref
+          linkend="vboxmanage-modifyvm-teleport" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Start the VM on the target host. Instead of running, the VM
+          shows a progress dialog, indicating that it is waiting for a
+          teleport request to arrive.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Start the VM on the <emphasis>source</emphasis> host as usual.
+          When it is running and you want it to be teleported, issue the
+          following command on the source host:
+        </para>
+
+<screen>VBoxManage controlvm &lt;sourcevmname&gt; teleport --host &lt;targethost&gt; --port &lt;port&gt;</screen>
+
+        <para>
+          where <computeroutput>&lt;sourcevmname&gt;</computeroutput> is
+          the name of the virtual machine on the source host (the
+          machine that is currently running),
+          <computeroutput>&lt;targethost&gt;</computeroutput> is the
+          host or IP name of the target host on which the machine is
+          waiting for the teleport request, and
+          <computeroutput>&lt;port&gt;</computeroutput> must be the same
+          number as specified in the command on the target host. See
+          <xref
+          linkend="vboxmanage-controlvm" />.
+        </para>
+      </listitem>
+
+    </orderedlist>
+
+    <para>
+      For testing, you can also teleport machines on the same host. In
+      that case, use localhost as the hostname on both the source and
+      the target host.
+    </para>
+
+    <note>
+      <para>
+        In rare cases, if the CPUs of the source and the target are very
+        different, teleporting can fail with an error message, or the
+        target may hang. This may happen especially if the VM is running
+        application software that is highly optimized to run on a
+        particular CPU without correctly checking that certain CPU
+        features are actually present. VirtualBox filters what CPU
+        capabilities are presented to the guest operating system.
+        Advanced users can attempt to restrict these virtual CPU
+        capabilities with the <computeroutput>VBoxManage --modifyvm
+        --cpuid</computeroutput> command. See
+        <xref
+        linkend="vboxmanage-modifyvm-teleport" />.
+      </para>
+    </note>
+
   </sect1>
+
 </chapter>
Index: /trunk/doc/manual/en_US/user_Glossary.xml
===================================================================
--- /trunk/doc/manual/en_US/user_Glossary.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_Glossary.xml	(revision 73276)
@@ -1,495 +1,702 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <glossary id="Glossary">
-  <glossdiv>
+
+  <glossdiv>
+
     <title>A</title>
 
-    <glossentry>
-      <glossterm>ACPI</glossterm>
-
-      <glossdef>
-        <para>Advanced Configuration and Power Interface, an industry
-        specification for BIOS and hardware extensions to configure PC
-        hardware and perform power management. Windows 2000 and higher as well
-        as Linux 2.4 and higher support ACPI. Windows can only enable or
-        disable ACPI support at installation time.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>AHCI</glossterm>
-
-      <glossdef>
-        <para>Advanced Host Controller Interface, the interface that supports
-        SATA devices such as hard disks. See <xref
-        linkend="harddiskcontrollers" />.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>AMD-V</glossterm>
-
-      <glossdef>
-        <para>The hardware virtualization features built into modern AMD
-        processors. See <xref linkend="hwvirt" />.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>API</glossterm>
-
-      <glossdef>
-        <para>Application Programming Interface.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>APIC</glossterm>
-
-      <glossdef>
-        <para>Advanced Programmable Interrupt Controller, a newer version of
-        the original PC PIC (programmable interrupt controller). Most modern
-        CPUs contain an on-chip APIC ("local APIC"). Many systems also contain
-        an I/O APIC (input output APIC) as a separate chip which provides more
-        than 16 IRQs. Windows 2000 and higher use a different kernel if they
-        detect an I/O APIC during installation. Therefore an I/O APIC must not
-        be removed after installation.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>ATA</glossterm>
-
-      <glossdef>
-        <para>Advanced Technology Attachment, an industry standard for hard
-        disk interfaces (synonymous with IDE). See <xref
-        linkend="harddiskcontrollers" />.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>ACPI</glossterm>
+
+      <glossdef>
+
+        <para>
+          Advanced Configuration and Power Interface, an industry
+          specification for BIOS and hardware extensions to configure PC
+          hardware and perform power management. Windows 2000 and higher
+          as well as Linux 2.4 and higher support ACPI. Windows can only
+          enable or disable ACPI support at installation time.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>AHCI</glossterm>
+
+      <glossdef>
+
+        <para>
+          Advanced Host Controller Interface, the interface that
+          supports SATA devices such as hard disks. See
+          <xref
+        linkend="harddiskcontrollers" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>AMD-V</glossterm>
+
+      <glossdef>
+
+        <para>
+          The hardware virtualization features built into modern AMD
+          processors. See <xref linkend="hwvirt" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>API</glossterm>
+
+      <glossdef>
+
+        <para>
+          Application Programming Interface.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>APIC</glossterm>
+
+      <glossdef>
+
+        <para>
+          Advanced Programmable Interrupt Controller, a newer version of
+          the original PC PIC (programmable interrupt controller). Most
+          modern CPUs contain an on-chip APIC, called a local APIC. Many
+          systems also contain an I/O APIC (input output APIC) as a
+          separate chip which provides more than 16 IRQs. Windows 2000
+          and higher use a different kernel if they detect an I/O APIC
+          during installation. Therefore an I/O APIC must not be removed
+          after installation.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>ATA</glossterm>
+
+      <glossdef>
+
+        <para>
+          Advanced Technology Attachment, an industry standard for hard
+          disk interfaces which is synonymous with IDE. See
+          <xref
+        linkend="harddiskcontrollers" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>B</title>
 
-    <glossentry>
-      <glossterm>BIOS</glossterm>
-
-      <glossdef>
-        <para>Basic Input/Output System, the firmware built into most personal
-        computers which is responsible of initializing the hardware after the
-        computer has been turned on and then booting an operating system.
-        VirtualBox ships with its own virtual BIOS that runs when a virtual
-        machine is started.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>BIOS</glossterm>
+
+      <glossdef>
+
+        <para>
+          Basic Input/Output System, the firmware built into most
+          personal computers which is responsible of initializing the
+          hardware after the computer has been turned on and then
+          booting an operating system. VirtualBox ships with its own
+          virtual BIOS that runs when a virtual machine is started.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>C</title>
 
-    <glossentry>
-      <glossterm>COM</glossterm>
-
-      <glossdef>
-        <para>Microsoft Component Object Model, a programming infrastructure
-        for modular software. COM allows applications to provide application
-        programming interfaces which can be accessed from various other
-        programming languages and applications. VirtualBox makes use of COM
-        both internally and externally to provide a comprehensive API to 3rd
-        party developers.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>COM</glossterm>
+
+      <glossdef>
+
+        <para>
+          Microsoft Component Object Model, a programming infrastructure
+          for modular software. COM allows applications to provide
+          application programming interfaces which can be accessed from
+          various other programming languages and applications.
+          VirtualBox makes use of COM both internally and externally to
+          provide a comprehensive API to 3rd party developers.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>D</title>
 
-    <glossentry>
-      <glossterm>DHCP</glossterm>
-
-      <glossdef>
-        <para>Dynamic Host Configuration Protocol. This allows a networking
-        device in a network to acquire its IP address (and other networking
-        details) automatically, in order to avoid having to configure all
-        devices in a network with fixed IP addresses. VirtualBox has a
-        built-in DHCP server that delivers an IP addresses to a virtual
-        machine when networking is configured to NAT; see <xref
-        linkend="networkingdetails" />.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>DHCP</glossterm>
+
+      <glossdef>
+
+        <para>
+          Dynamic Host Configuration Protocol. This allows a networking
+          device in a network to acquire its IP address and other
+          networking details automatically, in order to avoid having to
+          configure all devices in a network with fixed IP addresses.
+          VirtualBox has a built-in DHCP server that delivers an IP
+          addresses to a virtual machine when networking is configured
+          to NAT. See <xref
+        linkend="networkingdetails" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>E</title>
 
-    <glossentry>
-      <glossterm>EFI</glossterm>
-
-      <glossdef>
-        <para>Extensible Firmware Interface, a firmware built into computers
-        which is designed to replace the aging BIOS. Originally designed by
-        Intel, most modern operating systems can now boot on computers which
-        have EFI instead of a BIOS built into them; see <xref
-        linkend="efi" />.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>EHCI</glossterm>
-
-      <glossdef>
-        <para>Enhanced Host Controller Interface, the interface that
-        implements the USB 2.0 standard.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>EFI</glossterm>
+
+      <glossdef>
+
+        <para>
+          Extensible Firmware Interface, a firmware built into computers
+          which is designed to replace the aging BIOS. Originally
+          designed by Intel, most modern operating systems can now boot
+          on computers which have EFI instead of a BIOS built into them.
+          See <xref
+        linkend="efi" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>EHCI</glossterm>
+
+      <glossdef>
+
+        <para>
+          Enhanced Host Controller Interface, the interface that
+          implements the USB 2.0 standard.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>G</title>
 
-    <glossentry>
-      <glossterm>GUI</glossterm>
-
-      <glossdef>
-        <para>Graphical User Interface. Commonly used as an antonym to a
-        "command line interface", in the context of VirtualBox, we sometimes
-        refer to the main graphical
-        <computeroutput>VirtualBox</computeroutput> program as the "GUI", to
-        differentiate it from the <computeroutput>VBoxManage</computeroutput>
-        interface.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>GUID</glossterm>
-
-      <glossdef>
-        <para>See UUID.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>GUI</glossterm>
+
+      <glossdef>
+
+        <para>
+          Graphical User Interface. Commonly used as an antonym to a
+          "command line interface". In the context of VirtualBox, we
+          sometimes refer to the main graphical
+          <computeroutput>VirtualBox</computeroutput> program as the
+          "GUI", to differentiate it from the
+          <computeroutput>VBoxManage</computeroutput> interface.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>GUID</glossterm>
+
+      <glossdef>
+
+        <para>
+          See UUID.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>I</title>
 
-    <glossentry>
-      <glossterm>IDE</glossterm>
-
-      <glossdef>
-        <para>Integrated Drive Electronics, an industry standard for hard disk
-        interfaces. See <xref linkend="harddiskcontrollers" />.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>I/O APIC</glossterm>
-
-      <glossdef>
-        <para>See APIC.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>iSCSI</glossterm>
-
-      <glossdef>
-        <para>Internet SCSI; see <xref linkend="storage-iscsi" />.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>IDE</glossterm>
+
+      <glossdef>
+
+        <para>
+          Integrated Drive Electronics, an industry standard for hard
+          disk interfaces. See <xref linkend="harddiskcontrollers" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>I/O APIC</glossterm>
+
+      <glossdef>
+
+        <para>
+          See APIC.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>iSCSI</glossterm>
+
+      <glossdef>
+
+        <para>
+          Internet SCSI. See <xref linkend="storage-iscsi" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>M</title>
 
-    <glossentry>
-      <glossterm>MAC</glossterm>
-
-      <glossdef>
-        <para>Media Access Control, a part of an Ethernet network card. A MAC
-        address is a 6-byte number which identifies a network card. It is
-        typically written in hexadecimal notation where the bytes are
-        separated by colons, such as
-        <computeroutput>00:17:3A:5E:CB:08</computeroutput>.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>MSI</glossterm>
-
-      <glossdef>
-        <para>Message Signaled Interrupts, as supported by modern chipsets
-        such as the ICH9; see <xref linkend="settings-motherboard" />. As
-        opposed to traditional pin-based interrupts, with MSI, a small amount
-        of data can accompany the actual interrupt message. This reduces the
-        amount of hardware pins required, allows for more interrupts and
-        better performance.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>MAC</glossterm>
+
+      <glossdef>
+
+        <para>
+          Media Access Control, a part of an Ethernet network card. A
+          MAC address is a 6-byte number which identifies a network
+          card. It is typically written in hexadecimal notation where
+          the bytes are separated by colons, such as
+          <computeroutput>00:17:3A:5E:CB:08</computeroutput>.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>MSI</glossterm>
+
+      <glossdef>
+
+        <para>
+          Message Signaled Interrupts, as supported by modern chipsets
+          such as the ICH9. See <xref linkend="settings-motherboard" />.
+          As opposed to traditional pin-based interrupts, with MSI, a
+          small amount of data can accompany the actual interrupt
+          message. This reduces the amount of hardware pins required,
+          allows for more interrupts and better performance.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>N</title>
 
-    <glossentry>
-      <glossterm>NAT</glossterm>
-
-      <glossdef>
-        <para>Network Address Translation. A technique to share networking
-        interfaces by which an interface modifies the source and/or target IP
-        addresses of network packets according to specific rules. Commonly
-        employed by routers and firewalls to shield an internal network from
-        the Internet, VirtualBox can use NAT to easily share a host's physical
-        networking hardware with its virtual machines. See <xref
-        linkend="network_nat" />.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>NAT</glossterm>
+
+      <glossdef>
+
+        <para>
+          Network Address Translation. A technique to share networking
+          interfaces by which an interface modifies the source and/or
+          target IP addresses of network packets according to specific
+          rules. Commonly employed by routers and firewalls to shield an
+          internal network from the Internet, VirtualBox can use NAT to
+          easily share a host's physical networking hardware with its
+          virtual machines. See <xref
+        linkend="network_nat" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>O</title>
 
-    <glossentry>
-      <glossterm>OVF</glossterm>
-
-      <glossdef>
-        <para>Open Virtualization Format, a cross-platform industry standard
-        to exchange virtual appliances between virtualization products; see
-        <xref linkend="ovf" />.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>OVF</glossterm>
+
+      <glossdef>
+
+        <para>
+          Open Virtualization Format, a cross-platform industry standard
+          to exchange virtual appliances between virtualization
+          products. See <xref linkend="ovf" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>P</title>
 
-    <glossentry>
-      <glossterm>PAE</glossterm>
-
-      <glossdef>
-        <para>Physical Address Extension. This allows accessing more than 4 GB
-        of RAM even in 32-bit environments; see <xref
-        linkend="settings-general-advanced" />.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>PIC</glossterm>
-
-      <glossdef>
-        <para>See APIC.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>PXE</glossterm>
-
-      <glossdef>
-        <para>Preboot Execution Environment, an industry standard for booting
-        PC systems from remote network locations. It includes DHCP for IP
-        configuration and TFTP for file transfer. Using UNDI, a hardware
-        independent driver stack for accessing the network card from bootstrap
-        code is available.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>PAE</glossterm>
+
+      <glossdef>
+
+        <para>
+          Physical Address Extension. This allows accessing more than 4
+          GB of RAM even in 32-bit environments. See
+          <xref
+        linkend="settings-general-advanced" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>PIC</glossterm>
+
+      <glossdef>
+
+        <para>
+          See APIC.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>PXE</glossterm>
+
+      <glossdef>
+
+        <para>
+          Preboot Execution Environment, an industry standard for
+          booting PC systems from remote network locations. It includes
+          DHCP for IP configuration and TFTP for file transfer. Using
+          UNDI, a hardware independent driver stack for accessing the
+          network card from bootstrap code is available.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>R</title>
 
-    <glossentry>
-      <glossterm>RDP</glossterm>
-
-      <glossdef>
-        <para>Remote Desktop Protocol, a protocol developed by Microsoft as an
-        extension to the ITU T.128 and T.124 video conferencing protocol. With
-        RDP, a PC system can be controlled from a remote location using a
-        network connection over which data is transferred in both directions.
-        Typically graphics updates and audio are sent from the remote machine
-        and keyboard and mouse input events are sent from the client. A
-        VirtualBox extension package by Oracle provides VRDP, an enhanced
-        implementation of the relevant standards which is largely compatible
-        with Microsoft's RDP implementation. See <xref linkend="vrde" /> for
-        details.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>RDP</glossterm>
+
+      <glossdef>
+
+        <para>
+          Remote Desktop Protocol, a protocol developed by Microsoft as
+          an extension to the ITU T.128 and T.124 video conferencing
+          protocol. With RDP, a PC system can be controlled from a
+          remote location using a network connection over which data is
+          transferred in both directions. Typically graphics updates and
+          audio are sent from the remote machine and keyboard and mouse
+          input events are sent from the client. A VirtualBox extension
+          package by Oracle provides VRDP, an enhanced implementation of
+          the relevant standards which is largely compatible with
+          Microsoft's RDP implementation. See <xref linkend="vrde" />
+          for details.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>S</title>
 
-    <glossentry>
-      <glossterm>SAS</glossterm>
-
-      <glossdef>
-        <para>Serial Attached SCSI, an industry standard for hard disk
-        interfaces. See <xref linkend="harddiskcontrollers" />.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>SATA</glossterm>
-
-      <glossdef>
-        <para>Serial ATA, an industry standard for hard disk interfaces. See
-        <xref linkend="harddiskcontrollers" />.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>SCSI</glossterm>
-
-      <glossdef>
-        <para>Small Computer System Interface. An industry standard for data
-        transfer between devices, especially for storage. See <xref
-        linkend="harddiskcontrollers" />.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>SMP</glossterm>
-
-      <glossdef>
-        <para>Symmetrical Multiprocessing, meaning that the resources of a
-        computer are shared between several processors. These can either be
-        several processor chips or, as is more common with modern hardware,
-        multiple CPU cores in one processor.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>SSD</glossterm>
-
-      <glossdef>
-        <para>Solid-state drive, uses microchips for storing data in a computer
-        system. Compared to classical hard-disks they are having no mechanical
-        components like spinning disks.
-        </para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>SAS</glossterm>
+
+      <glossdef>
+
+        <para>
+          Serial Attached SCSI, an industry standard for hard disk
+          interfaces. See <xref linkend="harddiskcontrollers" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>SATA</glossterm>
+
+      <glossdef>
+
+        <para>
+          Serial ATA, an industry standard for hard disk interfaces. See
+          <xref linkend="harddiskcontrollers" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>SCSI</glossterm>
+
+      <glossdef>
+
+        <para>
+          Small Computer System Interface. An industry standard for data
+          transfer between devices, especially for storage. See
+          <xref
+        linkend="harddiskcontrollers" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>SMP</glossterm>
+
+      <glossdef>
+
+        <para>
+          Symmetrical Multiprocessing, meaning that the resources of a
+          computer are shared between several processors. These can
+          either be several processor chips or, as is more common with
+          modern hardware, multiple CPU cores in one processor.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>SSD</glossterm>
+
+      <glossdef>
+
+        <para>
+          Solid-state drive, uses microchips for storing data in a
+          computer system. Compared to classical hard-disks they are
+          having no mechanical components like spinning disks.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>T</title>
 
-    <glossentry>
-      <glossterm>TAR</glossterm>
-
-      <glossdef>
-        <para>A widely used file format for archiving. Originally, this stood
-        for "Tape ARchive" and was already supported by very early Unix
-        versions for backing up data on tape. The file format is still widely
-        used today, for example, with OVF archives (with an
-        <computeroutput>.ova</computeroutput> file extension); see <xref
-        linkend="ovf" />.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>TAR</glossterm>
+
+      <glossdef>
+
+        <para>
+          A widely used file format for archiving. Originally, this
+          stood for Tape ARchive and was already supported by very early
+          Unix versions for backing up data on tape. The file format is
+          still widely used today. For example, with OVF archives using
+          an <computeroutput>.ova</computeroutput> file extension. See
+          <xref
+        linkend="ovf" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>U</title>
 
-    <glossentry>
-      <glossterm>UUID</glossterm>
-
-      <glossdef>
-        <para>A Universally Unique Identifier -- often also called GUID
-        (Globally Unique Identifier) -- is a string of numbers and letters
-        which can be computed dynamically and is guaranteed to be unique.
-        Generally, it is used as a global handle to identify entities.
-        VirtualBox makes use of UUIDs to identify VMs, Virtual Disk Images
-        (VDI files) and other entities.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>UUID</glossterm>
+
+      <glossdef>
+
+        <para>
+          A Universally Unique Identifier, often also called GUID
+          (Globally Unique Identifier). A UUID is a string of numbers
+          and letters which can be computed dynamically and is
+          guaranteed to be unique. Generally, it is used as a global
+          handle to identify entities. VirtualBox makes use of UUIDs to
+          identify VMs, Virtual Disk Images (VDI files), and other
+          entities.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>V</title>
 
-    <glossentry>
-      <glossterm>VM</glossterm>
-
-      <glossdef>
-        <para>Virtual Machine -- a virtual computer that VirtualBox allows you
-        to run on top of your actual hardware. See <xref
-        linkend="virtintro" /> for details.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>VMM</glossterm>
-
-      <glossdef>
-        <para>Virtual Machine Manager -- the component of VirtualBox that
-        controls VM execution. See <xref linkend="technical-components" /> for
-        a list of VirtualBox components.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>VRDE</glossterm>
-
-      <glossdef>
-        <para>VirtualBox Remote Desktop Extension. This interface is built
-        into VirtualBox to allow VirtualBox extension packages to supply
-        remote access to virtual machines. A VirtualBox extension package by
-        Oracle provides VRDP support; see <xref linkend="vrde" /> for
-        details.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>VRDP</glossterm>
-
-      <glossdef>
-        <para>See RDP.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>VT-x</glossterm>
-
-      <glossdef>
-        <para>The hardware virtualization features built into modern Intel
-        processors. See <xref linkend="hwvirt" />.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
-
-  <glossdiv>
+    <glossentry><glossterm>VM</glossterm>
+
+      <glossdef>
+
+        <para>
+          Virtual Machine. A virtual computer that VirtualBox enables
+          you to run on top of your actual hardware. See
+          <xref
+        linkend="virtintro" /> for details.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>VMM</glossterm>
+
+      <glossdef>
+
+        <para>
+          Virtual Machine Manager. The component of VirtualBox that
+          controls VM execution. See
+          <xref linkend="technical-components" /> for a list of
+          VirtualBox components.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>VRDE</glossterm>
+
+      <glossdef>
+
+        <para>
+          VirtualBox Remote Desktop Extension. This interface is built
+          into VirtualBox to allow VirtualBox extension packages to
+          supply remote access to virtual machines. A VirtualBox
+          extension package by Oracle provides VRDP support. See
+          <xref linkend="vrde" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>VRDP</glossterm>
+
+      <glossdef>
+
+        <para>
+          See RDP.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>VT-x</glossterm>
+
+      <glossdef>
+
+        <para>
+          The hardware virtualization features built into modern Intel
+          processors. See <xref linkend="hwvirt" />.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
+  <glossdiv>
+
     <title>X</title>
 
-    <glossentry>
-      <glossterm>xHCI</glossterm>
-
-      <glossdef>
-        <para>eXtended Host Controller Interface, the interface that
-        implements the USB 3.0 standard.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>XML</glossterm>
-
-      <glossdef>
-        <para>The eXtensible Markup Language, a metastandard for all kinds of
-        textual information. XML only specifies how data in the document is
-        organized generally and does not prescribe how to semantically
-        organize content.</para>
-      </glossdef>
-    </glossentry>
-
-    <glossentry>
-      <glossterm>XPCOM</glossterm>
-
-      <glossdef>
-        <para>Mozilla Cross Platform Component Object Model, a programming
-        infrastructure developed by the Mozilla browser project which is
-        similar to Microsoft COM and allows applications to provide a modular
-        programming interface. VirtualBox makes use of XPCOM on Linux both
-        internally and externally to provide a comprehensive API to
-        third-party developers.</para>
-      </glossdef>
-    </glossentry>
-  </glossdiv>
+    <glossentry><glossterm>xHCI</glossterm>
+
+      <glossdef>
+
+        <para>
+          eXtended Host Controller Interface, the interface that
+          implements the USB 3.0 standard.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>XML</glossterm>
+
+      <glossdef>
+
+        <para>
+          The eXtensible Markup Language, a metastandard for all kinds
+          of textual information. XML only specifies how data in the
+          document is organized generally and does not prescribe how to
+          semantically organize content.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+    <glossentry><glossterm>XPCOM</glossterm>
+
+      <glossdef>
+
+        <para>
+          Mozilla Cross Platform Component Object Model, a programming
+          infrastructure developed by the Mozilla browser project which
+          is similar to Microsoft COM and allows applications to provide
+          a modular programming interface. VirtualBox makes use of XPCOM
+          on Linux both internally and externally to provide a
+          comprehensive API to third-party developers.
+        </para>
+
+      </glossdef>
+
+    </glossentry>
+
+  </glossdiv>
+
 </glossary>
Index: /trunk/doc/manual/en_US/user_GuestAdditions.xml
===================================================================
--- /trunk/doc/manual/en_US/user_GuestAdditions.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_GuestAdditions.xml	(revision 73276)
@@ -1,231 +1,292 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="guestadditions">
+
   <title>Guest Additions</title>
 
-  <para>The previous chapter covered getting started with VirtualBox and
-  installing operating systems in a virtual machine. For any serious and
-  interactive use, the VirtualBox Guest Additions will make your life much
-  easier by providing closer integration between host and guest and improving
-  the interactive performance of guest systems. This chapter describes the
-  Guest Additions in detail.</para>
-
-  <sect1>
-    <title>Introduction</title>
-
-    <para>As mentioned in <xref linkend="virtintro" />, the Guest Additions
-    are designed to be installed <emphasis>inside</emphasis> a virtual machine
-    after the guest operating system has been installed. They consist of
-    device drivers and system applications that optimize the guest operating
-    system for better performance and usability. Please see <xref
-    linkend="guestossupport" /> for details on what guest operating systems
-    are fully supported with Guest Additions by VirtualBox.</para>
-
-    <para>The VirtualBox Guest Additions for all supported guest operating
-    systems are provided as a single CD-ROM image file which is called
-    <computeroutput>VBoxGuestAdditions.iso</computeroutput>. This image file
-    is located in the installation directory of VirtualBox. To install the
-    Guest Additions for a particular VM, you mount this ISO file in your VM as
-    a virtual CD-ROM and install from there.</para>
-
-    <para>The Guest Additions offer the following features:<glosslist>
-        <glossentry>
-          <glossterm>Mouse pointer integration</glossterm>
-
-          <glossdef>
-            <para>To overcome the limitations for mouse support that were
-            described in <xref linkend="keyb_mouse_normal" />, this provides
-            you with seamless mouse support. You will only have one mouse
-            pointer and pressing the Host key is no longer required to "free"
-            the mouse from being captured by the guest OS. To make this work,
-            a special mouse driver is installed in the guest that communicates
-            with the "real" mouse driver on your host and moves the guest
-            mouse pointer accordingly.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Shared folders</glossterm>
-
-          <glossdef>
-            <para>These provide an easy way to exchange files between the host
-            and the guest. Much like ordinary Windows network shares, you can
-            tell VirtualBox to treat a certain host directory as a shared
-            folder, and VirtualBox will make it available to the guest
-            operating system as a network share, irrespective of whether guest
-            actually has a network. For details, please refer to <xref
-            linkend="sharedfolders" />.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Better video support</glossterm>
-
-          <glossdef>
-            <para>While the virtual graphics card which VirtualBox emulates
-            for any guest operating system provides all the basic features,
-            the custom video drivers that are installed with the Guest
-            Additions provide you with extra high and non-standard video modes
-            as well as accelerated video performance.</para>
-
-            <para>In addition, with Windows, Linux and Solaris guests, you can
-            resize the virtual machine's window if the Guest Additions are
-            installed. The video resolution in the guest will be automatically
-            adjusted (as if you had manually entered an arbitrary resolution
-            in the guest's display settings). Please see <xref
-            linkend="intro-resize-window" /> also.</para>
-
-            <para>Finally, if the Guest Additions are installed, 3D graphics
-            and 2D video for guest applications can be accelerated; see <xref
-            linkend="guestadd-video" />.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Seamless windows</glossterm>
-
-          <glossdef>
-            <para>With this feature, the individual windows that are displayed
-            on the desktop of the virtual machine can be mapped on the host's
-            desktop, as if the underlying application was actually running on
-            the host. See <xref linkend="seamlesswindows" /> for
-            details.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Generic host/guest communication channels</glossterm>
-
-          <glossdef>
-            <para>The Guest Additions enable you to control and monitor guest
-            execution in ways other than those mentioned above. The so-called
-            "guest properties" provide a generic string-based mechanism to
-            exchange data bits between a guest and a host, some of which have
-            special meanings for controlling and monitoring the guest; see
-            <xref linkend="guestadd-guestprops" /> for details.</para>
-
-            <para>Additionally, applications can be started in a guest from
-            the host; see <xref linkend="guestadd-guestcontrol" />.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Time synchronization</glossterm>
-
-          <glossdef>
-            <para>With the Guest Additions installed, VirtualBox can ensure
-            that the guest's system time is better synchronized with that of
-            the host.</para>
-
-            <para>For various reasons, the time in the guest might run at a
-            slightly different rate than the time on the host. The host could
-            be receiving updates via NTP and its own time might not run
-            linearly. A VM could also be paused, which stops the flow of time
-            in the guest for a shorter or longer period of time. When the wall
-            clock time between the guest and host only differs slightly, the
-            time synchronization service attempts to gradually and smoothly
-            adjust the guest time in small increments to either "catch up" or
-            "lose" time. When the difference is too great (e.g., a VM paused
-            for hours or restored from saved state), the guest time is changed
-            immediately, without a gradual adjustment.</para>
-
-            <para>The Guest Additions will re-synchronize the time regularly.
-            See <xref linkend="changetimesync" /> for how to configure the
-            parameters of the time synchronization mechanism.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Shared clipboard</glossterm>
-
-          <glossdef>
-            <para>With the Guest Additions installed, the clipboard of the
-            guest operating system can optionally be shared with your host
-            operating system; see <xref linkend="generalsettings" />.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Automated logons (credentials passing)</glossterm>
-
-          <glossdef>
-            <para>For details, please see <xref linkend="autologon" />.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist></para>
-
-    <para>Each version of VirtualBox, even minor releases, ship with their own
-    version of the Guest Additions. While the interfaces through which the
-    VirtualBox core communicates with the Guest Additions are kept stable so
-    that Guest Additions already installed in a VM should continue to work
-    when VirtualBox is upgraded on the host, for best results, it is
-    recommended to keep the Guest Additions at the same version.</para>
-
-    <para>Starting with VirtualBox 3.1, the Windows and Linux Guest Additions
-    therefore check automatically whether they have to be updated. If the host
-    is running a newer VirtualBox version than the Guest Additions, a
-    notification with further instructions is displayed in the guest.</para>
-
-    <para>To disable this update check for the Guest Additions of a given
-    virtual machine, set the value of its
-    <computeroutput>/VirtualBox/GuestAdd/CheckHostVersion</computeroutput>
-    guest property to <computeroutput>0</computeroutput>; see <xref
-    linkend="guestadd-guestprops" /> for details.</para>
+  <para>
+    The previous chapter covered getting started with VirtualBox and
+    installing operating systems in a virtual machine. For any serious
+    and interactive use, the VirtualBox Guest Additions will make your
+    life much easier by providing closer integration between host and
+    guest and improving the interactive performance of guest systems.
+    This chapter describes the Guest Additions in detail.
+  </para>
+
+  <sect1 id="guestadd-intro">
+
+    <title>Introduction to Guest Additions</title>
+
+    <para>
+      As mentioned in <xref linkend="virtintro" />, the Guest Additions
+      are designed to be installed <emphasis>inside</emphasis> a virtual
+      machine after the guest operating system has been installed. They
+      consist of device drivers and system applications that optimize
+      the guest operating system for better performance and usability.
+      See <xref
+    linkend="guestossupport" /> for details on what
+      guest operating systems are fully supported with Guest Additions
+      by VirtualBox.
+    </para>
+
+    <para>
+      The VirtualBox Guest Additions for all supported guest operating
+      systems are provided as a single CD-ROM image file which is called
+      <computeroutput>VBoxGuestAdditions.iso</computeroutput>. This
+      image file is located in the installation directory of VirtualBox.
+      To install the Guest Additions for a particular VM, you mount this
+      ISO file in your VM as a virtual CD-ROM and install from there.
+    </para>
+
+    <para>
+      The Guest Additions offer the following features:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Mouse pointer integration</emphasis>. To
+          overcome the limitations for mouse support described in
+          <xref linkend="keyb_mouse_normal" />, this feature provides
+          you with seamless mouse support. You will only have one mouse
+          pointer and pressing the Host key is no longer required to
+          "free" the mouse from being captured by the guest OS. To make
+          this work, a special mouse driver is installed in the guest
+          that communicates with the "real" mouse driver on your host
+          and moves the guest mouse pointer accordingly.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Shared folders.</emphasis> These provide
+          an easy way to exchange files between the host and the guest.
+          Much like ordinary Windows network shares, you can tell
+          VirtualBox to treat a certain host directory as a shared
+          folder, and VirtualBox will make it available to the guest
+          operating system as a network share, irrespective of whether
+          guest actually has a network. See
+          <xref
+            linkend="sharedfolders" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Better video support.</emphasis> While
+          the virtual graphics card which VirtualBox emulates for any
+          guest operating system provides all the basic features, the
+          custom video drivers that are installed with the Guest
+          Additions provide you with extra high and non-standard video
+          modes, as well as accelerated video performance.
+        </para>
+
+        <para>
+          In addition, with Windows, Linux, and Solaris guests, you can
+          resize the virtual machine's window if the Guest Additions are
+          installed. The video resolution in the guest will be
+          automatically adjusted, as if you had manually entered an
+          arbitrary resolution in the guest's display settings. See
+          <xref
+            linkend="intro-resize-window" />.
+        </para>
+
+        <para>
+          If the Guest Additions are installed, 3D graphics and 2D video
+          for guest applications can be accelerated. See
+          <xref
+            linkend="guestadd-video" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Seamless windows.</emphasis> With this
+          feature, the individual windows that are displayed on the
+          desktop of the virtual machine can be mapped on the host's
+          desktop, as if the underlying application was actually running
+          on the host. See <xref linkend="seamlesswindows" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Generic host/guest communication
+          channels.</emphasis> The Guest Additions enable you to control
+          and monitor guest execution. The "guest properties" provide a
+          generic string-based mechanism to exchange data bits between a
+          guest and a host, some of which have special meanings for
+          controlling and monitoring the guest. See
+          <xref linkend="guestadd-guestprops" />.
+        </para>
+
+        <para>
+          Additionally, applications can be started in a guest from the
+          host. See <xref linkend="guestadd-guestcontrol" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Time synchronization.</emphasis> With
+          the Guest Additions installed, VirtualBox can ensure that the
+          guest's system time is better synchronized with that of the
+          host.
+        </para>
+
+        <para>
+          For various reasons, the time in the guest might run at a
+          slightly different rate than the time on the host. The host
+          could be receiving updates via NTP and its own time might not
+          run linearly. A VM could also be paused, which stops the flow
+          of time in the guest for a shorter or longer period of time.
+          When the wall clock time between the guest and host only
+          differs slightly, the time synchronization service attempts to
+          gradually and smoothly adjust the guest time in small
+          increments to either "catch up" or "lose" time. When the
+          difference is too great, for example if a VM paused for hours
+          or restored from saved state, the guest time is changed
+          immediately, without a gradual adjustment.
+        </para>
+
+        <para>
+          The Guest Additions will resynchronize the time regularly. See
+          <xref linkend="changetimesync" /> for how to configure the
+          parameters of the time synchronization mechanism.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Shared clipboard.</emphasis> With the
+          Guest Additions installed, the clipboard of the guest
+          operating system can optionally be shared with your host
+          operating system. See <xref linkend="generalsettings" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Automated logons.</emphasis> Also called
+          credentials passing. See <xref linkend="autologon" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Each version of VirtualBox, even minor releases, ship with their
+      own version of the Guest Additions. While the interfaces through
+      which the VirtualBox core communicates with the Guest Additions
+      are kept stable so that Guest Additions already installed in a VM
+      should continue to work when VirtualBox is upgraded on the host,
+      for best results, it is recommended to keep the Guest Additions at
+      the same version.
+    </para>
+
+    <para>
+      Starting with VirtualBox 3.1, the Windows and Linux Guest
+      Additions therefore check automatically whether they have to be
+      updated. If the host is running a newer VirtualBox version than
+      the Guest Additions, a notification with further instructions is
+      displayed in the guest.
+    </para>
+
+    <para>
+      To disable this update check for the Guest Additions of a given
+      virtual machine, set the value of its
+      <computeroutput>/VirtualBox/GuestAdd/CheckHostVersion</computeroutput>
+      guest property to <computeroutput>0</computeroutput>. See
+      <xref
+    linkend="guestadd-guestprops" />.
+    </para>
+
   </sect1>
 
-  <sect1>
+  <sect1 id="guestadd-install">
+
     <title>Installing and Maintaining Guest Additions</title>
 
-    <para>Guest Additions are available for virtual machines running Windows,
-    Linux, Solaris or OS/2. The following sections describe the specifics of
-    each variant in detail.</para>
+    <para>
+      Guest Additions are available for virtual machines running
+      Windows, Linux, Solaris, or OS/2. The following sections describe
+      the specifics of each variant in detail.
+    </para>
 
     <sect2 id="additions-windows">
+
       <title>Guest Additions for Windows</title>
 
-      <para>The VirtualBox Windows Guest Additions are designed to be
-      installed in a virtual machine running a Windows operating system. The
-      following versions of Windows guests are supported:</para>
+      <para>
+        The VirtualBox Windows Guest Additions are designed to be
+        installed in a virtual machine running a Windows operating
+        system. The following versions of Windows guests are supported:
+      </para>
 
       <itemizedlist>
-        <listitem>
-          <para>Microsoft Windows NT 4.0 (any service pack)</para>
-        </listitem>
-
-        <listitem>
-          <para>Microsoft Windows 2000 (any service pack)</para>
-        </listitem>
-
-        <listitem>
-          <para>Microsoft Windows XP (any service pack)</para>
-        </listitem>
-
-        <listitem>
-          <para>Microsoft Windows Server 2003 (any service pack)</para>
-        </listitem>
-
-        <listitem>
-          <para>Microsoft Windows Server 2008</para>
-        </listitem>
-
-        <listitem>
-          <para>Microsoft Windows Vista (all editions)</para>
-        </listitem>
-
-        <listitem>
-          <para>Microsoft Windows 7 (all editions)</para>
-        </listitem>
-
-        <listitem>
-          <para>Microsoft Windows 8 (all editions)</para>
-        </listitem>
-
-        <listitem>
-          <para>Microsoft Windows 10 RTM build 10240</para>
-        </listitem>
-
-        <listitem>
-          <para>Microsoft Windows Server 2012</para>
+
+        <listitem>
+          <para>
+            Microsoft Windows NT 4.0 (any service pack)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Microsoft Windows 2000 (any service pack)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Microsoft Windows XP (any service pack)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Microsoft Windows Server 2003 (any service pack)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Microsoft Windows Server 2008
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Microsoft Windows Vista (all editions)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Microsoft Windows 7 (all editions)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Microsoft Windows 8 (all editions)
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Microsoft Windows 10 RTM build 10240
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Microsoft Windows Server 2012
+          </para>
         </listitem>
 
@@ -233,704 +294,1104 @@
 
       <sect3 id="mountingadditionsiso">
-        <title>Installation</title>
-
-        <para>In the "Devices" menu in the virtual machine's menu bar,
-        VirtualBox has a handy menu item named "Insert Guest Additions CD image",
-        which mounts the Guest Additions ISO file inside your virtual machine.
-        A Windows guest should then automatically start the Guest Additions
-        installer, which installs the Guest Additions into your Windows
-        guest. Other guest operating systems (or if automatic start of
-        software on CD is disabled) need manual start of the installer.</para>
+
+        <title>Installing the Windows Guest Additions</title>
+
+        <para>
+          In the Devices menu in the virtual machine's menu bar,
+          VirtualBox has a menu item <emphasis role="bold">Insert Guest
+          Additions CD Image</emphasis>, which mounts the Guest
+          Additions ISO file inside your virtual machine. A Windows
+          guest should then automatically start the Guest Additions
+          installer, which installs the Guest Additions into your
+          Windows guest. Other guest operating systems, or if automatic
+          start of software on CD is disabled, need a manual start of
+          the installer.
+        </para>
 
         <note>
-          <para>For the basic Direct3D acceleration to work in a Windows guest,
-          you have to install the WDDM video driver available for Windows Vista
-          or higher.<footnote><para>An experimental WDDM driver was
-          added with VirtualBox 4.1.</para></footnote> For Windows 8 and higher
-          only the WDDM Direct3D video driver is available. For basic Direct3D
-          acceleration to work in Windows XP guests, you have to install the
-          Guest Additions in "Safe Mode", see <xref linkend="KnownIssues" /> for
-          details.</para>
+          <para>
+            For the basic Direct3D acceleration to work in a Windows
+            guest, you have to install the WDDM video driver available
+            for Windows Vista or higher.
+
+            <footnote>
+
+              <para>
+                An experimental WDDM driver was added with VirtualBox
+                4.1.
+              </para>
+
+            </footnote>
+
+            For Windows 8 and higher only the WDDM Direct3D video driver
+            is available. For basic Direct3D acceleration to work in
+            Windows XP guests, you have to install the Guest Additions
+            in Safe Mode. See <xref linkend="KnownIssues" /> for
+            details.
+          </para>
         </note>
 
-        <para>If you prefer to mount the additions manually, you can perform
-        the following steps:</para>
+        <para>
+          If you prefer to mount the Guest Additions manually, you can
+          perform the following steps:
+        </para>
 
         <orderedlist>
-          <listitem>
-            <para>Start the virtual machine in which you have installed
-            Windows.</para>
-          </listitem>
-
-          <listitem>
-            <para>Select "Mount CD/DVD-ROM" from the "Devices" menu in the
-            virtual machine's menu bar and then "CD/DVD-ROM image". This
-            brings up the Virtual Media Manager described in <xref
-            linkend="vdis" />.</para>
-          </listitem>
-
-          <listitem>
-            <para>In the Virtual Media Manager, press the "Add" button and
-            browse your host file system for the
-            <computeroutput>VBoxGuestAdditions.iso</computeroutput>
-            file:<itemizedlist>
-                <listitem>
-                  <para>On a Windows host, you can find this file in the
-                  VirtualBox installation directory (usually under
+
+          <listitem>
+            <para>
+              Start the virtual machine in which you have installed
+              Windows.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Select <emphasis role="bold">Mount CD/DVD-ROM</emphasis>
+              from the Devices menu in the virtual machine's menu bar
+              and then <emphasis role="bold">CD/DVD-ROM
+              Image</emphasis>. This displays the Virtual Media Manager,
+              described in <xref
+            linkend="vdis" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              In the Virtual Media Manager, click
+              <emphasis role="bold">Add</emphasis> and browse your host
+              file system for the
+              <computeroutput>VBoxGuestAdditions.iso</computeroutput>
+              file.
+            </para>
+
+            <itemizedlist>
+
+              <listitem>
+                <para>
+                  On a Windows host, this file is in the VirtualBox
+                  installation directory, usually in
                   <computeroutput>C:\Program
-                  files\Oracle\VirtualBox</computeroutput> ).</para>
-                </listitem>
-
-                <listitem>
-                  <para>On Mac OS X hosts, you can find this file in the
-                  application bundle of VirtualBox. (Right click on the
-                  VirtualBox icon in Finder and choose <emphasis>Show Package
-                  Contents</emphasis>. There it is located in the
-                  <computeroutput>Contents/MacOS</computeroutput>
-                  folder.)</para>
-                </listitem>
-
-                <listitem>
-                  <para>On a Linux host, you can find this file in the
-                  <computeroutput>additions</computeroutput> folder under
-                  where you installed VirtualBox (normally
-                  <computeroutput>/opt/VirtualBox/</computeroutput>).</para>
-                </listitem>
-
-                <listitem>
-                  <para>On Solaris hosts, you can find this file in the
-                  <computeroutput>additions</computeroutput> folder under
-                  where you installed VirtualBox (normally
-                  <computeroutput>/opt/VirtualBox</computeroutput>).</para>
-                </listitem>
-              </itemizedlist></para>
-          </listitem>
-
-          <listitem>
-            <para>Back in the Virtual Media Manager, select that ISO file and
-            press the "Select" button. This will mount the ISO file and
-            present it to your Windows guest as a CD-ROM.</para>
-          </listitem>
+                  files\Oracle\VirtualBox</computeroutput>.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  On Mac OS X hosts, this file is in the application
+                  bundle of VirtualBox. Right-click on the VirtualBox
+                  icon in Finder and choose <emphasis role="bold">Show
+                  Package Contents</emphasis>. The file is located in
+                  the <computeroutput>Contents/MacOS</computeroutput>
+                  folder.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  On a Linux host, this file is in the
+                  <computeroutput>additions</computeroutput> folder
+                  where you installed VirtualBox, usually
+                  <computeroutput>/opt/VirtualBox/</computeroutput>.
+                </para>
+              </listitem>
+
+              <listitem>
+                <para>
+                  On Solaris hosts, this file is in the
+                  <computeroutput>additions</computeroutput> folder
+                  where you installed VirtualBox, usually
+                  <computeroutput>/opt/VirtualBox</computeroutput>.
+                </para>
+              </listitem>
+
+            </itemizedlist>
+          </listitem>
+
+          <listitem>
+            <para>
+              In the Virtual Media Manager, select the ISO file and
+              click <emphasis role="bold">Select</emphasis> button. This
+              mounts the ISO file and presents it to your Windows guest
+              as a CD-ROM.
+            </para>
+          </listitem>
+
         </orderedlist>
 
-        <para>Unless you have the Autostart feature disabled in your Windows
-        guest, Windows will now autostart the VirtualBox Guest Additions
-        installation program from the Additions ISO. If the Autostart feature
-        has been turned off, choose
-        <computeroutput>VBoxWindowsAdditions.exe</computeroutput> from the
-        CD/DVD drive inside the guest to start the installer.</para>
-
-        <para>The installer will add several device drivers to the Windows
-        driver database and then invoke the hardware detection wizard.</para>
-
-        <para>Depending on your configuration, it might display warnings that
-        the drivers are not digitally signed. You must confirm these in order
-        to continue the installation and properly install the
-        Additions.</para>
-
-        <para>After installation, reboot your guest operating system to
-        activate the Additions.</para>
+        <para>
+          Unless you have the Autostart feature disabled in your Windows
+          guest, Windows will now autostart the VirtualBox Guest
+          Additions installation program from the Additions ISO. If the
+          Autostart feature has been turned off, choose
+          <computeroutput>VBoxWindowsAdditions.exe</computeroutput> from
+          the CD/DVD drive inside the guest to start the installer.
+        </para>
+
+        <para>
+          The installer will add several device drivers to the Windows
+          driver database and then invoke the hardware detection wizard.
+        </para>
+
+        <para>
+          Depending on your configuration, it might display warnings
+          that the drivers are not digitally signed. You must confirm
+          these in order to continue the installation and properly
+          install the Additions.
+        </para>
+
+        <para>
+          After installation, reboot your guest operating system to
+          activate the Additions.
+        </para>
+
       </sect3>
 
-      <sect3>
+      <sect3 id="additions-windows-updating">
+
         <title>Updating the Windows Guest Additions</title>
 
-        <para>Windows Guest Additions can be updated by running the
-        installation program again, as previously described. This will then
-        replace the previous Additions drivers with updated versions.</para>
-
-        <para>Alternatively, you may also open the Windows Device Manager and
-        select "Update driver..." for two devices:</para>
+        <para>
+          Windows Guest Additions can be updated by running the
+          installation program again. This replaces the previous
+          Additions drivers with updated versions.
+        </para>
+
+        <para>
+          Alternatively, you can also open the Windows Device Manager
+          and select <emphasis role="bold">Update Driver...</emphasis>
+          for the following devices:
+        </para>
 
         <orderedlist>
-          <listitem>
-            <para>the VirtualBox Graphics Adapter and</para>
-          </listitem>
-
-          <listitem>
-            <para>the VirtualBox System Device.</para>
-          </listitem>
+
+          <listitem>
+            <para>
+              VirtualBox Graphics Adapter
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              VirtualBox System Device
+            </para>
+          </listitem>
+
         </orderedlist>
 
-        <para>For each, choose to provide your own driver and use "Have Disk"
-        to point the wizard to the CD-ROM drive with the Guest
-        Additions.</para>
+        <para>
+          For each, choose the option to provide your own driver, click
+          <emphasis role="bold">Have Disk</emphasis> and navigate to the
+          CD-ROM drive with the Guest Additions.
+        </para>
+
       </sect3>
 
-      <sect3>
+      <sect3 id="additions-windows-install-unattended">
+
         <title>Unattended Installation</title>
 
-        <para>As a prerequisite for avoid popups while performing an
-        unattended installation of the VirtualBox Guest Additions, the code
-        signing certificates used to sign the drivers needs to be installed in
-        the right certificates stores in the guest system.  Failing to do this
-        will cause a typical windows installation to pop up a dialog asking
-        whether its allowable to install each driver.</para>
-
-        <note><para>On some Windows versions like Windows 2000 and Windows XP the user intervention
-        popups mentioned above always will be displayed, even after importing the Oracle certificates.</para></note>
-
-        <para>Since VirtualBox 4.2 installing those code signing certificates
-        on a Windows guest can be done in an automated fashion using the
-        <computeroutput>VBoxCertUtil.exe</computeroutput> utility found on the Guest
-        Additions installation CD in the <computeroutput>cert</computeroutput>
-        folder:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>Log in as Administrator on the guest.</para>
-          </listitem>
-
-          <listitem>
-            <para>Mount the VirtualBox Guest Additions .ISO.</para>
-          </listitem>
-
-          <listitem>
-            <para>Open a command line window on the guest and change to
-            the <computeroutput>cert</computeroutput> folder on the VirtualBox
-            Guest Additions CD.</para>
-          </listitem>
-
-          <listitem>
-            <para>Do<screen>VBoxCertUtil.exe add-trusted-publisher vbox*.cer --root vbox*.cer</screen></para>
-            <para>This will install the certificates to the certificate store. When installing the same certificate
-            more than once, an appropriate error will be displayed.</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>Prior to VirtualBox 4.2 the code signing certificates need to be imported in more manual style
-        using the <computeroutput>certutil.exe</computeroutput> utility, which is shipped since Windows
-        Vista.  For Windows versions before Vista you need to download and install <computeroutput>certutil.exe</computeroutput>
-        manually. Since the certificates are not accompanied on the VirtualBox Guest Additions CD-ROM
-        prior to 4.2, these need to get extracted from a signed VirtualBox executable first.</para>
-
-        <para>In the following example the needed certificates will be extracted from the VirtualBox
-        Windows Guest Additions installer on the CD-ROM:</para>
-
-        <glosslist>
-          <glossentry>
-            <glossterm>VeriSign Code Signing CA</glossterm>
-            <glossdef>
-              <para>Open the Windows Explorer.</para>
-              <itemizedlist>
-                <listitem>
-                  <para>Right click on VBoxWindowsAdditions-&lt;Architecture&gt;.exe,
-                  click on "Properties"</para>
-                </listitem>
-                <listitem>
-                  <para>Go to tab "Digital Signatures", choose "Oracle Corporation" and click on "Details"</para>
-                </listitem>
-                <listitem>
-                  <para>In tab "General" click on "View Certificate"</para>
-                </listitem>
-                <listitem>
-                  <para>In tab "Certification Path" select "VeriSign Class 3 Public Primary CA"</para>
-                </listitem>
-                <listitem>
-                  <para>Click on "View Certificate"</para>
-                </listitem>
-                <listitem>
-                  <para>In tab "Details" click on "Copy to File ..."</para>
-                </listitem>
-                <listitem>
-                  <para>In the upcoming wizard choose "DER encoded binary X.509 (.CER)"
-                  and save the certificate file to a local path, finish the wizard</para>
-                </listitem>
-                <listitem>
-                  <para>Close certificate dialog for "Verisign Class 3 Code Signing
-                  2010 CA"</para>
-                </listitem>
-              </itemizedlist>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>Oracle Corporation</glossterm>
-            <glossdef>
-              <para>Open the Windows Explorer.</para>
-              <itemizedlist>
-                <listitem>
-                  <para>Right click on VBoxWindowsAdditions-&lt;Architecture&gt;.exe,
-                  click on "Properties"</para>
-                </listitem>
-                <listitem>
-                  <para>Go to tab "Digital Signatures", choose "Oracle Corporation" and click on "Details"</para>
-                </listitem>
-                <listitem>
-                  <para>In tab "General" click on "View Certificate"</para>
-                </listitem>
-                <listitem>
-                  <para>In tab "Details" click on "Copy to File ..."</para>
-                </listitem>
-                <listitem>
-                  <para>In the upcoming wizard choose "DER encoded binary X.509 (.CER)"
-                  and save the certificate file to a local path, finish the wizard</para>
-                </listitem>
-                <listitem>
-                  <para>Close certificate dialog for "Oracle Corporation"</para>
-                </listitem>
-              </itemizedlist>
-            </glossdef>
-          </glossentry>
-        </glosslist>
-
-        <para>After exporting the two certificates above they can be imported into the
-        certificate store using the <computeroutput>certutil.exe</computeroutput>
-        utility:</para>
-
-        <para><computeroutput>certutil -addstore -f Root "&lt;Path to exported
-        certificate file&gt;"</computeroutput></para>
-
-        <para>In order to allow for completely unattended guest installations,
-        you can specify a command line parameter to the install
-        launcher:</para>
-
-        <screen>VBoxWindowsAdditions.exe /S</screen>
-
-        <para>This automatically installs the right files and drivers for the
-        corresponding platform (32- or 64-bit).</para>
-
-        <note><para>By default on an unattended installation on a Vista or Windows
-        7 guest, there will be the XPDM graphics driver installed. This graphics
-        driver does not support Windows Aero / Direct3D on the guest &ndash; instead
-        the WDDM graphics driver needs to be installed. To select this driver by
-        default, add the command line parameter
-        <computeroutput>/with_wddm</computeroutput> when invoking the Windows
-        Guest Additions installer (only required for Vista and Windows 7).</para></note>
-        <note><para>For Windows Aero to run correctly on a guest, the guest's
-        VRAM size needs to be configured to at least 128 MB.</para></note>
-
-        <para>For more options regarding unattended guest installations,
-        consult the command line help by using the command:</para>
-
-        <screen>VBoxWindowsAdditions.exe /?</screen>
+        <para>
+          As a prerequisite for avoid popups while performing an
+          unattended installation of the VirtualBox Guest Additions, the
+          code signing certificates used to sign the drivers needs to be
+          installed in the right certificates stores in the guest
+          system. Failing to do this will cause a typical windows
+          installation to pop up a dialog asking whether its allowable
+          to install each driver.
+        </para>
+
+        <note>
+          <para>
+            On some Windows versions like Windows 2000 and Windows XP
+            the user intervention popups mentioned above always will be
+            displayed, even after importing the Oracle certificates.
+          </para>
+        </note>
+
+        <para>
+          Since VirtualBox 4.2, installing the code signing certificates
+          on a Windows guest can be done in an automated fashion using
+          the <computeroutput>VBoxCertUtil.exe</computeroutput> utility
+          found on the Guest Additions installation CD in the
+          <computeroutput>cert</computeroutput> folder:
+        </para>
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              Log in as Administrator on the guest.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Mount the VirtualBox Guest Additions .ISO.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Open a command line window on the guest and change to the
+              <computeroutput>cert</computeroutput> folder on the
+              VirtualBox Guest Additions CD.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Run the following command:
+            </para>
+
+<screen>VBoxCertUtil.exe add-trusted-publisher vbox*.cer --root vbox*.cer</screen>
+
+            <para>
+              This command installs the certificates to the certificate
+              store. When installing the same certificate more than
+              once, an appropriate error will be displayed.
+            </para>
+          </listitem>
+
+        </orderedlist>
+
+        <para>
+          Prior to VirtualBox 4.2 the code signing certificates need to
+          be imported in more manual style using the
+          <computeroutput>certutil.exe</computeroutput> utility, which
+          is shipped since Windows Vista. For Windows versions before
+          Vista you need to download and install
+          <computeroutput>certutil.exe</computeroutput> manually. Since
+          the certificates are not accompanied on the VirtualBox Guest
+          Additions CD-ROM prior to 4.2, these need to get extracted
+          from a signed VirtualBox executable first.
+        </para>
+
+        <para>
+          In the following examples the required certificates are
+          extracted from the VirtualBox Windows Guest Additions
+          installer on the CD-ROM.
+        </para>
+
+        <para>
+          For a VeriSign Code Signing CA certificate, do the following:
+        </para>
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              Open the Windows Explorer.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Right click on
+              VBoxWindowsAdditions-<replaceable>arch</replaceable>.exe,
+              and choose <emphasis role="bold">Properties</emphasis>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Go to the Digital Signatures tab, choose
+              <emphasis role="bold">Oracle Corporation</emphasis> and
+              click on <emphasis role="bold">Details</emphasis>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              On the General tab, click on <emphasis role="bold">View
+              Certificate</emphasis>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              On the Certification Path tab, select
+              <emphasis role="bold">VeriSign Class 3 Public Primary
+              CA</emphasis>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Click <emphasis role="bold">View Certificate</emphasis>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              On the Details tab, click <emphasis role="bold">Copy to
+              File</emphasis>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              In the displayed wizard choose <emphasis role="bold">DER
+              Encoded Binary X.509 (.CER)</emphasis> and save the
+              certificate file to a local path. Close the wizard.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Close the certificate dialog for Verisign Class 3 Code
+              Signing 2010 CA.
+            </para>
+          </listitem>
+
+        </orderedlist>
+
+        <para>
+          For an Oracle Corporation CA certificate, do the following:
+        </para>
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              Open the Windows Explorer.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Right-click on
+              VBoxWindowsAdditions-<replaceable>arch</replaceable>.exe
+              and choose <emphasis role="bold">Properties</emphasis>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Go to the Digital Signatures tab, choose
+              <emphasis role="bold">Oracle Corporation</emphasis> and
+              click on <emphasis role="bold">Details</emphasis>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              On the General tab, click on <emphasis role="bold">View
+              Certificate</emphasis>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              On the Details tab, click on <emphasis role="bold">Copy to
+              File</emphasis>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              In the displayed wizard choose <emphasis role="bold">DER
+              Encoded Binary X.509 (.CER)</emphasis> and save the
+              certificate file to a local path. Close the wizard
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Close the certificate dialog for Oracle Corporation.
+            </para>
+          </listitem>
+
+        </orderedlist>
+
+        <para>
+          After exporting the two certificates above they can be
+          imported into the certificate store using the
+          <computeroutput>certutil.exe</computeroutput> utility, as
+          follows:
+        </para>
+
+<screen>certutil -addstore -f Root "&lt;Path to
+          exported certificate file&gt;"</screen>
+
+        <para>
+          In order to allow for completely unattended guest
+          installations, you can specify a command line parameter to the
+          install launcher:
+        </para>
+
+<screen>VBoxWindowsAdditions.exe /S</screen>
+
+        <para>
+          This automatically installs the right files and drivers for
+          the corresponding platform, 32-bit or 64-bit.
+        </para>
+
+        <note>
+          <para>
+            By default on an unattended installation on a Vista or
+            Windows 7 guest, there will be the XPDM graphics driver
+            installed. This graphics driver does not support Windows
+            Aero / Direct3D on the guest. Instead, the WDDM graphics
+            driver needs to be installed. To select this driver by
+            default, add the command line parameter
+            <computeroutput>/with_wddm</computeroutput> when invoking
+            the Windows Guest Additions installer. This is only required
+            for Vista and Windows 7.
+          </para>
+        </note>
+
+        <note>
+          <para>
+            For Windows Aero to run correctly on a guest, the guest's
+            VRAM size needs to be configured to at least 128 MB.
+          </para>
+        </note>
+
+        <para>
+          For more options regarding unattended guest installations,
+          consult the command line help by using the command:
+        </para>
+
+<screen>VBoxWindowsAdditions.exe /?</screen>
+
       </sect3>
 
       <sect3 id="windows-guest-file-extraction">
-        <title>Manual file extraction</title>
-
-        <para>If you would like to install the files and drivers manually, you
-        can extract the files from the Windows Guest Additions setup by
-        typing:</para>
-
-        <screen>VBoxWindowsAdditions.exe /extract</screen>
-
-        <para>To explicitly extract the Windows Guest Additions for another
-        platform than the current running one (e.g. 64-bit files on a 32-bit
-        system), you have to execute the appropriate platform installer
-        (<computeroutput>VBoxWindowsAdditions-x86.exe</computeroutput> or
-        <computeroutput>VBoxWindowsAdditions-amd64.exe</computeroutput>) with
-        the <computeroutput>/extract</computeroutput> parameter.</para>
+
+        <title>Manual file Extraction</title>
+
+        <para>
+          If you would like to install the files and drivers manually,
+          you can extract the files from the Windows Guest Additions
+          setup as follows
+        </para>
+
+<screen>VBoxWindowsAdditions.exe /extract</screen>
+
+        <para>
+          To explicitly extract the Windows Guest Additions for another
+          platform than the current running one, such as 64-bit files on
+          a 32-bit system, you must use the appropriate platform
+          installer. Use
+          <computeroutput>VBoxWindowsAdditions-x86.exe</computeroutput>
+          or
+          <computeroutput>VBoxWindowsAdditions-amd64.exe</computeroutput>
+          with the <computeroutput>/extract</computeroutput> parameter.
+        </para>
+
       </sect3>
 
     </sect2>
 
-    <sect2>
+    <sect2 id="additions-linux">
+
       <title>Guest Additions for Linux</title>
 
-      <para>Like the Windows Guest Additions, the VirtualBox Guest Additions
-      for Linux are a set of device drivers and system applications which may
-      be installed in the guest operating system.</para>
-
-      <para>The following Linux distributions are officially supported:</para>
+      <para>
+        Like the Windows Guest Additions, the VirtualBox Guest Additions
+        for Linux are a set of device drivers and system applications
+        which may be installed in the guest operating system.
+      </para>
+
+      <para>
+        The following Linux distributions are officially supported:
+      </para>
 
       <itemizedlist>
-        <listitem>
-          <para>Oracle Linux as of version 5 including UEK kernels;</para>
-        </listitem>
-
-        <listitem>
-          <para>Fedora as of Fedora Core 4;</para>
-        </listitem>
-
-        <listitem>
-          <para>Redhat Enterprise Linux as of version 3;</para>
-        </listitem>
-
-        <listitem>
-          <para>SUSE and openSUSE Linux as of version 9;</para>
-        </listitem>
-
-        <listitem>
-          <para>Ubuntu as of version 5.10.</para>
-        </listitem>
+
+        <listitem>
+          <para>
+            Oracle Linux as of version 5, including UEK kernels
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Fedora as of Fedora Core 4
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Redhat Enterprise Linux as of version 3
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            SUSE and openSUSE Linux as of version 9
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Ubuntu as of version 5.10
+          </para>
+        </listitem>
+
       </itemizedlist>
 
-      <para>Many other distributions are known to work with the Guest
-      Additions.</para>
-
-      <para>The version of the Linux kernel supplied by default in SUSE and
-      openSUSE 10.2, Ubuntu 6.10 (all versions) and Ubuntu 6.06 (server
-      edition) contains a bug which can cause it to crash during startup when
-      it is run in a virtual machine. The Guest Additions work in those
-      distributions.</para>
-
-      <para>Note that some Linux distributions already come with all or part of
-      the VirtualBox Guest Additions. You may choose to keep the distribution's
-      version of the Guest Additions but these are often not up to date and
-      limited in functionality, so we recommend replacing them with the
-      Guest Additions that come with VirtualBox. The VirtualBox Linux Guest
-      Additions installer tries to detect existing installation and replace
-      them but depending on how the distribution integrates the Guest
-      Additions, this may require some manual interaction. It is highly
-      recommended to take a snapshot of the virtual machine before replacing
-      pre-installed Guest Additions.</para>
-
-      <sect3>
+      <para>
+        Many other distributions are known to work with the Guest
+        Additions.
+      </para>
+
+      <para>
+        The version of the Linux kernel supplied by default in SUSE and
+        openSUSE 10.2, Ubuntu 6.10 (all versions) and Ubuntu 6.06
+        (server edition) contains a bug which can cause it to crash
+        during startup when it is run in a virtual machine. The Guest
+        Additions work in those distributions.
+      </para>
+
+      <para>
+        Note that some Linux distributions already come with all or part
+        of the VirtualBox Guest Additions. You may choose to keep the
+        distribution's version of the Guest Additions but these are
+        often not up to date and limited in functionality, so we
+        recommend replacing them with the Guest Additions that come with
+        VirtualBox. The VirtualBox Linux Guest Additions installer tries
+        to detect existing installation and replace them but depending
+        on how the distribution integrates the Guest Additions, this may
+        require some manual interaction. It is highly recommended to
+        take a snapshot of the virtual machine before replacing
+        pre-installed Guest Additions.
+      </para>
+
+      <sect3 id="additions-linux-install">
+
         <title>Installing the Linux Guest Additions</title>
 
-        <para>The VirtualBox Guest Additions for Linux are provided on the
-        same virtual CD-ROM file as the Guest Additions for Windows described
-        above. They also come with an installation program guiding you through
-        the setup process, although, due to the significant differences between
-        Linux distributions, installation may be slightly more complex.</para>
-
-        <para>Installation generally involves the following steps:</para>
+        <para>
+          The VirtualBox Guest Additions for Linux are provided on the
+          same virtual CD-ROM file as the Guest Additions for Windows.
+          See <xref linkend="mountingadditionsiso"/>. They also come
+          with an installation program that guides you through the setup
+          process. However, due to the significant differences between
+          Linux distributions, installation may be slightly more complex
+          when compared to Windows.
+        </para>
+
+        <para>
+          Installation generally involves the following steps:
+        </para>
 
         <orderedlist>
-          <listitem>
-            <para>Before installing the Guest Additions, you will have to
-            prepare your guest system for building external kernel modules.
-            This works similarly as described in <xref
-            linkend="externalkernelmodules" />, except that this step must now
-            be performed in your Linux <emphasis>guest</emphasis> instead of
-            on a Linux host system, as described there.</para>
-
-            <para>If you suspect that something has gone wrong, check that your
-            guest is set up correctly and try executing the command
-            <screen>rcvboxadd setup</screen> as root.</para>
-          </listitem>
-
-          <listitem>
-            <para>Insert the
-            <computeroutput>VBoxGuestAdditions.iso</computeroutput> CD file
-            into your Linux guest's virtual CD-ROM drive, exactly the same way
-            as described for a Windows guest in <xref
-            linkend="mountingadditionsiso" />.</para>
-          </listitem>
-
-          <listitem>
-            <para>Change to the directory where your CD-ROM drive is mounted
-            and execute as root:</para>
-
-            <screen>sh ./VBoxLinuxAdditions.run</screen>
-
-          </listitem>
+
+          <listitem>
+            <para>
+              Before installing the Guest Additions, you prepare your
+              guest system for building external kernel modules. This
+              works as described in
+              <xref
+            linkend="externalkernelmodules" />,
+              except that this step must be performed in your Linux
+              <emphasis>guest</emphasis> instead of on a Linux host
+              system.
+            </para>
+
+            <para>
+              If you suspect that something has gone wrong, check that
+              your guest is set up correctly and run the following
+              command as root:
+            </para>
+
+<screen>rcvboxadd setup</screen>
+          </listitem>
+
+          <listitem>
+            <para>
+              Insert the
+              <computeroutput>VBoxGuestAdditions.iso</computeroutput> CD
+              file into your Linux guest's virtual CD-ROM drive, as
+              described for a Windows guest in
+              <xref
+            linkend="mountingadditionsiso" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Change to the directory where your CD-ROM drive is mounted
+              and run the following command as root:
+            </para>
+
+<screen>sh ./VBoxLinuxAdditions.run</screen>
+          </listitem>
+
         </orderedlist>
+
       </sect3>
 
-      <sect3>
-        <title>Graphics and mouse integration</title>
-
-        <para>In Linux and Solaris guests, VirtualBox graphics and mouse
-        integration goes through the X Window System.  VirtualBox can use
-        the X.Org variant of the system (or XFree86 version 4.3 which is
-        identical to the first X.Org release). During the installation process,
-        the X.Org display server will be set up to use the graphics and mouse
-        drivers which come with the Guest Additions.</para>
-
-        <para>After installing the Guest Additions into a fresh installation of
-        a supported Linux distribution or Solaris system (many unsupported
-        systems will work correctly too), the guest's graphics
-        mode will change to fit the size of the VirtualBox window
-        on the host when it is resized.  You can also ask the guest system to
-        switch to a particular resolution by sending a "video mode hint" using
-        the <computeroutput>VBoxManage</computeroutput> tool.</para>
-
-        <para>Multiple guest monitors are supported in guests using the X.Org
-        server version 1.3 (which is part of release 7.3 of the X Window System
-        version 11) or a later version. The layout of the guest screens can
-        be adjusted as needed using the tools which come with the guest
-        operating system.</para>
-
-        <para>If you want to understand more about the details of how the
-        X.Org drivers are set up (in particular if you wish to use them in a
-        setting which our installer doesn't handle correctly), you should read
-        <xref linkend="guestxorgsetup" />.</para>
+      <sect3 id="additions-linux-graphics-mouse">
+
+        <title>Graphics and Mouse Integration</title>
+
+        <para>
+          In Linux and Solaris guests, VirtualBox graphics and mouse
+          integration goes through the X Window System. VirtualBox can
+          use the X.Org variant of the system, or XFree86 version 4.3
+          which is identical to the first X.Org release. During the
+          installation process, the X.Org display server will be set up
+          to use the graphics and mouse drivers which come with the
+          Guest Additions.
+        </para>
+
+        <para>
+          After installing the Guest Additions into a fresh installation
+          of a supported Linux distribution or Solaris system, many
+          unsupported systems will work correctly too, the guest's
+          graphics mode will change to fit the size of the VirtualBox
+          window on the host when it is resized. You can also ask the
+          guest system to switch to a particular resolution by sending a
+          video mode hint using the
+          <computeroutput>VBoxManage</computeroutput> tool.
+        </para>
+
+        <para>
+          Multiple guest monitors are supported in guests using the
+          X.Org server version 1.3, which is part of release 7.3 of the
+          X Window System version 11, or a later version. The layout of
+          the guest screens can be adjusted as needed using the tools
+          which come with the guest operating system.
+        </para>
+
+        <para>
+          If you want to understand more about the details of how the
+          X.Org drivers are set up, in particular if you wish to use
+          them in a setting which our installer does not handle
+          correctly, see <xref linkend="guestxorgsetup" />.
+        </para>
+
       </sect3>
 
-      <sect3>
+      <sect3 id="additions-linux-updating">
+
         <title>Updating the Linux Guest Additions</title>
 
-        <para>The Guest Additions can simply be updated by going through the
-        installation procedure again with an updated CD-ROM image. This will
-        replace the drivers with updated versions. You should reboot after
-        updating the Guest Additions.</para>
+        <para>
+          The Guest Additions can simply be updated by going through the
+          installation procedure again with an updated CD-ROM image.
+          This will replace the drivers with updated versions. You
+          should reboot after updating the Guest Additions.
+        </para>
+
       </sect3>
 
-      <sect3>
+      <sect3 id="additions-linux-uninstall">
+
         <title>Uninstalling the Linux Guest Additions</title>
 
-        <para>If you have a version of the Guest Additions installed on your
-        virtual machine and wish to remove it without installing new ones, you
-        can do so by inserting the Guest Additions CD image into the virtual
-        CD-ROM drive as described above and running the installer for the
-        current Guest Additions with the "uninstall" parameter from the path
-        that the CD image is mounted on in the guest: <screen>sh ./VBoxLinuxAdditions.run uninstall</screen></para>
-
-        <para>While this will normally work without issues, you may need to do some
-        manual cleanup of the guest (particularly of the XFree86Config or
-        xorg.conf file) in some cases, particularly if the Additions version
-        installed or the guest operating system were very old, or if you made
-        your own changes to the Guest Additions setup after you installed
-        them.</para>
-
-        <para>Starting with version 3.1.0, you can uninstall the Additions by
-        invoking <screen>/opt/VBoxGuestAdditions-@VBOX_VERSION_STRING@/uninstall.sh</screen>Please
-        replace
-        <computeroutput>/opt/VBoxGuestAdditions-@VBOX_VERSION_STRING@</computeroutput>
-        with the correct Guest Additions installation directory.</para>
+        <para>
+          If you have a version of the Guest Additions installed on your
+          virtual machine and wish to remove it without installing new
+          ones, you can do so by inserting the Guest Additions CD image
+          into the virtual CD-ROM drive as described above and running
+          the installer for the current Guest Additions with the
+          <computeroutput>uninstall</computeroutput> parameter from the
+          path that the CD image is mounted on in the guest:
+
+<screen>sh ./VBoxLinuxAdditions.run uninstall</screen>
+        </para>
+
+        <para>
+          While this will normally work without issues, you may need to
+          do some manual cleanup of the guest in some cases, especially
+          of the XFree86Config or xorg.conf file. In particular, if the
+          Additions version installed or the guest operating system were
+          very old, or if you made your own changes to the Guest
+          Additions setup after you installed them.
+        </para>
+
+        <para>
+          Starting with version 3.1.0, you can uninstall the Additions
+          as follows:
+        </para>
+
+<screen>/opt/VBoxGuestAdditions-<replaceable>version</replaceable>/uninstall.sh</screen>
+
+        <para>
+          Replace
+          <computeroutput>/opt/VBoxGuestAdditions-<replaceable>version</replaceable></computeroutput>
+          with the correct Guest Additions installation directory.
+        </para>
+
       </sect3>
+
     </sect2>
 
-    <sect2>
+    <sect2 id="additions-solaris">
+
       <title>Guest Additions for Solaris</title>
 
-      <para>Like the Windows Guest Additions, the VirtualBox Guest Additions
-      for Solaris take the form of a set of device drivers and system
-      applications which may be installed in the guest operating
-      system.</para>
-
-      <para>The following Solaris distributions are officially
-      supported:</para>
+      <para>
+        Like the Windows Guest Additions, the VirtualBox Guest Additions
+        for Solaris take the form of a set of device drivers and system
+        applications which may be installed in the guest operating
+        system.
+      </para>
+
+      <para>
+        The following Solaris distributions are officially supported:
+      </para>
 
       <itemizedlist>
-        <listitem>
-          <para>Solaris 11 including Solaris 11 Express;</para>
-        </listitem>
-
-        <listitem>
-          <para>Solaris 10 (u5 and higher);</para>
-        </listitem>
+
+        <listitem>
+          <para>
+            Solaris 11, including Solaris 11 Express
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Solaris 10 u5 and higher
+          </para>
+        </listitem>
+
       </itemizedlist>
 
-      <para>Other distributions may work if they are based on comparable
-      software releases.</para>
-
-      <sect3>
+      <para>
+        Other distributions may work if they are based on comparable
+        software releases.
+      </para>
+
+      <sect3 id="additions-solaris-install">
+
         <title>Installing the Solaris Guest Additions</title>
 
-        <para>The VirtualBox Guest Additions for Solaris are provided on the
-        same ISO CD-ROM as the Additions for Windows and Linux described
-        above. They also come with an installation program guiding you through
-        the setup process.</para>
-
-        <para>Installation involves the following steps:</para>
+        <para>
+          The VirtualBox Guest Additions for Solaris are provided on the
+          same ISO CD-ROM as the Additions for Windows and Linux. They
+          come with an installation program that guides you through the
+          setup process.
+        </para>
+
+        <para>
+          Installation involves the following steps:
+        </para>
 
         <orderedlist>
-          <listitem>
-            <para>Mount the
-            <computeroutput>VBoxGuestAdditions.iso</computeroutput> file as
-            your Solaris guest's virtual CD-ROM drive, exactly the same way as
-            described for a Windows guest in <xref
-            linkend="mountingadditionsiso" />.</para>
-
-            <para>If in case the CD-ROM drive on the guest doesn't get mounted
-            (observed on some versions of Solaris 10), execute as root:</para>
-
-            <screen>svcadm restart volfs</screen>
-          </listitem>
-
-          <listitem>
-            <para>Change to the directory where your CD-ROM drive is mounted
-            and execute as root:</para>
-
-            <screen>pkgadd -G -d ./VBoxSolarisAdditions.pkg</screen>
-          </listitem>
-
-          <listitem>
-            <para>Choose "1" and confirm installation of the Guest Additions
-            package. After the installation is complete, re-login to X server
-            on your guest to activate the X11 Guest Additions.</para>
-          </listitem>
+
+          <listitem>
+            <para>
+              Mount the
+              <computeroutput>VBoxGuestAdditions.iso</computeroutput>
+              file as your Solaris guest's virtual CD-ROM drive, exactly
+              the same way as described for a Windows guest in
+              <xref
+            linkend="mountingadditionsiso" />.
+            </para>
+
+            <para>
+              If the CD-ROM drive on the guest does not get mounted, as
+              seen with some versions of Solaris 10, run the following
+              command as root:
+            </para>
+
+<screen>svcadm restart volfs</screen>
+          </listitem>
+
+          <listitem>
+            <para>
+              Change to the directory where your CD-ROM drive is mounted
+              and run the following command as root:
+            </para>
+
+<screen>pkgadd -G -d ./VBoxSolarisAdditions.pkg</screen>
+          </listitem>
+
+          <listitem>
+            <para>
+              Choose <emphasis role="bold">1</emphasis> and confirm
+              installation of the Guest Additions package. After the
+              installation is complete, log out and log in to X server
+              on your guest, to activate the X11 Guest Additions.
+            </para>
+          </listitem>
+
         </orderedlist>
+
       </sect3>
 
-      <sect3>
+      <sect3 id="additions-solaris-uninstall">
+
         <title>Uninstalling the Solaris Guest Additions</title>
 
-        <para>The Solaris Guest Additions can be safely removed by removing
-        the package from the guest. Open a root terminal session and
-        execute:</para>
-
-        <para><screen>pkgrm SUNWvboxguest</screen></para>
+        <para>
+          The Solaris Guest Additions can be safely removed by removing
+          the package from the guest. Open a root terminal session and
+          run the following command:
+        </para>
+
+        <para>
+<screen>pkgrm SUNWvboxguest</screen>
+        </para>
+
       </sect3>
 
-      <sect3>
+      <sect3 id="additions-solaris-updating">
+
         <title>Updating the Solaris Guest Additions</title>
 
-        <para>The Guest Additions should be updated by first uninstalling the
-        existing Guest Additions and then installing the new ones. Attempting
-        to install new Guest Additions without removing the existing ones is
-        not possible.</para>
+        <para>
+          The Guest Additions should be updated by first uninstalling
+          the existing Guest Additions and then installing the new ones.
+          Attempting to install new Guest Additions without removing the
+          existing ones is not possible.
+        </para>
+
       </sect3>
+
     </sect2>
 
-    <sect2>
+    <sect2 id="additions-os2">
+
       <title>Guest Additions for OS/2</title>
 
-      <para>VirtualBox also ships with a set of drivers that improve running
-      OS/2 in a virtual machine. Due to restrictions of OS/2 itself, this
-      variant of the Guest Additions has a limited feature set; see <xref
-      linkend="KnownIssues" /> for details.</para>
-
-      <para>The OS/2 Guest Additions are provided on the same ISO CD-ROM as
-      those for the other platforms. As a result, mount the ISO in OS/2 as
-      described previously. The OS/2 Guest Additions are located in the
-      directory <computeroutput>\32bit\OS2</computeroutput>.</para>
-
-      <para>As we do not provide an automatic installer at this time, please
-      refer to the <computeroutput>readme.txt</computeroutput> file in that
-      directory, which describes how to install the OS/2 Guest Additions
-      manually.</para>
+      <para>
+        VirtualBox also ships with a set of drivers that improve running
+        OS/2 in a virtual machine. Due to restrictions of OS/2 itself,
+        this variant of the Guest Additions has a limited feature set.
+        See <xref
+      linkend="KnownIssues" /> for details.
+      </para>
+
+      <para>
+        The OS/2 Guest Additions are provided on the same ISO CD-ROM as
+        those for the other platforms. Mount the ISO in OS/2 as
+        described previously. The OS/2 Guest Additions are located in
+        the directory <computeroutput>\32bit\OS2</computeroutput>.
+      </para>
+
+      <para>
+        We do not provide an automatic installer at this time. See the
+        <computeroutput>readme.txt</computeroutput> file in the CD-ROM
+        directory, which describes how to install the OS/2 Guest
+        Additions manually.
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="sharedfolders">
-    <title>Shared folders</title>
-
-    <para>With the "shared folders" feature of VirtualBox, you can access
-    files of your host system from within the guest system. This is similar
-    how you would use network shares in Windows networks -- except that shared
-    folders do not need require networking, only the Guest Additions. Shared
-    Folders are supported with Windows (2000 or newer), Linux and Solaris
-    guests.</para>
-
-    <para>Shared folders must physically reside on the
-    <emphasis>host</emphasis> and are then shared with the guest, which uses a
-    special file system driver in the Guest Addition to talk to the host. For
-    Windows guests, shared folders are implemented as a pseudo-network
-    redirector; for Linux and Solaris guests, the Guest Additions provide a
-    virtual file system.</para>
-
-    <para>To share a host folder with a virtual machine in VirtualBox, you
-    must specify the path of that folder and choose for it a "share name" that
-    the guest can use to access it. Hence, first create the shared folder on
-    the host; then, within the guest, connect to it.</para>
-
-    <para>There are several ways in which shared folders can be set up for a
-    particular virtual machine:<itemizedlist>
-        <listitem>
-          <para>In the window of a running VM, you can select "Shared folders"
-          from the "Devices" menu, or click on the folder icon on the status
-          bar in the bottom right corner.</para>
-        </listitem>
-
-        <listitem>
-          <para>If a VM is not currently running, you can configure shared
-          folders in each virtual machine's "Settings" dialog.</para>
-        </listitem>
-
-        <listitem>
-          <para>From the command line, you can create shared folders using
-          VBoxManage, as follows: <screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen></para>
-
-          <para>See <xref linkend="vboxmanage-sharedfolder" /> for
-          details.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>There are two types of shares:</para>
+
+    <title>Shared Folders</title>
+
+    <para>
+      With the <emphasis>shared folders</emphasis> feature of
+      VirtualBox, you can access files of your host system from within
+      the guest system. This is similar how you would use network shares
+      in Windows networks, except that shared folders do not need
+      require networking, only the Guest Additions. Shared Folders are
+      supported with Windows 2000 or later, Linux, and Solaris guests.
+    </para>
+
+    <para>
+      Shared folders must physically reside on the
+      <emphasis>host</emphasis> and are then shared with the guest,
+      which uses a special file system driver in the Guest Addition to
+      talk to the host. For Windows guests, shared folders are
+      implemented as a pseudo-network redirector. For Linux and Solaris
+      guests, the Guest Additions provide a virtual file system.
+    </para>
+
+    <para>
+      To share a host folder with a virtual machine in VirtualBox, you
+      must specify the path of that folder and choose for it a
+      <emphasis>share nam</emphasis>e that the guest can use to access
+      it. Hence, first create the shared folder on the host. Then,
+      within the guest, you can connect to it.
+    </para>
+
+    <para>
+      There are several ways in which shared folders can be set up for a
+      particular virtual machine:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          In the window of a running VM, you select
+          <emphasis role="bold">Shared Folders</emphasis> from the
+          <emphasis role="bold">Devices</emphasis> menu, or click on the
+          folder icon on the status bar in the bottom right corner.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          If a VM is not currently running, you can configure shared
+          folders in each virtual machine's Settings dialog.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          From the command line, you can create shared folders using
+          VBoxManage, as follows:
+        </para>
+
+<screen>VBoxManage sharedfolder add "VM name" --name "sharename" --hostpath "C:\test"</screen>
+
+        <para>
+          See <xref linkend="vboxmanage-sharedfolder" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      There are two types of shares:
+    </para>
 
     <orderedlist>
+
       <listitem>
-        <para>VM shares which are only available to the VM for which they have
-        been defined;</para>
+        <para>
+          VM shares which are only available to the VM for which they
+          have been defined.
+        </para>
       </listitem>
 
       <listitem>
-        <para>transient VM shares, which can be added and removed at runtime
-        and do not persist after a VM has stopped; for these, add the
-        <computeroutput>--transient</computeroutput> option to the above
-        command line.</para>
+        <para>
+          Transient VM shares, which can be added and removed at runtime
+          and do not persist after a VM has stopped. For these, add the
+          <computeroutput>--transient</computeroutput> option to the
+          above command line.
+        </para>
       </listitem>
+
     </orderedlist>
 
-    <para>Shared folders have read/write access to the files at the host path
-    by default. To restrict the guest to have read-only access, create a
-    read-only shared folder. This can either be achieved using the GUI or by
-    appending the parameter <computeroutput>--readonly</computeroutput> when
-    creating the shared folder with VBoxManage.</para>
-
-    <para>Starting with version 4.0, VirtualBox shared folders also support
-    symbolic links (<emphasis role="bold">symlinks</emphasis>), under the
-    following conditions:<orderedlist>
-        <listitem>
-          <para>The host operating system must support symlinks (i.e. a Mac,
-          Linux or Solaris host is required).</para>
-        </listitem>
-
-        <listitem>
-          <para>Currently only Linux and Solaris Guest Additions support
-          symlinks.</para>
-        </listitem>
-
-        <listitem>
-          <para>For security reasons the guest OS is not allowed to create
-          symlinks by default. If you trust the guest OS to not abuse the
-          functionality, you can enable creation of symlinks for "sharename"
-          with:
-          <screen>VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/sharename 1</screen></para>
-        </listitem>
-      </orderedlist></para>
+    <para>
+      Shared folders have read/write access to the files at the host
+      path by default. To restrict the guest to have read-only access,
+      create a read-only shared folder. This can either be achieved
+      using the GUI or by appending the parameter
+      <computeroutput>--readonly</computeroutput> when creating the
+      shared folder with VBoxManage.
+    </para>
+
+    <para>
+      Starting with version 4.0, VirtualBox shared folders also support
+      symbolic links (<emphasis>symlinks</emphasis>), under the
+      following conditions:
+    </para>
+
+    <orderedlist>
+
+      <listitem>
+        <para>
+          The host operating system must support symlinks. For example,
+          a Mac OS X, Linux, or Solaris host is required.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Currently only Linux and Solaris Guest Additions support
+          symlinks.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          For security reasons the guest OS is not allowed to create
+          symlinks by default. If you trust the guest OS to not abuse
+          the functionality, you can enable creation of symlinks for a
+          shared folder as follows:
+        </para>
+
+<screen>VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/<replaceable>sharename</replaceable> 1</screen>
+      </listitem>
+
+    </orderedlist>
 
     <sect2 id="sf_mount_manual">
-      <title>Manual mounting</title>
-
-      <para>You can mount the shared folder from inside a VM the same way as
-      you would mount an ordinary network share:</para>
-
-      <para><itemizedlist>
-          <listitem>
-            <para>In a Windows guest, shared folders are browseable and
-            therefore visible in Windows Explorer. So, to attach the host's
-            shared folder to your Windows guest, open Windows Explorer and
-            look for it under "My Networking Places" &rarr; "Entire Network"
-            &rarr; "VirtualBox Shared Folders". By right-clicking on a shared
-            folder and selecting "Map network drive" from the menu that pops
-            up, you can assign a drive letter to that shared folder.</para>
-
-            <para>Alternatively, on the Windows command line, use the
-            following:</para>
-
-            <screen>net use x: \\vboxsvr\sharename</screen>
-
-            <para>While <computeroutput>vboxsvr</computeroutput> is a fixed
-            name (note that <computeroutput>vboxsrv</computeroutput> would
-            also work), replace "x:" with the drive letter that you want to
-            use for the share, and <computeroutput>sharename</computeroutput>
-            with the share name specified with
-            <computeroutput>VBoxManage</computeroutput>.</para>
-          </listitem>
-
-          <listitem>
-            <para>In a Linux guest, use the following command:</para>
-
-            <screen>mount -t vboxsf [-o OPTIONS] sharename mountpoint</screen>
-
-            <para>To mount a shared folder during boot, add the following
-            entry to /etc/fstab:</para>
-
-            <screen>sharename   mountpoint   vboxsf   defaults  0   0</screen>
-          </listitem>
-
-          <listitem>
-            <para>In a Solaris guest, use the following command:</para>
-
-            <screen>mount -F vboxfs [-o OPTIONS] sharename mountpoint</screen>
-
-            <para>Replace <computeroutput>sharename</computeroutput> (use
-            lowercase) with the share name specified with
-            <computeroutput>VBoxManage</computeroutput> or the GUI, and
-            <computeroutput>mountpoint</computeroutput> with the path where
-            you want the share to be mounted on the guest (e.g.
-            <computeroutput>/mnt/share</computeroutput>). The usual mount
-            rules apply, that is, create this directory first if it does not
-            exist yet.</para>
-
-            <para>Here is an example of mounting the shared folder for the
-            user "jack" on Solaris:</para>
-
-            <screen>$ id
+
+      <title>Manual Mounting</title>
+
+      <para>
+        You can mount the shared folder from inside a VM, in the same
+        way as you would mount an ordinary network share:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            In a Windows guest, shared folders are browseable and
+            therefore visible in Windows Explorer. To attach the host's
+            shared folder to your Windows guest, open Windows Explorer
+            and look for the folder in <emphasis role="bold">My
+            Networking Place</emphasis>s, <emphasis role="bold">Entire
+            Network</emphasis>, <emphasis role="bold">VirtualBox Shared
+            Folders</emphasis>. By right-clicking on a shared folder and
+            selecting <emphasis role="bold">Map Network Drive</emphasis>
+            from the menu that pops up, you can assign a drive letter to
+            that shared folder.
+          </para>
+
+          <para>
+            Alternatively, on the Windows command line, use the
+            following command:
+          </para>
+
+<screen>net use x: \\vboxsvr\sharename</screen>
+
+          <para>
+            While <computeroutput>vboxsvr</computeroutput> is a fixed
+            name, note that <computeroutput>vboxsrv</computeroutput>
+            would also work, replace <replaceable>x:</replaceable> with
+            the drive letter that you want to use for the share, and
+            <replaceable>sharename</replaceable> with the share name
+            specified with <computeroutput>VBoxManage</computeroutput>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            In a Linux guest, use the following command:
+          </para>
+
+<screen>mount -t vboxsf [-o OPTIONS] sharename mountpoint</screen>
+
+          <para>
+            To mount a shared folder during boot, add the following
+            entry to <computeroutput>/etc/fstab</computeroutput>:
+          </para>
+
+<screen>sharename   mountpoint   vboxsf   defaults  0   0</screen>
+        </listitem>
+
+        <listitem>
+          <para>
+            In a Solaris guest, use the following command:
+          </para>
+
+<screen>mount -F vboxfs [-o OPTIONS] sharename mountpoint</screen>
+
+          <para>
+            Replace <replaceable>sharename</replaceable>, use a
+            lowercase string, with the share name specified with
+            <computeroutput>VBoxManage</computeroutput> or the GUI.
+            Replace <replaceable>mountpoint</replaceable> with the path
+            where you want the share to be mounted on the guest, such as
+            <computeroutput>/mnt/share</computeroutput>. The usual mount
+            rules apply. For example, create this directory first if it
+            does not exist yet.
+          </para>
+
+          <para>
+            Here is an example of mounting the shared folder for the
+            user jack on Solaris:
+          </para>
+
+<screen>$ id
 uid=5000(jack) gid=1(other)
 $ mkdir /export/home/jack/mount
@@ -941,214 +1402,330 @@
 $</screen>
 
-            <para>Beyond the standard options supplied by the
-            <computeroutput>mount</computeroutput> command, the following are
-            available:</para>
-
-            <screen>iocharset CHARSET</screen>
-
-            <para>to set the character set used for I/O operations. Note that
-            on Linux guests, if the "iocharset" option is not specified then
-            the Guest Additions driver will attempt to use the character set
-            specified by the CONFIG_NLS_DEFAULT kernel option.  If this option
-            is not set either then UTF-8 will be used. Also,</para>
-
-            <screen>convertcp CHARSET</screen>
-
-            <para>is available in order to specify the character set used for
-            the shared folder name (utf8 by default).</para>
-
-            <para>The generic mount options (documented in the mount manual
-            page) apply also. Especially useful are the options
+          <para>
+            Beyond the standard options supplied by the
+            <computeroutput>mount</computeroutput> command, the
+            following are available:
+          </para>
+
+<screen>iocharset CHARSET</screen>
+
+          <para>
+            This option sets the character set used for I/O operations.
+            Note that on Linux guests, if the
+            <computeroutput>iocharset</computeroutput> option is not
+            specified, then the Guest Additions driver will attempt to
+            use the character set specified by the CONFIG_NLS_DEFAULT
+            kernel option. If this option is not set either, then UTF-8
+            is used.
+          </para>
+
+<screen>convertcp CHARSET</screen>
+
+          <para>
+            This option specifies the character set used for the shared
+            folder name. This is UTF-8 by default.
+          </para>
+
+          <para>
+            The generic mount options, documented in the
+            <computeroutput>mount</computeroutput> manual page, apply
+            also. Especially useful are the options
             <computeroutput>uid</computeroutput>,
             <computeroutput>gid</computeroutput> and
-            <computeroutput>mode</computeroutput>, as they allow access by
-            normal users (in read/write mode, depending on the settings) even
-            if root has mounted the filesystem.</para>
-          </listitem>
-        </itemizedlist></para>
+            <computeroutput>mode</computeroutput>, as they can allow
+            access by normal users in read/write mode, depending on the
+            settings, even if root has mounted the filesystem.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </sect2>
 
     <sect2 id="sf_mount_auto">
-      <title>Automatic mounting</title>
-
-      <para>Starting with version 4.0, VirtualBox can mount shared folders
-      automatically, at your option. If automatic mounting is enabled for a
-      specific shared folder, the Guest Additions will automatically mount
-      that folder as soon as a user logs into the guest OS. The details depend
-      on the guest OS type:<itemizedlist>
-          <listitem>
-            <para>With <emphasis role="bold">Windows guests,</emphasis> any
-            auto-mounted shared folder will receive its own drive letter (e.g.
-            <computeroutput>E:</computeroutput>) depending on the free drive
-            letters remaining in the guest.</para>
-
-            <para>If there no free drive letters left, auto-mounting will
-            fail; as a result, the number of auto-mounted shared folders is
-            typically limited to 22 or less with Windows guests.</para>
-          </listitem>
-
-          <listitem>
-            <para>With <emphasis role="bold">Linux guests,</emphasis>
-            auto-mounted shared folders are mounted into the
-            <computeroutput>/media</computeroutput> directory, along with the
-            prefix <computeroutput>sf_</computeroutput>. For example, the
-            shared folder <computeroutput>myfiles</computeroutput> would be
-            mounted to <computeroutput>/media/sf_myfiles</computeroutput> on
-            Linux and <computeroutput>/mnt/sf_myfiles</computeroutput> on
-            Solaris.</para>
-
-            <para>The guest property
+
+      <title>Automatic Mounting</title>
+
+      <para>
+        Starting with version 4.0, VirtualBox provides the option to
+        mount shared folders automatically If automatic mounting is
+        enabled for a specific shared folder, the Guest Additions will
+        automatically mount that folder as soon as a user logs in to the
+        guest OS. The details depend on the guest OS type, as follows:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Windows guests.</emphasis> Any
+            auto-mounted shared folder will receive its own drive
+            letter, such as <computeroutput>E:</computeroutput>,
+            depending on the free drive letters remaining in the guest.
+          </para>
+
+          <para>
+            If there are no free drive letters left, auto-mounting will
+            fail. As a result, the number of auto-mounted shared folders
+            is typically limited to 22 or less with Windows guests.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Linux guests.</emphasis> Auto-mounted
+            shared folders are mounted into the
+            <computeroutput>/media</computeroutput> directory, along
+            with the prefix <computeroutput>sf_</computeroutput>. For
+            example, the shared folder
+            <computeroutput>myfiles</computeroutput> would be mounted to
+            <computeroutput>/media/sf_myfiles</computeroutput> on Linux
+            and <computeroutput>/mnt/sf_myfiles</computeroutput> on
+            Solaris.
+          </para>
+
+          <para>
+            The guest property
             <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountPrefix</computeroutput>
-            determines the prefix that is used. Change that guest property to
-            a value other than "sf" to change that prefix; see <xref
-            linkend="guestadd-guestprops" /> for details.<note>
-                <para>Access to auto-mounted shared folders is only
-                granted to the user group
-                <computeroutput>vboxsf</computeroutput>, which is created by
-                the VirtualBox Guest Additions installer. Hence guest users
-                have to be member of that group to have read/write
-                access or to have read-only access in case the folder is not
-                mapped writable.</para>
-              </note></para>
-
-            <para>To change the mount directory to something other than
-            <computeroutput>/media</computeroutput>, you can set the guest
-            property
-            <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountDir</computeroutput>.</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="bold">Solaris guests</emphasis> behave like
-            Linux guests except that <computeroutput>/mnt</computeroutput> is
-            used as the default mount directory instead of
-            <computeroutput>/media</computeroutput>.</para>
-          </listitem>
-        </itemizedlist></para>
-
-      <para>To have any changes to auto-mounted shared folders applied while a
-      VM is running, the guest OS needs to be rebooted. (This applies only to
-      auto-mounted shared folders, not the ones which are mounted
-      manually.)</para>
+            determines the prefix that is used. Change that guest
+            property to a value other than
+            <computeroutput>sf</computeroutput> to use another prefix.
+            See <xref
+            linkend="guestadd-guestprops" />.
+          </para>
+
+          <note>
+            <para>
+              Access to auto-mounted shared folders is only granted to
+              the user group <computeroutput>vboxsf</computeroutput>,
+              which is created by the VirtualBox Guest Additions
+              installer. Therefore, guest users have to be member of
+              that group to have read/write access, or to have read-only
+              access if the folder is not mapped writable.
+            </para>
+          </note>
+
+          <para>
+            To change the mount directory to something other than
+            <computeroutput>/media</computeroutput>, you can set the
+            guest property
+            <computeroutput>/VirtualBox/GuestAdd/SharedFolders/MountDir</computeroutput>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Solaris guests</emphasis> behave like
+            Linux guests, except that
+            <computeroutput>/mnt</computeroutput> is used as the default
+            mount directory instead of
+            <computeroutput>/media</computeroutput>.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        To have any changes to auto-mounted shared folders applied while
+        a VM is running, the guest OS needs to be rebooted. This applies
+        only to auto-mounted shared folders, not the ones which are
+        mounted manually.
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="guestadd-dnd">
+
     <title>Drag and Drop</title>
 
-    <para>Starting with version 5.0, VirtualBox supports to drag and drop content
-    from the host to the guest and vice versa. For this to work the latest Guest
-    Additions must be installed on the guest.</para>
-
-    <para>Drag and drop transparently allows copying or opening files, directories
-    and even certain clipboard formats from one end to the other, e.g. from the
-    host to the guest or from the guest to the host. One then can perform drag and
-    drop operations between the host and a VM as it would be a native drag and drop
-    operation on the host OS.</para>
-
-    <para>At the moment drag and drop is implemented for Windows- and X-Windows-based
-    systems, both, on host and guest side. As X-Windows sports different drag and drop
-    protocols only the most used one, XDND, is supported for now. Applications using
-    other protocols (such as Motif or OffiX) will not be recognized by VirtualBox.</para>
-
-    <para>In context of using drag and drop the origin of the data is called
-    <emphasis role="bold">source</emphasis>, that is, where the actual data comes
-    from and is specified. On the other hand there is the
-    <emphasis role="bold">target</emphasis>, which specifies where the data from
-    the source should go to. Transferring data from the source to the target can
-    be done in various ways, e.g. copying, moving or linking.<footnote><para>At
-    the moment only copying of data is supported. Moving or linking is not yet
-    implemented.</para></footnote></para>
-
-    <para>When transferring data from the host to the guest OS, the host in
-    this case is the source, whereas the guest OS is the target. However, when
-    doing it the other way around, that is, transferring data from the guest OS
-    to the host, the guest OS this time became the source and the host is the
-    target.</para>
-
-    <para>For security reasons drag and drop can be configured at runtime on a
-    per-VM basis either using the "Drag and Drop" menu item in the "Devices" menu
-    of the virtual machine or VBoxManage. The following four modes are
-    available:</para>
-
-    <para><mediaobject>
-      <imageobject>
-        <imagedata align="center" fileref="images/dnd-modes.png"
+    <para>
+      Starting with version 5.0, VirtualBox enables you to drag and drop
+      content from the host to the guest, and vice versa. For this to
+      work the latest Guest Additions must be installed on the guest.
+    </para>
+
+    <para>
+      Drag and drop transparently allows copying or opening files,
+      directories, and even certain clipboard formats from one end to
+      the other. for example, from the host to the guest or from the
+      guest to the host. You then can perform drag and drop operations
+      between the host and a VM, as it would be a native drag and drop
+      operation on the host OS.
+    </para>
+
+    <para>
+      At the moment drag and drop is implemented for Windows-based and
+      X-Windows-based systems, both on the host and guest side. As
+      X-Windows supports many different drag and drop protocols only the
+      most common one, XDND, is supported for now. Applications using
+      other protocols, such as Motif or OffiX, will not be recognized by
+      VirtualBox.
+    </para>
+
+    <para>
+      In the context of using drag and drop, the origin of the data is
+      called the <emphasis>source</emphasis>. That is, where the actual
+      data comes from and is specified. The <emphasis>target</emphasis>
+      specifies where the data from the source should go to.
+      Transferring data from the source to the target can be done in
+      various ways, such as copying, moving, or linking.
+
+      <footnote>
+
+        <para>
+          At the moment only copying of data is supported. Moving or
+          linking is not yet implemented.
+        </para>
+
+      </footnote>
+    </para>
+
+    <para>
+      When transferring data from the host to the guest OS, the host in
+      this case is the source, whereas the guest OS is the target.
+      However, when transferring data from the guest OS to the host, the
+      guest OS this time became the source and the host is the target.
+    </para>
+
+    <para>
+      For security reasons drag and drop can be configured at runtime on
+      a per-VM basis either using the <emphasis role="bold">Drag and
+      Drop</emphasis> menu item in the "Devices" menu of the virtual
+      machine or VBoxManage. The following modes are available:
+    </para>
+
+    <para>
+      <mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/dnd-modes.png"
                    width="10cm" />
         </imageobject>
-      </mediaobject></para>
+      </mediaobject>
+    </para>
 
     <itemizedlist>
+
       <listitem>
-        <para><emphasis role="bold">Disabled</emphasis> disables the drag and drop
-        entirely. This is the default when creating new VMs.</para>
+        <para>
+          <emphasis role="bold">Disabled.</emphasis> Disables the drag
+          and drop feature entirely. This is the default when creating
+          new VMs.
+        </para>
       </listitem>
+
       <listitem>
-        <para><emphasis role="bold">Host To Guest</emphasis> enables performing
-        drag and drop operations from the host to the guest only.</para>
+        <para>
+          <emphasis role="bold">Host To Guest.</emphasis> Enables drag
+          and drop operations from the host to the guest only.
+        </para>
       </listitem>
+
       <listitem>
-        <para><emphasis role="bold">Guest To Host</emphasis> enables performing
-        drag and drop operations from the guest to the host only.</para>
+        <para>
+          <emphasis role="bold">Guest To Host.</emphasis> Enables drag
+          and drop operations from the guest to the host only.
+        </para>
       </listitem>
+
       <listitem>
-        <para><emphasis role="bold">Bidirectional</emphasis> enables performing
-        drag and drop operations to both directions, e.g. from the host to the guest
-        and vice versa.</para>
+        <para>
+          <emphasis role="bold">Bidirectional.</emphasis> Enables drag
+          and drop operations in both directions. From from the host to
+          the guest, and from the guest to the host.
+        </para>
       </listitem>
+
     </itemizedlist>
 
-    <note><para>Drag and drop support depends on the frontend being used; at the
-    moment only the VirtualBox Manager frontend provides this
-    functionality.</para></note>
-
-    <para>To use VBoxManage for controlling the current drag and drop mode, see <xref
-    linkend="vboxmanage" />. The commands <computeroutput>modifyvm</computeroutput>
-    and <computeroutput>controlvm</computeroutput> allow setting the VM's current
-    drag and drop mode via command line.</para>
+    <note>
+      <para>
+        Drag and drop support depends on the frontend being used. At the
+        moment, only the VirtualBox Manager frontend provides this
+        functionality.
+      </para>
+    </note>
+
+    <para>
+      To use VBoxManage for controlling the current drag and drop mode,
+      see <xref
+    linkend="vboxmanage" />. The commands
+      <computeroutput>modifyvm</computeroutput> and
+      <computeroutput>controlvm</computeroutput> allow setting of the
+      VM's current drag and drop mode via the command line.
+    </para>
 
     <sect2 id="guestadd-dnd-formats">
-      <title>Supported formats</title>
-
-      <para>As VirtualBox can run on a variety of host OSes and also supports a wide
-      range of guests, certain data formats must be translated after those
-      got transferred over so that the target OS (that is, the side which receiving the
-      data) is able to handle them in an appropriate manner.</para>
-
-      <note><para>When dragging files however, no data conversion is done in any way, e.g.
-      when transferring a file from a Linux guest to a Windows host the Linux-specific
-      line endings won't be converted to Windows ones.</para></note>
-
-      <para>The following formats are handled by the VirtualBox drag and drop service:
-        <itemizedlist>
-          <listitem>
-            <para><emphasis role="bold">Plain text</emphasis>, from applications such as
-            text editors, internet browsers and terminal windows</para>
-          </listitem>
-          <listitem>
-            <para><emphasis role="bold">Files</emphasis>, from file managers such
-            as Windows explorer, Nautilus and Finder</para>
-          </listitem>
-          <listitem>
-            <para><emphasis role="bold">Directories</emphasis>, where the same applies
-            as for files</para>
-          </listitem>
-        </itemizedlist>
-      </para>
+
+      <title>Supported Formats</title>
+
+      <para>
+        As VirtualBox can run on a variety of host operating systems and
+        also supports a wide range of guests, certain data formats must
+        be translated after transfer. This is so that the target
+        operating system, which receiving the data, is able to handle
+        them in an appropriate manner.
+      </para>
+
+      <note>
+        <para>
+          When dragging files no data conversion is done in any way. For
+          example, when transferring a file from a Linux guest to a
+          Windows host the Linux-specific line endings are not converted
+          to Windows line endings.
+        </para>
+      </note>
+
+      <para>
+        The following formats are handled by the VirtualBox drag and
+        drop service:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Plain text:</emphasis> From
+            applications such as text editors, internet browsers and
+            terminal windows.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Files:</emphasis> From file managers
+            such as Windows Explorer, Nautilus, and Finder.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Directories:</emphasis> For
+            directories, the same formats apply as for files.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </sect2>
 
     <sect2 id="guestadd-dnd-limitations">
-      <title>Known limitations</title>
-
-      <para>The following limitations are known:
-        <itemizedlist>
-          <listitem>
-            <para>On Windows hosts, dragging and dropping content from
-            <emphasis role="bold">UAC-elevated (User Account Control)</emphasis> programs
-            to non-UAC-elevated programs and vice versa is now allowed. So when starting
-            VirtualBox with Administrator privileges then drag and drop will not work with
-            the Windows Explorer which runs with regular user privileges by default.</para>
-          </listitem>
-        </itemizedlist>
-      </para>
+
+      <title>Known Limitations</title>
+
+      <para>
+        The following limitations are known for drag and drop:
+      </para>
+
+      <para>
+        On Windows hosts, dragging and dropping content between
+        UAC-elevated (User Account Control) programs and
+        non-UAC-elevated programs is not allowed. If you start
+        VirtualBox with Administrator privileges then drag and drop will
+        not work with Windows Explorer, which runs with regular user
+        privileges by default.
+      </para>
+
     </sect2>
 
@@ -1156,247 +1733,379 @@
 
   <sect1 id="guestadd-video">
-    <title>Hardware-accelerated graphics</title>
+
+    <title>Hardware-Accelerated Graphics</title>
 
     <sect2 id="guestadd-3d">
-      <title>Hardware 3D acceleration (OpenGL and Direct3D 8/9)</title>
-
-      <para>The VirtualBox Guest Additions contain experimental hardware 3D
-      support for Windows, Linux and Solaris guests.<footnote>
-          <para>OpenGL support for Windows guests was added with VirtualBox
-          2.1; support for Linux and Solaris followed with VirtualBox 2.2.
-          With VirtualBox 3.0, Direct3D 8/9 support was added for Windows
-          guests. OpenGL 2.0 is now supported as well.
-          With VirtualBox 4.1 Windows Aero theme support is added for
-          Windows Vista and Windows 7 guests (experimental)</para>
-        </footnote></para>
-
-      <para>With this feature, if an application inside your virtual machine
-      uses 3D features through the OpenGL or Direct3D 8/9 programming
-      interfaces, instead of emulating them in software (which would be slow),
-      VirtualBox will attempt to use your host's 3D hardware. This works for
-      all supported host platforms (Windows, Mac, Linux, Solaris), provided
-      that your host operating system can make use of your accelerated 3D
-      hardware in the first place.</para>
-
-      <para>The 3D acceleration currently has the following
-      preconditions:<orderedlist>
-          <listitem>
-            <para>It is only available for certain Windows, Linux and Solaris
-            guests. In particular:<itemizedlist>
-                <listitem>
-                  <para>3D acceleration with Windows guests requires Windows
-                  2000, Windows XP, Vista or Windows 7. Both OpenGL and
-                  Direct3D 8/9 (not with Windows 2000) are supported
-                  (experimental).</para>
-                </listitem>
-
-                <listitem>
-                  <para>OpenGL on Linux requires kernel 2.6.27 and higher as
-                  well as X.org server version 1.5 and higher. Ubuntu 10.10
-                  and Fedora 14 have been tested and confirmed as
-                  working.</para>
-                </listitem>
-
-                <listitem>
-                  <para>OpenGL on Solaris guests requires X.org server version
-                  1.5 and higher.</para>
-                </listitem>
-              </itemizedlist></para>
-          </listitem>
-
-          <listitem>
-            <para>The Guest Additions must be installed.<note>
-                <para>For the basic Direct3D acceleration to work in a Windows Guest,
-                VirtualBox needs to replace Windows system files in the
-                virtual machine. As a result, the Guest Additions installation
-                program offers Direct3D acceleration as an option that must
-                be explicitly enabled. Also, you must install the Guest
-                Additions in "Safe Mode". This does <emphasis role="bold">not</emphasis>
-                apply to the WDDM Direct3D video driver available for Vista
-                and higher, see <xref linkend="KnownIssues" /> for details.</para></note>
+
+      <title>Hardware 3D Acceleration (OpenGL and Direct3D 8/9)</title>
+
+      <para>
+        The VirtualBox Guest Additions contain experimental hardware 3D
+        support for Windows, Linux, and Solaris guests.
+
+        <footnote>
+
+          <para>
+            OpenGL support for Windows guests was added with VirtualBox
+            2.1; support for Linux and Solaris followed with VirtualBox
+            2.2. With VirtualBox 3.0, Direct3D 8/9 support was added for
+            Windows guests. OpenGL 2.0 is now supported as well. With
+            VirtualBox 4.1 Windows Aero theme support is added for
+            Windows Vista and Windows 7 guests (experimental)
+          </para>
+
+        </footnote>
+      </para>
+
+      <para>
+        With this feature, if an application inside your virtual machine
+        uses 3D features through the OpenGL or Direct3D 8/9 programming
+        interfaces, instead of emulating them in software, which would
+        be slow, VirtualBox will attempt to use your host's 3D hardware.
+        This works for all supported host platforms, provided that your
+        host operating system can make use of your accelerated 3D
+        hardware in the first place.
+      </para>
+
+      <para>
+        The 3D acceleration feature currently has the following
+        preconditions:
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+          <para>
+            It is only available for certain Windows, Linux, and Solaris
+            guests. In particular:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                3D acceleration with Windows guests requires Windows
+                2000, Windows XP, Vista or Windows 7. Both OpenGL and
+                Direct3D 8/9 (not with Windows 2000) are supported
+                (experimental).
               </para>
-          </listitem>
-
-          <listitem>
-            <para>Because 3D support is still experimental at this time, it is
-            disabled by default and must be <emphasis role="bold">manually
-            enabled</emphasis> in the VM settings (see <xref
-            linkend="generalsettings" />).<note>
+            </listitem>
+
+            <listitem>
+              <para>
+                OpenGL on Linux requires kernel 2.6.27 and higher as
+                well as X.org server version 1.5 and higher. Ubuntu
+                10.10 and Fedora 14 have been tested and confirmed as
+                working.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                OpenGL on Solaris guests requires X.org server version
+                1.5 and higher.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para>
+            The Guest Additions must be installed.
+          </para>
+
+          <note>
+            <para>
+              For the basic Direct3D acceleration to work in a Windows
+              Guest, VirtualBox needs to replace Windows system files in
+              the virtual machine. As a result, the Guest Additions
+              installation program offers Direct3D acceleration as an
+              option that must be explicitly enabled. Also, you must
+              install the Guest Additions in Safe Mode. This does
+              <emphasis>not</emphasis> apply to the WDDM Direct3D video
+              driver available for Vista and higher. See
+              <xref linkend="KnownIssues" /> for details.
+            </para>
+          </note>
+        </listitem>
+
+        <listitem>
+          <para>
+            Because 3D support is still experimental at this time, it is
+            disabled by default and must be <emphasis>manually
+            enabled</emphasis> in the VM settings. See
+            <xref
+            linkend="generalsettings" />.
+          </para>
+
+          <note>
             <para>
               Untrusted guest systems should not be allowed to use
-              VirtualBox's 3D acceleration features, just as untrusted host
-              software should not be allowed to use 3D acceleration.  Drivers
-              for 3D hardware are generally too complex to be made properly
-              secure and any software which is allowed to access them may be
-              able to compromise the operating system running them.  In
-              addition, enabling 3D acceleration gives the guest direct access
-              to a large body of additional program code in the VirtualBox
-              host process which it might conceivably be able to use to crash
-              the virtual machine.
-            </para>
-            </note></para>
-          </listitem>
-        </orderedlist></para>
-
-      <para>To enable Aero theme support,
-      the VirtualBox WDDM video driver must be installed,
-      which is available with the Guest Additions installation.
-      The WDDM driver is not installed by default for Vista and Windows 7
-      guest and must be <emphasis role="bold">manually
-      selected</emphasis> in the Guest Additions installer by answering "No"
-      in the "Would you like to install basic Direct3D support" dialog
-      displayed when the Direct3D feature is selected.</para>
-
-      <para>The Aero theme is not enabled by default. To enable it
-        <itemizedlist>
-          <listitem>
-            <para>In Windows Vista guest: right-click on the desktop, in the
-            context menu select "Personalize", then select "Windows Color and Appearance"
-            in the "Personalization" window, in the "Appearance Settings" dialog select
-            "Windows Aero" and press "OK"</para>
-          </listitem>
-          <listitem>
-            <para>In Windows 7 guest: right-click on the desktop, in the
-            context menu select "Personalize" and select any Aero theme
-            in the "Personalization" window</para>
-          </listitem>
-        </itemizedlist>
-      </para>
-
-      <para>Technically, VirtualBox implements this by installing an
-      additional hardware 3D driver inside your guest when the Guest Additions
-      are installed. This driver acts as a hardware 3D driver and reports to
-      the guest operating system that the (virtual) hardware is capable of 3D
-      hardware acceleration. When an application in the guest then requests
-      hardware acceleration through the OpenGL or Direct3D programming
-      interfaces, these are sent to the host through a special communication
-      tunnel implemented by VirtualBox, and then the <emphasis>host</emphasis>
-      performs the requested 3D operation via the host's programming
-      interfaces.</para>
+              VirtualBox's 3D acceleration features, just as untrusted
+              host software should not be allowed to use 3D
+              acceleration. Drivers for 3D hardware are generally too
+              complex to be made properly secure and any software which
+              is allowed to access them may be able to compromise the
+              operating system running them. In addition, enabling 3D
+              acceleration gives the guest direct access to a large body
+              of additional program code in the VirtualBox host process
+              which it might conceivably be able to use to crash the
+              virtual machine.
+            </para>
+          </note>
+        </listitem>
+
+      </orderedlist>
+
+      <para>
+        To enable Aero theme support, the VirtualBox WDDM video driver
+        must be installed, which is available with the Guest Additions
+        installation. The WDDM driver is not installed by default for
+        Vista and Windows 7 guest and must be <emphasis>manually
+        selected</emphasis> in the Guest Additions installer by clicking
+        <emphasis role="bold">No</emphasis> in the
+        <emphasis role="bold">Would You Like to Install Basic Direct3D
+        Support</emphasis> dialog displayed when the Direct3D feature is
+        selected.
+      </para>
+
+      <para>
+        The Aero theme is not enabled by default. To enable it, do the
+        following:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Windows Vista guests:</emphasis>
+            Right-click on the desktop and select
+            <emphasis role="bold">Personalize</emphasis>, then select
+            <emphasis role="bold">Windows Color and
+            Appearance</emphasis> in the Personalization window. In the
+            Appearance Settings dialog, select
+            <emphasis role="bold">Windows Aero</emphasis> and click
+            <emphasis role="bold">OK</emphasis>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Windows 7 guests:</emphasis>
+            Right-click on the desktop and select
+            <emphasis role="bold">Personalize</emphasis>. Select any
+            Aero theme in the Personalization window.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Technically, VirtualBox implements this by installing an
+        additional hardware 3D driver inside your guest when the Guest
+        Additions are installed. This driver acts as a hardware 3D
+        driver and reports to the guest operating system that the
+        (virtual) hardware is capable of 3D hardware acceleration. When
+        an application in the guest then requests hardware acceleration
+        through the OpenGL or Direct3D programming interfaces, these are
+        sent to the host through a special communication tunnel
+        implemented by VirtualBox, and then the
+        <emphasis>host</emphasis> performs the requested 3D operation
+        via the host's programming interfaces.
+      </para>
+
     </sect2>
 
     <sect2 id="guestadd-2d">
-      <title>Hardware 2D video acceleration for Windows guests</title>
-
-      <para>Starting with version 3.1, the VirtualBox Guest Additions contain
-      experimental hardware 2D video acceleration support for Windows
-      guests.</para>
-
-      <para>With this feature, if an application (e.g. a video player) inside
-      your Windows VM uses 2D video overlays to play a movie clip, then
-      VirtualBox will attempt to use your host's video acceleration hardware
-      instead of performing overlay stretching and color conversion in
-      software (which would be slow). This currently works for Windows, Linux
-      and Mac host platforms, provided that your host operating system can
-      make use of 2D video acceleration in the first place.</para>
-
-      <para>The 2D video acceleration currently has the following
-      preconditions:<orderedlist>
-          <listitem>
-            <para>It is only available for Windows guests (XP or
-            later).</para>
-          </listitem>
-
-          <listitem>
-            <para>The Guest Additions must be installed.</para>
-          </listitem>
-
-          <listitem>
-            <para>Because 2D support is still experimental at this time, it is
-            disabled by default and must be <emphasis role="bold">manually
-            enabled</emphasis> in the VM settings (see <xref
-            linkend="generalsettings" />).</para>
-          </listitem>
-        </orderedlist></para>
-
-      <para>Technically, VirtualBox implements this by exposing video overlay
-      DirectDraw capabilities in the Guest Additions video driver. The driver
-      sends all overlay commands to the host through a special communication
-      tunnel implemented by VirtualBox. On the host side, OpenGL is then used
-      to implement color space transformation and scaling</para>
+
+      <title>Hardware 2D Video Acceleration for Windows Guests</title>
+
+      <para>
+        Starting with version 3.1, the VirtualBox Guest Additions
+        contain experimental hardware 2D video acceleration support for
+        Windows guests.
+      </para>
+
+      <para>
+        With this feature, if an application such as a video player
+        inside your Windows VM uses 2D video overlays to play a movie
+        clip, then VirtualBox will attempt to use your host's video
+        acceleration hardware instead of performing overlay stretching
+        and color conversion in software, which would be slow. This
+        currently works for Windows, Linux and Mac host platforms,
+        provided that your host operating system can make use of 2D
+        video acceleration in the first place.
+      </para>
+
+      <para>
+        Hardware 2D video acceleration currently has the following
+        preconditions:
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+          <para>
+            Only available for Windows guests (XP or later).
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Guest Additions must be installed.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Because 2D support is still experimental at this time, it is
+            disabled by default and must be <emphasis>manually
+            enabled</emphasis> in the VM settings. See
+            <xref
+            linkend="generalsettings" />.
+          </para>
+        </listitem>
+
+      </orderedlist>
+
+      <para>
+        Technically, VirtualBox implements this by exposing video
+        overlay DirectDraw capabilities in the Guest Additions video
+        driver. The driver sends all overlay commands to the host
+        through a special communication tunnel implemented by
+        VirtualBox. On the host side, OpenGL is then used to implement
+        color space transformation and scaling
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="seamlesswindows">
-    <title>Seamless windows</title>
-
-    <para>With the "seamless windows" feature of VirtualBox, you can have the
-    windows that are displayed within a virtual machine appear side by side
-    next to the windows of your host. This feature is supported for the
-    following guest operating systems (provided that the Guest Additions are
-    installed):<itemizedlist>
-        <listitem>
-          <para>Windows guests (support added with VirtualBox 1.5);</para>
-        </listitem>
-
-        <listitem>
-          <para>Supported Linux or Solaris guests running the X Window System
-          (added with VirtualBox 1.6).</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>After seamless windows are enabled (see below), VirtualBox
-    suppresses the display of the Desktop background of your guest, allowing
-    you to run the windows of your guest operating system seamlessly next to
-    the windows of your host:</para>
-
-    <para><mediaobject>
-        <imageobject>
-          <imagedata align="center" fileref="images/seamless.png" width="14cm" />
-        </imageobject>
-      </mediaobject>To enable seamless mode, after starting the virtual
-    machine, press the Host key (normally the right control key) together with
-    "L". This will enlarge the size of the VM's display to the size of your
-    host screen and mask out the guest operating system's background. To go
-    back to the "normal" VM display (i.e. to disable seamless windows), press
-    the Host key and "L" again.</para>
+
+    <title>Seamless Windows</title>
+
+    <para>
+      With the <emphasis>seamless windows</emphasis> feature of
+      VirtualBox, you can have the windows that are displayed within a
+      virtual machine appear side by side next to the windows of your
+      host. This feature is supported for the following guest operating
+      systems, provided that the Guest Additions are installed:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Windows guests (support added with VirtualBox 1.5)
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Supported Linux or Solaris guests running the X Window System
+          (added with VirtualBox 1.6)
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      After seamless windows are enabled, VirtualBox suppresses the
+      display of the desktop background of your guest, allowing you to
+      run the windows of your guest operating system seamlessly next to
+      the windows of your host.
+    </para>
+
+    <mediaobject>
+      <imageobject>
+        <imagedata align="center" fileref="images/seamless.png" width="14cm" />
+      </imageobject>
+    </mediaobject>
+
+    <para>
+      To enable seamless mode, after starting the virtual machine, press
+      the <emphasis role="bold">Host key + L</emphasis>. The Host key is
+      normally the right control key. This will enlarge the size of the
+      VM's display to the size of your host screen and mask out the
+      guest operating system's background. To disable seamless windows
+      and go back to the normal VM display, press the Host key + L
+      again.
+    </para>
+
   </sect1>
 
   <sect1 id="guestadd-guestprops">
-    <title>Guest properties</title>
-
-    <para>Starting with version 2.1, VirtualBox allows for requesting certain
-    properties from a running guest, provided that the VirtualBox Guest
-    Additions are installed and the VM is running. This is good for two
-    things:<orderedlist>
-        <listitem>
-          <para>A number of predefined VM characteristics are automatically
-          maintained by VirtualBox and can be retrieved on the host, e.g. to
-          monitor VM performance and statistics.</para>
-        </listitem>
-
-        <listitem>
-          <para>In addition, arbitrary string data can be exchanged between
-          guest and host. This works in both directions.</para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>To accomplish this, VirtualBox establishes a private communication
-    channel between the VirtualBox Guest Additions and the host, and software
-    on both sides can use this channel to exchange string data for arbitrary
-    purposes. Guest properties are simply string keys to which a value is
-    attached. They can be set (written to) by either the host and the guest,
-    and they can also be read from both sides.</para>
-
-    <para>In addition to establishing the general mechanism of reading and
-    writing values, a set of predefined guest properties is automatically
-    maintained by the VirtualBox Guest Additions to allow for retrieving
-    interesting guest data such as the guest's exact operating system and
-    service pack level, the installed version of the Guest Additions, users
-    that are currently logged into the guest OS, network statistics and more.
-    These predefined properties are all prefixed with
-    <computeroutput>/VirtualBox/</computeroutput> and organized into a
-    hierarchical tree of keys.</para>
-
-    <para>Some of this runtime information is shown when you select "Session
-    Information Dialog" from a virtual machine's "Machine" menu.</para>
-
-    <para>A more flexible way to use this channel is via the
-    <computeroutput>VBoxManage guestproperty</computeroutput> command set; see
-    <xref linkend="vboxmanage-guestproperty" /> for details. For example, to
-    have <emphasis>all</emphasis> the available guest properties for a given
-    running VM listed with their respective values, use this:<screen>$ VBoxManage guestproperty enumerate "Windows Vista III"
-VirtualBox Command Line Management Interface Version @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@
-(C) 2005-@VBOX_C_YEAR@ @VBOX_VENDOR@
+
+    <title>Guest Properties</title>
+
+    <para>
+      Starting with version 2.1, VirtualBox enables requesting of
+      certain properties from a running guest, provided that the
+      VirtualBox Guest Additions are installed and the VM is running.
+      This provides the following advantages:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          A number of predefined VM characteristics are automatically
+          maintained by VirtualBox and can be retrieved on the host. For
+          example, to monitor VM performance and statistics.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Arbitrary string data can be exchanged between guest and host.
+          This works in both directions.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      To accomplish this, VirtualBox establishes a private communication
+      channel between the VirtualBox Guest Additions and the host, and
+      software on both sides can use this channel to exchange string
+      data for arbitrary purposes. Guest properties are simply string
+      keys to which a value is attached. They can be set, or written to,
+      by either the host and the guest. They can also be read from both
+      sides.
+    </para>
+
+    <para>
+      In addition to establishing the general mechanism of reading and
+      writing values, a set of predefined guest properties is
+      automatically maintained by the VirtualBox Guest Additions to
+      allow for retrieving interesting guest data such as the guest's
+      exact operating system and service pack level, the installed
+      version of the Guest Additions, users that are currently logged
+      into the guest OS, network statistics and more. These predefined
+      properties are all prefixed with
+      <computeroutput>/VirtualBox/</computeroutput> and organized into a
+      hierarchical tree of keys.
+    </para>
+
+    <para>
+      Some of this runtime information is shown when you select
+      <emphasis role="bold">Session Information Dialog</emphasis> from a
+      virtual machine's Machine menu.
+    </para>
+
+    <para>
+      A more flexible way to use this channel is via the
+      <computeroutput>VBoxManage guestproperty</computeroutput> command.
+      See <xref linkend="vboxmanage-guestproperty" />. For example, to
+      have <emphasis>all</emphasis> the available guest properties for a
+      given running VM listed with their respective values, use this
+      command:
+    </para>
+
+<screen>$ VBoxManage guestproperty enumerate "Windows Vista III"
+VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
+(C) 2005-2018 Oracle Corporation
 All rights reserved.
 
@@ -1412,25 +2121,25 @@
 Name: /VirtualBox/GuestAdd/Revision, value: 40720,
     timestamp: 1229098279345664000, flags:
-Name: /VirtualBox/GuestAdd/Version, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@,
+Name: /VirtualBox/GuestAdd/Version, value: <replaceable>version-number</replaceable>,
     timestamp: 1229098279479515000, flags:
-Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@r40720,
+Name: /VirtualBox/GuestAdd/Components/VBoxControl.exe, value: <replaceable>version-number</replaceable>r40720,
     timestamp: 1229098279651731000, flags:
-Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@r40720,
+Name: /VirtualBox/GuestAdd/Components/VBoxHook.dll, value: <replaceable>version-number</replaceable>r40720,
     timestamp: 1229098279804835000, flags:
-Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@r40720,
+Name: /VirtualBox/GuestAdd/Components/VBoxDisp.dll, value: <replaceable>version-number</replaceable>r40720,
     timestamp: 1229098279880611000, flags:
-Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@r40720,
+Name: /VirtualBox/GuestAdd/Components/VBoxMRXNP.dll, value: <replaceable>version-number</replaceable>r40720,
     timestamp: 1229098279882618000, flags:
-Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@r40720,
+Name: /VirtualBox/GuestAdd/Components/VBoxService.exe, value: <replaceable>version-number</replaceable>r40720,
     timestamp: 1229098279883195000, flags:
-Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@r40720,
+Name: /VirtualBox/GuestAdd/Components/VBoxTray.exe, value: <replaceable>version-number</replaceable>r40720,
     timestamp: 1229098279885027000, flags:
-Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@r40720,
+Name: /VirtualBox/GuestAdd/Components/VBoxGuest.sys, value: <replaceable>version-number</replaceable>r40720,
     timestamp: 1229098279886838000, flags:
-Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@r40720,
+Name: /VirtualBox/GuestAdd/Components/VBoxMouse.sys, value: <replaceable>version-number</replaceable>r40720,
     timestamp: 1229098279890600000, flags:
-Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@r40720,
+Name: /VirtualBox/GuestAdd/Components/VBoxSF.sys, value: <replaceable>version-number</replaceable>r40720,
     timestamp: 1229098279893056000, flags:
-Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@r40720,
+Name: /VirtualBox/GuestAdd/Components/VBoxVideo.sys, value: <replaceable>version-number</replaceable>r40720,
     timestamp: 1229098279895767000, flags:
 Name: /VirtualBox/GuestInfo/OS/LoggedInUsers, value: 1,
@@ -1451,20 +2160,29 @@
     timestamp: 1229099826300524000, flags:
 Name: /VirtualBox/GuestInfo/OS/LoggedInUsersList, value: username,
-    timestamp: 1229099826317386000, flags:</screen></para>
-
-    <para>To query the value of a single property, use the "get" subcommand
-    like this:<screen>$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product"
-VirtualBox Command Line Management Interface Version @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@
-(C) 2005-@VBOX_C_YEAR@ @VBOX_VENDOR@
+    timestamp: 1229099826317386000, flags:</screen>
+
+    <para>
+      To query the value of a single property, use the
+      <computeroutput>get</computeroutput> subcommand as follows:
+    </para>
+
+<screen>$ VBoxManage guestproperty get "Windows Vista III" "/VirtualBox/GuestInfo/OS/Product"
+VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
+(C) 2005-2018 Oracle Corporation
 All rights reserved.
 
-Value: Windows Vista Business Edition</screen></para>
-
-    <para>To add or change guest properties from the guest, use the tool
-    <computeroutput>VBoxControl</computeroutput>. This tool is included in the
-    Guest Additions of VirtualBox 2.2 or later. When started from a Linux
-    guest, this tool requires root privileges for security reasons:<screen>$ sudo VBoxControl guestproperty enumerate
-VirtualBox Guest Additions Command Line Management Interface Version @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@
-(C) 2009-@VBOX_C_YEAR@ @VBOX_VENDOR@
+Value: Windows Vista Business Edition</screen>
+
+    <para>
+      To add or change guest properties from the guest, use the tool
+      <computeroutput>VBoxControl</computeroutput>. This tool is
+      included in the Guest Additions of VirtualBox 2.2 or later. When
+      started from a Linux guest, this tool requires root privileges for
+      security reasons:
+    </para>
+
+<screen>$ sudo VBoxControl guestproperty enumerate
+VirtualBox Guest Additions Command Line Management Interface Version <replaceable>version-number</replaceable>
+(C) 2005-2018 Oracle Corporation
 All rights reserved.
 
@@ -1473,186 +2191,287 @@
 Name: /VirtualBox/GuestInfo/OS/Version, value: #59-Ubuntu SMP Thu Jan 28 01:23:03 UTC 2010,
     timestamp: 1265813265836305000, flags: &lt;NULL&gt;
-      ...</screen></para>
-
-    <para>For more complex needs, you can use the VirtualBox programming
-    interfaces; see <xref linkend="VirtualBoxAPI" />.</para>
+      ...</screen>
+
+    <para>
+      For more complex needs, you can use the VirtualBox programming
+      interfaces. See <xref linkend="VirtualBoxAPI" />.
+    </para>
+
   </sect1>
 
   <sect1 id="guestadd-guestcontrol">
-    <title>Guest control</title>
-
-    <para>Starting with version 3.2, the Guest Additions of VirtualBox allow
-    starting applications inside a VM from the host system.</para>
-
-    <para>For this to work, the application needs to be installed inside the
-    guest; no additional software needs to be installed on the host.
-    Additionally, text mode output (to stdout and stderr) can be shown on the
-    host for further processing along with options to specify user credentials
-    and a timeout value (in milliseconds) to limit time the application is
-    able to run.</para>
-
-    <para>This feature can be used to automate deployment of software within
-    the guest.</para>
-
-    <para>Starting with version 4.0, the Guest Additions for Windows allow for
-    automatic updating (only already installed Guest Additions 4.0 or later).
-    Also, copying files from host to the guest as well as remotely creating
-    guest directories is available.</para>
-
-    <para>To use these features, use the VirtualBox command line, see <xref
-    linkend="vboxmanage-guestcontrol" />.</para>
+
+    <title>Guest Control</title>
+
+    <para>
+      Starting with version 3.2, the Guest Additions of VirtualBox allow
+      starting applications inside a VM from the host system.
+    </para>
+
+    <para>
+      For this to work, the application needs to be installed inside the
+      guest. No additional software needs to be installed on the host.
+      Additionally, text mode output to stdout and stderr can be shown
+      on the host for further processing. There are options to specify
+      user credentials and a timeout value, in milliseconds, to limit
+      the time the application is able to run.
+    </para>
+
+    <para>
+      This feature can be used to automate deployment of software within
+      the guest.
+    </para>
+
+    <para>
+      Starting with version 4.0, the Guest Additions for Windows allow
+      for automatic updating. This applies for already installed Guest
+      Additions version 4.0 or later. Also, copying files from host to
+      the guest as well as remotely creating guest directories is
+      available.
+    </para>
+
+    <para>
+      To use these features, use the VirtualBox command line. See
+      <xref
+    linkend="vboxmanage-guestcontrol" />.
+    </para>
+
   </sect1>
 
-  <sect1>
-    <title>Memory overcommitment</title>
-
-    <para>In server environments with many VMs; the Guest Additions can be
-    used to share physical host memory between several VMs, reducing the total
-    amount of memory in use by the VMs. If memory usage is the limiting factor
-    and CPU resources are still available, this can help with packing more VMs
-    on each host.</para>
+  <sect1 id="guestadd-memory-usage">
+
+    <title>Memory Overcommitment</title>
+
+    <para>
+      In server environments with many VMs, the Guest Additions can be
+      used to share physical host memory between several VMs. This
+      reduces the total amount of memory in use by the VMs. If memory
+      usage is the limiting factor and CPU resources are still
+      available, this can help with running more VMs on each host.
+    </para>
 
     <sect2 id="guestadd-balloon">
-      <title>Memory ballooning</title>
-
-      <para>Starting with version 3.2, the Guest Additions of VirtualBox can
-      change the amount of host memory that a VM uses while the machine is
-      running. Because of how this is implemented, this feature is called
-      "memory ballooning".</para>
+
+      <title>Memory Ballooning</title>
+
+      <para>
+        Starting with version 3.2, the Guest Additions of VirtualBox can
+        change the amount of host memory that a VM uses while the
+        machine is running. Because of how this is implemented, this
+        feature is called <emphasis>memory ballooning</emphasis>.
+      </para>
 
       <note>
-        <para>VirtualBox supports memory ballooning only on 64-bit hosts, and
-        it is not supported on Mac OS X hosts.</para>
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              VirtualBox supports memory ballooning only on 64-bit
+              hosts. It is not supported on Mac OS X hosts.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Memory ballooning does not work with large pages enabled.
+              To turn off large pages support for a VM, run
+              <computeroutput>VBoxManage modifyvm &lt;VM name&gt;
+              --largepages off</computeroutput>
+            </para>
+          </listitem>
+
+        </itemizedlist>
       </note>
 
+      <para>
+        Normally, to change the amount of memory allocated to a virtual
+        machine, you have to shut down the virtual machine entirely and
+        modify its settings. With memory ballooning, memory that was
+        allocated for a virtual machine can be given to another virtual
+        machine without having to shut the machine down.
+      </para>
+
+      <para>
+        When memory ballooning is requested, the VirtualBox Guest
+        Additions, which run inside the guest, allocate physical memory
+        from the guest operating system on the kernel level and lock
+        this memory down in the guest. This ensures that the guest will
+        not use that memory any longer. No guest applications can
+        allocate it, and the guest kernel will not use it either.
+        VirtualBox can then reuse this memory and give it to another
+        virtual machine.
+      </para>
+
+      <para>
+        The memory made available through the ballooning mechanism is
+        only available for reuse by VirtualBox. It is
+        <emphasis>not</emphasis> returned as free memory to the host.
+        Requesting balloon memory from a running guest will therefore
+        not increase the amount of free, unallocated memory on the host.
+        Effectively, memory ballooning is therefore a memory
+        overcommitment mechanism for multiple virtual machines while
+        they are running. This can be useful to temporarily start
+        another machine, or in more complicated environments, for
+        sophisticated memory management of many virtual machines that
+        may be running in parallel depending on how memory is used by
+        the guests.
+      </para>
+
+      <para>
+        At this time, memory ballooning is only supported through
+        VBoxManage. Use the following command to increase or decrease
+        the size of the memory balloon within a running virtual machine
+        that has Guest Additions installed:
+      </para>
+
+<screen>VBoxManage controlvm "VM name" guestmemoryballoon n</screen>
+
+      <para>
+        where <replaceable>VM name</replaceable> is the name or UUID of
+        the virtual machine in question and <replaceable>n</replaceable>
+        is the amount of memory to allocate from the guest in megabytes.
+        See <xref
+      linkend="vboxmanage-controlvm" />.
+      </para>
+
+      <para>
+        You can also set a default balloon that will automatically be
+        requested from the VM every time after it has started up with
+        the following command:
+
+<screen>VBoxManage modifyvm "VM name" --guestmemoryballoon n</screen>
+      </para>
+
+      <para>
+        By default, no balloon memory is allocated. This is a VM
+        setting, like other <computeroutput>modifyvm</computeroutput>
+        settings, and therefore can only be set while the machine is
+        shut down. See <xref
+      linkend="vboxmanage-modifyvm" />.
+      </para>
+
+    </sect2>
+
+    <sect2 id="guestadd-pagefusion">
+
+      <title>Page Fusion</title>
+
+      <para>
+        Whereas memory ballooning simply reduces the amount of RAM that
+        is available to a VM, Page Fusion works differently. It avoids
+        memory duplication between several similar running VMs.
+      </para>
+
+      <para>
+        In a server environment running several similar VMs, for example
+        with identical operating systems, on the same host, lots of
+        memory pages are identical. VirtualBox's Page Fusion technology,
+        introduced with VirtualBox 3.2, is a novel technique to
+        efficiently identify these identical memory pages and share them
+        between multiple VMs.
+      </para>
+
       <note>
-        <para>Memory ballooning does not work with large pages enabled. To
-        turn off large pages support for a VM, run
-        <computeroutput>VBoxManage modifyvm &lt;VM name&gt; --largepages off</computeroutput>
+        <para>
+          VirtualBox supports Page Fusion only on 64-bit hosts, and it
+          is not supported on Mac OS X hosts. Page Fusion currently
+          works only with Windows 2000 and later guests.
         </para>
       </note>
 
-      <para>Normally, to change the amount of memory allocated to a virtual
-      machine, one has to shut down the virtual machine entirely and modify
-      its settings. With memory ballooning, memory that was allocated for a
-      virtual machine can be given to another virtual machine without having
-      to shut the machine down.</para>
-
-      <para>When memory ballooning is requested, the VirtualBox Guest
-      Additions (which run inside the guest) allocate physical memory from the
-      guest operating system on the kernel level and lock this memory down in
-      the guest. This ensures that the guest will not use that memory any
-      longer: no guest applications can allocate it, and the guest kernel will
-      not use it either. VirtualBox can then re-use this memory and give it to
-      another virtual machine.</para>
-
-      <para>The memory made available through the ballooning mechanism is only
-      available for re-use by VirtualBox. It is <emphasis>not</emphasis>
-      returned as free memory to the host. Requesting balloon memory from a
-      running guest will therefore not increase the amount of free,
-      unallocated memory on the host. Effectively, memory ballooning is
-      therefore a memory overcommitment mechanism for multiple virtual
-      machines while they are running. This can be useful to temporarily start
-      another machine, or in more complicated environments, for sophisticated
-      memory management of many virtual machines that may be running in
-      parallel depending on how memory is used by the guests.</para>
-
-      <para>At this time, memory ballooning is only supported through
-      VBoxManage. Use the following command to increase or decrease the size
-      of the memory balloon within a running virtual machine that has Guest
-      Additions installed: <screen>VBoxManage controlvm "VM name" guestmemoryballoon &lt;n&gt;</screen>where
-      <computeroutput>"VM name"</computeroutput> is the name or UUID of the
-      virtual machine in question and
-      <computeroutput>&lt;n&gt;</computeroutput> is the amount of memory to
-      allocate from the guest in megabytes. See <xref
-      linkend="vboxmanage-controlvm" /> for more information.</para>
-
-      <para>You can also set a default balloon that will automatically be
-      requested from the VM every time after it has started up with the
-      following command: <screen>VBoxManage modifyvm "VM name" --guestmemoryballoon &lt;n&gt;</screen></para>
-
-      <para>By default, no balloon memory is allocated. This is a VM setting,
-      like other <computeroutput>modifyvm</computeroutput> settings, and
-      therefore can only be set while the machine is shut down; see <xref
-      linkend="vboxmanage-modifyvm" />.</para>
+      <para>
+        The more similar the VMs on a given host are, the more
+        efficiently Page Fusion can reduce the amount of host memory
+        that is in use. It therefore works best if all VMs on a host run
+        identical operating systems, such as Windows XP Service Pack 2.
+        Instead of having a complete copy of each operating system in
+        each VM, Page Fusion identifies the identical memory pages in
+        use by these operating systems and eliminates the duplicates,
+        sharing host memory between several machines. This is called
+        <emphasis>deduplication</emphasis>. If a VM tries to modify a
+        page that has been shared with other VMs, a new page is
+        allocated again for that VM with a copy of the shared page. This
+        is called <emphasis>copy on write</emphasis>. All this is fully
+        transparent to the virtual machine.
+      </para>
+
+      <para>
+        You may be familiar with this kind of memory overcommitment from
+        other hypervisor products, which call this feature
+        <emphasis>page sharing</emphasis> or <emphasis>same page
+        merging</emphasis>. However, Page Fusion differs significantly
+        from those other solutions, whose approaches have several
+        drawbacks:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Traditional hypervisors scan <emphasis>all</emphasis> guest
+            memory and compute checksums (hashes) for every single
+            memory page. Then, they look for pages with identical hashes
+            and compare the entire content of those pages. If two pages
+            produce the same hash, it is very likely that the pages are
+            identical in content. This process can take rather long,
+            especially if the system is not idling. As a result, the
+            additional memory only becomes available after a significant
+            amount of time, such as hours or sometimes days. Even worse,
+            this kind of page sharing algorithm generally consumes
+            significant CPU resources and increases the virtualization
+            overhead by 10 to 20%.
+          </para>
+
+          <para>
+            Page Fusion in VirtualBox uses logic in the VirtualBox Guest
+            Additions to quickly identify memory cells that are most
+            likely identical across VMs. It can therefore achieve most
+            of the possible savings of page sharing almost immediately
+            and with almost no overhead.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Page Fusion is also much less likely to be confused by
+            identical memory that it will eliminate, just to learn
+            seconds later that the memory will now change and having to
+            perform a highly expensive and often service-disrupting
+            reallocation.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        At this time, Page Fusion can only be controlled with
+        VBoxManage, and only while a VM is shut down. To enable Page
+        Fusion for a VM, use the following command:
+      </para>
+
+<screen>VBoxManage modifyvm "VM name" --pagefusion on</screen>
+
+      <para>
+        You can observe Page Fusion operation using some metrics.
+        <computeroutput>RAM/VMM/Shared</computeroutput> shows the total
+        amount of fused pages, whereas the per-VM metric
+        <computeroutput>Guest/RAM/Usage/Shared</computeroutput> will
+        return the amount of fused memory for a given VM. See
+        <xref
+        linkend="vboxmanage-metrics" /> for information on
+        how to query metrics.
+      </para>
+
+      <note>
+        <para>
+          Enabling Page Fusion might indirectly increase the chances for
+          malicious guests to successfully attack other VMs running on
+          the same host. See <xref linkend="pot-insecure"/>.
+        </para>
+      </note>
+
     </sect2>
 
-    <sect2 id="guestadd-pagefusion">
-      <title>Page Fusion</title>
-
-      <para>Whereas memory ballooning simply reduces the amount of RAM that is
-      available to a VM, Page Fusion works differently: it avoids memory
-      duplication between several similar running VMs.</para>
-
-      <para>In a server environment running several similar VMs (e.g. with
-      identical operating systems) on the same host, lots of memory pages are
-      identical. VirtualBox's Page Fusion technology, introduced with
-      VirtualBox 3.2, is a novel technique to efficiently identify these
-      identical memory pages and share them between multiple VMs.<note>
-          <para>VirtualBox supports Page Fusion only on 64-bit hosts, and it
-          is not supported on Mac OS X hosts. Page Fusion currently works only
-          with Windows guests (2000 and later).</para>
-        </note></para>
-
-      <para>The more similar the VMs on a given host are, the more efficiently
-      Page Fusion can reduce the amount of host memory that is in use. It
-      therefore works best if all VMs on a host run identical operating
-      systems (e.g. Windows XP Service Pack 2). Instead of having a complete
-      copy of each operating system in each VM, Page Fusion identifies the
-      identical memory pages in use by these operating systems and eliminates
-      the duplicates, sharing host memory between several machines
-      ("deduplication"). If a VM tries to modify a page that has been shared
-      with other VMs, a new page is allocated again for that VM with a copy of
-      the shared page ("copy on write"). All this is fully transparent to the
-      virtual machine.</para>
-
-      <para>You may be familiar with this kind of memory overcommitment from
-      other hypervisor products, which call this feature "page sharing" or
-      "same page merging". However, Page Fusion differs significantly from
-      those other solutions, whose approaches have several
-      drawbacks:<orderedlist>
-          <listitem>
-            <para>Traditional hypervisors scan <emphasis>all</emphasis> guest
-            memory and compute checksums (hashes) for every single memory
-            page. Then, they look for pages with identical hashes and compare
-            the entire content of those pages; if two pages produce the same
-            hash, it is very likely that the pages are identical in content.
-            This, of course, can take rather long, especially if the system is
-            not idling. As a result, the additional memory only becomes
-            available after a significant amount of time (this can be hours or
-            even days!). Even worse, this kind of page sharing algorithm
-            generally consumes significant CPU resources and increases the
-            virtualization overhead by 10-20%.</para>
-
-            <para>Page Fusion in VirtualBox uses logic in the VirtualBox Guest
-            Additions to quickly identify memory cells that are most likely
-            identical across VMs. It can therefore achieve most of the
-            possible savings of page sharing almost immediately and with
-            almost no overhead.</para>
-          </listitem>
-
-          <listitem>
-            <para>Page Fusion is also much less likely to be confused by
-            identical memory that it will eliminate just to learn seconds
-            later that the memory will now change and having to perform a
-            highly expensive and often service-disrupting reallocation.</para>
-          </listitem>
-        </orderedlist></para>
-
-      <para>At this time, Page Fusion can only be controlled with VBoxManage,
-      and only while a VM is shut down. To enable Page Fusion for a VM, use
-      the following command:<screen>VBoxManage modifyvm "VM name" --pagefusion on</screen></para>
-
-      <para>You can observe Page Fusion operation using some metrics.
-      <computeroutput>RAM/VMM/Shared</computeroutput> shows the total amount
-      of fused pages, whereas the per-VM metric
-      <computeroutput>Guest/RAM/Usage/Shared</computeroutput> will return the
-      amount of fused memory for a given VM. Please refer to <xref
-        linkend="metrics" /> for information on how to query metrics.</para>
-
-      <note><para>Enabling Page Fusion might indirectly increase the chances
-      for malicious guests to successfully attack other VMs running on the
-      same host, see <xref linkend="pot-insecure"/>.</para></note>
-    </sect2>
   </sect1>
+
 </chapter>
Index: /trunk/doc/manual/en_US/user_Installation.xml
===================================================================
--- /trunk/doc/manual/en_US/user_Installation.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_Installation.xml	(revision 73276)
@@ -1,893 +1,1319 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="installation">
-  <title>Installation details</title>
-
-  <para>As installation of VirtualBox varies depending on your host operating
-  system, we provide installation instructions in four separate chapters for
-  Windows, Mac OS X, Linux and Solaris, respectively.</para>
+
+  <title>Installation Details</title>
+
+  <para>
+    As installation of VirtualBox varies depending on your host
+    operating system, we provide installation instructions in four
+    separate chapters for Windows, Mac OS X, Linux and Solaris,
+    respectively.
+  </para>
 
   <sect1 id="installation_windows">
-    <title>Installing on Windows hosts</title>
-
-    <sect2>
+
+    <title>Installing on Windows Hosts</title>
+
+    <sect2 id="install-win-prereq">
+
       <title>Prerequisites</title>
 
-      <para>For the various versions of Windows that we support as host
-      operating systems, please refer to <xref
-      linkend="hostossupport" />.</para>
-
-      <para>In addition, Windows Installer 1.1 or higher must be present on
-      your system. This should be the case if you have all recent Windows
-      updates installed.</para>
-    </sect2>
-
-    <sect2>
-      <title>Performing the installation</title>
-
-      <para>The VirtualBox installation can be started <itemizedlist>
+      <para>
+        For the various versions of Windows that are supported as host
+        operating systems, please refer to
+        <xref
+      linkend="hostossupport" />.
+      </para>
+
+      <para>
+        In addition, Windows Installer 1.1 or higher must be present on
+        your system. This should be the case if you have all recent
+        Windows updates installed.
+      </para>
+
+    </sect2>
+
+    <sect2 id="install-win-performing">
+
+      <title>Performing the Installation</title>
+
+      <para>
+        The VirtualBox installation can be started in either of the
+        following ways:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            By double-clicking on the executable file, which contains
+            both 32-bit and 64-bit architectures.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            By entering the following command:
+          </para>
+
+<screen>VirtualBox-&lt;version&gt;-&lt;revision&gt;-Win.exe -extract</screen>
+
+          <para>
+            This will extract both installers into a temporary
+            directory, along with .MSI files. Run the following command
+            to to perform the installation:
+          </para>
+
+<screen>msiexec /i VirtualBox-&lt;version&gt;-&lt;revision&gt;-MultiArch_&lt;x86|amd64&gt;.msi</screen>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Using either way displays the installation Welcome dialog and
+        enables you to choose where to install VirtualBox, and which
+        components to install. In addition to the VirtualBox
+        application, the following components are available:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">USB support.</emphasis> This package
+            contains special drivers for your Windows host that
+            VirtualBox requires to fully support USB devices inside your
+            virtual machines.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Networking.</emphasis> This package
+            contains extra networking drivers for your Windows host that
+            VirtualBox needs to support Bridged Networking. This enables
+            your VM's virtual network cards to be accessed from other
+            machines on your physical network.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Python support.</emphasis> This
+            package contains Python scripting support for the VirtualBox
+            API, see <xref linkend="VirtualBoxAPI" />. For this to work,
+            an already working Windows Python installation on the system
+            is required.
+          </para>
+
+          <para>
+            See, for example:
+            <ulink
+              url="http://www.python.org/download/windows/">http://www.python.org/download/windows/</ulink>.
+          </para>
+
+          <note>
+            <para>
+              Python version at least 2.6 is required. Since VirtualBox
+              5.1, Python 3 is also supported.
+            </para>
+          </note>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Depending on your Windows configuration, you may see warnings
+        about unsigned drivers, or similar. Click
+        <emphasis role="bold">Continue</emphasis> for these warnings, as
+        otherwise VirtualBox might not function correctly after
+        installation.
+      </para>
+
+      <para>
+        The installer will create a VirtualBox group in the Windows
+        Start menu, which allows you to launch the application and
+        access its documentation.
+      </para>
+
+      <para>
+        With standard settings, VirtualBox will be installed for all
+        users on the local system. If this is not wanted, you must
+        invoke the installer by first extracting as follows:
+      </para>
+
+<screen>VirtualBox.exe -extract</screen>
+
+      <para>
+        Then, run either of the following commands on the extracted .MSI
+        files. This will install VirtualBox only for the current user.
+      </para>
+
+<screen>VirtualBox.exe -msiparams ALLUSERS=2</screen>
+
+<screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi ALLUSERS=2</screen>
+
+      <para>
+        If you do not want to install all features of VirtualBox, you
+        can set the optional <computeroutput>ADDLOCAL</computeroutput>
+        parameter to explicitly name the features to be installed. The
+        following features are available:
+      </para>
+
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            VBoxApplication
+          </term>
+
           <listitem>
-            <para>either by double-clicking on its executable file (contains
-            both 32- and 64-bit architectures)</para>
+            <para>
+              Main binaries of VirtualBox.
+
+              <note>
+                <para>
+                  This feature must not be absent, since it contains the
+                  minimum set of files to have working VirtualBox
+                  installation.
+                </para>
+              </note>
+            </para>
           </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            VBoxUSB
+          </term>
 
           <listitem>
-            <para>or by entering <screen>VirtualBox-&lt;version&gt;-&lt;revision&gt;-Win.exe -extract</screen></para>
-
-            <para>on the command line. This will extract both installers into
-            a temporary directory in which you'll then find the usual .MSI
-            files. Then you can do a <screen>msiexec /i VirtualBox-&lt;version&gt;-&lt;revision&gt;-MultiArch_&lt;x86|amd64&gt;.msi</screen>
-            to perform the installation.</para>
+            <para>
+              USB support.
+            </para>
           </listitem>
-        </itemizedlist></para>
-
-      <para>In either case, this will display the installation welcome dialog
-      and allow you to choose where to install VirtualBox to and which
-      components to install. In addition to the VirtualBox application, the
-      following components are available:<glosslist>
-          <glossentry>
-            <glossterm>USB support</glossterm>
-
-            <glossdef>
-              <para>This package contains special drivers for your Windows
-              host that VirtualBox requires to fully support USB devices
-              inside your virtual machines.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>Networking</glossterm>
-
-            <glossdef>
-              <para>This package contains extra networking drivers for your
-              Windows host that VirtualBox needs to support Bridged Networking
-              (to make your VM's virtual network cards accessible from other
-              machines on your physical network).</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>Python Support</glossterm>
-
-            <glossdef>
-              <para>This package contains Python scripting support for the
-              VirtualBox API (see <xref linkend="VirtualBoxAPI" />). For this
-              to work, an already working Windows Python installation on the
-              system is required.
-                <note><para>Python version &ge; 2.6 is required. Since VirtualBox 5.1 Python 3 is also supported.</para></note>
-                <footnote>
-                  <para>See, for example, <ulink
-                  url="http://www.python.org/download/windows/">http://www.python.org/download/windows/</ulink>.</para>
-                </footnote></para>
-            </glossdef>
-          </glossentry>
-        </glosslist></para>
-
-      <para>Depending on your Windows configuration, you may see warnings
-      about "unsigned drivers" or similar. Please select "Continue" on these
-      warnings as otherwise VirtualBox might not function correctly after
-      installation.</para>
-
-      <para>The installer will create a "VirtualBox" group in the Windows
-      "Start" menu which allows you to launch the application and access its
-      documentation.</para>
-
-      <para>With standard settings, VirtualBox will be installed for all users
-      on the local system. In case this is not wanted, you have to invoke the
-      installer by first extracting it by using <screen>VirtualBox.exe -extract</screen>
-      and then do as follows: <screen>VirtualBox.exe -msiparams ALLUSERS=2</screen>
-      or <screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi ALLUSERS=2</screen>
-      on the extracted .MSI files. This will install VirtualBox only for the
-      current user.</para>
-
-      <para>If you do not want to install all features of VirtualBox, you can
-      set the optional <computeroutput>ADDLOCAL</computeroutput> parameter to
-      explicitly name the features to be installed. The following features are
-      available: <glosslist>
-          <glossentry>
-            <glossterm>VBoxApplication</glossterm>
-
-            <glossdef>
-              <para>Main binaries of VirtualBox.<note>
-                  <para>This feature must not be absent since it contains the
-                  minimum set of files to have working VirtualBox
-                  installation.</para>
-                </note></para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>VBoxUSB</glossterm>
-
-            <glossdef>
-              <para>USB support.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>VBoxNetwork</glossterm>
-
-            <glossdef>
-              <para>All networking support; includes the VBoxNetworkFlt and
-              VBoxNetworkAdp features (see below).</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>VBoxNetworkFlt</glossterm>
-
-            <glossdef>
-              <para>Bridged networking support.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>VBoxNetworkAdp</glossterm>
-
-            <glossdef>
-              <para>Host-only networking support.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>VBoxPython</glossterm>
-
-            <glossdef>
-              <para>Python support.
-                <note><para>Python version &ge; 2.6 is required. Since VirtualBox 5.1 Python 3 is also supported.</para></note>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            VBoxNetwork
+          </term>
+
+          <listitem>
+            <para>
+              All networking support. This includes the VBoxNetworkFlt
+              and VBoxNetworkAdp features.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            VBoxNetworkFlt
+          </term>
+
+          <listitem>
+            <para>
+              Bridged networking support.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            VBoxNetworkAdp
+          </term>
+
+          <listitem>
+            <para>
+              Host-only networking support
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            VBoxPython
+          </term>
+
+          <listitem>
+            <para>
+              Python support
+            </para>
+
+            <note>
+              <para>
+                Python version at least 2.6 is required. Since
+                VirtualBox 5.1, Python 3 is also supported.
               </para>
-            </glossdef>
-          </glossentry>
-        </glosslist>For example, to only install USB support along with the
-      main binaries, do a: <screen>VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB</screen>
-      or <screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi ADDLOCAL=VBoxApplication,VBoxUSB</screen></para>
-
-      <para>
-      The user is able to choose between NDIS5 and NDIS6 host network filters drivers during
-      the installation. This is realized via a command line parameter
-      <computeroutput>NETWORKTYPE</computeroutput>.
-      The NDIS6 driver is default for Windows Vista and later. For older Windows versions,
-      the installer will automatically select the NDIS5 driver and this cannot be changed.
-      For Windows Vista and later the user can force to install the (legacy) NDIS5 host
-      network filter driver using <computeroutput>NETWORKTYPE=NDIS5</computeroutput>. For
-      example, to install the NDIS5 driver on Windows 7, do
-      <screen>VirtualBox.exe -msiparams NETWORKTYPE=NDIS5</screen>
-      or
-      <screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi NETWORKTYPE=NDIS5</screen>
-      </para>
-
-
-    </sect2>
-
-    <sect2>
+            </note>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+
+      <para>
+        For example, to only install USB support along with the main
+        binaries, run either of the following commands:
+      </para>
+
+<screen>VirtualBox.exe -msiparams ADDLOCAL=VBoxApplication,VBoxUSB</screen>
+
+<screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi ADDLOCAL=VBoxApplication,VBoxUSB</screen>
+
+      <para>
+        The user is able to choose between NDIS5 and NDIS6 host network
+        filter drivers during the installation. This is done using a
+        command line parameter,
+        <computeroutput>NETWORKTYPE</computeroutput>. The NDIS6 driver
+        is default for Windows Vista and later. For older Windows
+        versions, the installer will automatically select the NDIS5
+        driver and this cannot be changed. For Windows Vista and later
+        the user can force an install of the legacy NDIS5 host network
+        filter driver by using
+        <computeroutput>NETWORKTYPE=NDIS5</computeroutput>. For example,
+        to install the NDIS5 driver on Windows 7 use either of the
+        following commands:
+      </para>
+
+<screen>VirtualBox.exe -msiparams NETWORKTYPE=NDIS5</screen>
+
+<screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi NETWORKTYPE=NDIS5</screen>
+
+    </sect2>
+
+    <sect2 id="install-win-uninstall">
+
       <title>Uninstallation</title>
 
-      <para>As VirtualBox uses the standard Microsoft Windows installer,
-      VirtualBox can be safely uninstalled at any time by choosing the program
-      entry in the "Add/Remove Programs" applet in the Windows Control
-      Panel.</para>
-    </sect2>
-
-    <sect2>
-      <title>Unattended installation</title>
-
-      <para>Unattended installations can be performed using the standard MSI
-      support.</para>
-
-    </sect2>
-
-    <sect2>
-      <title>Public properties</title>
-
-      <para>The following public properties can be specified via MSI API,
-      <screen>VirtualBox.exe -msiparams NAME=VALUE [...]</screen>
-      or
-      <screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi NAME=VALUE [...]</screen>
-      to control additional behavior and/or features of the Windows host installer:
-        <glosslist>
-          <glossentry>
-            <glossterm>VBOX_INSTALLDESKTOPSHORTCUT</glossterm>
-
-            <glossdef>
-              <para>Specifies whether or not a VirtualBox icon on the desktop
-              should be created.</para>
-
-              <para>Set to <computeroutput>1</computeroutput> to enable,
-              <computeroutput>0</computeroutput> to disable. Default is 1.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>VBOX_INSTALLQUICKLAUNCHSHORTCUT</glossterm>
-
-            <glossdef>
-              <para>Specifies whether or not a VirtualBox icon in the Quick Launch
-              Bar should be created.</para>
-
-              <para>Set to <computeroutput>1</computeroutput> to enable,
-              <computeroutput>0</computeroutput> to disable. Default is 1.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>VBOX_REGISTERFILEEXTENSIONS</glossterm>
-
-            <glossdef>
-              <para>Specifies whether or not the file extensions .vbox,
-              .vbox-extpack, .ovf, .ova, .vdi, .vmdk, .vhd and .vdd should be
-              associated with VirtualBox. Files of these types then will be opened
-              with VirtualBox.</para>
-
-              <para>Set to <computeroutput>1</computeroutput> to enable,
-              <computeroutput>0</computeroutput> to disable. Default is 1.</para>
-            </glossdef>
-          </glossentry>
-
-          <glossentry>
-            <glossterm>VBOX_START</glossterm>
-
-            <glossdef>
-              <para>Specifies whether or not VirtualBox should be started right after
-              successful installation.</para>
-
-              <para>Set to <computeroutput>1</computeroutput> to enable,
-              <computeroutput>0</computeroutput> to disable. Default is 1.</para>
-            </glossdef>
-          </glossentry>
-        </glosslist>
-      </para>
-
-    </sect2>
+      <para>
+        As VirtualBox uses the standard Microsoft Windows installer,
+        VirtualBox can be safely uninstalled at any time. Click the
+        program entry in the <emphasis role="bold">Add/Remove
+        Programs</emphasis> list in the Windows Control Panel.
+      </para>
+
+    </sect2>
+
+    <sect2 id="install-win-unattended">
+
+      <title>Unattended Installation</title>
+
+      <para>
+        Unattended installations can be performed using the standard MSI
+        support.
+      </para>
+
+    </sect2>
+
+    <sect2 id="install-win-public-props">
+
+      <title>Public Properties</title>
+
+      <para>
+        Public properties can be specified via MSI API, to control
+        additional behavior and features of the Windows host installer.
+        Use either of the following commands:
+      </para>
+
+<screen>VirtualBox.exe -msiparams NAME=VALUE [...]</screen>
+
+<screen>msiexec /i VirtualBox-&lt;version&gt;-MultiArch_&lt;x86|amd64&gt;.msi NAME=VALUE [...]</screen>
+
+      <para>
+        The following public properties are available.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            VBOX_INSTALLDESKTOPSHORTCUT
+          </para>
+
+          <para>
+            Specifies whether or not a VirtualBox icon on the desktop
+            should be created.
+          </para>
+
+          <para>
+            Set to <computeroutput>1</computeroutput> to enable,
+            <computeroutput>0</computeroutput> to disable. Default is 1.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            VBOX_INSTALLQUICKLAUNCHSHORTCUT
+          </para>
+
+          <para>
+            Specifies whether or not a VirtualBox icon in the Quick
+            Launch Bar should be created.
+          </para>
+
+          <para>
+            Set to <computeroutput>1</computeroutput> to enable,
+            <computeroutput>0</computeroutput> to disable. Default is 1.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            VBOX_REGISTERFILEEXTENSIONS
+          </para>
+
+          <para>
+            Specifies whether or not the file extensions .vbox,
+            .vbox-extpack, .ovf, .ova, .vdi, .vmdk, .vhd and .vdd should
+            be associated with VirtualBox. Files of these types then
+            will be opened with VirtualBox.
+          </para>
+
+          <para>
+            Set to <computeroutput>1</computeroutput> to enable,
+            <computeroutput>0</computeroutput> to disable. Default is 1.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            VBOX_START
+          </para>
+
+          <para>
+            Specifies whether or not VirtualBox should be started right
+            after successful installation.
+          </para>
+
+          <para>
+            Set to <computeroutput>1</computeroutput> to enable,
+            <computeroutput>0</computeroutput> to disable. Default is 1.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
   </sect1>
 
-  <sect1>
-    <title>Installing on Mac OS X hosts</title>
-
-    <sect2>
-      <title>Performing the installation</title>
-
-      <para>For Mac OS X hosts, VirtualBox ships in a disk image
-      (<computeroutput>dmg</computeroutput>) file. Perform the following
-      steps: <orderedlist>
+  <sect1 id="installation-mac">
+
+    <title>Installing on Mac OS X Hosts</title>
+
+    <sect2 id="install-mac-performing">
+
+      <title>Performing the Installation</title>
+
+      <para>
+        For Mac OS X hosts, VirtualBox ships in a disk image
+        (<computeroutput>dmg</computeroutput>) file. Perform the
+        following steps to install on a Mac OS X host:
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+          <para>
+            Double-click on the <computeroutput>dmg</computeroutput>
+            file, to mount the contents.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            A window opens, prompting you to double-click on the
+            <computeroutput>VirtualBox.pkg</computeroutput> installer
+            file displayed in that window.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            This will start the installer, which allows you to select
+            where to install VirtualBox.
+          </para>
+        </listitem>
+
+      </orderedlist>
+
+      <para>
+        After installation, you can find a VirtualBox icon in the
+        "Applications" folder in the Finder.
+      </para>
+
+    </sect2>
+
+    <sect2 id="install-mac-uninstall">
+
+      <title>Uninstallation</title>
+
+      <para>
+        To uninstall VirtualBox, open the disk image
+        <computeroutput>dmg</computeroutput> file and double-click on
+        the uninstall icon shown.
+      </para>
+
+    </sect2>
+
+    <sect2 id="install-mac-unattended">
+
+      <title>Unattended Installation</title>
+
+      <para>
+        To perform a non-interactive installation of VirtualBox you can
+        use the command line version of the installer application.
+      </para>
+
+      <para>
+        Mount the disk image (<computeroutput>dmg</computeroutput>)
+        file, as described in the installation procedure, or use the
+        following command line:
+      </para>
+
+<screen>hdiutil attach /path/to/VirtualBox-xyz.dmg</screen>
+
+      <para>
+        Open a terminal session and run the following command:
+      </para>
+
+<screen>sudo installer -pkg /Volumes/VirtualBox/VirtualBox.pkg -target /Volumes/Macintosh\ HD</screen>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="install-linux-host">
+
+    <title>Installing on Linux Hosts</title>
+
+    <sect2 id="install-linux-prereq">
+
+      <title>Prerequisites</title>
+
+      <para>
+        For the various versions of Linux that are supported as host
+        operating systems, see <xref
+      linkend="hostossupport" />.
+      </para>
+
+      <para>
+        You will need to install the following packages on your Linux
+        system before starting the installation. Some systems will do
+        this for you automatically when you install VirtualBox.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Qt 5.3.2 or higher. Qt 5.6.2 or higher is recommended.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            SDL 1.2.7 or higher. This graphics library is typically
+            called <computeroutput>libsdl</computeroutput> or similar.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <note>
+        <para>
+          These packages are only required if you want to run the
+          VirtualBox graphical user interfaces. In particular,
+          <computeroutput>VirtualBox</computeroutput>, the graphical
+          VirtualBox manager, requires both Qt and SDL.
+          <computeroutput>VBoxSDL</computeroutput>, the simplified GUI,
+          requires only SDL. If you only want to run
+          <computeroutput>VBoxHeadless</computeroutput>, neither Qt nor
+          SDL are required.
+        </para>
+      </note>
+
+    </sect2>
+
+    <sect2 id="externalkernelmodules">
+
+      <title>The VirtualBox Driver Modules</title>
+
+      <para>
+        In order to run other operating systems in virtual machines
+        alongside your main operating system, VirtualBox needs to
+        integrate very tightly into the system. To do this it installs a
+        driver module called <computeroutput>vboxdrv</computeroutput>
+        which does a lot of that work into the system kernel, which is
+        the part of the operating system which controls your processor
+        and physical hardware. Without this kernel module, you can still
+        use the VirtualBox manager to configure virtual machines, but
+        they will not start. It also installs network drivers called
+        <computeroutput>vboxnetflt</computeroutput> and
+        <computeroutput>vboxnetadp</computeroutput> which enable virtual
+        machines to make more use of your computer's network
+        capabilities and are needed for any virtual machine networking
+        beyond the basic NAT mode.
+      </para>
+
+      <para>
+        Since distributing driver modules separately from the kernel is
+        not something which Linux supports well, the install process
+        creates the modules on the system where they will be used. This
+        usually means first installing software packages from the
+        distribution which are needed for the build process. Normally,
+        these will be the GNU compiler (GCC), GNU Make (make) and
+        packages containing header files for your kernel, as well as
+        making sure that all system updates are installed and that the
+        system is running the most up-to-date kernel included in the
+        distribution. <emphasis>The running kernel and the header files
+        must be updated to matching versions</emphasis>. The following
+        list includes some instructions for common distributions. For
+        most of them you may want to start by finding the version name
+        of your kernel, using the command <computeroutput>uname
+        -r</computeroutput> in a terminal. The instructions assume that
+        you have not changed too much from the original installation,
+        particularly not installed a different kernel type. If you have,
+        then you will need to determine yourself what to set up.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            With Debian and Ubuntu-based distributions, you must install
+            the correct version of the
+            <computeroutput>linux-headers</computeroutput>, usually
+            whichever of
+            <computeroutput>linux-headers-generic</computeroutput>,
+            <computeroutput>linux-headers-amd64</computeroutput>,
+            <computeroutput>linux-headers-i686</computeroutput> or
+            <computeroutput>linux-headers-i686-pae</computeroutput> best
+            matches the kernel version name. Also, the
+            <computeroutput>linux-kbuild </computeroutput> package if it
+            exists. Basic Ubuntu releases should have the correct
+            packages installed by default.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            On Fedora, Redhat, Oracle Linux and many other RPM-based
+            systems, the kernel version sometimes has a code of letters
+            or a word close to the end of the version name. For example
+            "uek" for the Oracle Enterprise kernel or "default" or
+            "desktop" for the standard SUSE kernels. In this case, the
+            package name is
+            <computeroutput>kernel-uek-devel</computeroutput> or
+            equivalent. If there is no such code, it is usually
+            <computeroutput>kernel-devel</computeroutput>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            On older SUSE and openSUSE Linux, you must install the
+            <computeroutput>kernel-source</computeroutput> and
+            <computeroutput>kernel-syms</computeroutput> packages.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        If you suspect that something has gone wrong with module
+        installation, check that your system is set up as described
+        above and try running the following command, as root:
+      </para>
+
+<screen>rcvboxdrv setup</screen>
+
+    </sect2>
+
+    <sect2 id="install-linux-performing">
+
+      <title>Performing the Installation</title>
+
+      <para>
+        VirtualBox is available in a number of package formats native to
+        various common Linux distributions> See
+        <xref linkend="hostossupport" />. In addition, there is an
+        alternative generic installer (.run) which should work on most
+        Linux distributions. The generic installer packages are built on
+        EL5 systems and thus require reasonably old versions of glibc
+        (version 2.5) and other system libraries.
+      </para>
+
+      <sect3 id="install-linux-debian-ubuntu">
+
+        <title>Installing VirtualBox from a Debian/Ubuntu Package</title>
+
+        <para>
+          Download the appropriate package for your distribution. The
+          following examples assume that you are installing to a 32-bit
+          Ubuntu Wily system. Use <computeroutput>dpkg</computeroutput>
+          to install the Debian package,as follows:
+        </para>
+
+<screen>sudo dpkg -i virtualbox-5.0_<replaceable>version-number</replaceable>_Ubuntu_wily_i386.deb</screen>
+
+        <para>
+          The installer will also try to build kernel modules suitable
+          for the current running kernel. If the build process is not
+          successful you will be shown a warning and the package will be
+          left unconfigured. Look at
+          <computeroutput>/var/log/vbox-install.log</computeroutput> to
+          find out why the compilation failed. You may have to install
+          the appropriate Linux kernel headers, see
+          <xref
+        linkend="externalkernelmodules" />. After
+          correcting any problems, run the following command:
+        </para>
+
+<screen>sudo rcvboxdrv setup</screen>
+
+        <para>
+          This will start a second attempt to build the module.
+        </para>
+
+        <para>
+          If a suitable kernel module was found in the package or the
+          module was successfully built, the installation script will
+          attempt to load that module. If this fails, please see
+          <xref
+        linkend="ts_linux-kernelmodule-fails-to-load" />
+          for further information.
+        </para>
+
+        <para>
+          Once VirtualBox has been successfully installed and
+          configured, you can start it by clicking
+          <emphasis role="bold">VirtualBox</emphasis> in your Start menu
+          or from the command line. See
+          <xref linkend="startingvboxonlinux" />.
+        </para>
+
+      </sect3>
+
+      <sect3 id="install-linux-alt-installer">
+
+        <title>Using the Alternative Generic Installer (VirtualBox.run)</title>
+
+        <para>
+          The alternative generic installer performs the following
+          steps:
+        </para>
+
+        <itemizedlist>
+
           <listitem>
-            <para>Double-click on that file to have its contents
-            mounted.</para>
+            <para>
+              Unpacks the application files to the target directory,
+
+<screen>/opt/VirtualBox/</screen>
+
+              which cannot be changed.
+            </para>
           </listitem>
 
           <listitem>
-            <para>A window will open telling you to double click on the
-            <computeroutput>VirtualBox.pkg</computeroutput> installer file
-            displayed in that window.</para>
+            <para>
+              Builds and installs the VirtualBox kernel modules:
+              <computeroutput>vboxdrv</computeroutput>,
+              <computeroutput>vboxnetflt</computeroutput>, and
+              <computeroutput>vboxnetadp</computeroutput>.
+            </para>
           </listitem>
 
           <listitem>
-            <para>This will start the installer, which will allow you to
-            select where to install VirtualBox to.</para>
+            <para>
+              Creates <computeroutput>/sbin/rcvboxdrv</computeroutput>,
+              an init script to start the VirtualBox kernel module.
+            </para>
           </listitem>
-        </orderedlist></para>
-
-      <para>After installation, you can find a VirtualBox icon in the
-      "Applications" folder in the Finder.</para>
-    </sect2>
-
-    <sect2>
-      <title>Uninstallation</title>
-
-      <para>To uninstall VirtualBox, open the disk image (dmg) file again and
-      double-click on the uninstall icon contained therein.</para>
-    </sect2>
-
-    <sect2>
-      <title>Unattended installation</title>
-
-      <para>To perform a non-interactive installation of VirtualBox you can
-      use the command line version of the installer application.</para>
-
-      <para>Mount the disk image (dmg) file as described in the normal
-      installation or use the following command line:</para>
-
-      <screen>hdiutil attach /path/to/VirtualBox-xyz.dmg</screen>
-
-      <para>Then open a terminal session and execute:</para>
-
-      <screen>sudo installer -pkg /Volumes/VirtualBox/VirtualBox.pkg -target /Volumes/Macintosh\ HD</screen>
-    </sect2>
-  </sect1>
-
-  <sect1 id="install-linux-host">
-    <title>Installing on Linux hosts</title>
-
-    <sect2>
-      <title>Prerequisites</title>
-
-      <para>For the various versions of Linux that we support as host
-      operating systems, please refer to <xref
-      linkend="hostossupport" />.</para>
-
-      <para>You will need to install the following packages on your Linux
-      system before starting the installation (some systems will do this for
-      you automatically when you install VirtualBox):</para>
-
-      <itemizedlist>
-        <listitem>
-          <para>Qt 5.3.2 or higher (Qt 5.6.2 or higher recommended);</para>
-        </listitem>
-
-        <listitem>
-          <para>SDL 1.2.7 or higher (this graphics library is typically called
-          <computeroutput>libsdl</computeroutput> or similar).</para>
-        </listitem>
-      </itemizedlist>
-
-      <note>
-        <para>To be precise, these packages are only required if you want to
-        run the VirtualBox graphical user interfaces. In particular,
-        <computeroutput>VirtualBox</computeroutput>, the graphical VirtualBox
-        manager, requires both Qt and SDL;
-        <computeroutput>VBoxSDL</computeroutput>, our simplified GUI, requires
-        only SDL. By contrast, if you only want to run
-        <computeroutput>VBoxHeadless</computeroutput>, neither Qt nor SDL are
-        required.</para>
-      </note>
-    </sect2>
-
-    <sect2 id="externalkernelmodules">
-      <title>The VirtualBox driver modules</title>
-
-      <para>In order to run other operating systems in virtual machines
-      alongside your main operating system, VirtualBox needs to integrate
-      very tightly into the system.  To do this it installs a "driver"
-      module called <computeroutput>vboxdrv</computeroutput> which does
-      a lot of that work into the system kernel, which is the part of
-      the operating system which controls your processor and physical
-      hardware. Without this kernel module, you can still use the
-      VirtualBox manager to configure virtual machines, but they will not
-      start. It also installs network drivers called
-      <computeroutput>vboxnetflt</computeroutput> and
-      <computeroutput>vboxnetadp</computeroutput> which let virtual machines
-      make more use of your computer's network capabilities and are needed
-      for any virtual machine networking beyond the basic "NAT" mode.</para>
-
-      <para>Since distributing driver modules separately from the kernel
-      is not something which Linux supports well, we create the modules
-      on the system where they will be used.  This usually means first
-      installing software packages from the distribution which are needed
-      for the "build" process.  Normally, these will be the GNU compiler
-      (GCC), GNU Make (make) and packages containing "header files" for
-      your kernel - and making sure that all system updates are
-      installed and that the system is running the most up-to-date
-      kernel included in the distribution. <emphasis>The running kernel
-      and the header files must be updated to matching versions.</emphasis>
-      We will give some instructions for common distributions.  For most
-      of them you will want to start by finding the version name of your
-      kernel using the command
-      <computeroutput>uname -r</computeroutput> in a terminal.  They
-      assume that you have not changed too much from the original
-      installation, particularly not installed a different kernel type.
-      If you have then you will need to determine yourself what to set
-      up.</para>
-
-      <itemizedlist>
-        <listitem>
-          <para>With Debian and Ubuntu-based distributions, you
-          must install the right version of the
-          <computeroutput>linux-headers</computeroutput>, usually
-          whichever of <computeroutput>linux-headers-generic
-          </computeroutput>, <computeroutput>linux-headers-amd64
-          </computeroutput>, <computeroutput>linux-headers-i686
-          </computeroutput> or <computeroutput>linux-headers-i686-pae
-          </computeroutput> best matches the kernel version name;
-          and if it exists the <computeroutput>linux-kbuild
-          </computeroutput>
-          package. Basic Ubuntu releases should have the right
-          packages installed by default.</para>
-        </listitem>
-
-        <listitem>
-          <para>On Fedora, Redhat, Oracle Linux and many other
-          RPM-based systems, the kernel version sometimes has
-          a code of letters or a word close to the end of the
-          version name, for example "uek" for the Oracle
-          Enterprise kernel or "default" or "desktop" for the
-          standard SUSE kernels.  In this case the package name is
-          <computeroutput>kernel-uek-devel</computeroutput> or
-          equivalent.  If there is no such code, it is usually
-          <computeroutput>kernel-devel</computeroutput>.</para>
-        </listitem>
-
-        <listitem>
-          <para>On older SUSE and openSUSE Linux, you must install
-          the <computeroutput>kernel-source</computeroutput>
-          and <computeroutput>kernel-syms</computeroutput>
-          packages.</para>
-        </listitem>
-      </itemizedlist>
-
-      <para>If you suspect that something has gone wrong with module installation,
-      check that your system is set up as described above and try running (as root)
-      the following command:</para>
-
-      <screen>rcvboxdrv setup</screen>
-    </sect2>
-
-    <sect2>
-      <title>Performing the installation</title>
-
-      <para>VirtualBox is available in a number of package formats native to
-      various common Linux distributions (see <xref linkend="hostossupport" />
-      for details). In addition, there is an alternative generic installer
-      (.run) which should work on most Linux distributions. The generic
-      installer packages are built on EL5 systems and thus require reasonable
-      old versions of glibc (version 2.5) and other system libraries.</para>
-
-      <sect3>
-        <title>Installing VirtualBox from a Debian/Ubuntu package</title>
-
-        <para>First, download the appropriate package for your distribution.
-        The following examples assume that you are installing to a 32-bit
-        Ubuntu Wily system. Use <computeroutput>dpkg</computeroutput> to
-        install the Debian package:</para>
-
-        <screen>sudo dpkg -i virtualbox-5.0_@VBOX_VERSION_STRING@_Ubuntu_wily_i386.deb</screen>
-
-        <para>The installer will also try to build kernel modules suitable for
-        the current running kernel. If the build process is not successful you
-        will be shown a
-        warning and the package will be left unconfigured. Please have a look
-        at <computeroutput>/var/log/vbox-install.log</computeroutput> to find
-        out why the compilation failed. You may have to install the
-        appropriate Linux kernel headers (see <xref
-        linkend="externalkernelmodules" />). After correcting any problems, do
-        <screen>sudo rcvboxdrv setup</screen>This will start a
-        second attempt to build the module.</para>
-
-        <para>If a suitable kernel module was found in the package or the
-        module was successfully built, the installation script will attempt to
-        load that module. If this fails, please see <xref
-        linkend="ts_linux-kernelmodule-fails-to-load" /> for further
-        information.</para>
-
-        <para>Once VirtualBox has been successfully installed and configured,
-        you can start it by selecting "VirtualBox" in your start menu or from
-        the command line (see <xref linkend="startingvboxonlinux" />).</para>
+
+          <listitem>
+            <para>
+              Creates a new system group called
+              <computeroutput>vboxusers</computeroutput>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Creates symbolic links in
+              <computeroutput>/usr/bin</computeroutput> to a shell
+              script
+              <computeroutput>/opt/VirtualBox/VBox</computeroutput>
+              which does some sanity checks and dispatches to the actual
+              executables: <computeroutput>VirtualBox</computeroutput>,
+              <computeroutput>VBoxSDL</computeroutput>,
+              <computeroutput>VBoxVRDP</computeroutput>,
+              <computeroutput>VBoxHeadless</computeroutput> and
+              <computeroutput>VBoxManage</computeroutput>
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Creates
+              <computeroutput>/etc/udev/rules.d/60-vboxdrv.rules</computeroutput>,
+              a description file for udev, if that is present, which
+              makes the USB devices accessible to all users in the
+              <computeroutput>vboxusers</computeroutput> group.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Writes the installation directory to
+              <computeroutput>/etc/vbox/vbox.cfg</computeroutput>.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          The installer must be executed as root with either
+          <computeroutput>install</computeroutput> or
+          <computeroutput>uninstall</computeroutput> as the first
+          parameter. For example;
+        </para>
+
+<screen>sudo ./VirtualBox.run install</screen>
+
+        <para>
+          Or if you do not have the
+          <computeroutput>sudo</computeroutput> command available, run
+          the following as root instead:
+
+<screen>./VirtualBox.run install</screen>
+        </para>
+
+        <para>
+          Add every user who needs to access USB devices from a
+          VirtualBox guests to the group
+          <computeroutput>vboxusers</computeroutput>. Either use the GUI
+          user management tools or run the following command as root:
+        </para>
+
+<screen>sudo usermod -a -G vboxusers username</screen>
+
+        <note>
+          <para>
+            The <computeroutput>usermod</computeroutput> command of some
+            older Linux distributions does not support the
+            <computeroutput>-a</computeroutput> option, which adds the
+            user to the given group without affecting membership of
+            other groups. In this case, find out the current group
+            memberships with the <computeroutput>groups</computeroutput>
+            command and add all these groups in a comma-separated list
+            to the command line after the
+            <computeroutput>-G</computeroutput> option. For example:
+            <computeroutput>usermod -G group1,group2,vboxusers
+            username</computeroutput>.
+          </para>
+        </note>
+
       </sect3>
 
-      <sect3>
-        <title>Using the alternative generic installer (VirtualBox.run)</title>
-
-        <para>The alternative generic installer performs the following steps:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para>It unpacks the application files to the target directory,
-            <screen>/opt/VirtualBox/</screen> which cannot be changed.</para>
-          </listitem>
-
-          <listitem>
-            <para>It builds the VirtualBox kernel modules
-            (<computeroutput>vboxdrv</computeroutput>,
-            <computeroutput>vboxnetflt</computeroutput> and
-            <computeroutput>vboxnetadp</computeroutput>) and installs
-            them.</para>
-          </listitem>
-
-          <listitem>
-            <para>It creates
-            <computeroutput>/sbin/rcvboxdrv</computeroutput>, an init
-            script to start the VirtualBox kernel module.</para>
-          </listitem>
-
-          <listitem>
-            <para>It creates a new system group called
-            <computeroutput>vboxusers</computeroutput>.</para>
-          </listitem>
-
-          <listitem>
-            <para>It creates symbolic links in
-            <computeroutput>/usr/bin</computeroutput> to the a shell script
-            (<computeroutput>/opt/VirtualBox/VBox</computeroutput>) which does
-            some sanity checks and dispatches to the actual executables,
-            <computeroutput>VirtualBox</computeroutput>,
-            <computeroutput>VBoxSDL</computeroutput>,
-            <computeroutput>VBoxVRDP</computeroutput>,
-            <computeroutput>VBoxHeadless</computeroutput> and
-            <computeroutput>VBoxManage</computeroutput></para>
-          </listitem>
-
-          <listitem>
-            <para>It creates
-            <computeroutput>/etc/udev/rules.d/60-vboxdrv.rules</computeroutput>,
-            a description file for udev, if that is present, which makes the
-            USB devices accessible to all users in the
-            <computeroutput>vboxusers</computeroutput> group.</para>
-          </listitem>
-
-          <listitem>
-            <para>It writes the installation directory to
-            <computeroutput>/etc/vbox/vbox.cfg</computeroutput>.</para>
-          </listitem>
-        </itemizedlist>
-
-        <para>The installer must be executed as root with either
-        <computeroutput>install</computeroutput> or
-        <computeroutput>uninstall</computeroutput> as the first
-        parameter.</para>
-
-        <screen>sudo ./VirtualBox.run install</screen>
-
-        <para>Or if you do not have the "sudo" command available, run the
-        following as root instead:<screen>./VirtualBox.run install</screen></para>
-
-        <para>After that you need to put every user which should be able to
-        access USB devices from VirtualBox guests in the group
-        <computeroutput>vboxusers</computeroutput>, either through the GUI
-        user management tools or by running the following command as
-        root:</para>
-
-        <screen>sudo usermod -a -G vboxusers username</screen>
-
-        <para><note>
-            <para>The <computeroutput>usermod</computeroutput> command of some
-            older Linux distributions does not support the
-            <computeroutput>-a</computeroutput> option (which adds the user to
-            the given group without affecting membership of other groups). In
-            this case, find out the current group memberships with the
-            <computeroutput>groups</computeroutput> command and add all these
-            groups in a comma-separated list to the command line after the
-            <computeroutput>-G</computeroutput> option, e.g. like this:
-            <computeroutput>usermod -G group1,group2,vboxusers
-            username</computeroutput>.</para>
-          </note></para>
-      </sect3>
-
-      <sect3>
-        <title>Performing a manual installation</title>
-
-        <para>If, for any reason, you cannot use the shell script installer
-        described previously, you can also perform a manual installation.
-        Invoke the installer like this:</para>
-
-        <screen>./VirtualBox.run --keep --noexec</screen>
-
-        <para>This will unpack all the files needed for installation in the
-        directory <computeroutput>install</computeroutput> under the current
-        directory. The VirtualBox application files are contained in
-        <computeroutput>VirtualBox.tar.bz2</computeroutput> which you can
-        unpack to any directory on your system. For example:</para>
-
-        <screen>sudo mkdir /opt/VirtualBox
+      <sect3 id="install-linux-manual">
+
+        <title>Performing a Manual Installation</title>
+
+        <para>
+          If you cannot use the shell script installer described in
+          <xref linkend="install-linux-alt-installer"/>, you can perform
+          a manual installation. Invoke the installer as follows:
+        </para>
+
+<screen>./VirtualBox.run --keep --noexec</screen>
+
+        <para>
+          This will unpack all the files needed for installation in the
+          directory <computeroutput>install</computeroutput> under the
+          current directory. The VirtualBox application files are
+          contained in
+          <computeroutput>VirtualBox.tar.bz2</computeroutput> which you
+          can unpack to any directory on your system. For example:
+        </para>
+
+<screen>sudo mkdir /opt/VirtualBox
 sudo tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen>
 
-        <para>or as root:<screen>mkdir /opt/VirtualBox
-tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen></para>
-
-        <para>The sources for VirtualBox's kernel module are provided in the
-        <computeroutput>src</computeroutput> directory. To build the module,
-        change to the directory and issue</para>
-
-        <screen>make</screen>
-
-        <para>If everything builds correctly, issue the following command to
-        install the module to the appropriate module directory:</para>
-
-        <screen>sudo make install</screen>
-
-        <para>In case you do not have sudo, switch the user account to root
-        and perform<screen>make install</screen></para>
-
-        <para>The VirtualBox kernel module needs a device node to operate. The
-        above make command will tell you how to create the device node,
-        depending on your Linux system. The procedure is slightly different
-        for a classical Linux setup with a
-        <computeroutput>/dev</computeroutput> directory, a system with the now
-        deprecated <computeroutput>devfs</computeroutput> and a modern Linux
-        system with <computeroutput>udev</computeroutput>.</para>
-
-        <para>On certain Linux distributions, you might experience
-        difficulties building the module. You will have to analyze the error
-        messages from the build system to diagnose the cause of the problems.
-        In general, make sure that the correct Linux kernel sources are used
-        for the build process.</para>
-
-        <para>Note that the <computeroutput>/dev/vboxdrv</computeroutput>
-        kernel module device node must be owned by root:root and must be
-        read/writable only for the user.</para>
-
-        <para>Next, you will have to install the system initialization script
-        for the kernel module:<screen>cp /opt/VirtualBox/vboxdrv.sh /sbin/rcvboxdrv</screen>(assuming
-        you installed VirtualBox to the
-        <computeroutput>/opt/VirtualBox</computeroutput> directory) and
-        activate the initialization script using the right method for your
-        distribution. You should create VirtualBox's configuration
-        file:<screen>mkdir /etc/vbox
-echo INSTALL_DIR=/opt/VirtualBox &gt; /etc/vbox/vbox.cfg</screen>and, for
-        convenience, create the following symbolic links:</para>
-
-        <screen>ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VirtualBox
+        <para>
+          or as root:
+
+<screen>mkdir /opt/VirtualBox
+tar jxf ./install/VirtualBox.tar.bz2 -C /opt/VirtualBox</screen>
+        </para>
+
+        <para>
+          The sources for VirtualBox's kernel module are provided in the
+          <computeroutput>src</computeroutput> directory. To build the
+          module, change to the directory and issue
+        </para>
+
+<screen>make</screen>
+
+        <para>
+          If everything builds correctly, issue the following command to
+          install the module to the appropriate module directory:
+        </para>
+
+<screen>sudo make install</screen>
+
+        <para>
+          In case you do not have sudo, switch the user account to root
+          and run the following command:
+
+<screen>make install</screen>
+        </para>
+
+        <para>
+          The VirtualBox kernel module needs a device node to operate.
+          The above make command will tell you how to create the device
+          node, depending on your Linux system. The procedure is
+          slightly different for a classical Linux setup with a
+          <computeroutput>/dev</computeroutput> directory, a system with
+          the now deprecated <computeroutput>devfs</computeroutput> and
+          a modern Linux system with
+          <computeroutput>udev</computeroutput>.
+        </para>
+
+        <para>
+          On certain Linux distributions, you might experience
+          difficulties building the module. You will have to analyze the
+          error messages from the build system to diagnose the cause of
+          the problems. In general, make sure that the correct Linux
+          kernel sources are used for the build process.
+        </para>
+
+        <para>
+          Note that the <computeroutput>/dev/vboxdrv</computeroutput>
+          kernel module device node must be owned by root:root and must
+          be read/writable only for the user.
+        </para>
+
+        <para>
+          Next, you install the system initialization script for the
+          kernel module and activate the initialization script using the
+          right method for your distribution, as follows:
+
+<screen>cp /opt/VirtualBox/vboxdrv.sh /sbin/rcvboxdrv</screen>
+
+          This example assumes you installed VirtualBox to the
+          <computeroutput>/opt/VirtualBox</computeroutput> directory.
+          Create a configuration file for VitrualBox:
+
+<screen>mkdir /etc/vbox
+echo INSTALL_DIR=/opt/VirtualBox &gt; /etc/vbox/vbox.cfg</screen>
+
+          Create the following symbolic links:
+        </para>
+
+<screen>ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VirtualBox
 ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxManage
 ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxHeadless
 ln -sf /opt/VirtualBox/VBox.sh /usr/bin/VBoxSDL</screen>
+
       </sect3>
 
-      <sect3>
-        <title>Updating and uninstalling VirtualBox</title>
-
-        <para>Before updating or uninstalling VirtualBox, you must terminate
-        any virtual machines which are currently running and exit the
-        VirtualBox or VBoxSVC applications. To update VirtualBox, simply run
-        the installer of the updated version. To uninstall VirtualBox, invoke
-        the installer like this: <screen>sudo ./VirtualBox.run uninstall</screen>
-        or as root<screen>./VirtualBox.run uninstall</screen>. Starting with
-        version 2.2.2, you can uninstall the .run package by invoking <screen>/opt/VirtualBox/uninstall.sh</screen>To
-        manually uninstall VirtualBox, simply undo the steps in the manual
-        installation in reverse order.</para>
+      <sect3 id="install-linux-update-uninstall">
+
+        <title>Updating and Uninstalling VirtualBox</title>
+
+        <para>
+          Before updating or uninstalling VirtualBox, you must terminate
+          any virtual machines which are currently running and exit the
+          VirtualBox or VBoxSVC applications. To update VirtualBox,
+          simply run the installer of the updated version. To uninstall
+          VirtualBox, invoke the installer like this:
+
+<screen>sudo ./VirtualBox.run uninstall</screen>
+
+          or as root:
+
+<screen>./VirtualBox.run uninstall</screen>
+
+          Starting with version 2.2.2, you can uninstall the .run
+          package as follows:
+
+<screen>/opt/VirtualBox/uninstall.sh</screen>
+
+          To manually uninstall VirtualBox, simply perform the manual
+          installation steps in reverse order.
+        </para>
+
       </sect3>
 
-      <sect3>
-        <title>Automatic installation of Debian packages</title>
-
-        <para>The Debian packages will request some user feedback when
-        installed for the first time. The debconf system is used to perform
-        this task. To prevent any user interaction during installation,
-        default values can be defined. A file
-        <computeroutput>vboxconf</computeroutput> can contain the following
-        debconf settings: <screen>virtualbox virtualbox/module-compilation-allowed boolean true
-virtualbox virtualbox/delete-old-modules boolean true</screen>The first line
-        allows compilation of the vboxdrv kernel module if no module was found
-        for the current kernel. The second line allows the package to delete
-        any old vboxdrv kernel modules compiled by previous
-        installations.</para>
-
-        <para>These default settings can be applied with <screen>debconf-set-selections vboxconf</screen>
-        prior to the installation of the VirtualBox Debian package.</para>
-
-        <para>In addition there are some common configuration options that can
-        be set prior to the installation, described in <xref
-        linkend="linux_install_opts" />.</para>
+      <sect3 id="install-linux-debian-automatic">
+
+        <title>Automatic Installation of Debian Packages</title>
+
+        <para>
+          The Debian packages will request some user feedback when
+          installed for the first time. The debconf system is used to
+          perform this task. To prevent any user interaction during
+          installation, default values can be defined. A file
+          <computeroutput>vboxconf</computeroutput> can contain the
+          following debconf settings:
+
+<screen>virtualbox virtualbox/module-compilation-allowed boolean true
+virtualbox virtualbox/delete-old-modules boolean true</screen>
+
+          The first line allows compilation of the vboxdrv kernel module
+          if no module was found for the current kernel. The second line
+          allows the package to delete any old vboxdrv kernel modules
+          compiled by previous installations.
+        </para>
+
+        <para>
+          These default settings can be applied prior to the
+          installation of the VirtualBox Debian package, as follows:
+        </para>
+
+<screen>debconf-set-selections vboxconf</screen>
+
+        <para>
+          In addition there are some common configuration options that
+          can be set prior to the installation. See
+          <xref
+        linkend="linux_install_opts" />.
+        </para>
+
       </sect3>
 
-      <sect3>
-        <title>Automatic installation of .rpm packages</title>
-
-        <para>The .rpm format does not provide a configuration system
-        comparable to the debconf system. See <xref
-        linkend="linux_install_opts" /> for how to set some common
-        installation options provided by VirtualBox.</para>
+      <sect3 id="install-linux-rpm-automatic">
+
+        <title>Automatic Installation of RPM Packages</title>
+
+        <para>
+          The RPM format does not provide a configuration system
+          comparable to the debconf system. See
+          <xref
+        linkend="linux_install_opts" /> for how to set
+          some common installation options provided by VirtualBox.
+        </para>
+
       </sect3>
 
       <sect3 id="linux_install_opts">
-        <title>Automatic installation options</title>
-
-        <para>To configure the installation process of our .deb and .rpm
-        packages, you can create a response file named
-        <computeroutput>/etc/default/virtualbox</computeroutput>. The
-        automatic generation of the udev rule can be prevented by the
-        following setting: <screen>INSTALL_NO_UDEV=1</screen> The creation of
-        the group vboxusers can be prevented by <screen>INSTALL_NO_GROUP=1</screen>
-        If the line <screen>INSTALL_NO_VBOXDRV=1</screen> is specified, the
-        package installer will not try to build the
-        <computeroutput>vboxdrv</computeroutput> kernel module if no module
-        fitting the current kernel was found.</para>
+
+        <title>Automatic Installation Options</title>
+
+        <para>
+          To configure the installation process for .deb and .rpm
+          packages, you can create a response file named
+          <computeroutput>/etc/default/virtualbox</computeroutput>. The
+          automatic generation of the udev rule can be prevented by the
+          following setting:
+
+<screen>INSTALL_NO_UDEV=1</screen>
+
+          The creation of the group vboxusers can be prevented as
+          follows:
+
+<screen>INSTALL_NO_GROUP=1</screen>
+
+          If the following line is specified, the package installer will
+          not try to build the <computeroutput>vboxdrv</computeroutput>
+          kernel module if no module fitting the current kernel was
+          found.
+        </para>
+
+<screen>INSTALL_NO_VBOXDRV=1</screen>
+
       </sect3>
-    </sect2>
-
-    <sect2>
-      <title>The vboxusers group</title>
-
-      <para>The Linux installers create the system user group
-      <computeroutput>vboxusers</computeroutput> during installation. Any
-      system user who is going to use USB devices from VirtualBox guests must
-      be a member of that group. A user can be made a member of the group
-      <computeroutput>vboxusers</computeroutput> through the GUI user/group
-      management or at the command line with</para>
-
-      <screen>sudo usermod -a -G vboxusers username</screen>
+
+    </sect2>
+
+    <sect2 id="install-linux-vboxusers">
+
+      <title>The vboxusers Group</title>
+
+      <para>
+        The Linux installers create the system user group
+        <computeroutput>vboxusers</computeroutput> during installation.
+        Any system user who is going to use USB devices from VirtualBox
+        guests must be a member of that group. A user can be made a
+        member of the group <computeroutput>vboxusers</computeroutput>
+        through the GUI user/group management or using the following
+        command:
+      </para>
+
+<screen>sudo usermod -a -G vboxusers username</screen>
+
     </sect2>
 
     <sect2 id="startingvboxonlinux">
+
       <title>Starting VirtualBox on Linux</title>
 
-      <para>The easiest way to start a VirtualBox program is by running the
-      program of your choice (<computeroutput>VirtualBox</computeroutput>,
-      <computeroutput>VBoxManage</computeroutput>,
-      <computeroutput>VBoxSDL</computeroutput> or
-      <computeroutput>VBoxHeadless</computeroutput>) from a terminal. These
-      are symbolic links to <computeroutput>VBox.sh</computeroutput> that
-      start the required program for you.</para>
-
-      <para>The following detailed instructions should only be of interest if
-      you wish to execute VirtualBox without installing it first. You should
-      start by compiling the <computeroutput>vboxdrv</computeroutput> kernel
-      module (see above) and inserting it into the Linux kernel. VirtualBox
-      consists of a service daemon (<computeroutput>VBoxSVC</computeroutput>)
-      and several application programs. The daemon is automatically started if
-      necessary. All VirtualBox applications will communicate with the daemon
-      through Unix local domain sockets. There can be multiple daemon
-      instances under different user accounts and applications can only
-      communicate with the daemon running under the user account as the
-      application. The local domain socket resides in a subdirectory of your
-      system's directory for temporary files called
-      <computeroutput>.vbox-&lt;username&gt;-ipc</computeroutput>. In case of
-      communication problems or server startup problems, you may try to remove
-      this directory.</para>
-
-      <para>All VirtualBox applications
-      (<computeroutput>VirtualBox</computeroutput>,
-      <computeroutput>VBoxSDL</computeroutput>,
-      <computeroutput>VBoxManage</computeroutput> and
-      <computeroutput>VBoxHeadless</computeroutput>) require the VirtualBox
-      directory to be in the library path:</para>
-
-      <screen>LD_LIBRARY_PATH=. ./VBoxManage showvminfo "Windows XP"</screen>
-    </sect2>
+      <para>
+        The easiest way to start a VirtualBox program is by running the
+        program of your choice
+        (<computeroutput>VirtualBox</computeroutput>,
+        <computeroutput>VBoxManage</computeroutput>,
+        <computeroutput>VBoxSDL</computeroutput>, or
+        <computeroutput>VBoxHeadless</computeroutput>) from a terminal.
+        These are symbolic links to
+        <computeroutput>VBox.sh</computeroutput> that start the required
+        program for you.
+      </para>
+
+      <para>
+        The following detailed instructions should only be of interest
+        if you wish to execute VirtualBox without installing it first.
+        You should start by compiling the
+        <computeroutput>vboxdrv</computeroutput> kernel module and
+        inserting it into the Linux kernel. VirtualBox consists of a
+        service daemon, <computeroutput>VBoxSVC</computeroutput>, and
+        several application programs. The daemon is automatically
+        started if necessary. All VirtualBox applications will
+        communicate with the daemon through Unix local domain sockets.
+        There can be multiple daemon instances under different user
+        accounts and applications can only communicate with the daemon
+        running under the user account as the application. The local
+        domain socket resides in a subdirectory of your system's
+        directory for temporary files called
+        <computeroutput>.vbox-&lt;username&gt;-ipc</computeroutput>. In
+        case of communication problems or server startup problems, you
+        may try to remove this directory.
+      </para>
+
+      <para>
+        All VirtualBox applications
+        (<computeroutput>VirtualBox</computeroutput>,
+        <computeroutput>VBoxSDL</computeroutput>,
+        <computeroutput>VBoxManage</computeroutput>, and
+        <computeroutput>VBoxHeadless</computeroutput>) require the
+        VirtualBox directory to be in the library path, as follows:
+      </para>
+
+<screen>LD_LIBRARY_PATH=. ./VBoxManage showvminfo "Windows XP"</screen>
+
+    </sect2>
+
   </sect1>
 
   <sect1 id="install-solaris-host">
-    <title>Installing on Solaris hosts</title>
-
-    <para>For the specific versions of Solaris that we support as host
-    operating systems, please refer to <xref
-    linkend="hostossupport" />.</para>
-
-    <para>If you have a previously installed instance of VirtualBox on your
-    Solaris host, please uninstall it first before installing a new instance.
-    Refer to <xref linkend="uninstall-solaris-host" /> for uninstall
-    instructions.</para>
-
-    <sect2>
-      <title>Performing the installation</title>
-
-      <para>VirtualBox is available as a standard Solaris package. Download
-      the VirtualBox SunOS package which includes the 64-bit
-      versions of VirtualBox. <emphasis>The installation must be performed as
-      root and from the global zone</emphasis> as the VirtualBox installer
-      loads kernel drivers which cannot be done from non-global zones. To
-      verify which zone you are currently in, execute the
-      <computeroutput>zonename</computeroutput> command. Execute the following
-      commands:</para>
-
-      <screen>gunzip -cd VirtualBox-@VBOX_VERSION_STRING@-SunOS.tar.gz | tar xvf -</screen>
-
-      <para>Starting with VirtualBox 3.1 the VirtualBox kernel package is no
-      longer a separate package and has been integrated into the main package.
-      Install the VirtualBox package using:</para>
-
-      <screen>pkgadd -d VirtualBox-@VBOX_VERSION_STRING@-SunOS.pkg</screen>
-
-      <para>The installer will then prompt you to enter the package you wish
-      to install. Choose "1" or "all" and proceed. Next the installer will ask
-      you if you want to allow the postinstall script to be executed. Choose
-      "y" and proceed as it is essential to execute this script which installs
-      the VirtualBox kernel module. Following this confirmation the installer
-      will install VirtualBox and execute the postinstall setup script.</para>
-
-      <para>Once the postinstall script has been executed your installation is
-      now complete. You may now safely delete the uncompressed package and
-      <computeroutput>autoresponse</computeroutput> files from your system.
-      VirtualBox would be installed in
-      <computeroutput>/opt/VirtualBox</computeroutput>.</para>
+
+    <title>Installing on Solaris Hosts</title>
+
+    <para>
+      For the specific versions of Solaris that are supported as host
+      operating systems, see <xref
+    linkend="hostossupport" />.
+    </para>
+
+    <para>
+      If you have a previously installed instance of VirtualBox on your
+      Solaris host, please uninstall it first before installing a new
+      instance. See <xref linkend="uninstall-solaris-host" /> for
+      uninstall instructions.
+    </para>
+
+    <sect2 id="install-solaris-performing">
+
+      <title>Performing the Installation</title>
+
+      <para>
+        VirtualBox is available as a standard Solaris package. Download
+        the VirtualBox SunOS package which includes the 64-bit versions
+        of VirtualBox. <emphasis>The installation must be performed as
+        root and from the global zone</emphasis> as the VirtualBox
+        installer loads kernel drivers which cannot be done from
+        non-global zones. To verify which zone you are currently in,
+        execute the <computeroutput>zonename</computeroutput> command.
+        Execute the following commands:
+      </para>
+
+<screen>gunzip -cd VirtualBox-<replaceable>version-number</replaceable>-SunOS.tar.gz | tar xvf -</screen>
+
+      <para>
+        Starting with VirtualBox 3.1 the VirtualBox kernel package is no
+        longer a separate package and has been integrated into the main
+        package. Install the VirtualBox package as follows:
+      </para>
+
+<screen>pkgadd -d VirtualBox-<replaceable>version-number</replaceable>-SunOS.pkg</screen>
+
+      <para>
+        The installer will then prompt you to enter the package you wish
+        to install. Choose <emphasis role="bold">1</emphasis> or
+        <emphasis role="bold">all</emphasis> and proceed. Next the
+        installer will ask you if you want to allow the postinstall
+        script to be executed. Choose <emphasis role="bold">y</emphasis>
+        and proceed, as it is essential to execute this script which
+        installs the VirtualBox kernel module. Following this
+        confirmation the installer will install VirtualBox and execute
+        the postinstall setup script.
+      </para>
+
+      <para>
+        Once the postinstall script has been executed your installation
+        is now complete. You may now safely delete the uncompressed
+        package and <computeroutput>autoresponse</computeroutput> files
+        from your system. VirtualBox is installed in
+        <computeroutput>/opt/VirtualBox</computeroutput>.
+      </para>
 
       <note>
-        <para>If you need to use VirtualBox from non-global zones, please read
-        <xref linkend="solaris-zones" />.</para>
+        <para>
+          If you need to use VirtualBox from non-global zones, see
+          <xref linkend="solaris-zones" />.
+        </para>
       </note>
-    </sect2>
-
-    <sect2>
-      <title>The vboxuser group</title>
-
-      <para>Starting with VirtualBox 4.1, the installer creates the system
-      user group <computeroutput>vboxuser</computeroutput> during installation
-      for Solaris hosts that support the USB features required by VirtualBox.
-      Any system user who is going to use USB devices from VirtualBox guests
-      must be a member of this group. A user can be made a member of this
-      group through the GUI user/group management or at the command line by
-      executing as root:</para>
-
-      <screen>usermod -G vboxuser username</screen>
-
-      <para>Note that adding an active user to that group will require that
-      user to log out and back in again. This should be done manually after
-      successful installation of the package.</para>
-    </sect2>
-
-    <sect2>
+
+    </sect2>
+
+    <sect2 id="install-solaris-vboxuser">
+
+      <title>The vboxuser Group</title>
+
+      <para>
+        Starting with VirtualBox 4.1, the installer creates the system
+        user group <computeroutput>vboxuser</computeroutput> during
+        installation for Solaris hosts that support the USB features
+        required by VirtualBox. Any system user who is going to use USB
+        devices from VirtualBox guests must be a member of this group. A
+        user can be made a member of this group through the GUI
+        user/group management or at the command line by executing as
+        root:
+      </para>
+
+<screen>usermod -G vboxuser username</screen>
+
+      <para>
+        Note that adding an active user to that group will require that
+        user to log out and back in again. This should be done manually
+        after successful installation of the package.
+      </para>
+
+    </sect2>
+
+    <sect2 id="install-solaris-starting">
+
       <title>Starting VirtualBox on Solaris</title>
 
-      <para>The easiest way to start a VirtualBox program is by running the
-      program of your choice (<computeroutput>VirtualBox</computeroutput>,
-      <computeroutput>VBoxManage</computeroutput>,
-      <computeroutput>VBoxSDL</computeroutput> or
-      <computeroutput>VBoxHeadless</computeroutput>) from a terminal. These
-      are symbolic links to <computeroutput>VBox.sh</computeroutput> that
-      start the required program for you.</para>
-
-      <para>Alternatively, you can directly invoke the required programs from
-      <computeroutput>/opt/VirtualBox</computeroutput>. Using the links
-      provided is easier as you do not have to type the full path.</para>
-
-      <para>You can configure some elements of the
-      <computeroutput>VirtualBox</computeroutput> Qt GUI such as fonts and
-      colours by executing <computeroutput>VBoxQtconfig</computeroutput> from
-      the terminal.</para>
+      <para>
+        The easiest way to start a VirtualBox program is by running the
+        program of your choice
+        (<computeroutput>VirtualBox</computeroutput>,
+        <computeroutput>VBoxManage</computeroutput>,
+        <computeroutput>VBoxSDL</computeroutput>, or
+        <computeroutput>VBoxHeadless</computeroutput>) from a terminal.
+        These are symbolic links to
+        <computeroutput>VBox.sh</computeroutput> that start the required
+        program for you.
+      </para>
+
+      <para>
+        Alternatively, you can directly invoke the required programs
+        from <computeroutput>/opt/VirtualBox</computeroutput>. Using the
+        links provided is easier as you do not have to type the full
+        path.
+      </para>
+
+      <para>
+        You can configure some elements of the
+        <computeroutput>VirtualBox</computeroutput> Qt GUI, such as
+        fonts and colours, by running
+        <computeroutput>VBoxQtconfig</computeroutput> from the terminal.
+      </para>
+
     </sect2>
 
     <sect2 id="uninstall-solaris-host">
+
       <title>Uninstallation</title>
 
-      <para>Uninstallation of VirtualBox on Solaris requires root permissions.
-      To perform the uninstallation, start a root terminal session and
-      execute:</para>
-
-      <screen>pkgrm SUNWvbox</screen>
-
-      <para>After confirmation, this will remove VirtualBox from your
-      system.</para>
-
-      <para>If you are uninstalling VirtualBox version 3.0 or lower, you need
-      to remove the VirtualBox kernel interface package, execute:</para>
-
-      <para><screen>pkgrm SUNWvboxkern</screen></para>
-    </sect2>
-
-    <sect2>
-      <title>Unattended installation</title>
-
-      <para>To perform a non-interactive installation of VirtualBox we have
-      provided a response file named
-      <computeroutput>autoresponse</computeroutput> that the installer will
-      use for responses to inputs rather than ask them from you.</para>
-
-      <para>Extract the tar.gz package as described in the normal
-      installation. Then open a root terminal session and execute:</para>
-
-      <screen>pkgadd -d VirtualBox-@VBOX_VERSION_STRING@-SunOS-x86 -n -a autoresponse SUNWvbox</screen>
-
-      <para>To perform a non-interactive uninstallation, open a root terminal
-      session and execute:</para>
-
-      <screen>pkgrm -n -a /opt/VirtualBox/autoresponse SUNWvbox</screen>
+      <para>
+        Uninstallation of VirtualBox on Solaris requires root
+        permissions. To perform the uninstallation, start a root
+        terminal session and run the following command:
+      </para>
+
+<screen>pkgrm SUNWvbox</screen>
+
+      <para>
+        After confirmation, this will remove VirtualBox from your
+        system.
+      </para>
+
+      <para>
+        If you are uninstalling VirtualBox version 3.0 or lower, you
+        need to remove the VirtualBox kernel interface package, as
+        follows:
+      </para>
+
+      <para>
+<screen>pkgrm SUNWvboxkern</screen>
+      </para>
+
+    </sect2>
+
+    <sect2 id="install-solaris-unattended">
+
+      <title>Unattended Installation</title>
+
+      <para>
+        To perform a non-interactive installation of VirtualBox there is
+        a response file named
+        <computeroutput>autoresponse</computeroutput>, that the
+        installer will use for responses to inputs rather than ask them
+        from you.
+      </para>
+
+      <para>
+        Extract the tar.gz package as described in the normal
+        installation instructions. Then open a root terminal session and
+        run the following command:
+      </para>
+
+<screen>pkgadd -d VirtualBox-<replaceable>version-number</replaceable>-SunOS-x86 -n -a autoresponse SUNWvbox</screen>
+
+      <para>
+        To perform a non-interactive uninstallation, open a root
+        terminal session and run the following command:
+      </para>
+
+<screen>pkgrm -n -a /opt/VirtualBox/autoresponse SUNWvbox</screen>
+
     </sect2>
 
     <sect2 id="solaris-zones">
-      <title>Configuring a zone for running VirtualBox</title>
-
-      <para>Assuming that VirtualBox has already been installed into your
-      zone, you need to give the zone access to VirtualBox's device node. This
-      is done by performing the following steps. Start a root terminal and
-      execute:</para>
-
-      <screen>zonecfg -z vboxzone</screen>
-
-      <para>Replace "vboxzone" with the name of the zone in which you intend
-      to run VirtualBox.</para>
-
-      <para>Inside the <computeroutput>zonecfg</computeroutput> prompt add the
-      <computeroutput>device</computeroutput> resource and
-      <computeroutput>match</computeroutput> properties to the zone. Here's
-      how it can be done:</para>
-
-      <screen>zonecfg:vboxzone&gt;add device
+
+      <title>Configuring a Zone for Running VirtualBox</title>
+
+      <para>
+        Assuming that VirtualBox has already been installed into your
+        zone, you need to give the zone access to VirtualBox's device
+        node. This is done by performing the following steps. Start a
+        root terminal and run the following command:
+      </para>
+
+<screen>zonecfg -z vboxzone</screen>
+
+      <para>
+        Replace "vboxzone" with the name of the zone where you intend to
+        run VirtualBox.
+      </para>
+
+      <para>
+        Use<computeroutput>zonecfg</computeroutput> to add the
+        <computeroutput>device</computeroutput> resource and
+        <computeroutput>match</computeroutput> properties to the zone,
+        as follows:
+      </para>
+
+<screen>zonecfg:vboxzone&gt;add device
 zonecfg:vboxzone:device&gt;set match=/dev/vboxdrv
 zonecfg:vboxzone:device&gt;end
@@ -897,16 +1323,22 @@
 zonecfg:vboxzone&gt;exit</screen>
 
-      <para>If you are running VirtualBox 2.2.0 or above on Solaris 11 or
-      above, you may add a device for <computeroutput>/dev/vboxusbmon</computeroutput>
-      too, similar to what was shown above. This does not apply to Solaris 10
-      hosts due to lack of USB support.</para>
-
-      <para>If you are not using sparse root zones, you will need to loopback
-      mount <computeroutput>/opt/VirtualBox</computeroutput> from the global zone
-      (specified below using the <computeroutput>dir</computeroutput> attribute) into
-      the non-global zone at the same path (specified using the
-      <computeroutput>special</computeroutput> attribute). For example:</para>
-
-      <screen>zonecfg:vboxzone&gt;add fs
+      <para>
+        If you are running VirtualBox 2.2.0 or above on Solaris 11 or
+        above, you may also add a device for
+        <computeroutput>/dev/vboxusbmon</computeroutput>, similar to
+        that shown above. This does not apply to Solaris 10 hosts, due
+        to lack of USB support.
+      </para>
+
+      <para>
+        If you are not using sparse root zones, you will need to
+        loopback mount <computeroutput>/opt/VirtualBox</computeroutput>
+        from the global zone into the non-global zone at the same path.
+        This is specified below using the
+        <computeroutput>dir</computeroutput> attribute and the
+        <computeroutput>special</computeroutput> attribute. For example:
+      </para>
+
+<screen>zonecfg:vboxzone&gt;add fs
 zonecfg:vboxzone:device&gt;set dir=/opt/VirtualBox
 zonecfg:vboxzone:device&gt;set special=/opt/VirtualBox
@@ -915,7 +1347,13 @@
 zonecfg:vboxzone&gt;exit</screen>
 
-      <para>Next reboot the zone using <computeroutput>zoneadm</computeroutput>
-      and you should be able to run VirtualBox from within the configured zone.</para>
-    </sect2>
+      <para>
+        Reboot the zone using <computeroutput>zoneadm</computeroutput>
+        and you should be able to run VirtualBox from within the
+        configured zone.
+      </para>
+
+    </sect2>
+
   </sect1>
+
 </chapter>
Index: /trunk/doc/manual/en_US/user_Introduction.xml
===================================================================
--- /trunk/doc/manual/en_US/user_Introduction.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_Introduction.xml	(revision 73276)
@@ -1,1598 +1,2355 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="Introduction">
-  <title>First steps</title>
-
-  <para>Welcome to @VBOX_PRODUCT@!</para>
-
-  <para>VirtualBox is a cross-platform virtualization application. What does
-  that mean? For one thing, it installs on your existing Intel or AMD-based
-  computers, whether they are running Windows, Mac, Linux or Solaris operating
-  systems. Secondly, it extends the capabilities of your existing computer so
-  that it can run multiple operating systems (inside multiple virtual
-  machines) at the same time. So, for example, you can run Windows and Linux
-  on your Mac, run Windows Server 2008 on your Linux server, run Linux on your
-  Windows PC, and so on, all alongside your existing applications. You can
-  install and run as many virtual machines as you like -- the only practical
-  limits are disk space and memory.</para>
-
-  <para>VirtualBox is deceptively simple yet also very powerful. It can run
-  everywhere from small embedded systems or desktop class machines all the way
-  up to datacenter deployments and even Cloud environments.</para>
-
-  <para>The following screenshot shows you how VirtualBox, installed on a Mac
-  computer, is running Windows 8 in a virtual machine window:</para>
-
-  <para><mediaobject>
+
+  <title>First Steps</title>
+
+  <para>
+    Welcome to Oracle VM VirtualBox.
+  </para>
+
+  <para>
+    VirtualBox is a cross-platform virtualization application. What does
+    that mean? For one thing, it installs on your existing Intel or
+    AMD-based computers, whether they are running Windows, Mac, Linux or
+    Solaris operating systems. Secondly, it extends the capabilities of
+    your existing computer so that it can run multiple operating
+    systems, inside multiple virtual machines, at the same time. So, for
+    example, you can run Windows and Linux on your Mac, run Windows
+    Server 2008 on your Linux server, run Linux on your Windows PC, and
+    so on, all alongside your existing applications. You can install and
+    run as many virtual machines as you like. The only practical limits
+    are disk space and memory.
+  </para>
+
+  <para>
+    VirtualBox is deceptively simple yet also very powerful. It can run
+    everywhere from small embedded systems or desktop class machines all
+    the way up to datacenter deployments and even Cloud environments.
+  </para>
+
+  <para>
+    The following screenshot shows how VirtualBox, installed on a Mac
+    computer, is running Windows 8 in a virtual machine window:
+  </para>
+
+  <mediaobject>
+    <imageobject>
+      <imagedata align="center" fileref="images/vm-vista-running.png"
+                   width="14cm" />
+    </imageobject>
+  </mediaobject>
+
+  <para>
+    In this User Manual, we will begin simply with a quick introduction
+    to virtualization and how to get your first virtual machine running
+    with the easy-to-use VirtualBox graphical user interface. Subsequent
+    chapters will go into much more detail covering more powerful tools
+    and features, but fortunately, it is not necessary to read the
+    entire User Manual before you can use VirtualBox.
+  </para>
+
+  <para>
+    You can find a summary of VirtualBox's capabilities in
+    <xref
+  linkend="features-overview" />. For existing VirtualBox
+    users who just want to see what is new in this release, there is a
+    detailed list in <xref
+  linkend="ChangeLog" />.
+  </para>
+
+  <sect1 id="virt-why-useful">
+
+    <title>Why is Virtualization Useful?</title>
+
+    <para>
+      The techniques and features that VirtualBox provides are useful in
+      the following scenarios:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Running multiple operating systems
+          simultaneously.</emphasis> VirtualBox allows you to run more
+          than one operating system at a time. This way, you can run
+          software written for one operating system on another, such as
+          Windows software on Linux or a Mac, without having to reboot
+          to use it. Since you can configure what kinds of "virtual"
+          hardware should be presented to each such operating system,
+          you can install an old operating system such as DOS or OS/2
+          even if your real computer's hardware is no longer supported
+          by that operating system.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Easier software
+          installations.</emphasis> Software vendors can use virtual
+          machines to ship entire software configurations. For example,
+          installing a complete mail server solution on a real machine
+          can be a tedious task. With VirtualBox, such a complex setup,
+          often called an "appliance", can be packed into a virtual
+          machine. Installing and running a mail server becomes as easy
+          as importing such an appliance into VirtualBox.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Testing and disaster
+          recovery.</emphasis> Once installed, a virtual machine and its
+          virtual hard disks can be considered a "container" that can be
+          arbitrarily frozen, woken up, copied, backed up, and
+          transported between hosts.
+        </para>
+
+        <para>
+          On top of that, with the use of another VirtualBox feature
+          called "snapshots", one can save a particular state of a
+          virtual machine and revert back to that state, if necessary.
+          This way, one can freely experiment with a computing
+          environment. If something goes wrong , such as prolems after
+          installing software or infecting the guest with a virus, you
+          can easily switch back to a previous snapshot and avoid the
+          need of frequent backups and restores.
+        </para>
+
+        <para>
+          Any number of snapshots can be created, allowing you to travel
+          back and forward in virtual machine time. You can delete
+          snapshots while a VM is running to reclaim disk space.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Infrastructure consolidation.</emphasis>
+          Virtualization can significantly reduce hardware and
+          electricity costs. Most of the time, computers today only use
+          a fraction of their potential power and run with low average
+          system loads. A lot of hardware resources as well as
+          electricity is thereby wasted. So, instead of running many
+          such physical computers that are only partially used, one can
+          pack many virtual machines onto a few powerful hosts and
+          balance the loads between them.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="virtintro">
+
+    <title>Some Terminology</title>
+
+    <para>
+      When dealing with virtualization, and also for understanding the
+      following chapters of this documentation, it helps to acquaint
+      oneself with a bit of crucial terminology, especially the
+      following terms:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="strong">Host operating system (host
+          OS).</emphasis> This is the operating system of the physical
+          computer on which VirtualBox was installed. There are versions
+          of VirtualBox for Windows, Mac OS X, Linux and Solaris hosts.
+          See <xref linkend="hostossupport" />.
+        </para>
+
+        <para>
+          Most of the time, this manual discusses all VirtualBox
+          versions together. There may be platform-specific differences
+          which we will point out where appropriate.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="strong"> Guest operating system (guest
+          OS).</emphasis> This is the operating system that is running
+          inside the virtual machine. Theoretically, VirtualBox can run
+          any x86 operating system. such as DOS, Windows, OS/2, FreeBSD,
+          and OpenBSD. But to achieve near-native performance of the
+          guest code on your machine, we had to go through a lot of
+          optimizations that are specific to certain operating systems.
+          So while your favorite operating system
+          <emphasis>may</emphasis> run as a guest, we officially support
+          and optimize for a select few, which include the most common
+          operating systems.
+        </para>
+
+        <para>
+          See <xref linkend="guestossupport" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="strong">Virtual machine (VM).</emphasis> This
+          is the special environment that VirtualBox creates for your
+          guest operating system while it is running. In other words,
+          you run your guest operating system "in" a VM. Normally, a VM
+          will be shown as a window on your computer's desktop, but
+          depending on which of the various frontends of VirtualBox you
+          use, it can be displayed in full screen mode or remotely on
+          another computer.
+        </para>
+
+        <para>
+          In a more abstract way, internally, VirtualBox thinks of a VM
+          as a set of parameters that determine its behavior. They
+          include hardware settings, such as: how much memory the VM
+          should have, what hard disks VirtualBox should virtualize
+          through which container files, what CDs are mounted. They also
+          include state information, such as: whether the VM is
+          currently running, saved, if the VM has snapshots. These
+          settings are mirrored in the VirtualBox Manager window as well
+          as the <computeroutput>VBoxManage</computeroutput> command
+          line program. See <xref linkend="vboxmanage" />. In other
+          words, a VM is also what you can see in its settings dialog.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="strong">Guest Additions.</emphasis> This
+          refers to special software packages which are shipped with
+          VirtualBox but designed to be installed
+          <emphasis>inside</emphasis> a VM to improve performance of the
+          guest OS and to add extra features. See
+          <xref
+          linkend="guestadditions" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="features-overview">
+
+    <title>Features Overview</title>
+
+    <para>
+      The following is a brief outline of VirtualBox's main features:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Portability.</emphasis> VirtualBox runs
+          on a large number of 32-bit and 64-bit host operating systems
+          See <xref linkend="hostossupport" />.
+        </para>
+
+        <para>
+          VirtualBox is a so-called <emphasis>hosted</emphasis>
+          hypervisor, sometimes referred to as a <emphasis>type
+          2</emphasis> hypervisor. Whereas a
+          <emphasis>bare-metal</emphasis> or <emphasis>type 1</emphasis>
+          hypervisor would run directly on the hardware, VirtualBox
+          requires an existing operating system to be installed. It can
+          thus run alongside existing applications on that host.
+        </para>
+
+        <para>
+          To a very large degree, VirtualBox is functionally identical
+          on all of the host platforms, and the same file and image
+          formats are used. This allows you to run virtual machines
+          created on one host on another host with a different host
+          operating system. For example, you can create a virtual
+          machine on Windows and then run it under Linux.
+        </para>
+
+        <para>
+          In addition, virtual machines can easily be imported and
+          exported using the Open Virtualization Format (OVF), an
+          industry standard created for this purpose. You can even
+          import OVFs that were created with a different virtualization
+          software. See <xref
+            linkend="ovf" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">No hardware virtualization
+          required.</emphasis> For many scenarios, VirtualBox does not
+          require the processor features built into newer hardware like
+          Intel VT-x or AMD-V. As opposed to many other virtualization
+          solutions, you can therefore use VirtualBox even on older
+          hardware where these features are not present. See
+          <xref
+        linkend="hwvirt" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Guest Additions: shared folders,
+          seamless windows, 3D virtualization.</emphasis> The VirtualBox
+          Guest Additions are software packages which can be installed
+          <emphasis>inside</emphasis> of supported guest systems to
+          improve their performance and to provide additional
+          integration and communication with the host system. After
+          installing the Guest Additions, a virtual machine will support
+          automatic adjustment of video resolutions, seamless windows,
+          accelerated 3D graphics and more. See
+          <xref
+        linkend="guestadditions" />.
+        </para>
+
+        <para>
+          In particular, Guest Additions provide for "shared folders",
+          which let you access files from the host system from within a
+          guest machine. See <xref
+        linkend="sharedfolders" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Great hardware support.</emphasis> Among
+          others, VirtualBox supports the following:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">Guest multiprocessing
+              (SMP).</emphasis> VirtualBox can present up to 32 virtual
+              CPUs to each virtual machine, irrespective of how many CPU
+              cores are physically present on your host.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">USB device support.</emphasis>
+              VirtualBox implements a virtual USB controller and allows
+              you to connect arbitrary USB devices to your virtual
+              machines without having to install device-specific drivers
+              on the host. USB support is not limited to certain device
+              categories. See <xref linkend="settings-usb" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">Hardware compatibility.</emphasis>
+              VirtualBox virtualizes a vast array of virtual devices,
+              among them many devices that are typically provided by
+              other virtualization platforms. That includes IDE, SCSI
+              and SATA hard disk controllers, several virtual network
+              cards and sound cards, virtual serial and parallel ports
+              and an Input/Output Advanced Programmable Interrupt
+              Controller (I/O APIC), which is found in many modern PC
+              systems. This eases cloning of PC images from real
+              machines and importing of third-party virtual machines
+              into VirtualBox.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">Full ACPI support.</emphasis> The
+              Advanced Configuration and Power Interface (ACPI) is fully
+              supported by VirtualBox. This eases cloning of PC images
+              from real machines or third-party virtual machines into
+              VirtualBox. With its unique <emphasis>ACPI power status
+              support</emphasis>, VirtualBox can even report to
+              ACPI-aware guest operating systems the power status of the
+              host. For mobile systems running on battery, the guest can
+              thus enable energy saving and notify the user of the
+              remaining power, for example in full screen modes.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">Multiscreen resolutions.</emphasis>
+              VirtualBox virtual machines support screen resolutions
+              many times that of a physical screen, allowing them to be
+              spread over a large number of screens attached to the host
+              system.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">Built-in iSCSI support.</emphasis>
+              This unique feature allows you to connect a virtual
+              machine directly to an iSCSI storage server without going
+              through the host system. The VM accesses the iSCSI target
+              directly without the extra overhead that is required for
+              virtualizing hard disks in container files. See
+              <xref
+            linkend="storage-iscsi" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">PXE Network boot.</emphasis> The
+              integrated virtual network cards of VirtualBox fully
+              support remote booting via the Preboot Execution
+              Environment (PXE).
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Multigeneration branched
+          snapshots.</emphasis> VirtualBox can save arbitrary snapshots
+          of the state of the virtual machine. You can go back in time
+          and revert the virtual machine to any such snapshot and start
+          an alternative VM configuration from there, effectively
+          creating a whole snapshot tree. See
+          <xref linkend="snapshots" />. You can create and delete
+          snapshots while the virtual machine is running.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">VM groups.</emphasis> VirtualBox
+          provides a groups feature that enables the user to organize
+          and control virtual machines collectively, as well as
+          individually. In addition to basic groups, it is also possible
+          for any VM to be in more than one group, and for groups to be
+          nested in a hierarchy. This means you can have groups of
+          groups. In general, the operations that can be performed on
+          groups are the same as those that can be applied to individual
+          VMs: Start, Pause, Reset, Close (Save state, Send Shutdown,
+          Poweroff), Discard Saved State, Show in fileSystem, Sort.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Clean architecture; unprecedented
+          modularity.</emphasis> VirtualBox has an extremely modular
+          design with well-defined internal programming interfaces and a
+          clean separation of client and server code. This makes it easy
+          to control it from several interfaces at once. For example,
+          you can start a VM simply by clicking on a button in the
+          VirtualBox graphical user interface and then control that
+          machine from the command line, or even remotely. See
+          <xref linkend="frontends" />.
+        </para>
+
+        <para>
+          Due to its modular architecture, VirtualBox can also expose
+          its full functionality and configurability through a
+          comprehensive <emphasis role="bold">software development kit
+          (SDK),</emphasis> which allows for integrating every aspect of
+          VirtualBox with other software systems. See
+          <xref linkend="VirtualBoxAPI" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Remote machine display.</emphasis> The
+          VirtualBox Remote Desktop Extension (VRDE) allows for
+          high-performance remote access to any running virtual machine.
+          This extension supports the Remote Desktop Protocol (RDP)
+          originally built into Microsoft Windows, with special
+          additions for full client USB support.
+        </para>
+
+        <para>
+          The VRDE does not rely on the RDP server that is built into
+          Microsoft Windows; instead, it is plugged directly into the
+          virtualization layer. As a result, it works with guest
+          operating systems other than Windows, even in text mode, and
+          does not require application support in the virtual machine
+          either. The VRDE is described in detail in
+          <xref linkend="vrde" />.
+        </para>
+
+        <para>
+          On top of this special capacity, VirtualBox offers you more
+          unique features:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">Extensible RDP
+              authentication.</emphasis> VirtualBox already supports
+              Winlogon on Windows and PAM on Linux for RDP
+              authentication. In addition, it includes an easy-to-use
+              SDK which allows you to create arbitrary interfaces for
+              other methods of authentication. See
+              <xref linkend="vbox-auth" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">USB over RDP.</emphasis> Via RDP
+              virtual channel support, VirtualBox also allows you to
+              connect arbitrary USB devices locally to a virtual machine
+              which is running remotely on a VirtualBox RDP server. See
+              <xref
+              linkend="usb-over-rdp" />.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="hostossupport">
+
+    <title>Supported Host Operating Systems</title>
+
+    <para>
+      Currently, VirtualBox runs on the following host operating
+      systems:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Windows hosts:</emphasis>
+
+          <footnote>
+
+            <para>
+              Support for 64-bit Windows was added with VirtualBox 1.5.
+              Support for Windows XP was removed with VirtualBox 5.0.
+              Support for Windows Vista was removed with VirtualBox 5.2.
+            </para>
+
+          </footnote>
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              Windows Server 2008 (64-bit)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Windows Server 2008 R2 (64-bit)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Windows 7 (32-bit and 64-bit)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Windows 8 (32-bit and 64-bit)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Windows 8.1 (32-bit and 64-bit)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Windows 10 RTM build 10240 (32-bit and 64-bit)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Windows Server 2012 (64-bit)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Windows Server 2012 R2 (64-bit)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Windows Server 2016 (64-bit)
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Mac OS X hosts (64-bit):</emphasis>
+
+          <footnote>
+
+            <para>
+              Preliminary Mac OS X support (beta stage) was added with
+              VirtualBox 1.4, full support with 1.6. Mac OS X 10.4
+              (Tiger) support was removed with VirtualBox 3.1. Support
+              for Mac OS X 10.7 (Lion) and earlier was removed with
+              VirtualBox 5.0. Support for Mac OS X 10.8 (Mountain Lion)
+              was removed with VirtualBox 5.1. Support for Mac OS X 10.9
+              (Mavericks) was removed with VirtualBox 5.2.
+            </para>
+
+          </footnote>
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              10.10 (Yosemite)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              10.11 (El Capitan)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              10.12 (Sierra)
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              10.13 (High Sierra)
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          Intel hardware is required. See also
+          <xref
+        linkend="KnownIssues" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Linux hosts (32-bit and 64-bit).
+          Includes the following:</emphasis>
+
+          <footnote>
+
+            <para>
+              Support for 64-bit Linux was added with VirtualBox 1.4.
+            </para>
+
+          </footnote>
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              Ubuntu 14.04 LTS, 16.04 LTS, and 17.04
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Debian GNU/Linux 7 ("Wheezy"), 8 ("Jessie"), and 9
+              ("Stretch")
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Oracle Enterprise Linux 5, Oracle Linux 6, and 7
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Redhat Enterprise Linux 5, 6, and 7
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Fedora 25 and 26
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Gentoo Linux
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              openSUSE 13.2
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          It should be possible to use VirtualBox on most systems based
+          on Linux kernel 2.6 or 3.x using either the VirtualBox
+          installer or by doing a manual installation. See
+          <xref linkend="install-linux-host" />. However, the formally
+          tested and supported Linux distributions are those for which
+          we offer a dedicated package.
+        </para>
+
+        <para>
+          Note that starting with VirtualBox 2.1, Linux 2.4-based host
+          operating systems are no longer supported.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Solaris hosts (64-bit only).</emphasis>
+          The following versions are supported with the restrictions
+          listed in <xref
+        linkend="KnownIssues" />:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              Solaris 11
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Solaris 10 (U10 and higher)
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Note that the above list is informal. Oracle support for customers
+      who have a support contract is limited to a subset of the listed
+      host operating systems. Also, any feature which is marked as
+      <emphasis>experimental</emphasis> is not supported. Feedback and
+      suggestions about such features are welcome.
+    </para>
+
+  </sect1>
+
+  <sect1 id="hostcpurequirements">
+
+    <title>Host CPU Requirements</title>
+
+    <para>
+      SSE2 is required starting with VirtualBox version 5.2.10 and
+      version 5.1.24.
+    </para>
+
+  </sect1>
+
+  <sect1 id="intro-installing">
+
+    <title>Installing VirtualBox and Extension Packs</title>
+
+    <para>
+      VirtualBox comes in many different packages, and installation
+      depends on your host operating system. If you have installed
+      software before, installation should be straightforward. On each
+      host platform, VirtualBox uses the installation method that is
+      most common and easy to use. If you run into trouble or have
+      special requirements, see <xref linkend="installation" /> for
+      details about the various installation methods.
+    </para>
+
+    <para>
+      Starting with version 4.0, VirtualBox is split into several
+      components:
+    </para>
+
+    <orderedlist>
+
+      <listitem>
+        <para>
+          The base package consists of all open source components and is
+          licensed under the GNU General Public License V2.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Additional extension packs can be downloaded which extend the
+          functionality of the VirtualBox base package. Currently,
+          Oracle provides a single extension pack, available from:
+          <ulink
+          url="http://www.virtualbox.org">http://www.virtualbox.org</ulink>.
+          The extension pack provides the following added functionality:
+        </para>
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              The virtual USB 2.0 (EHCI) device. See
+              <xref
+                linkend="settings-usb" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              The virtual USB 3.0 (xHCI) device. See
+              <xref
+                linkend="settings-usb" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              VirtualBox Remote Desktop Protocol (VRDP) support. See
+              <xref linkend="vrde" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Host webcam passthrough. See
+              <xref
+                    linkend="webcam-passthrough" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Intel PXE boot ROM.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Experimental support for PCI passthrough on Linux hosts.
+              See <xref linkend="pcipassthrough" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Disk image encryption with AES algorithm. See
+              <xref linkend="diskencryption" />.
+            </para>
+          </listitem>
+
+        </orderedlist>
+
+        <para>
+          VirtualBox extension packages have a
+          <computeroutput>.vbox-extpack</computeroutput> file name
+          extension. To install an extension, simply double-click on the
+          package file and a Network Operations Manager window will
+          appear, guiding you through the required steps.
+        </para>
+
+        <para>
+          To view the extension packs that are currently installed,
+          start the VirtualBox Manager, as shown in
+          <xref linkend="intro-starting"/>. From the
+          <emphasis role="bold">File</emphasis> menu, select
+          <emphasis role="bold">Preferences</emphasis>. In the window
+          that displays, go to the
+          <emphasis role="bold">Extensions</emphasis> category. This
+          shows you the extensions which are currently installed, and
+          enables you to remove a package or add a new package.
+        </para>
+
+        <para>
+          Alternatively, you can use the VBoxManage command line. See
+          <xref linkend="vboxmanage-extpack" />.
+        </para>
+      </listitem>
+
+    </orderedlist>
+
+  </sect1>
+
+  <sect1 id="intro-starting">
+
+    <title>Starting VirtualBox</title>
+
+    <para>
+      After installation, you can start VirtualBox as follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          On a Windows host, in the Programs menu, click on the item in
+          the <emphasis role="bold">VirtualBox</emphasis> group. On
+          Vista or Windows 7, you can also type
+          <computeroutput>VirtualBox</computeroutput> in the search box
+          of the Start menu.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          On a Mac OS X host, in the Finder, double-click on the
+          <emphasis role="bold">VirtualBox</emphasis> item in the
+          "Applications" folder. You may want to drag this item onto
+          your Dock.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          On a Linux or Solaris host, depending on your desktop
+          environment, a VirtualBox item may have been placed in either
+          the System or System Tools group of your Applications menu.
+          Alternatively, you can type
+          <computeroutput>VirtualBox</computeroutput> in a terminal.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      When you start VirtualBox for the first time, a window like the
+      following is displayed:
+    </para>
+
+    <mediaobject>
       <imageobject>
-        <imagedata align="center" fileref="images/vm-vista-running.png"
-                   width="14cm" />
+        <imagedata align="center" fileref="images/virtualbox-main-empty.png"
+                     width="10cm" />
       </imageobject>
-    </mediaobject></para>
-
-  <para>In this User Manual, we'll begin simply with a quick introduction to
-  virtualization and how to get your first virtual machine running with the
-  easy-to-use VirtualBox graphical user interface. Subsequent chapters will go
-  into much more detail covering more powerful tools and features, but
-  fortunately, it is not necessary to read the entire User Manual before you
-  can use VirtualBox.</para>
-
-  <para>You can find a summary of VirtualBox's capabilities in <xref
-  linkend="features-overview" />. For existing VirtualBox users who just want
-  to see what's new in this release, there is a detailed list in <xref
-  linkend="ChangeLog" />.</para>
-
-  <sect1>
-    <title>Why is virtualization useful?</title>
-
-    <para>The techniques and features that VirtualBox provides are useful for
-    several scenarios:</para>
-
-    <itemizedlist>
-      <listitem>
-        <para><emphasis role="bold">Running multiple operating systems
-        simultaneously.</emphasis> VirtualBox allows you to run more than one
-        operating system at a time. This way, you can run software written for
-        one operating system on another (for example, Windows software on
-        Linux or a Mac) without having to reboot to use it. Since you can
-        configure what kinds of "virtual" hardware should be presented to each
-        such operating system, you can install an old operating system such as
-        DOS or OS/2 even if your real computer's hardware is no longer
-        supported by that operating system.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Easier software installations.</emphasis>
-        Software vendors can use virtual machines to ship entire software
-        configurations. For example, installing a complete mail server
-        solution on a real machine can be a tedious task. With VirtualBox,
-        such a complex setup (then often called an "appliance") can be packed
-        into a virtual machine. Installing and running a mail server becomes
-        as easy as importing such an appliance into VirtualBox.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Testing and disaster recovery.</emphasis>
-        Once installed, a virtual machine and its virtual hard disks can be
-        considered a "container" that can be arbitrarily frozen, woken up,
-        copied, backed up, and transported between hosts.</para>
-
-        <para>On top of that, with the use of another VirtualBox feature
-        called "snapshots", one can save a particular state of a virtual
-        machine and revert back to that state, if necessary. This way, one can
-        freely experiment with a computing environment. If something goes
-        wrong (e.g. after installing misbehaving software or infecting the
-        guest with a virus), one can easily switch back to a previous snapshot
-        and avoid the need of frequent backups and restores.</para>
-
-        <para>Any number of snapshots can be created, allowing you to travel
-        back and forward in virtual machine time. You can delete snapshots
-        while a VM is running to reclaim disk space.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Infrastructure consolidation.</emphasis>
-        Virtualization can significantly reduce hardware and electricity
-        costs. Most of the time, computers today only use a fraction of their
-        potential power and run with low average system loads. A lot of
-        hardware resources as well as electricity is thereby wasted. So,
-        instead of running many such physical computers that are only
-        partially used, one can pack many virtual machines onto a few powerful
-        hosts and balance the loads between them.</para>
-      </listitem>
-    </itemizedlist>
+    </mediaobject>
+
+    <para>
+      This window is called the <emphasis
+    role="bold">"VirtualBox
+      Manager"</emphasis>. On the left, you can see a pane that will
+      later list all your virtual machines. Since you have not created
+      any, the list is empty. A row of buttons above it allows you to
+      create new VMs and work on existing VMs, once you have some. The
+      pane on the right displays the properties of the virtual machine
+      currently selected, if any. Again, since you do not have any
+      machines yet, the pane displays a welcome message.
+    </para>
+
+    <para>
+      To give you an idea what VirtualBox might look like later, after
+      you have created many machines, here is another example:
+    </para>
+
+    <mediaobject>
+      <imageobject>
+        <imagedata align="center" fileref="images/virtualbox-main.png"
+                     width="10cm" />
+      </imageobject>
+    </mediaobject>
+
   </sect1>
 
-  <sect1 id="virtintro">
-    <title>Some terminology</title>
-
-    <para>When dealing with virtualization (and also for understanding the
-    following chapters of this documentation), it helps to acquaint oneself
-    with a bit of crucial terminology, especially the following terms:</para>
-
-    <glosslist>
-      <glossentry>
-        <glossterm>Host operating system (host OS).</glossterm>
-
-        <glossdef>
-          <para>This is the operating system of the physical computer on which
-          VirtualBox was installed. There are versions of VirtualBox for
-          Windows, Mac OS X, Linux and Solaris hosts; for details, please see
-          <xref linkend="hostossupport" />.</para>
-
-          <para>Most of the time, this User Manual discusses all VirtualBox
-          versions together. There may be platform-specific differences which
-          we will point out where appropriate.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>Guest operating system (guest OS).</glossterm>
-
-        <glossdef>
-          <para>This is the operating system that is running inside the
-          virtual machine. Theoretically, VirtualBox can run any x86 operating
-          system (DOS, Windows, OS/2, FreeBSD, OpenBSD), but to achieve
-          near-native performance of the guest code on your machine, we had to
-          go through a lot of optimizations that are specific to certain
-          operating systems. So while your favorite operating system
-          <emphasis>may</emphasis> run as a guest, we officially support and
-          optimize for a select few (which, however, include the most common
-          ones).</para>
-
-          <para>See <xref linkend="guestossupport" /> for details.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>Virtual machine (VM).</glossterm>
-
-        <glossdef>
-          <para>This is the special environment that VirtualBox creates for
-          your guest operating system while it is running. In other words, you
-          run your guest operating system "in" a VM. Normally, a VM will be
-          shown as a window on your computer's desktop, but depending on which
-          of the various frontends of VirtualBox you use, it can be displayed
-          in full screen mode or remotely on another computer.</para>
-
-          <para>In a more abstract way, internally, VirtualBox thinks of a VM
-          as a set of parameters that determine its behavior. They include
-          hardware settings (how much memory the VM should have, what hard
-          disks VirtualBox should virtualize through which container files,
-          what CDs are mounted etc.) as well as state information (whether the
-          VM is currently running, saved, its snapshots etc.). These settings
-          are mirrored in the VirtualBox Manager window as well as the
-          <computeroutput>VBoxManage</computeroutput> command line program;
-          see <xref linkend="vboxmanage" />. In other words, a VM is also what
-          you can see in its settings dialog.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm>Guest Additions.</glossterm>
-
-        <glossdef>
-          <para>This refers to special software packages which are shipped
-          with VirtualBox but designed to be installed
-          <emphasis>inside</emphasis> a VM to improve performance of the guest
-          OS and to add extra features. This is described in detail in <xref
-          linkend="guestadditions" />.</para>
-        </glossdef>
-      </glossentry>
-    </glosslist>
-  </sect1>
-
-  <sect1 id="features-overview">
-    <title>Features overview</title>
-
-    <para>Here's a brief outline of VirtualBox's main features:</para>
-
-    <itemizedlist>
-      <listitem>
-        <para><emphasis role="bold">Portability.</emphasis> VirtualBox runs on
-        a large number of 32-bit and 64-bit host operating systems (again, see
-        <xref linkend="hostossupport" /> for details).</para>
-
-        <para>VirtualBox is a so-called "hosted" hypervisor (sometimes
-        referred to as a "type 2" hypervisor). Whereas a "bare-metal" or "type
-        1" hypervisor would run directly on the hardware, VirtualBox requires
-        an existing operating system to be installed. It can thus run
-        alongside existing applications on that host.</para>
-
-        <para>To a very large degree, VirtualBox is functionally identical on
-        all of the host platforms, and the same file and image formats are
-        used. This allows you to run virtual machines created on one host on
-        another host with a different host operating system; for example, you
-        can create a virtual machine on Windows and then run it under
-        Linux.</para>
-
-        <para>In addition, virtual machines can easily be imported and
-        exported using the Open Virtualization Format (OVF, see <xref
-        linkend="ovf" />), an industry standard created for this purpose. You
-        can even import OVFs that were created with a different virtualization
-        software.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">No hardware virtualization
-        required.</emphasis> For many scenarios, VirtualBox does not require
-        the processor features built into newer hardware like Intel VT-x or
-        AMD-V. As opposed to many other virtualization solutions, you can
-        therefore use VirtualBox even on older hardware where these features
-        are not present. The technical details are explained in <xref
-        linkend="hwvirt" />.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Guest Additions: shared folders, seamless
-        windows, 3D virtualization.</emphasis> The VirtualBox Guest Additions
-        are software packages which can be installed
-        <emphasis>inside</emphasis> of supported guest systems to improve
-        their performance and to provide additional integration and
-        communication with the host system. After installing the Guest
-        Additions, a virtual machine will support automatic adjustment of
-        video resolutions, seamless windows, accelerated 3D graphics and more.
-        The Guest Additions are described in detail in <xref
-        linkend="guestadditions" />.</para>
-
-        <para>In particular, Guest Additions provide for "shared folders",
-        which let you access files from the host system from within a guest
-        machine. Shared folders are described in <xref
-        linkend="sharedfolders" />.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Great hardware support.</emphasis> Among
-        others, VirtualBox supports:</para>
-
-        <itemizedlist>
-          <listitem>
-            <para><emphasis role="bold">Guest multiprocessing
-            (SMP).</emphasis> VirtualBox can present up to 32 virtual CPUs to
-            each virtual machine, irrespective of how many CPU cores are
-            physically present on your host.</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="bold">USB device support.</emphasis>
-            VirtualBox implements a virtual USB controller and allows you to
-            connect arbitrary USB devices to your virtual machines without
-            having to install device-specific drivers on the host. USB support
-            is not limited to certain device categories. For details, see
-            <xref linkend="settings-usb" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="bold">Hardware compatibility.</emphasis>
-            VirtualBox virtualizes a vast array of virtual devices, among them
-            many devices that are typically provided by other virtualization
-            platforms. That includes IDE, SCSI and SATA hard disk controllers,
-            several virtual network cards and sound cards, virtual serial and
-            parallel ports and an Input/Output Advanced Programmable Interrupt
-            Controller (I/O APIC), which is found in many modern PC systems.
-            This eases cloning of PC images from real machines and importing
-            of third-party virtual machines into VirtualBox.</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="bold">Full ACPI support.</emphasis> The
-            Advanced Configuration and Power Interface (ACPI) is fully
-            supported by VirtualBox. This eases cloning of PC images from real
-            machines or third-party virtual machines into VirtualBox. With its
-            unique <emphasis role="bold">ACPI power status support,</emphasis>
-            VirtualBox can even report to ACPI-aware guest operating systems
-            the power status of the host. For mobile systems running on
-            battery, the guest can thus enable energy saving and notify the
-            user of the remaining power (e.g. in full screen modes).</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="bold">Multiscreen resolutions.</emphasis>
-            VirtualBox virtual machines support screen resolutions many times
-            that of a physical screen, allowing them to be spread over a large
-            number of screens attached to the host system.</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="bold">Built-in iSCSI support.</emphasis>
-            This unique feature allows you to connect a virtual machine
-            directly to an iSCSI storage server without going through the host
-            system. The VM accesses the iSCSI target directly without the
-            extra overhead that is required for virtualizing hard disks in
-            container files. For details, see <xref
-            linkend="storage-iscsi" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><emphasis role="bold">PXE Network boot.</emphasis> The
-            integrated virtual network cards of VirtualBox fully support
-            remote booting via the Preboot Execution Environment (PXE).</para>
-          </listitem>
-        </itemizedlist>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Multigeneration branched
-        snapshots.</emphasis> VirtualBox can save arbitrary snapshots of the
-        state of the virtual machine. You can go back in time and revert the
-        virtual machine to any such snapshot and start an alternative VM
-        configuration from there, effectively creating a whole snapshot tree.
-        For details, see <xref linkend="snapshots" />. You can create and
-        delete snapshots while the virtual machine is running.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">VM groups.</emphasis> VirtualBox provides a
-        groups feature that enables the user to organize and control virtual machines
-        collectively, as well as individually. In addition to basic groups, it
-        is also possible for any VM to be in more than one group, and for
-        groups to be nested in a hierarchy -- i.e. groups of groups. In
-        general, the operations that can be performed on groups are the same as
-        those that can be applied to individual VMs i.e. Start, Pause, Reset,
-        Close (Save state, Send Shutdown, Poweroff), Discard Saved State, Show
-        in fileSystem, Sort.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Clean architecture; unprecedented
-        modularity.</emphasis> VirtualBox has an extremely modular design with
-        well-defined internal programming interfaces and a clean separation of
-        client and server code. This makes it easy to control it from several
-        interfaces at once: for example, you can start a VM simply by clicking
-        on a button in the VirtualBox graphical user interface and then
-        control that machine from the command line, or even remotely. See
-        <xref linkend="frontends" /> for details.</para>
-
-        <para>Due to its modular architecture, VirtualBox can also expose its
-        full functionality and configurability through a comprehensive
-        <emphasis role="bold">software development kit (SDK),</emphasis> which
-        allows for integrating every aspect of VirtualBox with other software
-        systems. Please see <xref linkend="VirtualBoxAPI" /> for
-        details.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Remote machine display.</emphasis> The
-        VirtualBox Remote Desktop Extension (VRDE) allows for high-performance
-        remote access to any running virtual machine. This extension supports
-        the Remote Desktop Protocol (RDP) originally built into Microsoft
-        Windows, with special additions for full client USB support.</para>
-
-        <para>The VRDE does not rely on the RDP server that is built into
-        Microsoft Windows; instead, it is plugged directly into the
-        virtualization layer. As a result, it works with guest operating
-        systems other than Windows (even in text mode) and does not require
-        application support in the virtual machine either. The VRDE is
-        described in detail in <xref linkend="vrde" />.</para>
-
-        <para>On top of this special capacity, VirtualBox offers you more
-        unique features:<itemizedlist>
-            <listitem>
-              <para><emphasis role="bold">Extensible RDP
-              authentication.</emphasis> VirtualBox already supports Winlogon
-              on Windows and PAM on Linux for RDP authentication. In addition,
-              it includes an easy-to-use SDK which allows you to create
-              arbitrary interfaces for other methods of authentication; see
-              <xref linkend="vbox-auth" /> for details.</para>
-            </listitem>
-
-            <listitem>
-              <para><emphasis role="bold">USB over RDP.</emphasis> Via RDP
-              virtual channel support, VirtualBox also allows you to connect
-              arbitrary USB devices locally to a virtual machine which is
-              running remotely on a VirtualBox RDP server; see <xref
-              linkend="usb-over-rdp" /> for details.</para>
-            </listitem>
-          </itemizedlist></para>
-      </listitem>
-    </itemizedlist>
-  </sect1>
-
-  <sect1 id="hostossupport">
-    <title>Supported host operating systems</title>
-
-    <para>Currently, VirtualBox runs on the following host operating
-    systems:</para>
-
-    <itemizedlist>
-      <listitem>
-        <para><emphasis role="bold">Windows</emphasis> hosts:<footnote>
-          <para>Support for 64-bit Windows was added with VirtualBox
-          1.5. Support for Windows XP was removed with VirtualBox 5.0.
-          Support for Windows Vista was removed with VirtualBox 5.2.</para>
-          </footnote>
-
-          <itemizedlist>
-            <listitem>
-              <para>Windows Server 2008 (64-bit)</para>
-            </listitem>
-
-            <listitem>
-              <para>Windows Server 2008 R2 (64-bit)</para>
-            </listitem>
-
-            <listitem>
-              <para>Windows 7 (32-bit and 64-bit)</para>
-            </listitem>
-
-            <listitem>
-              <para>Windows 8 (32-bit and 64-bit)</para>
-            </listitem>
-
-            <listitem>
-              <para>Windows 8.1 (32-bit and 64-bit)</para>
-            </listitem>
-
-            <listitem>
-              <para>Windows 10 RTM build 10240 (32-bit and 64-bit)</para>
-            </listitem>
-
-            <listitem>
-              <para>Windows Server 2012 (64-bit)</para>
-            </listitem>
-
-            <listitem>
-              <para>Windows Server 2012 R2 (64-bit)</para>
-            </listitem>
-
-            <listitem>
-              <para>Windows Server 2016 (64-bit)</para>
-            </listitem>
-
-          </itemizedlist></para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Mac OS X</emphasis> hosts (64-bit):<footnote>
-            <para>Preliminary Mac OS X support (beta stage) was added with
-            VirtualBox 1.4, full support with 1.6. Mac OS X 10.4 (Tiger)
-            support was removed with VirtualBox 3.1. Support for Mac OS X 10.7
-            (Lion) and earlier was removed with VirtualBox 5.0. Support for Mac
-            OS X 10.8 (Mountain Lion) was removed with VirtualBox 5.1. Support
-            for Mac OS X 10.9 (Mavericks) was removed with VirtualBox 5.2.</para>
-          </footnote></para>
-
-        <itemizedlist>
-
-          <listitem>
-            <para>10.10 (Yosemite)</para>
-          </listitem>
-
-          <listitem>
-            <para>10.11 (El Capitan)</para>
-          </listitem>
-
-          <listitem>
-            <para>10.12 (Sierra)</para>
-          </listitem>
-
-          <listitem>
-            <para>10.13 (High Sierra)</para>
-          </listitem>
-
-        </itemizedlist>
-
-        <para>Intel hardware is required; please see <xref
-        linkend="KnownIssues" /> also.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Linux</emphasis> hosts (32-bit and
-        64-bit<footnote>
-            <para>Support for 64-bit Linux was added with VirtualBox
-            1.4.</para>
-          </footnote>). Among others, this includes:<itemizedlist>
-            <listitem>
-              <para>Ubuntu 14.04 LTS, 16.04 LTS, and 17.04</para>
-            </listitem>
-
-            <listitem>
-              <para>Debian GNU/Linux 7 ("Wheezy"), 8 ("Jessie") and 9 ("Stretch")</para>
-            </listitem>
-
-            <listitem>
-              <para>Oracle Enterprise Linux 5, Oracle Linux 6 and 7</para>
-            </listitem>
-
-            <listitem>
-              <para>Redhat Enterprise Linux 5, 6 and 7</para>
-            </listitem>
-
-            <listitem>
-              <para>Fedora 25 and 26</para>
-            </listitem>
-
-            <listitem>
-              <para>Gentoo Linux</para>
-            </listitem>
-
-            <listitem>
-              <para>openSUSE 13.2</para>
-            </listitem>
-
-          </itemizedlist></para>
-
-        <para>It should be possible to use VirtualBox on most systems based on
-        Linux kernel 2.6 or 3.x using either the VirtualBox installer or by doing a
-        manual installation; see <xref linkend="install-linux-host" />. However,
-        the formally tested and supported Linux distributions are those for
-        which we offer a dedicated package.</para>
-
-        <para>Note that starting with VirtualBox 2.1, Linux 2.4-based host
-        operating systems are no longer supported.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Solaris</emphasis> hosts (64-bit only) are
-        supported with the restrictions listed in <xref
-        linkend="KnownIssues" />:<itemizedlist>
-            <listitem>
-              <para>Solaris 11</para>
-            </listitem>
-
-            <listitem>
-              <para>Solaris 10 (U10 and higher)</para>
-            </listitem>
-          </itemizedlist></para>
-      </listitem>
-    </itemizedlist>
-    <para>Note that the above list is informal. Oracle support for customers
-    who have a support contract is limited to a subset of the listed host
-    operating systems. Also, any feature which is marked as  <emphasis
-    role="bold">experimental</emphasis> is not supported. Feedback and
-    suggestions about such features are welcome.</para>
-  </sect1>
-
-  <sect1 id="hostcpurequirements">
-    <title>Host CPU Requirements</title>
-
-    <para>SSE2 is required starting with VirtualBox version 5.2.10 and version 5.1.24.</para>
-
-  </sect1>
-
-  <sect1 id="intro-installing">
-    <title>Installing VirtualBox and extension packs</title>
-
-    <para>VirtualBox comes in many different packages, and installation
-    depends on your host operating system. If you have installed software
-    before, installation should be straightforward: on each host platform,
-    VirtualBox uses the installation method that is most common and easy to
-    use. If you run into trouble or have special requirements, please refer to
-    <xref linkend="installation" /> for details about the various installation
-    methods.</para>
-
-    <para>Starting with version 4.0, VirtualBox is split into several
-    components.<orderedlist>
-        <listitem>
-          <para>The base package consists of all open-source components and is
-          licensed under the GNU General Public License V2.</para>
-        </listitem>
-
-        <listitem>
-          <para>Additional extension packs can be downloaded which extend the
-          functionality of the VirtualBox base package. Currently, Oracle
-          provides the one extension pack, which can be found at <ulink
-          url="http://www.virtualbox.org">http://www.virtualbox.org</ulink>
-          and provides the following added functionality:<orderedlist>
-              <listitem>
-                <para>The virtual USB 2.0 (EHCI) device; see <xref
-                linkend="settings-usb" />.</para>
-              </listitem>
-
-              <listitem>
-                <para>The virtual USB 3.0 (xHCI) device; see <xref
-                linkend="settings-usb" />.</para>
-              </listitem>
-
-              <listitem>
-                <para>VirtualBox Remote Desktop Protocol (VRDP) support; see
-                <xref linkend="vrde" />.</para>
-              </listitem>
-
-              <listitem>
-                <para>Host webcam passthrough; see chapter <xref
-                    linkend="webcam-passthrough" />.</para>
-              </listitem>
-
-              <listitem>
-                <para>Intel PXE boot ROM.</para>
-              </listitem>
-
-              <listitem>
-                <para>Experimental support for PCI passthrough on Linux hosts;
-                  see <xref linkend="pcipassthrough" />.</para>
-              </listitem>
-
-              <listitem>
-                <para>Disk image encryption with AES algorithm;
-                  see <xref linkend="diskencryption" />.</para>
-              </listitem>
-            </orderedlist></para>
-
-          <para>VirtualBox extension packages have a
-          <computeroutput>.vbox-extpack</computeroutput> file name extension.
-          To install an extension, simply double-click on the package file
-          and a Network Operations Manager window will appear, guiding you
-          through the required steps.</para>
-
-          <para>To view the extension packs that are currently installed,
-          please start the VirtualBox Manager (see the next section). From the
-          "File" menu, please select "Preferences". In the window that shows
-          up, go to the "Extensions" category which shows you the extensions
-          which are currently installed and allows you to remove a package or
-          add a new one.</para>
-
-          <para>Alternatively you can use VBoxManage on the command line: see
-          <xref linkend="vboxmanage-extpack" /> for details.</para>
-        </listitem>
-      </orderedlist></para>
-  </sect1>
-
-  <sect1>
-    <title>Starting VirtualBox</title>
-
-    <para>After installation, you can start VirtualBox as
-    follows:<itemizedlist>
-        <listitem>
-          <para>On a Windows host, in the standard "Programs" menu, click on
-          the item in the "VirtualBox" group. On Vista or Windows 7, you can
-          also type "VirtualBox" in the search box of the "Start" menu.</para>
-        </listitem>
-
-        <listitem>
-          <para>On a Mac OS X host, in the Finder, double-click on the
-          "VirtualBox" item in the "Applications" folder. (You may want to
-          drag this item onto your Dock.)</para>
-        </listitem>
-
-        <listitem>
-          <para>On a Linux or Solaris host, depending on your desktop
-          environment, a "VirtualBox" item may have been placed in either the
-          "System" or "System Tools" group of your "Applications" menu.
-          Alternatively, you can type
-          <computeroutput>VirtualBox</computeroutput> in a terminal.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>When you start VirtualBox for the first time, a window like the
-    following should come up:</para>
-
-    <para><mediaobject>
-        <imageobject>
-          <imagedata align="center" fileref="images/virtualbox-main-empty.png"
-                     width="10cm" />
-        </imageobject>
-      </mediaobject>This window is called the <emphasis
-    role="bold">"VirtualBox Manager".</emphasis> On the left, you can see a
-    pane that will later list all your virtual machines. Since you have not
-    created any, the list is empty. A row of buttons above it allows you to
-    create new VMs and work on existing VMs, once you have some. The pane on
-    the right displays the properties of the virtual machine currently
-    selected, if any. Again, since you don't have any machines yet, the pane
-    displays a welcome message.</para>
-
-    <para>To give you an idea what VirtualBox might look like later, after you
-    have created many machines, here's another example:</para>
-
-    <para><mediaobject>
-        <imageobject>
-          <imagedata align="center" fileref="images/virtualbox-main.png"
-                     width="10cm" />
-        </imageobject>
-      </mediaobject></para>
-  </sect1>
-
   <sect1 id="gui-createvm">
-    <title>Creating your first virtual machine</title>
-
-    <para>Click on the "New" button at the top of the VirtualBox Manager
-    window. A wizard will pop up to guide you through setting up a new virtual
-    machine (VM):</para>
-
-    <para><mediaobject>
+
+    <title>Creating Your First Virtual Machine</title>
+
+    <para>
+      Click on the <emphasis role="bold">New</emphasis> button at the
+      top of the VirtualBox Manager window. A wizard will pop up to
+      guide you through setting up a new virtual machine (VM):
+    </para>
+
+    <para>
+      <mediaobject>
         <imageobject>
           <imagedata align="center" fileref="images/create-vm-1.png"
                      width="10cm" />
         </imageobject>
-      </mediaobject>On the following pages, the wizard will ask you for the
-    bare minimum of information that is needed to create a VM, in
-    particular:<orderedlist>
-        <listitem>
-          <para>The <emphasis role="bold">VM name</emphasis> will later be
-          shown in the VM list of the VirtualBox Manager window, and it will
-          be used for the VM's files on disk. Even though any name could be
-          used, keep in mind that once you have created a few VMs, you will
-          appreciate if you have given your VMs rather informative names; "My
-          VM" would thus be less useful than "Windows XP SP2 with
-          OpenOffice".</para>
-        </listitem>
-
-        <listitem>
-          <para>For <emphasis role="bold">"Operating System Type",</emphasis>
-          select the operating system that you want to install later. The
-          supported operating systems are grouped; if you want to install
-          something very unusual that is not listed, select "Other". Depending
-          on your selection, VirtualBox will enable or disable certain VM
+      </mediaobject>
+
+      On the following pages, the wizard will ask you for the bare
+      minimum of information that is needed to create a VM, in
+      particular:
+    </para>
+
+    <orderedlist>
+
+      <listitem>
+        <para>
+          The <emphasis role="bold">Name</emphasis> of the VM will later
+          be shown in the VM list of the VirtualBox Manager window, and
+          it will be used for the VM's files on disk. Even though any
+          name can be used, bear in mind that if you create a few VMs,
+          you will appreciate if you have given your VMs rather
+          informative names."My VM" would thus be less useful than
+          "Windows XP SP2 with OpenOffice", for example.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          For <emphasis role="bold">Operating System Type</emphasis>
+          select the operating system that you want to install later.
+          The supported operating systems are grouped. If you want to
+          install something very unusual that is not listed, select
+          <emphasis role="bold">Other</emphasis>. Depending on your
+          selection, VirtualBox will enable or disable certain VM
           settings that your guest operating system may require. This is
-          particularly important for 64-bit guests (see <xref
-          linkend="intro-64bitguests" />). It is therefore recommended to
-          always set it to the correct value.</para>
-        </listitem>
-
-        <listitem>
-          <para>On the next page, select the <emphasis role="bold">memory
-          (RAM)</emphasis> that VirtualBox should allocate every time the
-          virtual machine is started. The amount of memory given here will be
-          taken away from your host machine and presented to the guest
-          operating system, which will report this size as the (virtual)
-          computer's installed RAM.</para>
-
-          <para><note>
-              <para>Choose this setting carefully! The memory you give to the
-              VM will not be available to your host OS while the VM is
-              running, so do not specify more than you can spare. For example,
-              if your host machine has 1 GB of RAM and you enter 512 MB as the
-              amount of RAM for a particular virtual machine, while that VM is
-              running, you will only have 512 MB left for all the other
-              software on your host. If you run two VMs at the same time, even
-              more memory will be allocated for the second VM (which may not
-              even be able to start if that memory is not available). On the
-              other hand, you should specify as much as your guest OS (and
-              your applications) will require to run properly.</para>
-            </note></para>
-
-          <para>A Windows XP guest will require at least a few hundred MB RAM
-          to run properly, and Windows Vista will even refuse to install with
-          less than 512 MB. Of course, if you want to run graphics-intensive
-          applications in your VM, you may require even more RAM.</para>
-
-          <para>So, as a rule of thumb, if you have 1 GB of RAM or more in
-          your host computer, it is usually safe to allocate 512 MB to each
-          VM. But, in any case, make sure you always have at least 256 to 512
-          MB of RAM left on your host operating system. Otherwise you may
-          cause your host OS to excessively swap out memory to your hard disk,
-          effectively bringing your host system to a standstill.</para>
-
-          <para>As with the other settings, you can change this setting later,
-          after you have created the VM.</para>
-        </listitem>
-
-        <listitem>
-          <para>Next, you must specify a <emphasis role="bold">virtual hard
-          disk</emphasis> for your VM.</para>
-
-          <para>There are many and potentially complicated ways in which
-          VirtualBox can provide hard disk space to a VM (see <xref
-          linkend="storage" /> for details), but the most common way is to use
-          a large image file on your "real" hard disk, whose contents
-          VirtualBox presents to your VM as if it were a complete hard disk.
-          This file represents an entire hard disk then, so you can even copy
-          it to another host and use it with another VirtualBox
-          installation.</para>
-
-          <para>The wizard shows you the following window:</para>
-
-          <para><mediaobject>
-              <imageobject>
-                <imagedata align="center" fileref="images/create-vm-2.png"
-                           width="10cm" />
-              </imageobject>
-            </mediaobject></para>
-
-          <para>Here you have the following options:</para>
-
-          <para><itemizedlist>
-              <listitem>
-                <para>To create a new, empty virtual hard disk, press the
-                <emphasis role="bold">"New"</emphasis> button.</para>
-              </listitem>
-
-              <listitem>
-                <para>You can pick an <emphasis
-                role="bold">existing</emphasis> disk image file.</para>
-
-                <para>The <emphasis role="bold">drop-down list</emphasis>
-                presented in the window contains all disk images which are
-                currently remembered by VirtualBox, probably because they are
-                currently attached to a virtual machine (or have been in the
-                past).</para>
-
-                <para>Alternatively, you can click on the small <emphasis
-                role="bold">folder button</emphasis> next to the drop-down
-                list to bring up a standard file dialog, which allows you to
-                pick any disk image file on your host disk.</para>
-              </listitem>
-            </itemizedlist>Most probably, if you are using VirtualBox for the
-          first time, you will want to create a new disk image. Hence, press
-          the "New" button.</para>
-
-          <para>This brings up another window, the <emphasis
-          role="bold">"Create New Virtual Disk Wizard",</emphasis> which helps
-          you create a new disk image file in the new virtual machine's
-          folder.</para>
-
-          <para>VirtualBox supports two types of image files:<itemizedlist>
-              <listitem>
-                <para>A <emphasis role="bold">dynamically allocated
-                file</emphasis> will only grow in size when the guest actually
-                stores data on its virtual hard disk. It will therefore
-                initially be small on the host hard drive and only later grow
-                to the size specified as it is filled with data.</para>
-              </listitem>
-
-              <listitem>
-                <para>A <emphasis role="bold">fixed-size file</emphasis> will
-                immediately occupy the file specified, even if only a fraction
-                of the virtual hard disk space is actually in use. While
-                occupying much more space, a fixed-size file incurs less
-                overhead and is therefore slightly faster than a dynamically
-                allocated file.</para>
-              </listitem>
-            </itemizedlist></para>
-
-          <para>For details about the differences, please refer to <xref
-          linkend="vdidetails" />.</para>
-
-          <para>To prevent your physical hard disk from running full,
-          VirtualBox limits the size of the image file. Still, it needs to be
-          large enough to hold the contents of your operating system and the
-          applications you want to install -- for a modern Windows or Linux
-          guest, you will probably need several gigabytes for any serious
-          use. The limit of the image file size can be changed later (see <xref
-          linkend="vboxmanage-modifyvdi"/> for details).</para>
-
+          particularly important for 64-bit guests. See
+          <xref
+          linkend="intro-64bitguests" />. It is
+          therefore recommended to always set it to the correct value.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          On the next page, select the <emphasis role="bold">Memory
+          (RAM)</emphasis> that VirtualBox should allocate every time
+          the virtual machine is started. The amount of memory given
+          here will be taken away from your host machine and presented
+          to the guest operating system, which will report this size as
+          the virtual computer's installed RAM.
+        </para>
+
+        <caution>
+          <para>
+            Choose this setting carefully. The memory you give to the VM
+            will not be available to your host OS while the VM is
+            running, so do not specify more than you can spare. For
+            example, if your host machine has 1 GB of RAM and you enter
+            512 MB as the amount of RAM for a particular virtual
+            machine, while that VM is running, you will only have 512 MB
+            left for all the other software on your host. If you run two
+            VMs at the same time, even more memory will be allocated for
+            the second VM, which may not even be able to start if that
+            memory is not available. On the other hand, you should
+            specify as much as your guest OS and your applications will
+            require to run properly.
+          </para>
+        </caution>
+
+        <para>
+          A Windows XP guest will require at least a few hundred MB of
+          RAM to run properly, and Windows Vista will not install with
+          less than 512 MB. If you want to run graphics-intensive
+          applications in your VM, you may require even more RAM.
+        </para>
+
+        <para>
+          As a rule of thumb, if you have 1 GB of RAM or more in your
+          host computer, it is usually safe to allocate 512 MB to each
+          VM. In any case, make sure you always have at least 256 to 512
+          MB of RAM left on your host operating system. Otherwise you
+          may cause your host OS to excessively swap out memory to your
+          hard disk, effectively bringing your host system to a
+          standstill.
+        </para>
+
+        <para>
+          As with the other settings, you can change this setting later,
+          after you have created the VM.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Next, you must specify a <emphasis role="bold">Virtual Hard
+          Disk</emphasis> for your VM.
+        </para>
+
+        <para>
+          There are many and potentially complicated ways in which
+          VirtualBox can provide hard disk space to a VM, see
+          <xref
+          linkend="storage" />, but the most common way
+          is to use a large image file on your "real" hard disk, whose
+          contents VirtualBox presents to your VM as if it were a
+          complete hard disk. This file represents an entire hard disk
+          then, so you can even copy it to another host and use it with
+          another VirtualBox installation.
+        </para>
+
+        <para>
+          The wizard displays the following window:
+        </para>
+
+        <para>
           <mediaobject>
             <imageobject>
-              <imagedata align="center" fileref="images/create-vdi-1.png"
-                         width="10cm" />
+              <imagedata align="center" fileref="images/create-vm-2.png"
+                           width="10cm" />
             </imageobject>
           </mediaobject>
-
-          <para>After having selected or created your image file, again press
-          <emphasis role="bold">"Next"</emphasis> to go to the next
-          page.</para>
+        </para>
+
+        <para>
+          At this screen, you have the following options:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              To create a new, empty virtual hard disk, click the
+              <emphasis role="bold">New</emphasis> button.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              You can pick an
+              <emphasis
+               >existing</emphasis> disk image
+              file.
+            </para>
+
+            <para>
+              The drop-down list presented in the window lists all disk
+              images which are currently remembered by VirtualBox. These
+              disk images are currently attached to a virtual machine,
+              or have been attached to a virtual machine.
+            </para>
+
+            <para>
+              Alternatively, click on the small
+              <emphasis
+                role="bold">folder
+              icon</emphasis> next to the drop-down list to display a
+              standard file dialog, where you can select any disk image
+              file on your host disk.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          If you are using VirtualBox for the first time, you will want
+          to create a new disk image. Click the
+          <emphasis role="bold">New</emphasis> button.
+        </para>
+
+        <para>
+          This displays another window, the
+          <emphasis
+          role="bold">Create New Virtual Disk
+          Wizard</emphasis>. This wizard helps you to create a new disk
+          image file in the new virtual machine's folder.
+        </para>
+
+        <para>
+          VirtualBox supports the following types of image files:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              A <emphasis role="bold">dynamically allocated
+              file</emphasis> will only grow in size when the guest
+              actually stores data on its virtual hard disk. It will
+              therefore initially be small on the host hard drive and
+              only later grow to the size specified as it is filled with
+              data.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              A <emphasis role="bold">fixed-size file</emphasis> will
+              immediately occupy the file specified, even if only a
+              fraction of the virtual hard disk space is actually in
+              use. While occupying much more space, a fixed-size file
+              incurs less overhead and is therefore slightly faster than
+              a dynamically allocated file.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          For details about the differences, see
+          <xref
+          linkend="vdidetails" />.
+        </para>
+
+        <para>
+          To prevent your physical hard disk from running full,
+          VirtualBox limits the size of the image file. Still, it needs
+          to be large enough to hold the contents of your operating
+          system and the applications you want to install. For a modern
+          Windows or Linux guest, you will probably need several
+          gigabytes for any serious use. The limit of the image file
+          size can be changed later, see
+          <xref
+          linkend="vboxmanage-modifyvdi"/>.
+        </para>
+
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" fileref="images/create-vdi-1.png"
+                         width="10cm" />
+          </imageobject>
+        </mediaobject>
+
+        <para>
+          After having selected or created your image file, again click
+          <emphasis role="bold">Next</emphasis> to go to the next page.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          After clicking on <emphasis role="bold">Finish</emphasis>
+          button, your new virtual machine is created. The virtual
+          machine is displayed in the list on the left side of the
+          Manager window, with the name that you entered initially.
+        </para>
+      </listitem>
+
+    </orderedlist>
+
+    <note>
+      <para>
+        After becoming familiar with the use of wizards, consider using
+        the Expert Mode available in some wizards. Where available, this
+        is selectable using a button, and speeds up the process of using
+        wizards.
+      </para>
+    </note>
+
+  </sect1>
+
+  <sect1 id="intro-running">
+
+    <title>Running Your Virtual Machine</title>
+
+    <para>
+      To start a virtual machine, you have several options:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Double-click on its entry in the list within the Manager
+          window.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Select its entry in the list in the Manager window, and click
+          the <emphasis role="bold">Start</emphasis> button at the top.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          For virtual machines created with VirtualBox 4.0 or later,
+          navigate to the <computeroutput>VirtualBox
+          VMs</computeroutput> folder in your system user's home
+          directory. Find the subdirectory of the machine you want to
+          start and double-click on the machine settings file, which has
+          a <computeroutput>.vbox</computeroutput> file extension.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Starting a virtual machine displays a new window, and the virtual
+      machine which you selected will boot up. Everything which would
+      normally be seen on the virtual system's monitor is shown in the
+      window. See the screenshot image in
+      <xref linkend="Introduction"/>.
+    </para>
+
+    <para>
+      In general, you can use the virtual machine as you would use a
+      real computer. There are couple of points worth mentioning
+      however.
+    </para>
+
+    <sect2 id="intro-starting-vm-first-time">
+
+      <title>Starting a New VM for the First Time</title>
+
+      <para>
+        When a VM is started for the first time, the
+        <emphasis role="bold">First Start Wizard</emphasis>, is
+        displayed. This wizard helps you to select an installation
+        medium. Since the VM is created empty, it would otherwise behave
+        just like a real computer with no operating system installed. It
+        will do nothing and display an error message that no bootable
+        operating system was found.
+      </para>
+
+      <para>
+        For this reason, the wizard helps you to select a medium to
+        install an operating system from.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            If you have physical CD or DVD media from which you want to
+            install your guest operating system, such as a Windows
+            installation CD or DVD, put the media into your host's CD or
+            DVD drive.
+          </para>
+
+          <para>
+            In the wizard's drop-down list of installation media, select
+            <emphasis role="bold">Host Drive</emphasis> with the correct
+            drive letter. In the case of a Linux host, choose a device
+            file. This will allow your VM to access the media in your
+            host drive, and you can proceed to install from there.
+          </para>
         </listitem>
 
         <listitem>
-          <para>After clicking on <emphasis role="bold">"Finish"</emphasis>,
-          your new virtual machine will be created. You will then see it in
-          the list on the left side of the Manager window, with the name you
-          entered initially.</para>
+          <para>
+            If you have downloaded installation media from the Internet
+            in the form of an ISO image file such as with a Linux
+            distribution, you would normally burn this file to an empty
+            CD or DVD and proceed as described above. With VirtualBox
+            however, you can skip this step and mount the ISO file
+            directly. VirtualBox will then present this file as a CD or
+            DVD-ROM drive to the virtual machine, much like it does with
+            virtual hard disk images.
+          </para>
+
+          <para>
+            In this case, the wizard's drop-down list contains a list of
+            installation media that were previously used with
+            VirtualBox.
+          </para>
+
+          <para>
+            If your medium is not in the list, especially if you are
+            using VirtualBox for the first time, click the small folder
+            icon next to the drop-down list to display a standard file
+            dialog. Here you can pick an image file on your host disks.
+          </para>
         </listitem>
-      </orderedlist></para>
-
-    <note><para>After becoming familiar with the use of wizards, consider using
-      the Expert Mode available in some wizards. Where available, this is
-      selectable using a button, and speeds up user processes using
-      wizards.</para></note>
-  </sect1>
-
-  <sect1>
-    <title>Running your virtual machine</title>
-
-    <para>To start a virtual machine, you have several options:<itemizedlist>
+
+      </itemizedlist>
+
+      <para>
+        After completing the choices in the wizard, you will be able to
+        install your operating system.
+      </para>
+
+    </sect2>
+
+    <sect2 id="keyb_mouse_normal">
+
+      <title>Capturing and Releasing Keyboard and Mouse</title>
+
+      <para>
+        As of version 3.2, VirtualBox provides a virtual USB tablet
+        device to new virtual machines through which mouse events are
+        communicated to the guest operating system. If you are running a
+        modern guest operating system that can handle such devices,
+        mouse support may work out of the box without the mouse being
+        <emphasis>captured</emphasis> as described below. See
+        <xref linkend="settings-motherboard" />.
+      </para>
+
+      <para>
+        Otherwise, if the virtual machine only sees standard PS/2 mouse
+        and keyboard devices, since the operating system in the virtual
+        machine does not know that it is not running on a real computer,
+        it expects to have exclusive control over your keyboard and
+        mouse. But unless you are running the VM in full screen mode,
+        your VM needs to share keyboard and mouse with other
+        applications and possibly other VMs on your host.
+      </para>
+
+      <para>
+        After installing a guest operating system and before you install
+        the Guest Additions, described later, either your VM or the rest
+        of your computer can "own" the keyboard and the mouse. Both
+        cannot own the keyboard and mouse at the same time. You will see
+        a <emphasis>second</emphasis> mouse pointer which is always
+        confined to the limits of the VM window. You activate the VM by
+        clicking inside it.
+      </para>
+
+      <para>
+        To return ownership of keyboard and mouse to your host operating
+        system, VirtualBox reserves a special key on your keyboard: the
+        <emphasis role="bold">Host key</emphasis>. By default, this is
+        the <emphasis>right Ctrl key</emphasis> on your keyboard. On a
+        Mac host, the default Host key is the left Command key. You can
+        change this default in the VirtualBox Global Settings. See
+        <xref
+        linkend="globalsettings" />. The current setting
+        for the Host key is always displayed at the bottom right of your
+        VM window.
+      </para>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/vm-hostkey.png"
+                       width="7cm" />
+        </imageobject>
+      </mediaobject>
+
+      <para>
+        This means the following:
+      </para>
+
+      <itemizedlist>
+
         <listitem>
-          <para>Double-click on its entry in the list within the Manager
-          window or</para>
+          <para>
+            Your <emphasis role="bold">keyboard</emphasis> is owned by
+            the VM if the VM window on your host desktop has the
+            keyboard focus. If you have many windows open in your guest
+            operating system, the window that has the focus in your VM
+            is used. This means that if you want to type within your VM,
+            click on the title bar of your VM window first.
+          </para>
+
+          <para>
+            To release keyboard ownership, press the Host key. As
+            explained above, this is typically the right Ctrl key.
+          </para>
+
+          <para>
+            Note that while the VM owns the keyboard, some key
+            sequences, such as Alt-Tab, will no longer be seen by the
+            host, but will go to the guest instead. After you press the
+            Host key to reenable the host keyboard, all key presses will
+            go through the host again, so that sequences such as Alt-Tab
+            will no longer reach the guest. For technical reasons it may
+            not be possible for the VM to get all keyboard input even
+            when it does own the keyboard. Examples of this are the
+            Ctrl-Alt-Del sequence on Windows hosts or single keys
+            grabbed by other applications on X11 hosts like the GNOME
+            desktop's "Control key highlights mouse pointer"
+            functionality.
+          </para>
         </listitem>
 
         <listitem>
-          <para>select its entry in the list in the Manager window it and
-          press the "Start" button at the top or</para>
+          <para>
+            Your <emphasis role="bold">mouse</emphasis> is owned by the
+            VM only after you have clicked in the VM window. The host
+            mouse pointer will disappear, and your mouse will drive the
+            guest's pointer instead of your normal mouse pointer.
+          </para>
+
+          <para>
+            Note that mouse ownership is independent of that of the
+            keyboard. Even after you have clicked on a titlebar to be
+            able to type into the VM window, your mouse is not
+            necessarily owned by the VM yet.
+          </para>
+
+          <para>
+            To release ownership of your mouse by the VM, press the Host
+            key.
+          </para>
         </listitem>
 
+      </itemizedlist>
+
+      <para>
+        As this behavior can be inconvenient, VirtualBox provides a set
+        of tools and device drivers for guest systems called the
+        VirtualBox Guest Additions which make VM keyboard and mouse
+        operation a lot more seamless. Most importantly, the Additions
+        will get rid of the second "guest" mouse pointer and make your
+        host mouse pointer work directly in the guest.
+      </para>
+
+      <para>
+        This is described in <xref
+      linkend="guestadditions" />.
+      </para>
+
+    </sect2>
+
+    <sect2 id="specialcharacters">
+
+      <title>Typing Special Characters</title>
+
+      <para>
+        Operating systems expect certain key combinations to initiate
+        certain procedures. Some of these key combinations may be
+        difficult to enter into a virtual machine, as there are three
+        candidates as to who receives keyboard input: the host operating
+        system, VirtualBox, or the guest operating system. Which of
+        these three receives keypresses depends on a number of factors,
+        including the key itself.
+      </para>
+
+      <itemizedlist>
+
         <listitem>
-          <para>for virtual machines created with VirtualBox 4.0 or later,
-          navigate to the "VirtualBox VMs" folder in your system user's home
-          directory, find the subdirectory of the machine you want to start
-          and double-click on the machine settings file (with a
-          <computeroutput>.vbox</computeroutput> file extension).</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>This opens up a new window, and the virtual machine which you
-    selected will boot up. Everything which would normally be seen on the
-    virtual system's monitor is shown in the window, as can be seen with the
-    image in <xref linkend="virtintro" />.</para>
-
-    <para>In general, you can use the virtual machine much like you would use
-    a real computer. There are couple of points worth mentioning
-    however.</para>
-
-    <sect2>
-      <title>Starting a new VM for the first time</title>
-
-      <para>When a VM gets started for the first time, another wizard -- the
-      <emphasis role="bold">"First Start Wizard"</emphasis> -- will pop up to
-      help you select an <emphasis role="bold">installation medium</emphasis>.
-      Since the VM is created empty, it would otherwise behave just like a
-      real computer with no operating system installed: it will do nothing and
-      display an error message that no bootable operating system was
-      found.</para>
-
-      <para>For this reason, the wizard helps you select a medium to install
-      an operating system from.</para>
-
-      <itemizedlist>
-        <listitem>
-          <para>If you have physical CD or DVD media from which you want to
-          install your guest operating system (e.g. in the case of a Windows
-          installation CD or DVD), put the media into your host's CD or DVD
-          drive.</para>
-
-          <para>Then, in the wizard's drop-down list of installation media,
-          select <emphasis role="bold">"Host drive"</emphasis> with the
-          correct drive letter (or, in the case of a Linux host, device file).
-          This will allow your VM to access the media in your host drive, and
-          you can proceed to install from there.</para>
-        </listitem>
-
-        <listitem>
-          <para>If you have downloaded installation media from the Internet in
-          the form of an ISO image file (most probably in the case of a Linux
-          distribution), you would normally burn this file to an empty CD or
-          DVD and proceed as just described. With VirtualBox however, you can
-          skip this step and mount the ISO file directly. VirtualBox will then
-          present this file as a CD or DVD-ROM drive to the virtual machine,
-          much like it does with virtual hard disk images.</para>
-
-          <para>For this case, the wizard's drop-down list contains a list of
-          installation media that were previously used with VirtualBox.</para>
-
-          <para>If your medium is not in the list (especially if you are using
-          VirtualBox for the first time), select the small folder icon next to
-          the drop-down list to bring up a standard file dialog, with which
-          you can pick the image file on your host disks.</para>
-        </listitem>
-      </itemizedlist>
-
-      <para>In both cases, after making the choices in the wizard, you will be
-      able to install your operating system.</para>
-    </sect2>
-
-    <sect2 id="keyb_mouse_normal">
-      <title>Capturing and releasing keyboard and mouse</title>
-
-      <para>As of version 3.2, VirtualBox provides a virtual USB tablet device
-      to new virtual machines through which mouse events are communicated to
-      the guest operating system. As a result, if you are running a modern
-      guest operating system that can handle such devices, mouse support may
-      work out of the box without the mouse being "captured" as described
-      below; see <xref linkend="settings-motherboard" /> for more
-      information.</para>
-
-      <para>Otherwise, if the virtual machine only sees standard PS/2 mouse
-      and keyboard devices, since the operating system in the virtual machine
-      does not "know" that it is not running on a real computer, it expects to
-      have exclusive control over your keyboard and mouse. This is, however,
-      not the case since, unless you are running the VM in full screen mode,
-      your VM needs to share keyboard and mouse with other applications and
-      possibly other VMs on your host.</para>
-
-      <para>As a result, initially after installing a guest operating system
-      and before you install the Guest Additions (we will explain this in a
-      minute), only one of the two -- your VM or the rest of your computer --
-      can "own" the keyboard and the mouse. You will see a
-      <emphasis>second</emphasis> mouse pointer which will always be confined
-      to the limits of the VM window. Basically, you activate the VM by
-      clicking inside it.</para>
-
-      <para>To return ownership of keyboard and mouse to your host operating
-      system, VirtualBox reserves a special key on your keyboard for itself:
-      the <emphasis role="bold">"host key".</emphasis> By default, this is the
-      <emphasis>right Control key</emphasis> on your keyboard; on a Mac host,
-      the default host key is the left Command key. You can change this
-      default in the VirtualBox Global Settings, see <xref
-        linkend="globalsettings" />. In any case, the current
-      setting for the host key is always displayed <emphasis>at the bottom
-      right of your VM window,</emphasis> should you have forgotten about
-      it:</para>
-
-      <para><mediaobject>
-          <imageobject>
-            <imagedata align="center" fileref="images/vm-hostkey.png"
-                       width="7cm" />
-          </imageobject>
-        </mediaobject>In detail, all this translates into the
-      following:</para>
-
-      <para><itemizedlist>
-          <listitem>
-            <para>Your <emphasis role="bold">keyboard</emphasis> is owned by
-            the VM if the VM window on your host desktop has the keyboard
-            focus (and then, if you have many windows open in your guest
-            operating system as well, the window that has the focus in your
-            VM). This means that if you want to type within your VM, click on
-            the title bar of your VM window first.</para>
-
-            <para>To release keyboard ownership, press the Host key (as
-            explained above, typically the right Control key).</para>
-
-            <para>Note that while the VM owns the keyboard, some key sequences
-            (like Alt-Tab for example) will no longer be seen by the host, but
-            will go to the guest instead. After you press the host key to
-            re-enable the host keyboard, all key presses will go through the
-            host again, so that sequences like Alt-Tab will no longer reach
-            the guest.  For technical reasons it may not be possible for the
-            VM to get all keyboard input even when it does own the keyboard.
-            Examples of this are the Ctrl-Alt-Del sequence on Windows hosts
-            or single keys grabbed by other applications on X11 hosts like
-            the GNOME desktop's "Control key highlights mouse pointer"
-            functionality.</para>
-          </listitem>
-
-          <listitem>
-            <para>Your <emphasis role="bold">mouse</emphasis> is owned by the
-            VM only after you have clicked in the VM window. The host mouse
-            pointer will disappear, and your mouse will drive the guest's
-            pointer instead of your normal mouse pointer.</para>
-
-            <para>Note that mouse ownership is independent of that of the
-            keyboard: even after you have clicked on a titlebar to be able to
-            type into the VM window, your mouse is not necessarily owned by
-            the VM yet.</para>
-
-            <para>To release ownership of your mouse by the VM, also press the
-            Host key.</para>
-          </listitem>
-        </itemizedlist></para>
-
-      <para>As this behavior can be inconvenient, VirtualBox provides a set of
-      tools and device drivers for guest systems called the "VirtualBox Guest
-      Additions" which make VM keyboard and mouse operation a lot more
-      seamless. Most importantly, the Additions will get rid of the second
-      "guest" mouse pointer and make your host mouse pointer work directly in
-      the guest.</para>
-
-      <para>This will be described later in <xref
-      linkend="guestadditions" />.</para>
-    </sect2>
-
-    <sect2 id="specialcharacters">
-      <title>Typing special characters</title>
-
-      <para>Operating systems expect certain key combinations to initiate
-      certain procedures. Some of these key combinations may be difficult to
-      enter into a virtual machine, as there are three candidates as to who
-      receives keyboard input: the host operating system, VirtualBox, or the
-      guest operating system. Who of these three receives keypresses depends
-      on a number of factors, including the key itself.</para>
-
-      <itemizedlist>
-        <listitem>
-          <para>Host operating systems reserve certain key combinations for
-          themselves. For example, it is impossible to enter the <emphasis
-          role="bold">Ctrl+Alt+Delete</emphasis> combination if you want to
-          reboot the guest operating system in your virtual machine, because
-          this key combination is usually hard-wired into the host OS (both
-          Windows and Linux intercept this), and pressing this key combination
-          will therefore reboot your <emphasis>host</emphasis>.</para>
-
-          <para>Also, on Linux and Solaris hosts, which use the X Window
-          System, the key combination <emphasis
-          role="bold">Ctrl+Alt+Backspace</emphasis> normally resets the X
-          server (to restart the entire graphical user interface in case it
-          got stuck). As the X server intercepts this combination, pressing it
-          will usually restart your <emphasis>host</emphasis> graphical user
-          interface (and kill all running programs, including VirtualBox, in
-          the process).</para>
-
-          <para>Third, on Linux hosts supporting virtual terminals, the key
-          combination <emphasis role="bold">Ctrl+Alt+Fx</emphasis> (where Fx
-          is one of the function keys from F1 to F12) normally allows to
-          switch between virtual terminals. As with Ctrl+Alt+Delete, these
-          combinations are intercepted by the host operating system and
-          therefore always switch terminals on the
-          <emphasis>host</emphasis>.</para>
-
-          <para>If, instead, you want to send these key combinations to the
-          <emphasis>guest</emphasis> operating system in the virtual machine,
-          you will need to use one of the following methods:</para>
+          <para>
+            Host operating systems reserve certain key combinations for
+            themselves. For example, it is impossible to enter the
+            <emphasis
+          role="bold">Ctrl+Alt+Delete</emphasis>
+            combination if you want to reboot the guest operating system
+            in your virtual machine, because this key combination is
+            usually hard-wired into the host OS, both Windows and Linux
+            intercept this, and pressing this key combination will
+            therefore reboot your <emphasis>host</emphasis>.
+          </para>
+
+          <para>
+            On Linux and Solaris hosts, which use the X Window System,
+            the key combination
+            <emphasis
+          role="bold">Ctrl+Alt+Backspace</emphasis>
+            normally resets the X server and restarts the entire
+            graphical user interface. As the X server intercepts this
+            combination, pressing it will usually restart your
+            <emphasis>host</emphasis> graphical user interface and kill
+            all running programs, including VirtualBox, in the process.
+          </para>
+
+          <para>
+            On Linux hosts supporting virtual terminals, the key
+            combination <emphasis role="bold">Ctrl+Alt+Fx</emphasis>,
+            where Fx is one of the function keys from F1 to F12,
+            normally allows you to switch between virtual terminals. As
+            with Ctrl+Alt+Delete, these combinations are intercepted by
+            the host operating system and therefore always switch
+            terminals on the <emphasis>host</emphasis>.
+          </para>
+
+          <para>
+            If, instead, you want to send these key combinations to the
+            <emphasis>guest</emphasis> operating system in the virtual
+            machine, you will need to use one of the following methods:
+          </para>
 
           <itemizedlist>
+
             <listitem>
-              <para>Use the items in the "Input" &rarr; "Keyboard" menu of the
-              virtual machine window. There you will find "Insert Ctrl+Alt+Delete"
-              and "Ctrl+Alt+Backspace"; the latter will only have an effect with
-              Linux or Solaris guests, however.</para>
+              <para>
+                Use the items in the
+                <emphasis role="bold">Input</emphasis>,
+                <emphasis role="bold">Keyboard</emphasis> menu of the
+                virtual machine window. This menu includes the settings
+                <emphasis role="bold">Insert Ctrl+Alt+Delete</emphasis>
+                and <emphasis role="bold">Ctrl+Alt+Backspace</emphasis>.
+                The latter will only have an effect with Linux or
+                Solaris guests, however.
+              </para>
             </listitem>
 
             <listitem>
-              <para>Press special key combinations with the Host key (normally
-              the right Control key), which VirtualBox will then translate for
-              the virtual machine:<itemizedlist>
-                  <listitem>
-                    <para><emphasis role="bold">Host key + Del</emphasis> to
-                    send Ctrl+Alt+Del (to reboot the guest);</para>
-                  </listitem>
-
-                  <listitem>
-                    <para><emphasis role="bold">Host key +
-                    Backspace</emphasis> to send Ctrl+Alt+Backspace (to
-                    restart the graphical user interface of a Linux or Solaris
-                    guest);</para>
-                  </listitem>
-
-                  <listitem>
-                    <para><emphasis role="bold">Host key + F1</emphasis> (or
-                    other function keys) to simulate Ctrl+Alt+F1 (or other
-                    function keys, i.e. to switch between virtual terminals in
-                    a Linux guest).</para>
-                  </listitem>
-                </itemizedlist></para>
+              <para>
+                Use special key combinations with the Host key, normally
+                the right Control key. VirtualBox will then translate
+                these key combinations for the virtual machine:
+              </para>
+
+              <itemizedlist>
+
+                <listitem>
+                  <para>
+                    <emphasis role="bold">Host key + Del</emphasis> to
+                    send Ctrl+Alt+Del to reboot the guest.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    <emphasis role="bold">Host key +
+                    Backspace</emphasis> to send Ctrl+Alt+Backspace to
+                    restart the graphical user interface of a Linux or
+                    Solaris guest.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    <emphasis role="bold">Host key + Function
+                    key</emphasis>. For example, to simulate Ctrl+Alt+Fx
+                    to switch between virtual terminals in a Linux
+                    guest.
+                  </para>
+                </listitem>
+
+              </itemizedlist>
             </listitem>
+
           </itemizedlist>
         </listitem>
 
         <listitem>
-          <para>For some other keyboard combinations such as <emphasis
-          role="bold">Alt-Tab</emphasis> (to switch between open windows),
-          VirtualBox allows you to configure whether these combinations will
-          affect the host or the guest, if a virtual machine currently has the
-          focus. This is a global setting for all virtual machines and can be
-          found under "File" &rarr; "Preferences" &rarr; "Input" &rarr;
-          "Auto-capture keyboard".</para>
+          <para>
+            For some other keyboard combinations such as
+            <emphasis
+          role="bold">Alt-Tab</emphasis> to switch
+            between open windows, VirtualBox allows you to configure
+            whether these combinations will affect the host or the
+            guest, if a virtual machine currently has the focus. This is
+            a global setting for all virtual machines and can be found
+            under "File", "Preferences", "Input".
+          </para>
         </listitem>
+
       </itemizedlist>
+
     </sect2>
 
-    <sect2>
-      <title>Changing removable media</title>
-
-      <para>While a virtual machine is running, you can change removable media
-      in the "Devices" menu of the VM's window. Here you can select in detail
-      what VirtualBox presents to your VM as a CD, DVD, or floppy.</para>
-
-      <para>The settings are the same as would be available for the VM in the
-      "Settings" dialog of the VirtualBox main window, but since that dialog
-      is disabled while the VM is in the "running" or "saved" state, this
-      extra menu saves you from having to shut down and restart the VM every
-      time you want to change media.</para>
-
-      <para>Hence, in the "Devices" menu, VirtualBox allows you to attach the
-      host drive to the guest or select a floppy or DVD image using the Disk
-      Image Manager, all as described in <xref
-      linkend="configbasics" />.</para>
+    <sect2 id="intro-removable-media-changing">
+
+      <title>Changing Removable Media</title>
+
+      <para>
+        While a virtual machine is running, you can change removable
+        media in the <emphasis role="bold">Devices</emphasis> menu of
+        the VM's window. Here you can select in detail what VirtualBox
+        presents to your VM as a CD, DVD, or floppy.
+      </para>
+
+      <para>
+        The settings are the same as would be available for the VM in
+        the Settings dialog of the VirtualBox main window, but since
+        that dialog is disabled while the VM is in the "running" or
+        "saved" state, this extra menu saves you from having to shut
+        down and restart the VM every time you want to change media.
+      </para>
+
+      <para>
+        Hence, in the Devices menu, VirtualBox allows you to attach the
+        host drive to the guest or select a floppy or DVD image using
+        the Disk Image Manager, as described in
+        <xref
+      linkend="configbasics" />.
+      </para>
+
     </sect2>
 
     <sect2 id="intro-resize-window">
-      <title>Resizing the machine's window</title>
-
-      <para>You can resize the virtual machine's window when it is running. In
-      that case, one of three things will happen:<orderedlist>
-          <listitem>
-            <para>If you have <emphasis role="bold">"scale mode"</emphasis>
-            enabled, then the virtual machine's screen will be scaled to the
-            size of the window. This can be useful if you have many machines
-            running and want to have a look at one of them while it is running
-            in the background. Alternatively, it might be useful to enlarge a
-            window if the VM's output screen is very small, for example
-            because you are running an old operating system in it.</para>
-
-            <para>To enable scale mode, press the <emphasis role="bold">host
-            key + C</emphasis>, or select "Scale mode" from the "Machine" menu
-            in the VM window. To leave scale mode, press the host key + C
-            again.</para>
-
-            <para>The aspect ratio of the guest screen is preserved when
+
+      <title>Resizing the Machine's Window</title>
+
+      <para>
+        You can resize the virtual machine's window when it is running.
+        In that case, one of three things will happen:
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+          <para>
+            If you have <emphasis role="bold">scale mode</emphasis>
+            enabled, then the virtual machine's screen will be scaled to
+            the size of the window. This can be useful if you have many
+            machines running and want to have a look at one of them
+            while it is running in the background. Alternatively, it
+            might be useful to enlarge a window if the VM's output
+            screen is very small, for example because you are running an
+            old operating system in it.
+          </para>
+
+          <para>
+            To enable scale mode, press the <emphasis role="bold">Host
+            key + C</emphasis>, or select <emphasis role="bold">Scale
+            mode</emphasis> from the
+            <emphasis role="bold">Machine</emphasis> menu in the VM
+            window. To leave scale mode, press the Host key + C again.
+          </para>
+
+          <para>
+            The aspect ratio of the guest screen is preserved when
             resizing the window. To ignore the aspect ratio, press Shift
-            during the resize operation.</para>
-
-            <para>Please see <xref linkend="KnownIssues" /> for additional
-            remarks.</para>
-          </listitem>
-
-          <listitem>
-            <para>If you have the Guest Additions installed and they support
-            automatic <emphasis role="bold">resizing</emphasis>, the Guest
-            Additions will automatically adjust the screen resolution of the
-            guest operating system. For example, if you are running a Windows
-            guest with a resolution of 1024x768 pixels and you then resize the
-            VM window to make it 100 pixels wider, the Guest Additions will
-            change the Windows display resolution to 1124x768.</para>
-
-            <para>Please see <xref linkend="guestadditions" /> for more
-            information about the Guest Additions.</para>
-          </listitem>
-
-          <listitem>
-            <para>Otherwise, if the window is bigger than the VM's screen, the
-            screen will be centered. If it is smaller, then scroll bars will
-            be added to the machine window.</para>
-          </listitem>
-        </orderedlist></para>
+            during the resize operation.
+          </para>
+
+          <para>
+            See <xref linkend="KnownIssues" /> for additional remarks.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            If you have the Guest Additions installed and they support
+            automatic <emphasis role="bold">resizing</emphasis>, the
+            Guest Additions will automatically adjust the screen
+            resolution of the guest operating system. For example, if
+            you are running a Windows guest with a resolution of
+            1024x768 pixels and you then resize the VM window to make it
+            100 pixels wider, the Guest Additions will change the
+            Windows display resolution to 1124x768.
+          </para>
+
+          <para>
+            See <xref linkend="guestadditions" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Otherwise, if the window is bigger than the VM's screen, the
+            screen will be centered. If it is smaller, then scroll bars
+            will be added to the machine window.
+          </para>
+        </listitem>
+
+      </orderedlist>
+
     </sect2>
 
-    <sect2>
-      <title>Saving the state of the machine</title>
-
-      <para>When you click on the "Close" button of your virtual machine
-      window (at the top right of the window, just like you would close any
-      other window on your system), VirtualBox asks you whether you want to
-      "save" or "power off" the VM. (As a shortcut, you can also press the
-      Host key together with "Q".)</para>
-
-      <para><mediaobject>
+    <sect2 id="intro-save-machine-state">
+
+      <title>Saving the State of the Machine</title>
+
+      <para>
+        When you click on the <emphasis role="bold">Close</emphasis>
+        button of your virtual machine window, at the top right of the
+        window, just like you would close any other window on your
+        system, VirtualBox asks you whether you want to save or power
+        off the VM. As a shortcut, you can also press Host key + Q.
+      </para>
+
+      <para>
+        <mediaobject>
           <imageobject>
             <imagedata align="center" fileref="images/vm-close.png"
                        width="11cm" />
           </imageobject>
-        </mediaobject>The difference between these three options is crucial.
-      They mean:</para>
+        </mediaobject>
+
+        The difference between the three options is crucial. They mean
+        the following:
+      </para>
 
       <itemizedlist>
+
         <listitem>
-          <para><emphasis role="bold">Save the machine state:</emphasis> With
-          this option, VirtualBox "freezes" the virtual machine by completely
-          saving its state to your local disk.</para>
-
-          <para>When you start the VM again later, you will find that the VM
-          continues exactly where it was left off. All your programs will
-          still be open, and your computer resumes operation. Saving the state
-          of a virtual machine is thus in some ways similar to suspending a
-          laptop computer (e.g. by closing its lid).</para>
+          <para>
+            <emphasis role="bold">Save the machine state:</emphasis>
+            With this option, VirtualBox <emphasis>freezes</emphasis>
+            the virtual machine by completely saving its state to your
+            local disk.
+          </para>
+
+          <para>
+            When you start the VM again later, you will find that the VM
+            continues exactly where it was left off. All your programs
+            will still be open, and your computer resumes operation.
+            Saving the state of a virtual machine is thus in some ways
+            similar to suspending a laptop computer by closing its lid.
+          </para>
         </listitem>
 
         <listitem>
-          <para><emphasis role="bold">Send the shutdown signal.</emphasis>
-          This will send an ACPI shutdown signal to the virtual machine, which
-          has the same effect as if you had pressed the power button on a real
-          computer. So long as the VM is running a fairly modern operating
-          system, this should trigger a proper shutdown mechanism from within
-          the VM.</para>
+          <para>
+            <emphasis role="bold">Send the shutdown signal.</emphasis>
+            This will send an ACPI shutdown signal to the virtual
+            machine, which has the same effect as if you had pressed the
+            power button on a real computer. So long as the VM is
+            running a fairly modern operating system, this should
+            trigger a proper shutdown mechanism from within the VM.
+          </para>
         </listitem>
 
         <listitem>
-          <para><emphasis role="bold">Power off the machine:</emphasis> With
-          this option, VirtualBox also stops running the virtual machine, but
-          <emphasis>without</emphasis> saving its state.<warning>
-              <para>This is equivalent to pulling the power plug on a real
-              computer without shutting it down properly. If you start the
-              machine again after powering it off, your operating system will
-              have to reboot completely and may begin a lengthy check of its
-              (virtual) system disks. As a result, this should not normally be
-              done, since it can potentially cause data loss or an
-              inconsistent state of the guest system on disk.</para>
-            </warning></para>
-
-          <para>As an exception, if your virtual machine has any snapshots
-          (see the next chapter), you can use this option to quickly <emphasis
-          role="bold">restore the current snapshot</emphasis> of the virtual
-          machine. In that case, powering off the machine will not disrupt its
-          state, but any changes made since that snapshot was taken will be
-          lost.</para>
+          <para>
+            <emphasis role="bold">Power off the machine:</emphasis> With
+            this option, VirtualBox also stops running the virtual
+            machine, but <emphasis>without</emphasis> saving its state.
+          </para>
+
+          <warning>
+            <para>
+              This is equivalent to pulling the power plug on a real
+              computer without shutting it down properly. If you start
+              the machine again after powering it off, your operating
+              system will have to reboot completely and may begin a
+              lengthy check of its virtual system disks. As a result,
+              this should not normally be done, since it can potentially
+              cause data loss or an inconsistent state of the guest
+              system on disk.
+            </para>
+          </warning>
+
+          <para>
+            As an exception, if your virtual machine has any snapshots,
+            see <xref linkend="snapshots"/>, you can use this option to
+            quickly <emphasis
+          role="bold">restore the current
+            snapshot</emphasis> of the virtual machine. In that case,
+            powering off the machine will not disrupt its state, but any
+            changes made since that snapshot was taken will be lost.
+          </para>
         </listitem>
+
       </itemizedlist>
 
-      <para>The <emphasis role="bold">"Discard"</emphasis> button in the
-      VirtualBox Manager window discards a virtual machine's saved state. This
-      has the same effect as powering it off, and the same warnings
-      apply.</para>
+      <para>
+        The <emphasis role="bold">Discard</emphasis> button in the
+        VirtualBox Manager window discards a virtual machine's saved
+        state. This has the same effect as powering it off, and the same
+        warnings apply.
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="gui-vmgroups">
-    <title>Using VM groups</title>
-
-    <para>VM groups enable the user to create ad hoc groups of VMs, and to
-    manage and perform functions on them collectively, as well as individually.
-    There are a number of features relating to groups:</para>
+
+    <title>Using VM Groups</title>
+
+    <para>
+      VM groups enable the user to create ad hoc groups of VMs, and to
+      manage and perform functions on them collectively, as well as
+      individually. There are a number of features relating to groups.
+    </para>
 
     <orderedlist>
+
+      <listitem>
+        <para>
+          Create a group using the GUI. Do one of the following:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              Drag one VM on top of another VM.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Select multiple VMs and select
+              <emphasis role="bold">Group</emphasis> from the
+              right-click menu, as shown in the following image.
+            </para>
+
+            <para>
+              <mediaobject>
+                <imageobject>
+                  <imagedata align="center" fileref="images/vm-groups.png"
+                 width="10cm" />
+                </imageobject>
+              </mediaobject>
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          Create and manage a group using the command line. Do one of
+          the following:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              Create a group and assign a VM. For example:
+            </para>
+
+<screen>VBoxManage modifyvm "Fred" --groups "/TestGroup"</screen>
+
+            <para>
+              This command creates a group "TestGroup" and attaches the
+              VM "Fred" to that group.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Detach a VM from the group, and delete the group if empty.
+              For example:
+            </para>
+
+<screen>VBoxManage modifyvm "Fred" --groups ""</screen>
+
+            <para>
+              This command detaches all groups from the VM "Fred" and
+              deletes the empty group.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          Create multiple groups. For example:
+        </para>
+
+<screen>VBoxManage modifyvm "Fred" --groups "/TestGroup,/TestGroup2"</screen>
+
+        <para>
+          This command creates the groups "TestGroup" and "TestGroup2",
+          if they do not exist, and attaches the VM "Fred" to both of
+          them.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Create nested groups, having a group hierarchy. For example:
+        </para>
+
+<screen>VBoxManage modifyvm "Fred" --groups "/TestGroup/TestGroup2"</screen>
+
+        <para>
+          This command attaches the VM "Fred" to the subgroup
+          "TestGroup2" of the "TestGroup" group.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The following is a summary of group commands: Start, Pause,
+          Reset, Close (save state, send shutdown signal, poweroff),
+          Discard Saved State, Show in File System, Sort.
+        </para>
+      </listitem>
+
+    </orderedlist>
+
+  </sect1>
+
+  <sect1 id="snapshots">
+
+    <title>Snapshots</title>
+
+    <para>
+      With snapshots, you can save a particular state of a virtual
+      machine for later use. At any later time, you can revert to that
+      state, even though you may have changed the VM considerably since
+      then. A snapshot of a virtual machine is thus similar to a machine
+      in "saved" state, as described above, but there can be many of
+      them, and these saved states are preserved.
+    </para>
+
+    <para>
+      You can see the snapshots of a virtual machine by first selecting
+      a machine in the VirtualBox Manager and then clicking on the
+      <emphasis role="bold">Snapshots</emphasis> button at the top
+      right. Until you take a snapshot of the machine, the list of
+      snapshots will be empty except for the
+      <emphasis role="bold">Current State</emphasis> item, which
+      represents the "now" point in the lifetime of the virtual machine.
+    </para>
+
+    <sect2 id="snapshots-take-restore-delete">
+
+      <title>Taking, Restoring, and Deleting Snapshots</title>
+
+      <para>
+        There are three operations related to snapshots, as follows:
+      </para>
+
+      <orderedlist>
+
         <listitem>
           <para>
-            Create a group using GUI option 1) Drag one VM on top of another
-            VM.
-          </para>
-          <para>
-            Create a group using GUI option 2) Select multiple VMs and select
-            "Group" on the right click menu, as follows:
-          </para>
-
-          <para><mediaobject>
-          <imageobject>
-          <imagedata align="center" fileref="images/vm-groups.png"
-                     width="10cm" />
-          </imageobject>
-          </mediaobject></para>
-
+            <emphasis role="bold">Take a snapshot</emphasis>. This makes
+            a copy of the machine's current state, to which you can go
+            back at any given time later.
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                If your VM is currently running, select
+                <emphasis role="bold">Take Snapshot</emphasis> from the
+                <emphasis role="bold">Machine</emphasis> pull-down menu
+                of the VM window.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If your VM is currently in either the Saved or the
+                Powered Off state, as displayed next to the VM in the
+                VirtualBox main window, click on the
+                <emphasis role="bold">Snapshots </emphasis>tab on the
+                top right of the main window. Do one of the following:
+              </para>
+
+              <itemizedlist>
+
+                <listitem>
+                  <para>
+                    Click on the small camera icon.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    Right-click on the <emphasis role="bold">Current
+                    State </emphasis>item in the list and select
+                    <emphasis role="bold">Take Snapshot</emphasis> from
+                    the menu.
+                  </para>
+                </listitem>
+
+              </itemizedlist>
+            </listitem>
+
+          </itemizedlist>
+
+          <para>
+            In either case, a window is displayed prompting you for a
+            snapshot name. This name is purely for reference purposes to
+            help you remember the state of the snapshot. For example, a
+            useful name would be "Fresh installation from scratch, no
+            Guest Additions", or "Service Pack 3 just installed". You
+            can also add a longer text in the Description field.
+          </para>
+
+          <para>
+            Your new snapshot will then appear in the snapshots list.
+            Underneath your new snapshot, you will see an item called
+            Current State, signifying that the current state of your VM
+            is a variation based on the snapshot you took earlier. If
+            you later take another snapshot, you will see that they will
+            be displayed in sequence, and each subsequent snapshot is
+            derived from an earlier one.
+          </para>
+
+          <mediaobject>
+            <imageobject>
+              <imagedata align="center" fileref="images/snapshots-1.png"
+                             width="12cm" />
+            </imageobject>
+          </mediaobject>
+
+          <para>
+            VirtualBox imposes no limits on the number of snapshots you
+            can take. The only practical limitation is disk space on
+            your host. Each snapshot stores the state of the virtual
+            machine and thus occupies some disk space. See
+            <xref linkend="snapshots-contents"/> for details on what is
+            stored in a snapshot.
+          </para>
         </listitem>
+
         <listitem>
           <para>
-            Command line option 1) Create a group and assign a VM:
-            <screen>VBoxManage modifyvm "Fred" --groups "/TestGroup"</screen>
-            creates a group "TestGroup" and attaches the VM "Fred" to that group.
-          </para>
-          <para>
-            Command line option 2) Detach a VM from the group, and delete the group
-            if empty: <screen>VBoxManage modifyvm "Fred" --groups ""</screen>
-            It detaches all groups from the VM "Fred" and deletes the empty group.
+            <emphasis role="bold">Restore a snapshot</emphasis>. You do
+            this by right-clicking on any snapshot you have taken in the
+            list of snapshots. By restoring a snapshot, you go back or
+            forward in time. The current state of the machine is lost,
+            and the machine is restored to the exact state it was in
+            when the snapshot was taken.
+
+            <footnote>
+
+              <para>
+                Both the terminology and the functionality of restoring
+                snapshots has changed with VirtualBox 3.1. Before that
+                version, it was only possible to go back to the very
+                last snapshot taken -- not earlier ones, and the
+                operation was called "Discard current state" instead of
+                "Restore last snapshot". The limitation has been lifted
+                with version 3.1. It is now possible to restore
+                <emphasis>any</emphasis> snapshot, going backward and
+                forward in time.
+              </para>
+
+            </footnote>
+          </para>
+
+          <note>
+            <para>
+              Restoring a snapshot will affect the virtual hard drives
+              that are connected to your VM, as the entire state of the
+              virtual hard drive will be reverted as well. This means
+              also that all files that have been created since the
+              snapshot and all other file changes <emphasis>will be
+              lost. </emphasis>In order to prevent such data loss while
+              still making use of the snapshot feature, it is possible
+              to add a second hard drive in "write-through" mode using
+              the <computeroutput>VBoxManage</computeroutput> interface
+              and use it to store your data. As write-through hard
+              drives are <emphasis>not</emphasis> included in snapshots,
+              they remain unaltered when a machine is reverted. See
+              <xref
+              linkend="hdimagewrites" />.
+            </para>
+          </note>
+
+          <para>
+            To avoid losing the current state when restoring a snapshot,
+            you can create a new snapshot before the restore.
+          </para>
+
+          <para>
+            By restoring an earlier snapshot and taking more snapshots
+            from there, it is even possible to create a kind of
+            alternate reality and to switch between these different
+            histories of the virtual machine. This can result in a whole
+            tree of virtual machine snapshots, as shown in the
+            screenshot above.
           </para>
         </listitem>
+
         <listitem>
           <para>
-            Multiple groups e.g.:
-            <screen>VBoxManage modifyvm "Fred" --groups "/TestGroup,/TestGroup2"</screen>
-            It creates the groups "TestGroup" and "TestGroup2" (if they don't exist yet)
-            and attaches the VM "Fred" to both of them.
+            <emphasis role="bold">Delete a snapshot</emphasis>. This
+            does not affect the state of the virtual machine, but only
+            releases the files on disk that VirtualBox used to store the
+            snapshot data, thus freeing disk space. To delete a
+            snapshot, right-click on it in the snapshots tree and select
+            <emphasis role="bold">Delete</emphasis>. Snapshots can be
+            deleted even while a machine is running.
+          </para>
+
+          <note>
+            <para>
+              Whereas taking and restoring snapshots are fairly quick
+              operations, deleting a snapshot can take a considerable
+              amount of time since large amounts of data may need to be
+              copied between several disk image files. Temporary disk
+              files may also need large amounts of disk space while the
+              operation is in progress.
+            </para>
+          </note>
+
+          <para>
+            There are some situations which cannot be handled while a VM
+            is running, and you will get an appropriate message that you
+            need to perform this snapshot deletion when the VM is shut
+            down.
           </para>
         </listitem>
+
+      </orderedlist>
+
+    </sect2>
+
+    <sect2 id="snapshots-contents">
+
+      <title>Snapshot Contents</title>
+
+      <para>
+        Think of a snapshot as a point in time that you have preserved.
+        More formally, a snapshot consists of the following three
+        things:
+      </para>
+
+      <itemizedlist>
+
         <listitem>
           <para>
-            Nested groups -- hierarchy of groups e.g.:
-            <screen>VBoxManage modifyvm "Fred" --groups "/TestGroup/TestGroup2"</screen>
-            It attaches the VM "Fred" to the subgroup "TestGroup2" of the "TestGroup"
-            group.
+            The snapshot contains a complete copy of the VM settings,
+            including the hardware configuration, so that when you
+            restore a snapshot, the VM settings are restored as well.
+            For example, if you changed the hard disk configuration or
+            the VM's system settings, that change is undone when you
+            restore the snapshot.
+          </para>
+
+          <para>
+            The copy of the settings is stored in the machine
+            configuration, an XML text file, and thus occupies very
+            little space.
           </para>
         </listitem>
+
         <listitem>
           <para>
-          Summary of group commands: Start, Pause, Reset, Close (save state,
-          send shutdown signal, poweroff), Discard Saved State, Show in File
-          System, Sort.
+            The complete state of all the virtual disks attached to the
+            machine is preserved. Going back to a snapshot means that
+            all changes that had been made to the machine's disks, file
+            by file and bit by bit, will be undone as well. Files that
+            were since created will disappear, files that were deleted
+            will be restored, changes to files will be reverted.
+          </para>
+
+          <para>
+            Strictly speaking, this is only true for virtual hard disks
+            in "normal" mode. You can configure disks to behave
+            differently with snapshots, see
+            <xref
+            linkend="hdimagewrites" />. Even more
+            formally and technically correct, it is not the virtual disk
+            itself that is restored when a snapshot is restored.
+            Instead, when a snapshot is taken, VirtualBox creates
+            differencing images which contain only the changes since the
+            snapshot were taken, and when the snapshot is restored,
+            VirtualBox throws away that differencing image, thus going
+            back to the previous state. This is both faster and uses
+            less disk space. For the details, which can be complex, see
+            <xref linkend="diffimages" />.
+          </para>
+
+          <para>
+            Creating the differencing image as such does not occupy much
+            space on the host disk initially, since the differencing
+            image will initially be empty and grow dynamically later
+            with each write operation to the disk. The longer you use
+            the machine after having created the snapshot, however, the
+            more the differencing image will grow in size.
           </para>
         </listitem>
-      </orderedlist>
+
+        <listitem>
+          <para>
+            If you took a snapshot while the machine was running, the
+            memory state of the machine is also saved in the snapshot.
+            This is in the same way that memory can be saved when you
+            close a VM window. When you restore such a snapshot,
+            execution resumes at exactly the point when the snapshot was
+            taken.
+          </para>
+
+          <para>
+            The memory state file can be as large as the memory size of
+            the virtual machine and will therefore occupy quite some
+            disk space as well.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
   </sect1>
 
-  <sect1 id="snapshots">
-    <title>Snapshots</title>
-
-    <para>With snapshots, you can save a particular state of a virtual machine
-    for later use. At any later time, you can revert to that state, even
-    though you may have changed the VM considerably since then. A snapshot of
-    a virtual machine is thus similar to a machine in "saved" state, as
-    described above, but there can be many of them, and these saved states are
-    preserved.</para>
-
-    <para>You can see the snapshots of a virtual machine by first selecting a
-    machine in the VirtualBox Manager and then clicking on the "Snapshots"
-    button at the top right. Until you take a snapshot of the machine, the
-    list of snapshots will be empty except for the "Current state" item, which
-    represents the "Now" point in the lifetime of the virtual machine.</para>
-
-    <sect2>
-      <title>Taking, restoring and deleting snapshots</title>
-
-      <para>There are three operations related to snapshots:<orderedlist>
-          <listitem>
-            <para>You can <emphasis role="bold">take a snapshot</emphasis>.
-            This makes a copy of the machine's current state, to which you can
-            go back at any given time later.<itemizedlist>
-                <listitem>
-                  <para>If your VM is currently running, select "Take
-                  snapshot" from the "Machine" pull-down menu of the VM
-                  window.</para>
-                </listitem>
-
-                <listitem>
-                  <para>If your VM is currently in either the "saved" or the
-                  "powered off" state (as displayed next to the VM in the
-                  VirtualBox main window), click on the "Snapshots" tab on the
-                  top right of the main window, and then<itemizedlist>
-                      <listitem>
-                        <para>either on the small camera icon (for "Take
-                        snapshot") or</para>
-                      </listitem>
-
-                      <listitem>
-                        <para>right-click on the "Current State" item in the
-                        list and select "Take snapshot" from the menu.</para>
-                      </listitem>
-                    </itemizedlist></para>
-                </listitem>
-              </itemizedlist></para>
-
-            <para>In any case, a window will pop up and ask you for a snapshot
-            name. This name is purely for reference purposes to help you
-            remember the state of the snapshot. For example, a useful name
-            would be "Fresh installation from scratch, no Guest Additions", or
-            "Service Pack 3 just installed". You can also add a longer text in
-            the "Description" field if you want.</para>
-
-            <para>Your new snapshot will then appear in the snapshots list.
-            Underneath your new snapshot, you will see an item called "Current
-            state", signifying that the current state of your VM is a
-            variation based on the snapshot you took earlier. If you later
-            take another snapshot, you will see that they will be displayed in
-            sequence, and each subsequent snapshot is derived from an earlier
-            one:<mediaobject>
-                <imageobject>
-                  <imagedata align="center" fileref="images/snapshots-1.png"
-                             width="12cm" />
-                </imageobject>
-              </mediaobject></para>
-
-            <para>VirtualBox imposes no limits on the number of snapshots you
-            can take. The only practical limitation is disk space on your
-            host: each snapshot stores the state of the virtual machine and
-            thus occupies some disk space. (See the next section for details
-            on what exactly is stored in a snapshot.)</para>
-          </listitem>
-
-          <listitem>
-            <para>You can <emphasis role="bold">restore a snapshot</emphasis>
-            by right-clicking on any snapshot you have taken in the list of
-            snapshots. By restoring a snapshot, you go back (or forward) in
-            time: the current state of the machine is lost, and the machine is
-            restored to the exact state it was in when the snapshot was
-            taken.<footnote>
-                <para>Both the terminology and the functionality of restoring
-                snapshots has changed with VirtualBox 3.1. Before that
-                version, it was only possible to go back to the very last
-                snapshot taken -- not earlier ones, and the operation was
-                called "Discard current state" instead of "Restore last
-                snapshot". The limitation has been lifted with version 3.1. It
-                is now possible to restore <emphasis>any</emphasis> snapshot,
-                going backward and forward in time.</para>
-              </footnote></para>
-
-            <note>
-              <para>Restoring a snapshot will affect the virtual hard drives
-              that are connected to your VM, as the entire state of the
-              virtual hard drive will be reverted as well. This means also
-              that all files that have been created since the snapshot and all
-              other file changes <emphasis>will be lost. </emphasis>In order
-              to prevent such data loss while still making use of the snapshot
-              feature, it is possible to add a second hard drive in
-              "write-through" mode using the
-              <computeroutput>VBoxManage</computeroutput> interface and use it
-              to store your data. As write-through hard drives are
-              <emphasis>not</emphasis> included in snapshots, they remain
-              unaltered when a machine is reverted. See <xref
-              linkend="hdimagewrites" os="" /> for details.</para>
-            </note>
-
-            <para>To avoid losing the current state when restoring a snapshot,
-            you can create a new snapshot before the restore.</para>
-
-            <para>By restoring an earlier snapshot and taking more snapshots
-            from there, it is even possible to create a kind of alternate
-            reality and to switch between these different histories of the
-            virtual machine. This can result in a whole tree of virtual
-            machine snapshots, as shown in the screenshot above.</para>
-          </listitem>
-
-          <listitem>
-            <para>You can also <emphasis role="bold">delete a
-            snapshot</emphasis>, which will not affect the state of the
-            virtual machine, but only release the files on disk that
-            VirtualBox used to store the snapshot data, thus freeing disk
-            space. To delete a snapshot, right-click on it in the snapshots
-            tree and select "Delete". As of VirtualBox 3.2, snapshots can be
-            deleted even while a machine is running.<note>
-                <para>Whereas taking and restoring snapshots are fairly quick
-                operations, deleting a snapshot can take a considerable amount
-                of time since large amounts of data may need to be copied
-                between several disk image files. Temporary disk files may
-                also need large amounts of disk space while the operation is
-                in progress.</para>
-              </note></para>
-
-            <para>There are some situations which cannot be handled while a VM
-            is running, and you will get an appropriate message that you need
-            to perform this snapshot deletion when the VM is shut down.</para>
-          </listitem>
-        </orderedlist></para>
-    </sect2>
-
-    <sect2>
-      <title>Snapshot contents</title>
-
-      <para>Think of a snapshot as a point in time that you have preserved.
-      More formally, a snapshot consists of three things:<itemizedlist>
-          <listitem>
-            <para>It contains a complete copy of the VM settings, including
-            the hardware configuration, so that when you restore a snapshot,
-            the VM settings are restored as well. (For example, if you changed
-            the hard disk configuration or the VM's system settings, that
-            change is undone when you restore the snapshot.)</para>
-
-            <para>The copy of the settings is stored in the machine
-            configuration, an XML text file, and thus occupies very little
-            space.</para>
-          </listitem>
-
-          <listitem>
-            <para>The complete state of all the virtual disks attached to the
-            machine is preserved. Going back to a snapshot means that all
-            changes that had been made to the machine's disks -- file by file,
-            bit by bit -- will be undone as well. Files that were since
-            created will disappear, files that were deleted will be restored,
-            changes to files will be reverted.</para>
-
-            <para>(Strictly speaking, this is only true for virtual hard disks
-            in "normal" mode. As mentioned above, you can configure disks to
-            behave differently with snapshots; see <xref
-            linkend="hdimagewrites" />. Even more formally and technically
-            correct, it is not the virtual disk itself that is restored when a
-            snapshot is restored. Instead, when a snapshot is taken,
-            VirtualBox creates differencing images which contain only the
-            changes since the snapshot were taken, and when the snapshot is
-            restored, VirtualBox throws away that differencing image, thus
-            going back to the previous state. This is both faster and uses
-            less disk space. For the details, which can be complex, please see
-            <xref linkend="diffimages" />.)</para>
-
-            <para>Creating the differencing image as such does not occupy much
-            space on the host disk initially, since the differencing image
-            will initially be empty (and grow dynamically later with each
-            write operation to the disk). The longer you use the machine after
-            having created the snapshot, however, the more the differencing
-            image will grow in size.</para>
-          </listitem>
-
-          <listitem>
-            <para>Finally, if you took a snapshot while the machine was
-            running, the memory state of the machine is also saved in the
-            snapshot (the same way the memory can be saved when you close the
-            VM window). When you restore such a snapshot, execution resumes at
-            exactly the point when the snapshot was taken.</para>
-
-            <para>The memory state file can be as large as the memory size of
-            the virtual machine and will therefore occupy quite some disk
-            space as well.</para>
-          </listitem>
-        </itemizedlist></para>
-    </sect2>
+  <sect1 id="configbasics">
+
+    <title>Virtual Machine Configuration</title>
+
+    <para>
+      When you select a virtual machine from the list in the Manager
+      window, you will see a summary of that machine's settings on the
+      right.
+    </para>
+
+    <para>
+      Clicking on the <emphasis role="bold">Settings</emphasis> button
+      in the toolbar at the top brings up a detailed window where you
+      can configure many of the properties of the selected VM. But be
+      careful. Even though it is possible to change all VM settings
+      after installing a guest operating system, certain changes might
+      prevent a guest operating system from functioning correctly if
+      done after installation.
+    </para>
+
+    <note>
+      <para>
+        The Settings button is disabled while a VM is either in the
+        Running or Saved state. This is because the settings dialog
+        allows you to change fundamental characteristics of the virtual
+        computer that is created for your guest operating system, and
+        this operating system may perform well when, for example, half
+        of its memory is taken away. As a result, if the Settings button
+        is disabled, shut down the current VM first.
+      </para>
+    </note>
+
+    <para>
+      VirtualBox provides a wide range of parameters that can be changed
+      for a virtual machine. The various settings that can be changed in
+      the Settings window are described in detail in
+      <xref
+    linkend="BasicConcepts" />. Even more parameters are
+      available with the VirtualBox command line interface. See
+      <xref
+    linkend="vboxmanage" />.
+    </para>
+
   </sect1>
 
-  <sect1 id="configbasics">
-    <title>Virtual machine configuration</title>
-
-    <para>When you select a virtual machine from the list in the Manager
-    window, you will see a summary of that machine's settings on the
-    right.</para>
-
-    <para>Clicking on the "Settings" button in the toolbar at the top brings
-    up a detailed window where you can configure many of the properties of the
-    selected VM. But be careful: even though it is possible to change all VM
-    settings after installing a guest operating system, certain changes might
-    prevent a guest operating system from functioning correctly if done after
-    installation.</para>
-
-    <note>
-      <para>The "Settings" button is disabled while a VM is either in the
-      "running" or "saved" state. This is simply because the settings dialog
-      allows you to change fundamental characteristics of the virtual computer
-      that is created for your guest operating system, and this operating
-      system may not take it well when, for example, half of its memory is
-      taken away from under its feet. As a result, if the "Settings" button is
-      disabled, shut down the current VM first.</para>
-    </note>
-
-    <para>VirtualBox provides a plethora of parameters that can be changed for
-    a virtual machine. The various settings that can be changed in the
-    "Settings" window are described in detail in <xref
-    linkend="BasicConcepts" />. Even more parameters are available with the
-    VirtualBox command line interface; see <xref
-    linkend="vboxmanage" />.</para>
+  <sect1 id="intro-removing">
+
+    <title>Removing Virtual Machines</title>
+
+    <para>
+      To remove a virtual machine which you no longer need, right-click
+      on it in the Manager's VM list and select
+      <emphasis role="bold">Remove</emphasis>.
+    </para>
+
+    <para>
+      A confirmation window is displayed that allows you to select
+      whether the machine should only be removed from the list of
+      machines or whether the files associated with it should also be
+      deleted.
+    </para>
+
+    <para>
+      The Remove menu item is disabled while a machine is running.
+    </para>
+
   </sect1>
 
-  <sect1>
-    <title>Removing virtual machines</title>
-
-    <para>To remove a virtual machine which you no longer need, right-click on
-    it in the Manager's VM list select "Remove" from the context menu that
-    comes up.</para>
-
-    <para>A confirmation window will come up that allows you to select whether
-    the machine should only be removed from the list of machines or whether
-    the files associated with it should also be deleted.</para>
-
-    <para>The "Remove" menu item is disabled while a machine is
-    running.</para>
-  </sect1>
-
   <sect1 id="clone">
-    <title>Cloning virtual machines</title>
-
-    <para>To experiment with a VM configuration, test different guest OS levels
-    or to simply backup a VM, VirtualBox can create a full or a linked copy of
-    an existing VM.<footnote><para>Cloning support was introduced with VirtualBox
-    4.1.</para></footnote></para>
-
-    <para>A wizard will guide you through the clone process:</para>
+
+    <title>Cloning Virtual Machines</title>
+
+    <para>
+      To experiment with a VM configuration, test different guest OS
+      levels or to simply backup a VM, VirtualBox can create a full or a
+      linked copy of an existing VM.
+
+      <footnote>
+
+        <para>
+          Cloning support was introduced with VirtualBox 4.1.
+        </para>
+
+      </footnote>
+    </para>
+
+    <para>
+      A wizard guides you through the clone process.
+    </para>
 
     <mediaobject>
@@ -1603,259 +2360,405 @@
     </mediaobject>
 
-    <para>This wizard can be invoked from the context menu of the Manager's VM
-    list (select "Clone") or the "Snapshots" view of the selected VM. First
-    choose a new name for the clone. When you select <emphasis
-    role="bold">Reinitialize the MAC address of all network cards</emphasis>
-    every network card get a new MAC address assigned. This is useful when
-    both, the source VM and the cloned VM, have to operate on the same network.
-    If you leave this unchanged, all network cards have the same MAC address
-    like the one in the source VM. Depending on how you invoke the wizard you
-    have different choices for the cloning operation. First you need to decide
-    if the clone should be linked to the source VM or a fully independent clone
-    should be created:</para>
+    <para>
+      This wizard can be started from the right-click menu of the
+      Manager's VM list, by clicking
+      <emphasis role="bold">Clone</emphasis>, or the
+      <emphasis role="bold">Snapshots</emphasis> view of the selected
+      VM. First choose a new name for the clone. When you select
+      <emphasis
+    role="bold">Reinitialize the MAC address of all
+      network cards</emphasis> every network card get a new MAC address
+      assigned. This is useful when both the source VM and the cloned VM
+      have to operate on the same network. If you leave this unchanged,
+      all network cards have the same MAC address like the one in the
+      source VM. Depending on how you invoke the wizard you have
+      different choices for the cloning operation. First you need to
+      decide if the clone should be linked to the source VM or if a
+      fully independent clone should be created.
+    </para>
+
     <itemizedlist>
-      <listitem>
-         <para><emphasis role="bold">Full clone:</emphasis> In this mode all
-             depending disk images are copied to the new VM folder. The clone
-             can fully operate without the source VM.
-         </para>
-      </listitem>
-
-      <listitem>
-         <para><emphasis role="bold">Linked clone:</emphasis> In this mode new
-             differencing disk images are created where the parent disk images
-             are the source disk images. If you selected the current state of
-             the source VM as clone point, a new snapshot will be created
-             implicitly.
-         </para>
-      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Full clone:</emphasis> In this mode, all
+          dependent disk images are copied to the new VM folder. The
+          clone can fully operate without the source VM.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Linked clone:</emphasis> In this mode,
+          new differencing disk images are created where the parent disk
+          images are the source disk images. If you selected the current
+          state of the source VM as clone point, a new snapshot will be
+          created implicitly.
+        </para>
+      </listitem>
+
     </itemizedlist>
 
-    <para>After selecting the clone mode, you need to decide about what exactly
-    should be cloned. You can always create a clone of the <emphasis
-        role="italic">current state</emphasis> only or <emphasis
-        role="italic">all</emphasis>. When you select <emphasis
-        role="italic">all</emphasis>, the current state and in addition all
-    snapshots are cloned. Have you started from a snapshot which has additional
-    children, you can also clone the <emphasis role="italic">current state and
-        all children</emphasis>. This creates a clone starting with this
-    snapshot and includes all child snapshots.</para>
-
-    <para>The clone operation itself can be a lengthy operation depending on
-    the size and count of the attached disk images. Also keep in mind that
-    every snapshot has differencing disk images attached, which need to be
-    cloned as well.</para>
-
-    <para>The "Clone" menu item is disabled while a machine is running.</para>
-
-    <para>For how to clone a VM at the command line, please see <xref
-    linkend="vboxmanage-clonevm" />.</para>
+    <para>
+      After selecting the clone mode, you need to decide what exactly
+      should be cloned. You can always create a clone of the
+      <emphasis>current state</emphasis> only or
+      <emphasis>all</emphasis>. When you select
+      <emphasis>all</emphasis>, the current state and in addition all
+      snapshots are cloned. If you started from a snapshot which has
+      additional children, you can also clone the
+      <emphasis role="italic">current state and all children</emphasis>.
+      This creates a clone starting with this snapshot and includes all
+      child snapshots.
+    </para>
+
+    <para>
+      The clone operation itself can be a lengthy operation depending on
+      the size and count of the attached disk images. Also keep in mind
+      that every snapshot has differencing disk images attached, which
+      need to be cloned as well.
+    </para>
+
+    <para>
+      The Clone menu item is disabled while a machine is running.
+    </para>
+
+    <para>
+      To clone a VM from the command line, see
+      <xref
+    linkend="vboxmanage-clonevm" />.
+    </para>
+
   </sect1>
 
   <sect1 id="ovf">
-    <title>Importing and exporting virtual machines</title>
-
-    <para>VirtualBox can import and export virtual machines in the
-    industry-standard Open Virtualization Format (OVF).<footnote>
-        <para>OVF support was originally introduced with VirtualBox 2.2 and
-        has seen major improvements with every version since.</para>
-      </footnote></para>
-
-    <para>OVF is a cross-platform standard supported by many virtualization
-    products which allows for creating ready-made virtual machines that can
-    then be imported into a virtualizer such as VirtualBox. VirtualBox makes
-    OVF import and export easy to access and supports it from the Manager
-    window as well as its command-line interface. This allows for packaging
-    so-called <emphasis role="bold">virtual appliances</emphasis>: disk images
-    together with configuration settings that can be distributed easily. This
-    way one can offer complete ready-to-use software packages (operating
-    systems with applications) that need no configuration or installation
-    except for importing into VirtualBox.<note>
-        <para>The OVF standard is complex, and support in VirtualBox is an
-        ongoing process. In particular, no guarantee is made that VirtualBox
-        supports all appliances created by other virtualization software. For
-        a list of known limitations, please see <xref
-        linkend="KnownIssues" />.</para>
-      </note></para>
-
-    <para>Appliances in OVF format can appear in two variants:<orderedlist>
-        <listitem>
-          <para>They can come in several files, as one or several disk images,
-          typically in the widely-used VMDK format (see <xref
-          linkend="vdidetails" />) and a textual description file in an XML
-          dialect with an <computeroutput>.ovf</computeroutput> extension.
-          These files must then reside in the same directory for VirtualBox to
-          be able to import them.</para>
-        </listitem>
-
-        <listitem>
-          <para>Alternatively, the above files can be packed together into a
+
+    <title>Importing and Exporting Virtual Machines</title>
+
+    <para>
+      VirtualBox can import and export virtual machines in the
+      industry-standard Open Virtualization Format (OVF).
+
+      <footnote>
+
+        <para>
+          OVF support was originally introduced with VirtualBox 2.2 and
+          has seen major improvements with every version since.
+        </para>
+
+      </footnote>
+    </para>
+
+    <para>
+      OVF is a cross-platform standard supported by many virtualization
+      products which allows for creating ready-made virtual machines
+      that can then be imported into a virtualizer such as VirtualBox.
+      VirtualBox makes OVF import and export easy to access and supports
+      it from the Manager window as well as its command-line interface.
+      This allows for packaging so-called <emphasis>virtual
+      appliances</emphasis>. These are disk images, together with
+      configuration settings that can be distributed easily. This way
+      one can offer complete ready-to-use software packages, including
+      operating systems with applications, that need no configuration or
+      installation except for importing into VirtualBox.
+    </para>
+
+    <note>
+      <para>
+        The OVF standard is complex, and support in VirtualBox is an
+        ongoing process. In particular, no guarantee is made that
+        VirtualBox supports all appliances created by other
+        virtualization software. For a list of known limitations, see
+        <xref
+        linkend="KnownIssues" />.
+      </para>
+    </note>
+
+    <para>
+      Appliances in OVF format can appear in the following variants:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          They can come in several files, as one or several disk images,
+          typically in the widely-used VMDK format. See
+          <xref
+          linkend="vdidetails" />. They also include a
+          textual description file in an XML dialect with an
+          <computeroutput>.ovf</computeroutput> extension. These files
+          must then reside in the same directory for VirtualBox to be
+          able to import them.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Alternatively, the above files can be packed together into a
           single archive file, typically with an
-          <computeroutput>.ova</computeroutput> extension. (Such archive files
-          use a variant of the TAR archive format and can therefore be
-          unpacked outside of VirtualBox with any utility that can unpack
-          standard TAR files.)</para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>To <emphasis role="bold">import</emphasis> an appliance in one of
-    the above formats, simply double-click on the OVF/OVA file.<footnote>
-        <para>Starting with version 4.0, VirtualBox creates file type
-        associations for OVF and OVA files on your host operating
-        system.</para>
-      </footnote> Alternatively, select "File" &rarr; "Import appliance" from
-    the Manager window. In the file dialog that comes up, navigate to the file
-    with either the <computeroutput>.ovf</computeroutput> or the
-    <computeroutput>.ova</computeroutput> file extension.</para>
-
-    <para>If VirtualBox can handle the file, a dialog similar to the following
-    will appear:</para>
-
-    <para><mediaobject>
-        <imageobject>
-          <imagedata align="center" fileref="images/ovf-import.png"
+          <computeroutput>.ova</computeroutput> extension. Such archive
+          files use a variant of the TAR archive format and can
+          therefore be unpacked outside of VirtualBox with any utility
+          that can unpack standard TAR files.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      To <emphasis role="bold">import an appliance</emphasis> in one of
+      the above formats, double-click on the OVF/OVA file.
+
+      <footnote>
+
+        <para>
+          Starting with version 4.0, VirtualBox creates file type
+          associations for OVF and OVA files on your host operating
+          system.
+        </para>
+
+      </footnote>
+
+      Alternatively, select <emphasis role="bold">File</emphasis>,
+      <emphasis role="bold">Import Appliance</emphasis> from the Manager
+      window. In the displayed file dialog, navigate to the file with
+      either the <computeroutput>.ovf</computeroutput> or the
+      <computeroutput>.ova</computeroutput> file extension.
+    </para>
+
+    <para>
+      If VirtualBox can handle the file, a dialog similar to the
+      following will appear:
+    </para>
+
+    <mediaobject>
+      <imageobject>
+        <imagedata align="center" fileref="images/ovf-import.png"
                      width="12cm" />
-        </imageobject>
-      </mediaobject>This presents the virtual machines described in the OVF
-    file and allows you to change the virtual machine settings by
-    double-clicking on the description items. Once you click on <emphasis
-    role="bold">"Import"</emphasis>, VirtualBox will copy the disk images and
-    create local virtual machines with the settings described in the dialog.
-    These will then show up in the Manager's list of virtual machines.</para>
-
-    <para>Note that since disk images tend to be big, and VMDK images that
-    come with virtual appliances are typically shipped in a special compressed
-    format that is unsuitable for being used by virtual machines directly, the
-    images will need to be unpacked and copied first, which can take a few
-    minutes.</para>
-
-    <para>For how to import an image at the command line, please see <xref
-    linkend="vboxmanage-import" />.</para>
-
-    <para>Conversely, to <emphasis role="bold">export</emphasis> virtual
-    machines that you already have in VirtualBox, select "File" &rarr; "Export
-    appliance". A different dialog window shows up that allows you to combine
-    several virtual machines into an OVF appliance. Then, select the target
-    location where the target files should be stored, and the conversion
-    process begins. This can again take a while.</para>
-
-    <para>For how to export an image at the command line, please see <xref
-    linkend="vboxmanage-export" />.<note>
-        <para>OVF cannot describe snapshots that were taken for a virtual
+      </imageobject>
+    </mediaobject>
+
+    <para>
+      This presents the virtual machines described in the OVF file and
+      allows you to change the virtual machine settings by
+      double-clicking on the description items. Once you click on
+      <emphasis
+    role="bold">"Import"</emphasis>, VirtualBox will
+      copy the disk images and create local virtual machines with the
+      settings described in the dialog. These will then show up in the
+      Manager's list of virtual machines.
+    </para>
+
+    <para>
+      Note that since disk images tend to be big, and VMDK images that
+      come with virtual appliances are typically shipped in a special
+      compressed format that is unsuitable for being used by virtual
+      machines directly, the images will need to be unpacked and copied
+      first, which can take a few minutes.
+    </para>
+
+    <para>
+      To import an image using the command line, see
+      <xref
+    linkend="vboxmanage-import" />.
+    </para>
+
+    <para>
+      To <emphasis role="bold">export virtual machines</emphasis> that
+      you already have in VirtualBox, select
+      <emphasis role="bold">File</emphasis>, <emphasis role="bold">
+      Export Appliance</emphasis>. A dialog window is displayed that
+      enables you to combine several virtual machines into an OVF
+      appliance. Select the target location where the target files
+      should be stored, and the conversion process begins. This can take
+      a while.
+    </para>
+
+    <para>
+      To export an image using the command line, see
+      <xref
+    linkend="vboxmanage-export" />.
+    </para>
+
+    <note>
+      <para>
+        OVF cannot describe snapshots that were taken for a virtual
         machine. As a result, when you export a virtual machine that has
-        snapshots, only the current state of the machine will be exported, and
-        the disk images in the export will have a "flattened" state identical
-        to the current state of the virtual machine.</para>
-      </note></para>
+        snapshots, only the current state of the machine will be
+        exported. The disk images in the export will have a "flattened"
+        state identical to the current state of the virtual machine.
+      </para>
+    </note>
+
   </sect1>
 
   <sect1 id="globalsettings">
+
     <title>Global Settings</title>
-    <para>The global settings dialog can be reached through the
-    <emphasis role="bold">File</emphasis> menu, selecting the
-    <emphasis role="bold">Preferences...</emphasis> item. It offers a selection
-    of settings which apply to all virtual machines of the current user or in
-    the case of <emphasis role="bold">Extensions</emphasis> to the entire
-    system:
-    <orderedlist>
-      <listitem>
-         <para><emphasis role="bold">General</emphasis> Enables the user to
-         specify the default folder/directory for VM files, and the VRDP
-         Authentication Library.</para>
-      </listitem>
-      <listitem>
-         <para><emphasis role="bold">Input</emphasis> Enables the user to
-         specify the Host Key. It identifies the key that toggles whether the
-         cursor is in the focus of the VM or the Host operating system
-         windows (see <xref linkend="keyb_mouse_normal"/>) and which is also
-         used to trigger certain VM actions (see <xref
-         linkend="specialcharacters"/>)</para>
-      </listitem>
-      <listitem>
-         <para><emphasis role="bold">Update</emphasis> Enables the user
-         to specify various settings for Automatic Updates.</para>
-      </listitem>
-      <listitem>
-         <para><emphasis role="bold">Language</emphasis> Enables the user to
-         specify the GUI language.</para>
-      </listitem>
-      <listitem>
-         <para><emphasis role="bold">Display</emphasis> Enables the user to
-         specify the screen resolution, and its width and height.</para>
-      </listitem>
-      <listitem>
-         <para><emphasis role="bold">Network</emphasis> Enables the user to
-         configure the details of Host Only Networks.</para>
-      </listitem>
-      <listitem>
-         <para><emphasis role="bold">Extensions</emphasis> Enables the user
-         to list and manage the installed extension packages.</para>
-      </listitem>
-      <listitem>
-         <para><emphasis role="bold">Proxy</emphasis> Enables the user to
-         configure a HTTP Proxy Server.</para>
-      </listitem>
-    </orderedlist></para>
+
+    <para>
+      The Global Settings dialog can be displayed using the
+      <emphasis role="bold">File</emphasis> menu, by clicking the
+      <emphasis role="bold">Preferences</emphasis> item. This dialog
+      offers a selection of settings, most of which apply to all virtual
+      machines of the current user. The
+      <emphasis role="bold">Extensions</emphasis> option applies to the
+      entire system.
+    </para>
+
+    <para>
+      The following settings are available:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">General.</emphasis> Enables the user to
+          specify the default folder/directory for VM files, and the
+          VRDP Authentication Library.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Input.</emphasis> Enables the user to
+          specify the Host yey. It identifies the key that toggles
+          whether the cursor is in the focus of the VM or the Host
+          operating system windows, see
+          <xref linkend="keyb_mouse_normal"/>, and which is also used to
+          trigger certain VM actions, see
+          <xref
+         linkend="specialcharacters"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Update.</emphasis> Enables the user to
+          specify various settings for Automatic Updates.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Language.</emphasis> Enables the user to
+          specify the GUI language.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Display.</emphasis> Enables the user to
+          specify the screen resolution, and its width and height.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Network.</emphasis> Enables the user to
+          configure the details of Host Only Networks.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Extensions.</emphasis> Enables the user
+          to list and manage the installed extension packages.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Proxy.</emphasis> Enables the user to
+          configure a HTTP Proxy Server.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
   <sect1 id="frontends">
-    <title>Alternative front-ends</title>
-
-    <para>As briefly mentioned in <xref linkend="features-overview" />,
-    VirtualBox has a very flexible internal design that allows for using
-    multiple interfaces to control the same virtual machines. To illustrate,
-    you can, for example, start a virtual machine with the VirtualBox Manager
-    window and then stop it from the command line. With VirtualBox's support
-    for the Remote Desktop Protocol (RDP), you can even run virtual machines
-    remotely on a headless server and have all the graphical output redirected
-    over the network.</para>
-
-    <para>In detail, the following front-ends are shipped in the standard
-    VirtualBox package:</para>
-
-    <para><orderedlist>
-        <listitem>
-          <para><computeroutput>VirtualBox</computeroutput> is the VirtualBox
-          Manager. This graphical user interface uses the Qt toolkit; most of
-          this User Manual is dedicated to describing it. While this is the
-          easiest to use, some of the more advanced VirtualBox features are
-          kept away from it to keep it simple.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxManage</computeroutput> is our
-          command-line interface for automated and very detailed control of
-          every aspect of VirtualBox. It is described in <xref
-          linkend="vboxmanage" />.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxSDL</computeroutput> is an alternative,
-          simple graphical front-end with an intentionally limited feature
-          set, designed to only display virtual machines that are controlled
-          in detail with <computeroutput>VBoxManage</computeroutput>. This is
-          interesting for business environments where displaying all the bells
-          and whistles of the full GUI is not feasible.
-          <computeroutput>VBoxSDL</computeroutput> is described in <xref
-          linkend="vboxsdl" />.</para>
-        </listitem>
-
-        <listitem>
-          <para>Finally, <computeroutput>VBoxHeadless</computeroutput> is yet
-          another front-end that produces no visible output on the host at
-          all, but can act as a RDP server if the VirtualBox Remote
-          Desktop Extension (VRDE) is installed and enabled for the VM.
-          As opposed to the other
-          graphical interfaces, the headless front-end requires no graphics
-          support. This is useful, for example, if you want to host your
-          virtual machines on a headless Linux server that has no X Window
-          system installed. For details, see <xref
-          linkend="vboxheadless" />.</para>
-        </listitem>
-      </orderedlist>If the above front-ends still do not satisfy your
-    particular needs, it is possible to create yet another front-end to the
-    complex virtualization engine that is the core of VirtualBox, as the
-    VirtualBox core neatly exposes all of its features in a clean API; please
-    refer to <xref linkend="VirtualBoxAPI" />.</para>
+
+    <title>Alternative Front-Ends</title>
+
+    <para>
+      As briefly mentioned in <xref linkend="features-overview" />,
+      VirtualBox has a very flexible internal design that allows for
+      using multiple interfaces to control the same virtual machines.
+      For example, you can start a virtual machine with the VirtualBox
+      Manager window and then stop it from the command line. With
+      VirtualBox's support for the Remote Desktop Protocol (RDP), you
+      can even run virtual machines remotely on a headless server and
+      have all the graphical output redirected over the network.
+    </para>
+
+    <para>
+      The following front-ends are shipped in the standard VirtualBox
+      package:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <computeroutput>VirtualBox</computeroutput> is the VirtualBox
+          Manager. This graphical user interface uses the Qt toolkit,
+          and is described throughout this User Manual. While this is
+          the simplest and easiest front-end to use, some of the more
+          advanced VirtualBox features are not included.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxManage</computeroutput> is a command-line
+          interface for automated and detailed control of every aspect
+          of VirtualBox. See <xref
+          linkend="vboxmanage" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxSDL</computeroutput> is an alternative,
+          simple graphical front-end with an intentionally limited
+          feature set, designed to only display virtual machines that
+          are controlled in detail with
+          <computeroutput>VBoxManage</computeroutput>. This can be used
+          in environments where displaying all the features of the full
+          GUI is not feasible. See <xref
+          linkend="vboxsdl" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxHeadless</computeroutput> is a front-end
+          that produces no visible output on the host at all, but can
+          act as a RDP server if the VirtualBox Remote Desktop Extension
+          (VRDE) is installed and enabled for the VM. As opposed to the
+          other graphical interfaces, the headless front-end requires no
+          graphics support. This is useful, for example, if you want to
+          host your virtual machines on a headless Linux server that has
+          no X Window system installed. See
+          <xref
+          linkend="vboxheadless" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      If the above front-ends still do not satisfy your particular
+      needs, it is possible to create yet another front-end to the
+      complex virtualization engine that is the core of VirtualBox, as
+      the VirtualBox core neatly exposes all of its features in a clean
+      API. See <xref linkend="VirtualBoxAPI" />.
+    </para>
+
   </sect1>
+
 </chapter>
Index: /trunk/doc/manual/en_US/user_KnownIssues.xml
===================================================================
--- /trunk/doc/manual/en_US/user_KnownIssues.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_KnownIssues.xml	(revision 73276)
@@ -1,314 +1,493 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="KnownIssues">
-  <title>Known limitations</title>
-    <sect1 id="ExperimentalFeatures">
-        <title>Experimental Features</title>
-        <para>Some VirtualBox features are labeled as experimental. Such
-            features are provided on an "as-is" basis and are not formally
-            supported. However, feedback and suggestions about such features are
-            welcome. A comprehensive list of experimental features follows:</para>
+
+  <title>Known Limitations</title>
+
+  <sect1 id="ExperimentalFeatures">
+
+    <title>Experimental Features</title>
+
+    <para>
+      Some VirtualBox features are labeled as experimental. Such
+      features are provided on an "as-is" basis and are not formally
+      supported. However, feedback and suggestions about such features
+      are welcome. A comprehensive list of experimental features is as
+      follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Hardware 3D acceleration support for Windows, Linux, and
+          Solaris guests
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Hardware 2D video playback acceleration support for Windows
+          guests
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          PCI pass-through (Linux hosts only)
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Mac OS X guests (Mac OS X hosts only)
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          ICH9 chipset emulation
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          EFI firmware
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Host CD/DVD drive pass-through
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Support of iSCSI via internal networking
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="KnownProblems">
+
+    <title>Known Issues</title>
+
+    <para>
+      The following section describes known problems with this release
+      of VirtualBox. Unless marked otherwise, these issues are planned
+      to be fixed in later releases.
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          The following <emphasis role="bold">Guest SMP (multiprocessor)
+          limitations</emphasis> exist:
+        </para>
+
         <itemizedlist>
-            <listitem>
-                <para>Hardware 3D acceleration support for Windows, Linux, and Solaris
-                guests</para>
-            </listitem>
-            <listitem>
-                <para>Hardware 2D video playback acceleration support for Windows
-                guests</para>
-            </listitem>
-            <listitem>
-                <para>PCI pass-through (Linux hosts only)</para>
-            </listitem>
-            <listitem>
-                <para>Mac OS X guests (Mac hosts only)</para>
-            </listitem>
-            <listitem>
-                <para>ICH9 chipset emulation</para>
-            </listitem>
-            <listitem>
-                <para>EFI firmware</para>
-            </listitem>
-            <listitem>
-                <para>Host CD/DVD drive pass-through</para>
-            </listitem>
-            <listitem>
-                <para>Support of iSCSI via internal networking</para>
-            </listitem>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">Poor performance</emphasis> with
+              32-bit guests on AMD CPUs. This affects mainly Windows and
+              Solaris guests, but possibly also some Linux kernel
+              revisions. Partially solved in 3.0.6 for 32 bits Windows
+              NT, 2000, XP and 2003 guests. Requires 3.0.6 or higher
+              Guest Additions to be installed.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">Poor performance</emphasis> with
+              32-bit guests on certain Intel CPU models that do not
+              include virtual APIC hardware optimization support. This
+              affects mainly Windows and Solaris guests, but possibly
+              also some Linux kernel revisions. Partially solved in
+              3.0.12 for 32 bits Windows NT, 2000, XP, and 2003 guests.
+              Requires 3.0.12 or higher Guest Additions to be installed.
+            </para>
+          </listitem>
+
         </itemizedlist>
-    </sect1>
-    <sect1 id="KnownProblems">
-      <title>Known Issues</title>
-      <para>The following section describes known problems with VirtualBox
-      @VBOX_VERSION_STRING@. Unless marked otherwise, these issues are planned to
-      be fixed in later releases.</para>
-
-      <itemizedlist>
-        <listitem>
-          <para>The following <emphasis role="bold">Guest SMP (multiprocessor)
-          limitations</emphasis> exist:<itemizedlist>
-              <listitem>
-                <para><emphasis role="bold">Poor performance</emphasis> with
-                32-bit guests on AMD CPUs. This affects mainly Windows and Solaris
-                guests, but possibly also some Linux kernel revisions. Partially
-                solved in 3.0.6 for 32 bits Windows NT, 2000, XP and 2003 guests.
-                Requires 3.0.6 or higher Guest Additions to be installed.</para>
-              </listitem>
-
-              <listitem>
-                <para><emphasis role="bold">Poor performance</emphasis> with
-                32-bit guests on certain Intel CPU models that do not include
-                virtual APIC hardware optimization support. This affects mainly
-                Windows and Solaris guests, but possibly also some Linux kernel
-                revisions. Partially solved in 3.0.12 for 32 bits Windows NT,
-                2000, XP and 2003 guests. Requires 3.0.12 or higher Guest
-                Additions to be installed.</para>
-              </listitem>
-            </itemizedlist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">NX (no execute, data execution
-          prevention)</emphasis> only works for guests running on 64-bit hosts
-          or guests running on 32-bit hosts with PAE enabled and requires that
-          hardware virtualization be enabled.</para>
-        </listitem>
-
-        <listitem>
-          <para>For <emphasis role="bold">basic Direct3D support in Windows
-          guests</emphasis> to work, the Guest Additions must be installed in
-          Windows "safe mode". Press F8 when the Windows guest is booting and
-          select "Safe mode", then install the Guest Additions. Otherwise Windows'
-          file protection mechanism will interfere with the replacement DLLs
-          installed by VirtualBox and keep restoring the original Windows system
-          DLLs. <note>
-          <para>This does <emphasis role="bold">not</emphasis> apply to the
-          WDDM Direct3D video driver available for Vista and Windows 7 guests
-          shipped with VirtualBox 4.1.</para>
-          </note></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Guest control.</emphasis> On Windows guests,
-          a process lauched via the guest control execute support will not be able
-          to display a graphical user interface <emphasis>unless</emphasis> the
-          user account under which it is running is currently logged in and has a
-          desktop session.</para>
-
-          <para>Also, to use accounts without or with an empty password, the
-          guest's group policy must be changed. To do so, open the group policy
-          editor on the command line by typing
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">NX (no execute, data execution
+          prevention)</emphasis> only works for guests running on 64-bit
+          hosts or guests running on 32-bit hosts with PAE enabled and
+          requires that hardware virtualization be enabled.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          For <emphasis role="bold">basic Direct3D support in Windows
+          guests</emphasis> to work, the Guest Additions must be
+          installed in Windows "safe mode". Press F8 when the Windows
+          guest is booting and select "Safe mode", then install the
+          Guest Additions. Otherwise the Windows file protection
+          mechanism will interfere with the replacement DLLs installed
+          by VirtualBox and keep restoring the original Windows system
+          DLLs.
+
+          <note>
+            <para>
+              This does <emphasis>not</emphasis> apply to the WDDM
+              Direct3D video driver available for Vista and Windows 7
+              guests shipped with VirtualBox 4.1.
+            </para>
+          </note>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Guest control.</emphasis> On Windows
+          guests, a process lauched via the guest control execute
+          support will not be able to display a graphical user interface
+          <emphasis>unless</emphasis> the user account under which it is
+          running is currently logged in and has a desktop session.
+        </para>
+
+        <para>
+          Also, to use accounts without or with an empty password, the
+          guest's group policy must be changed. To do so, open the group
+          policy editor on the command line by typing
           <computeroutput>gpedit.msc</computeroutput>, open the key
           <emphasis>Computer Configuration\Windows Settings\Security
-          Settings\Local Policies\Security Options</emphasis> and change the value
-          of <emphasis>Accounts: Limit local account use of blank passwords to
-          console logon only</emphasis> to <emphasis>Disabled</emphasis>.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Compacting virtual disk images is limited to
-          VDI files.</emphasis> The <code>VBoxManage modifyhd --compact</code>
-          command is currently only implemented for VDI files. At the moment the
-          only way to optimize the size of a virtual disk images in other formats
-          (VMDK, VHD) is to clone the image and then use the cloned image in the
-          VM configuration.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">OVF import/export:</emphasis><itemizedlist>
-              <listitem>
-                <para>OVF localization (multiple languages in one OVF file) is not
-                yet supported.</para>
-              </listitem>
-
-              <listitem>
-                <para>Some OVF sections like StartupSection,
-                DeploymentOptionSection and InstallSection are ignored.</para>
-              </listitem>
-
-              <listitem>
-                <para>OVF environment documents, including their property sections
-                and appliance configuration with ISO images, are not yet
-                supported.</para>
-              </listitem>
-
-              <listitem>
-                <para>Remote files via HTTP or other mechanisms are not yet
-                supported.</para>
-              </listitem>
-            </itemizedlist></para>
-        </listitem>
-
-        <listitem>
-          <para>Neither <emphasis role="bold">scale mode</emphasis> nor <emphasis
-          role="bold">seamless mode</emphasis> work correctly with guests using
-          OpenGL 3D features (such as with compiz-enabled window managers).</para>
-        </listitem>
-
-        <listitem>
-          <para>The RDP server in the VirtualBox extension pack supports only
-          audio streams in format 22.05kHz stereo 16 bit. If the RDP client
-          requests any other audio format there will be no audio.</para>
-        </listitem>
-
-        <listitem>
-          <para>Preserving the aspect ratio in scale mode works only on Windows
-          hosts and on Mac OS X hosts.</para>
-        </listitem>
-
-        <listitem>
-          <para>On <emphasis role="bold">Mac OS X hosts,</emphasis> the following
-          features are not yet implemented:</para>
-
-          <para><itemizedlist>
-              <listitem>
-                <para>Numlock emulation</para>
-              </listitem>
-
-              <listitem>
-                <para>CPU frequency metric</para>
-              </listitem>
-
-              <listitem>
-                <para>Memory ballooning</para>
-              </listitem>
-            </itemizedlist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Mac OS X guests:</emphasis>
-          <itemizedlist>
-              <listitem>
-                <para>Mac OS X guests can only run on a certain host hardware.
-                For details about license and host hardware limitations, please
-                see <xref linkend="intro-macosxguests" /> and check the Apple
-                software license conditions.</para>
-              </listitem>
-
-              <listitem>
-                <para>VirtualBox does not provide Guest Additions for Mac OS X
-                at this time.</para>
-              </listitem>
-
-              <listitem>
-                <para>The graphics resolution currently defaults to 1024x768 as
-                Mac OS X falls back to the built-in EFI display support. See
-                <xref linkend="efividmode" /> for more information on how to
-                change EFI video modes.</para>
-              </listitem>
-
-              <listitem>
-                <para>Mac OS X guests only work with one CPU assigned to the
-                VM. Support for SMP will be provided in a future release.</para>
-              </listitem>
-
-              <listitem>
-                <para>Depending on your system and version of Mac OS X, you
-                might experience guest hangs after some time. This can be fixed
-                by turning off energy saving (set timeout to "Never") in the
-                system preferences.</para>
-              </listitem>
-
-              <listitem>
-                <para>By default, the VirtualBox EFI enables debug output of the
-                Mac OS X kernel to help you diagnose boot problems. Note that
-                there is a lot of output and not all errors are fatal (they
-                would also show on your physical Mac). You can turn off these
-                messages by issuing this command:<screen>VBoxManage setextradata "VM name" "VBoxInternal2/EfiBootArgs" "  "</screen>To
-                revert to the previous behavior, use:<screen>VBoxManage setextradata "VM name" "VBoxInternal2/EfiBootArgs" ""</screen></para>
-              </listitem>
-
-              <listitem>
-                <para>It is currently not possible to start a Mac OS X guest in safe mode by specifying "-x" option
-                in "VBoxInternal2/EfiBootArgs" extradata.</para>
-              </listitem>
-            </itemizedlist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Solaris hosts:</emphasis> <itemizedlist>
-              <listitem>
-                <para>There is no support for USB devices connected to Solaris 10
-                hosts.</para>
-              </listitem>
-
-              <listitem>
-                <para>USB support on Solaris hosts requires Solaris 11 version
-                snv_124 or higher. Webcams and other isochronous devices are known
-                to have poor performance.</para>
-              </listitem>
-
-              <listitem>
-                <para>Host Webcam passthrough is restricted to 640x480 frames at
-                20 frames per second due to limitations in the Solaris V4L2 API.
-                This may be addressed in a future Solaris release.</para>
-              </listitem>
-
-              <listitem>
-                <para>No ACPI information (battery status, power source) is
-                reported to the guest.</para>
-              </listitem>
-
-              <listitem>
-                <para>No support for using wireless adapters with bridged
-                networking.</para>
-              </listitem>
-
-              <listitem>
-                <para>Crossbow-based bridged networking on Solaris 11 hosts does
-                not work directly with aggregate links. However, you can manually
-                create a VNIC (using <computeroutput>dladm</computeroutput>) over
-                the aggregate link and use that with a VM. This limitation does
-                not exist in Solaris 11u1 build 17 and newer.</para>
-              </listitem>
-            </itemizedlist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Guest Additions of version 4.1, 4.1.2 and 4.1.4 for Windows</emphasis>
-          Thus VirtualBox WDDM Video driver may be installed and kept in guest system
-          if Guest additions uninstallation is performed.
-          This is caused by a bug in Guest Additions uninstaller.
-          <note>
-            <para>This does <emphasis role="bold">not</emphasis> apply to Guest Additions update,
-            i.e. installing a one version of Guest Additions on top of another works correctly.</para>
-          </note>
-          To solve this problem, one should uninstall the VirtualBox WDDM Video driver manually.
-          To do that open Device Manager, and check whether the Display Adapter is named
-          "VirtualBox Graphics Adapter ..". If no - there is nothing to be done. If yes - right-click
-          the VirtualBox Graphics Adapter in Device Manager, select "Uninstall", check "Delete the driver software for this device"
-          and click "OK". Once uninstallation is done - in Device Manager go to menu "Action" and select
-          "Scan for hardware changes" to make the propper (Windows default) driver be picked up for the Graphics adapter.
+          Settings\Local Policies\Security Options</emphasis> and change
+          the value of <emphasis>Accounts: Limit local account use of
+          blank passwords to console logon only</emphasis> to
+          <emphasis>Disabled</emphasis>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Compacting virtual disk images is
+          limited to VDI files.</emphasis> The <code>VBoxManage modifyhd
+          --compact</code> command is currently only implemented for VDI
+          files. At the moment the only way to optimize the size of a
+          virtual disk images in other formats (VMDK, VHD) is to clone
+          the image and then use the cloned image in the VM
+          configuration.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">OVF import/export:</emphasis>
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              OVF localization, with multiple languages in a single OVF
+              file, is not yet supported.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Some OVF sections like StartupSection,
+              DeploymentOptionSection, and InstallSection are ignored.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              OVF environment documents, including their property
+              sections and appliance configuration with ISO images, are
+              not yet supported.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Remote files via HTTP or other mechanisms are not yet
+              supported.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          Neither <emphasis role="bold">scale mode</emphasis> nor
+          <emphasis
+          role="bold">seamless mode</emphasis> work
+          correctly with guests using OpenGL 3D features, such as with
+          compiz-enabled window managers.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The RDP server in the VirtualBox extension pack supports only
+          audio streams in format 22.05kHz stereo 16 bit. If the RDP
+          client requests any other audio format there will be no audio.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Preserving the aspect ratio in scale mode works only on
+          Windows hosts and on Mac OS X hosts.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          On <emphasis role="bold">Mac OS X hosts,</emphasis> the
+          following features are not yet implemented:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              Numlock emulation
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              CPU frequency metric
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Memory ballooning
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Mac OS X guests:</emphasis>
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              Mac OS X guests can only run on a certain host hardware.
+              For details about license and host hardware limitations.
+              See <xref linkend="intro-macosxguests" /> and check the
+              Apple software license conditions.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              VirtualBox does not provide Guest Additions for Mac OS X
+              at this time.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              The graphics resolution currently defaults to 1024x768 as
+              Mac OS X falls back to the built-in EFI display support.
+              See <xref linkend="efividmode" /> for more information on
+              how to change EFI video modes.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Mac OS X guests only work with one CPU assigned to the VM.
+              Support for SMP will be provided in a future release.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Depending on your system and version of Mac OS X, you
+              might experience guest hangs after some time. This can be
+              fixed by turning off energy saving. Set timeout to "Never"
+              in the system preferences.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              By default, the VirtualBox EFI enables debug output of the
+              Mac OS X kernel to help you diagnose boot problems. Note
+              that there is a lot of output and not all errors are
+              fatal. They would also show when using a physical Apple
+              Macintosh computer. You can turn off these messages by
+              issuing this command:
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal2/EfiBootArgs" "  "</screen>
+
+              To revert to the previous behavior, use:
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal2/EfiBootArgs" ""</screen>
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              It is currently not possible to start a Mac OS X guest in
+              safe mode by specifying "-x" option in
+              "VBoxInternal2/EfiBootArgs" extradata.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Solaris hosts:</emphasis>
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              There is no support for USB devices connected to Solaris
+              10 hosts.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              USB support on Solaris hosts requires Solaris 11 version
+              snv_124 or higher. Webcams and other isochronous devices
+              are known to have poor performance.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Host Webcam passthrough is restricted to 640x480 frames at
+              20 frames per second due to limitations in the Solaris
+              V4L2 API. This may be addressed in a future Solaris
+              release.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No ACPI information, such as battery status or power
+              source, is reported to the guest.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              No support for using wireless adapters with bridged
+              networking.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Crossbow-based bridged networking on Solaris 11 hosts does
+              not work directly with aggregate links. However, you can
+              use <computeroutput>dladm</computeroutput> to manually
+              create a VNIC over the aggregate link and use that with a
+              VM. This limitation does not exist in Solaris 11u1 build
+              17 and newer.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Guest Additions of version 4.1, 4.1.2
+          and 4.1.4 for Windows.</emphasis> The VirtualBox WDDM Video
+          driver may be installed and remain in the guest system when
+          Guest additions uninstallation is performed. This is caused by
+          a bug in Guest Additions uninstaller.
+        </para>
+
+        <note>
+          <para>
+            This does <emphasis>not</emphasis> apply to a Guest
+            Additions update. Installing one version of Guest Additions
+            on top of another works correctly.
           </para>
-        </listitem>
-
-        <listitem>
-          <para>Neither <emphasis>virtio</emphasis> nor <emphasis>Intel PRO/1000
-            </emphasis> drivers for <emphasis role="bold">Windows XP guests
-            </emphasis> support segmentation offloading. Therefore
-            Windows XP guests have slower transmission rates comparing to other
-            guest types. Refer to MS Knowledge base article 842264 for additional
-            information.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Guest Additions for OS/2.</emphasis> Shared
-          folders are not yet supported with OS/2 guests. In addition, seamless
-          windows and automatic guest resizing will probably never be implemented
-          due to inherent limitations of the OS/2 graphics system.</para>
-        </listitem>
-
-        <listitem>
-          <para>Some guest operating systems pre-dating ATAPI CD-ROMs may exhibit
-          long delays or entirely fail to boot in certain configurations. This is
-          most likely to happen when an IDE/ATAPI CD-ROM exists alone on a primary
-          or secondary IDE channel.</para>
-          <para>One of the affected operating systems is MS OS/2 1.21 (fails to boot
-          with an error message referencing COUNTRY.SYS) and MS OS/2 1.3 (long delays).
-          To avoid such problems, disable the emulated IDE/ATAPI CD-ROM; the guest OS
-          cannot use it anyway.</para>
-        </listitem>
-      </itemizedlist>
-    </sect1>
+        </note>
+
+        <para>
+          To solve this problem, uninstall the VirtualBox WDDM Video
+          driver manually. Open Device Manager, and check whether the
+          Display Adapter is named "VirtualBox Graphics Adapter ..". If
+          not, there is nothing to be done. If it is, right-click the
+          VirtualBox Graphics Adapter in Device Manager, select
+          <emphasis role="bold">Uninstall</emphasis>, check
+          <emphasis role="bold">Delete the Driver Software for this
+          Device</emphasis> and click
+          <emphasis role="bold">OK</emphasis>. Once uninstallation is
+          done, start Device Manager, go to the Action menu and select
+          <emphasis role="bold">Scan for Hardware Change</emphasis>s to
+          ensure that the correct Windows default driver be picked up
+          for the Graphics adapter.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Neither <emphasis>virtio</emphasis> nor <emphasis>Intel
+          PRO/1000 </emphasis> drivers for <emphasis role="bold">Windows
+          XP guests</emphasis> support segmentation offloading.
+          Therefore Windows XP guests have slower transmission rates
+          comparing to other guest types. Refer to MS Knowledge base
+          article 842264 for additional information.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Guest Additions for OS/2.</emphasis>
+          Shared folders are not yet supported with OS/2 guests. In
+          addition, seamless windows and automatic guest resizing will
+          probably never be implemented due to inherent limitations of
+          the OS/2 graphics system.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Some guest operating systems predating ATAPI CD-ROMs may
+          exhibit long delays or entirely fail to boot in certain
+          configurations. This is most likely to happen when an
+          IDE/ATAPI CD-ROM exists alone on a primary or secondary IDE
+          channel.
+        </para>
+
+        <para>
+          Affected operating systems are MS OS/2 1.21: fails to boot
+          with an error message referencing COUNTRY.SYS and MS OS/2 1.3:
+          long boot delays. To avoid such problems, disable the emulated
+          IDE/ATAPI CD-ROM. The guest OS cannot use this device, anyway.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
 </chapter>
Index: /trunk/doc/manual/en_US/user_Networking.xml
===================================================================
--- /trunk/doc/manual/en_US/user_Networking.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_Networking.xml	(revision 73276)
@@ -1,237 +1,295 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="networkingdetails">
-  <title>Virtual networking</title>
-
-  <para>As briefly mentioned in <xref linkend="settings-network" />,
-  VirtualBox provides up to eight virtual PCI Ethernet cards for each virtual
-  machine. For each such card, you can individually select<orderedlist>
-      <listitem>
-        <para>the hardware that will be virtualized as well as</para>
-      </listitem>
-
-      <listitem>
-        <para>the virtualization mode that the virtual card will be operating
-        in with respect to your physical networking hardware on the
-        host.</para>
-      </listitem>
-    </orderedlist></para>
-
-  <para>Four of the network cards can be configured in the "Network" section
-  of the settings dialog in the graphical user interface of VirtualBox. You
-  can configure all eight network cards on the command line via VBoxManage
-  modifyvm; see <xref linkend="vboxmanage-modifyvm" />.</para>
-
-  <para>This chapter explains the various networking settings in more
-  detail.</para>
+
+  <title>Virtual Networking</title>
+
+  <para>
+    As mentioned in <xref linkend="settings-network" />, VirtualBox
+    provides up to eight virtual PCI Ethernet cards for each virtual
+    machine. For each such card, you can individually select the
+    following:
+  </para>
+
+  <itemizedlist>
+
+    <listitem>
+      <para>
+        The hardware that will be virtualized.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        The virtualization mode that the virtual card operates in, with
+        respect to your physical networking hardware on the host.
+      </para>
+    </listitem>
+
+  </itemizedlist>
+
+  <para>
+    Four of the network cards can be configured in the Network section
+    of the settings dialog in the graphical user interface of
+    VirtualBox. You can configure all eight network cards on the command
+    line using VBoxManage modifyvm. See
+    <xref linkend="vboxmanage-modifyvm" />.
+  </para>
+
+  <para>
+    This chapter explains the various networking settings in more
+    detail.
+  </para>
 
   <sect1 id="nichardware">
-    <title>Virtual networking hardware</title>
-
-    <para>For each card, you can individually select what kind of
-    <emphasis>hardware</emphasis> will be presented to the virtual machine.
-    VirtualBox can virtualize the following six types of networking
-    hardware:<itemizedlist>
-        <listitem>
-          <para>AMD PCNet PCI II (Am79C970A);</para>
-        </listitem>
-
-        <listitem>
-          <para>AMD PCNet FAST III (Am79C973, the default);</para>
-        </listitem>
-
-        <listitem>
-          <para>Intel PRO/1000 MT Desktop (82540EM);</para>
-        </listitem>
-
-        <listitem>
-          <para>Intel PRO/1000 T Server (82543GC);</para>
-        </listitem>
-
-        <listitem>
-          <para>Intel PRO/1000 MT Server (82545EM);</para>
-        </listitem>
-
-        <listitem>
-          <para>Paravirtualized network adapter (virtio-net).</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>The PCNet FAST III is the default because it is supported by nearly
-    all operating systems out of the box, as well as the GNU GRUB boot
-    manager. As an exception, the Intel PRO/1000 family adapters are chosen
-    for some guest operating system types that no longer ship with drivers for
-    the PCNet card, such as Windows Vista.</para>
-
-    <para>The Intel PRO/1000 MT Desktop type works with Windows Vista and
-    later versions. The T Server variant of the Intel PRO/1000 card is
-    recognized by Windows XP guests without additional driver installation.
-    The MT Server variant facilitates OVF imports from other platforms.</para>
-
-    <para>The <emphasis role="bold">"Paravirtualized network adapter
-    (virtio-net)"</emphasis> is special. If you select this, then VirtualBox
-    does <emphasis>not</emphasis> virtualize common networking hardware (that
-    is supported by common guest operating systems out of the box). Instead,
-    VirtualBox then expects a special software interface for virtualized
-    environments to be provided by the guest, thus avoiding the complexity of
-    emulating networking hardware and improving network performance. Starting
-    with version 3.1, VirtualBox provides support for the industry-standard
-    "virtio" networking drivers, which are part of the open-source KVM
-    project.</para>
-
-    <para>The "virtio" networking drivers are available for the following
-    guest operating systems:</para>
-
-    <para><itemizedlist>
-        <listitem>
-          <para>Linux kernels version 2.6.25 or later can be configured to
-          provide virtio support; some distributions also back-ported virtio
-          to older kernels.</para>
-        </listitem>
-
-        <listitem>
-          <para>For Windows 2000, XP and Vista, virtio drivers can be
-          downloaded and installed from the KVM project web page.<footnote>
-              <para><ulink
-              url="http://www.linux-kvm.org/page/WindowsGuestDrivers">http://www.linux-kvm.org/page/WindowsGuestDrivers</ulink>.</para>
-            </footnote></para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>VirtualBox also has limited support for so-called <emphasis
-    role="bold">jumbo frames</emphasis>, i.e. networking packets with more
-    than 1500 bytes of data, provided that you use the Intel card
-    virtualization and bridged networking. In other words, jumbo frames are
-    not supported with the AMD networking devices; in those cases, jumbo
-    packets will silently be dropped for both the transmit and the receive
-    direction. Guest operating systems trying to use this feature will observe
-    this as a packet loss, which may lead to unexpected application behavior
-    in the guest. This does not cause problems with guest operating systems in
-    their default configuration, as jumbo frames need to be explicitly
-    enabled.</para>
+
+    <title>Virtual Networking Hardware</title>
+
+    <para>
+      For each card, you can individually select what kind of
+      <emphasis>hardware</emphasis> will be presented to the virtual
+      machine. VirtualBox can virtualize the following types of
+      networking hardware:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          AMD PCNet PCI II (Am79C970A)
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          AMD PCNet FAST III (Am79C973), the default setting
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Intel PRO/1000 MT Desktop (82540EM)
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Intel PRO/1000 T Server (82543GC)
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Intel PRO/1000 MT Server (82545EM)
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Paravirtualized network adapter (virtio-net)
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      The PCNet FAST III is the default because it is supported by
+      nearly all operating systems, as well as by the GNU GRUB boot
+      manager. As an exception, the Intel PRO/1000 family adapters are
+      chosen for some guest operating system types that no longer ship
+      with drivers for the PCNet card, such as Windows Vista.
+    </para>
+
+    <para>
+      The Intel PRO/1000 MT Desktop type works with Windows Vista and
+      later versions. The T Server variant of the Intel PRO/1000 card is
+      recognized by Windows XP guests without additional driver
+      installation. The MT Server variant facilitates OVF imports from
+      other platforms.
+    </para>
+
+    <para>
+      The Paravirtualized network adapter (virtio-net) is special. If
+      you select this adapter, then VirtualBox does
+      <emphasis>not</emphasis> virtualize common networking hardware
+      that is supported by common guest operating systems. Instead,
+      VirtualBox expects a special software interface for virtualized
+      environments to be provided by the guest, thus avoiding the
+      complexity of emulating networking hardware and improving network
+      performance. Starting with version 3.1, VirtualBox provides
+      support for the industry-standard <emphasis>virtio</emphasis>
+      networking drivers, which are part of the open source KVM project.
+    </para>
+
+    <para>
+      The virtio networking drivers are available for the following
+      guest operating systems:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Linux kernels version 2.6.25 or later can be configured to
+          provide virtio support. Some distributions have also
+          back-ported virtio to older kernels.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          For Windows 2000, XP, and Vista, virtio drivers can be
+          downloaded and installed from the KVM project web page:
+        </para>
+
+        <para>
+          <ulink
+              url="http://www.linux-kvm.org/page/WindowsGuestDrivers"/>.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      VirtualBox also has limited support for <emphasis>jumbo
+      frames</emphasis>. These are networking packets with more than
+      1500 bytes of data, provided that you use the Intel card
+      virtualization and bridged networking. Jumbo frames are not
+      supported with the AMD networking devices. In those cases, jumbo
+      packets will silently be dropped for both the transmit and the
+      receive direction. Guest operating systems trying to use this
+      feature will observe this as a packet loss, which may lead to
+      unexpected application behavior in the guest. This does not cause
+      problems with guest operating systems in their default
+      configuration, as jumbo frames need to be explicitly enabled.
+    </para>
+
   </sect1>
 
   <sect1 id="networkingmodes">
-    <title>Introduction to networking modes</title>
-
-    <para>Each of the eight networking adapters can be separately configured
-    to operate in one of the following modes:<glosslist>
-        <glossentry>
-          <glossterm>Not attached</glossterm>
-
-          <glossdef>
-            <para>In this mode, VirtualBox reports to the guest that a network
-            card is present, but that there is no connection -- as if no
-            Ethernet cable was plugged into the card. This way it is possible
-            to "pull" the virtual Ethernet cable and disrupt the connection,
-            which can be useful to inform a guest operating system that no
-            network connection is available and enforce a
-            reconfiguration.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Network Address Translation (NAT)</glossterm>
-
-          <glossdef>
-            <para>If all you want is to browse the Web, download files and
-            view e-mail inside the guest, then this default mode should be
-            sufficient for you, and you can safely skip the rest of this
-            section. Please note that there are certain limitations when using
-            Windows file sharing (see <xref linkend="nat-limitations" /> for
-            details).</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>NAT Network</glossterm>
-
-          <glossdef>
-            <para>The NAT network is a new NAT flavour introduced in
-              VirtualBox 4.3. See
-              <xref linkend="network_nat_service" xrefstyle="template: %n" />
-              for details.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Bridged networking</glossterm>
-
-          <glossdef>
-            <para>This is for more advanced networking needs such as network
-            simulations and running servers in a guest. When enabled,
-            VirtualBox connects to one of your installed network cards and
-            exchanges network packets directly, circumventing your host
-            operating system's network stack.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Internal networking</glossterm>
-
-          <glossdef>
-            <para>This can be used to create a different kind of
-            software-based network which is visible to selected virtual
-            machines, but not to applications running on the host or to the
-            outside world.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Host-only networking</glossterm>
-
-          <glossdef>
-            <para>This can be used to create a network containing the host and
-            a set of virtual machines, without the need for the host's
-            physical network interface. Instead, a virtual network interface
-            (similar to a loopback interface) is created on the host,
-            providing connectivity among virtual machines and the host.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Generic networking</glossterm>
-
-          <glossdef>
-            <para>Rarely used modes share the same generic network interface,
-            by allowing the user to select a driver which can be included with
-            VirtualBox or be distributed in an extension pack.</para>
-
-            <para>At the moment there are potentially two available
-            sub-modes:</para>
-
-            <para><glosslist>
-                <glossentry>
-                  <glossterm>UDP Tunnel</glossterm>
-
-                  <glossdef>
-                    <para>This can be used to interconnect virtual machines
-                    running on different hosts directly, easily and
-                    transparently, over existing network
-                    infrastructure.</para>
-                  </glossdef>
-                </glossentry>
-
-                <glossentry>
-                  <glossterm>VDE (Virtual Distributed Ethernet)
-                  networking</glossterm>
-
-                  <glossdef>
-                    <para>This option can be used to connect to a Virtual
-                    Distributed Ethernet switch on a Linux or a FreeBSD host.
-                    At the moment this needs compiling VirtualBox from
-                    sources, as the Oracle packages do not include it.</para>
-                  </glossdef>
-                </glossentry>
-              </glosslist></para>
-          </glossdef>
-        </glossentry>
-      </glosslist></para>
-
-    <para>The following table provides a quick overview of the most important
-    networking modes:</para>
-    <table>
-      <title>Overview</title>
+
+    <title>Introduction to Networking Modes</title>
+
+    <para>
+      Each of the networking adapters can be separately configured to
+      operate in one of the following modes:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Not attached.</emphasis> In this mode,
+          VirtualBox reports to the guest that a network card is
+          present, but that there is no connection. This is as if no
+          Ethernet cable was plugged into the card. Using this mode, it
+          is possible to "pull" the virtual Ethernet cable and disrupt
+          the connection, which can be useful to inform a guest
+          operating system that no network connection is available and
+          enforce a reconfiguration.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Network Address Translation
+          (NAT)</emphasis>. If all you want is to browse the Web,
+          download files, and view email inside the guest, then this
+          default mode should be sufficient for you, and you can skip
+          the rest of this section. Please note that there are certain
+          limitations when using Windows file sharing. See
+          <xref linkend="nat-limitations" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">NAT Network.</emphasis> The NAT network
+          is a new NAT flavour introduced in VirtualBox 4.3. See
+          <xref linkend="network_nat_service"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Bridged networking.</emphasis> This is
+          for more advanced networking needs, such as network
+          simulations and running servers in a guest. When enabled,
+          VirtualBox connects to one of your installed network cards and
+          exchanges network packets directly, circumventing your host
+          operating system's network stack.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Internal networking.</emphasis> This can
+          be used to create a different kind of software-based network
+          which is visible to selected virtual machines, but not to
+          applications running on the host or to the outside world.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Host-only networking.</emphasis> This
+          can be used to create a network containing the host and a set
+          of virtual machines, without the need for the host's physical
+          network interface. Instead, a virtual network interface,
+          similar to a loopback interface, is created on the host,
+          providing connectivity among virtual machines and the host.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"> Generic networking.</emphasis> Rarely
+          used modes which share the same generic network interface, by
+          allowing the user to select a driver which can be included
+          with VirtualBox or be distributed in an extension pack.
+        </para>
+
+        <para>
+          The following sub-modes are available:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">UDP Tunnel:</emphasis> Used to
+              interconnect virtual machines running on different hosts
+              directly, easily, and transparently, over an existing
+              network infrastructure.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <emphasis role="bold">VDE (Virtual Distributed Ethernet)
+              networking:</emphasis> Used to connect to a Virtual
+              Distributed Ethernet switch on a Linux or a FreeBSD host.
+              At the moment this option requires compilation of
+              VirtualBox from sources, as the Oracle packages do not
+              include it.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      <xref linkend="table-networking-modes"/> provides a quick overview
+      of the most important networking modes.
+    </para>
+
+    <table id="table-networking-modes">
+      <title>Overview of Networking Modes</title>
       <tgroup cols="5">
         <colspec align="left" />
@@ -289,752 +347,1192 @@
     </table>
 
-    <para>The following sections describe the available network modes in more
-    detail.</para>
+    <para>
+      The following sections describe the available network modes in
+      more detail.
+    </para>
+
   </sect1>
 
   <sect1 id="network_nat">
+
     <title>Network Address Translation (NAT)</title>
 
-    <para>Network Address Translation (NAT) is the simplest way of accessing
-    an external network from a virtual machine. Usually, it does not require
-    any configuration on the host network and guest system. For this reason,
-    it is the default networking mode in VirtualBox.</para>
-
-    <para>A virtual machine with NAT enabled acts much like a real computer
-    that connects to the Internet through a router. The "router", in this
-    case, is the VirtualBox networking engine, which maps traffic from and to
-    the virtual machine transparently. In VirtualBox this router is placed
-    between each virtual machine and the host. This separation maximizes
-    security since by default virtual machines cannot talk to each
-    other.</para>
-
-    <para>The disadvantage of NAT mode is that, much like a private network
-    behind a router, the virtual machine is invisible and unreachable from the
-    outside internet; you cannot run a server this way unless you set up port
-    forwarding (described below).</para>
-
-    <para>The network frames sent out by the guest operating system are
-    received by VirtualBox's NAT engine, which extracts the TCP/IP data and
-    resends it using the host operating system. To an application on the host,
-    or to another computer on the same network as the host, it looks like the
-    data was sent by the VirtualBox application on the host, using an IP
-    address belonging to the host. VirtualBox listens for replies to the
-    packages sent, and repacks and resends them to the guest machine on its
-    private network.</para>
-
-    <para>The virtual machine receives its network address and configuration
-    on the private network from a DHCP server integrated into VirtualBox. The
-    IP address thus assigned to the virtual machine is usually on a completely
-    different network than the host. As more than one card of a virtual
-    machine can be set up to use NAT, the first card is connected to the
-    private network 10.0.2.0, the second card to the network 10.0.3.0 and so
-    on. If you need to change the guest-assigned IP range for some reason,
-    please refer to <xref linkend="changenat" />.</para>
+    <para>
+      Network Address Translation (NAT) is the simplest way of accessing
+      an external network from a virtual machine. Usually, it does not
+      require any configuration on the host network and guest system.
+      For this reason, it is the default networking mode in VirtualBox.
+    </para>
+
+    <para>
+      A virtual machine with NAT enabled acts much like a real computer
+      that connects to the Internet through a router. The router, in
+      this case, is the VirtualBox networking engine, which maps traffic
+      from and to the virtual machine transparently. In VirtualBox this
+      router is placed between each virtual machine and the host. This
+      separation maximizes security since by default virtual machines
+      cannot talk to each other.
+    </para>
+
+    <para>
+      The disadvantage of NAT mode is that, much like a private network
+      behind a router, the virtual machine is invisible and unreachable
+      from the outside internet. You cannot run a server this way unless
+      you set up port forwarding. See <xref linkend="natforward"/>.
+    </para>
+
+    <para>
+      The network frames sent out by the guest operating system are
+      received by VirtualBox's NAT engine, which extracts the TCP/IP
+      data and resends it using the host operating system. To an
+      application on the host, or to another computer on the same
+      network as the host, it looks like the data was sent by the
+      VirtualBox application on the host, using an IP address belonging
+      to the host. VirtualBox listens for replies to the packages sent,
+      and repacks and resends them to the guest machine on its private
+      network.
+    </para>
+
+    <para>
+      The virtual machine receives its network address and configuration
+      on the private network from a DHCP server integrated into
+      VirtualBox. The IP address thus assigned to the virtual machine is
+      usually on a completely different network than the host. As more
+      than one card of a virtual machine can be set up to use NAT, the
+      first card is connected to the private network 10.0.2.0, the
+      second card to the network 10.0.3.0 and so on. If you need to
+      change the guest-assigned IP range, see
+      <xref linkend="changenat" />.
+    </para>
 
     <sect2 id="natforward">
-      <title>Configuring port forwarding with NAT</title>
-
-      <para>As the virtual machine is connected to a private network internal
-      to VirtualBox and invisible to the host, network services on the guest
-      are not accessible to the host machine or to other computers on the same
-      network. However, like a physical router, VirtualBox can make selected
-      services available to the world outside the guest through <emphasis
-      role="bold">port forwarding.</emphasis> This means that VirtualBox
-      listens to certain ports on the host and resends all packets which
-      arrive there to the guest, on the same or a different port.</para>
-
-      <para>To an application on the host or other physical (or virtual)
-      machines on the network, it looks as though the service being proxied is
-      actually running on the host. This also means that you cannot run the
-      same service on the same ports on the host. However, you still gain the
-      advantages of running the service in a virtual machine -- for example,
-      services on the host machine or on other virtual machines cannot be
-      compromised or crashed by a vulnerability or a bug in the service, and
-      the service can run in a different operating system than the host
-      system.</para>
-
-      <para>To configure Port Forwarding you can use the graphical Port
-      Forwarding editor which can be found in the Network Settings dialog
-      for Network Adaptors configured to use NAT. Here you can map host
-      ports to guest ports to allow network traffic to be routed to a
-      specific port in the guest.</para>
-
-      <para>Alternatively command line tool <computeroutput>VBoxManage</computeroutput> could be used;
-      for details, please refer to <xref linkend="vboxmanage-modifyvm" />.</para>
-
-      <para>You will need to know which ports on the guest the service uses
-      and to decide which ports to use on the host (often but not always you
-      will want to use the same ports on the guest and on the host). You can
-      use any ports on the host which are not already in use by a service. For
-      example, to set up incoming NAT connections to an
-      <computeroutput>ssh</computeroutput> server in the guest, use the
-      following command: <screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,,2222,,22"</screen>With
-      the above example, all TCP traffic arriving on port 2222 on any host
-      interface will be forwarded to port 22 in the guest. The protocol name
-      <computeroutput>tcp</computeroutput> is a mandatory attribute defining
-      which protocol should be used for forwarding
-      (<computeroutput>udp</computeroutput> could also be used). The name
-      <computeroutput>guestssh</computeroutput> is purely descriptive and will
-      be auto-generated if omitted. The number after
-      <computeroutput>--natpf</computeroutput> denotes the network card, like
-      in other parts of VBoxManage.</para>
-
-      <para>To remove this forwarding rule again, use the following command:
-      <screen>VBoxManage modifyvm "VM name" --natpf1 delete "guestssh"</screen></para>
-
-      <para>If for some reason the guest uses a static assigned IP address not
-      leased from the built-in DHCP server, it is required to specify the
-      guest IP when registering the forwarding rule: <screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,,2222,10.0.2.19,22"</screen>This
-      example is identical to the previous one, except that the NAT engine is
-      being told that the guest can be found at the 10.0.2.19 address.</para>
-
-      <para>To forward <emphasis>all</emphasis> incoming traffic from a
-      specific host interface to the guest, specify the IP of that host
-      interface like this:<screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,127.0.0.1,2222,,22"</screen>This
-      forwards all TCP traffic arriving on the localhost interface (127.0.0.1)
-      via port 2222 to port 22 in the guest.</para>
-
-      <para>It is possible to configure incoming NAT connections while the
-      VM is running, see <xref linkend="vboxmanage-controlvm"/>.</para>
+
+      <title>Configuring Port Forwarding with NAT</title>
+
+      <para>
+        As the virtual machine is connected to a private network
+        internal to VirtualBox and invisible to the host, network
+        services on the guest are not accessible to the host machine or
+        to other computers on the same network. However, like a physical
+        router, VirtualBox can make selected services available to the
+        world outside the guest through <emphasis>port
+        forwarding</emphasis>. This means that VirtualBox listens to
+        certain ports on the host and resends all packets which arrive
+        there to the guest, on the same or a different port.
+      </para>
+
+      <para>
+        To an application on the host or other physical (or virtual)
+        machines on the network, it looks as though the service being
+        proxied is actually running on the host. This also means that
+        you cannot run the same service on the same ports on the host.
+        However, you still gain the advantages of running the service in
+        a virtual machine. For example, services on the host machine or
+        on other virtual machines cannot be compromised or crashed by a
+        vulnerability or a bug in the service, and the service can run
+        in a different operating system than the host system.
+      </para>
+
+      <para>
+        To configure port forwarding you can use the graphical Port
+        Forwarding editor which can be found in the Network Settings
+        dialog for network adaptors configured to use NAT. Here, you can
+        map host ports to guest ports to allow network traffic to be
+        routed to a specific port in the guest.
+      </para>
+
+      <para>
+        Alternatively, the command line tool
+        <computeroutput>VBoxManage</computeroutput> can be used. See
+        <xref linkend="vboxmanage-modifyvm" />.
+      </para>
+
+      <para>
+        You will need to know which ports on the guest the service uses
+        and to decide which ports to use on the host. You may want to
+        use the same ports on the guest and on the host. You can use any
+        ports on the host which are not already in use by a service. For
+        example, to set up incoming NAT connections to an
+        <computeroutput>ssh</computeroutput> server in the guest, use
+        the following command:
+
+<screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,,2222,,22"</screen>
+
+        With the above example, all TCP traffic arriving on port 2222 on
+        any host interface will be forwarded to port 22 in the guest.
+        The protocol name <computeroutput>tcp</computeroutput> is a
+        mandatory attribute defining which protocol should be used for
+        forwarding, <computeroutput>udp</computeroutput> could also be
+        used. The name <computeroutput>guestssh</computeroutput> is
+        purely descriptive and will be auto-generated if omitted. The
+        number after <computeroutput>--natpf</computeroutput> denotes
+        the network card, as with other VBoxManage command.
+      </para>
+
+      <para>
+        To remove this forwarding rule, use the following command:
+
+<screen>VBoxManage modifyvm "VM name" --natpf1 delete "guestssh"</screen>
+      </para>
+
+      <para>
+        If for some reason the guest uses a static assigned IP address
+        not leased from the built-in DHCP server, it is required to
+        specify the guest IP when registering the forwarding rule:
+
+<screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,,2222,10.0.2.19,22"</screen>
+
+        This example is identical to the previous one, except that the
+        NAT engine is being told that the guest can be found at the
+        10.0.2.19 address.
+      </para>
+
+      <para>
+        To forward <emphasis>all</emphasis> incoming traffic from a
+        specific host interface to the guest, specify the IP of that
+        host interface like this:
+
+<screen>VBoxManage modifyvm "VM name" --natpf1 "guestssh,tcp,127.0.0.1,2222,,22"</screen>
+
+        This forwards all TCP traffic arriving on the localhost
+        interface (127.0.0.1) via port 2222 to port 22 in the guest.
+      </para>
+
+      <para>
+        It is possible to configure incoming NAT connections while the
+        VM is running, see <xref linkend="vboxmanage-controlvm"/>.
+      </para>
+
     </sect2>
 
     <sect2 id="nat-tftp">
-      <title>PXE booting with NAT</title>
-
-      <para>PXE booting is now supported in NAT mode. The NAT DHCP server
-      provides a boot file name of the form
-      <computeroutput>vmname.pxe</computeroutput> if the directory
-      <computeroutput>TFTP</computeroutput> exists in the directory where the
-      user's <computeroutput>VirtualBox.xml</computeroutput> file is kept. It
-      is the responsibility of the user to provide
-      <computeroutput>vmname.pxe</computeroutput>.</para>
+
+      <title>PXE Booting with NAT</title>
+
+      <para>
+        PXE booting is now supported in NAT mode. The NAT DHCP server
+        provides a boot file name of the form
+        <computeroutput>vmname.pxe</computeroutput> if the directory
+        <computeroutput>TFTP</computeroutput> exists in the directory
+        where the user's <computeroutput>VirtualBox.xml</computeroutput>
+        file is kept. It is the responsibility of the user to provide
+        <computeroutput>vmname.pxe</computeroutput>.
+      </para>
+
     </sect2>
 
     <sect2 id="nat-limitations">
-      <title>NAT limitations</title>
-
-      <para>There are four <emphasis role="bold">limitations</emphasis> of NAT
-      mode which users should be aware of:</para>
-
-      <glosslist>
-        <glossentry>
-          <glossterm>ICMP protocol limitations:</glossterm>
-
-          <glossdef>
-            <para>Some frequently used network debugging tools (e.g.
-            <computeroutput>ping</computeroutput> or tracerouting) rely on the
-            ICMP protocol for sending/receiving messages. While ICMP support
-            has been improved with VirtualBox 2.1
-            (<computeroutput>ping</computeroutput> should now work), some
-            other tools may not work reliably.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Receiving of UDP broadcasts is not reliable:</glossterm>
-
-          <glossdef>
-            <para>The guest does not reliably receive broadcasts, since, in
-            order to save resources, it only listens for a certain amount of
-            time after the guest has sent UDP data on a particular port. As a
-            consequence, NetBios name resolution based on broadcasts does not
-            always work (but WINS always works). As a workaround, you can use
-            the numeric IP of the desired server in the
-            <computeroutput>\\server\share</computeroutput> notation.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Protocols such as GRE are unsupported:</glossterm>
-
-          <glossdef>
-            <para>Protocols other than TCP and UDP are not supported. This
-            means some VPN products (e.g. PPTP from Microsoft) cannot be used.
-            There are other VPN products which use simply TCP and UDP.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Forwarding host ports &lt; 1024 impossible:</glossterm>
-
-          <glossdef>
-            <para>On Unix-based hosts (e.g. Linux, Solaris, Mac OS X) it is
-            not possible to bind to ports below 1024 from applications that
-            are not run by <computeroutput>root</computeroutput>. As a result,
-            if you try to configure such a port forwarding, the VM will refuse
-            to start.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-
-      <para>These limitations normally don't affect standard network use. But
-      the presence of NAT has also subtle effects that may interfere with
-      protocols that are normally working. One example is NFS, where the
-      server is often configured to refuse connections from non-privileged
-      ports (i.e. ports not below 1024).</para>
+
+      <title>NAT Limitations</title>
+
+      <para>
+        There are some limitations of NAT mode which users should be
+        aware of, as follows:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">ICMP protocol limitations.</emphasis>
+            Some frequently used network debugging tools, such as
+            <computeroutput>ping</computeroutput> or tracerouting, rely
+            on the ICMP protocol for sending and receiving messages.
+            While ICMP support has been improved with VirtualBox 2.1,
+            meaning <computeroutput>ping</computeroutput> should now
+            work, some other tools may not work reliably.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Receiving of UDP
+            broadcasts.</emphasis> The guest does not reliably receive
+            UDP broadcasts. In order to save resources, it only listens
+            for a certain amount of time after the guest has sent UDP
+            data on a particular port. As a consequence, NetBios name
+            resolution based on broadcasts does not always work, but
+            WINS always works. As a workaround, you can use the numeric
+            IP of the desired server in the
+            <computeroutput>\\server\share</computeroutput> notation.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Some protocols are not
+            supported.</emphasis> Protocols other than TCP and UDP are
+            not supported. GRE is not supported. This means some VPN
+            products, such as PPTP from Microsoft, cannot be used. There
+            are other VPN products which use only TCP and UDP.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <emphasis role="bold">Forwarding host ports below
+            1024.</emphasis> On Unix-based hosts, such as Linux,
+            Solaris, and Mac OS X, it is not possible to bind to ports
+            below 1024 from applications that are not run by
+            <computeroutput>root</computeroutput>. As a result, if you
+            try to configure such a port forwarding, the VM will refuse
+            to start.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        These limitations normally do not affect standard network use.
+        But the presence of NAT has also subtle effects that may
+        interfere with protocols that are normally working. One example
+        is NFS, where the server is often configured to refuse
+        connections from non-privileged ports, which are those ports not
+        below 1024.
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="network_nat_service">
+
     <title>Network Address Translation Service</title>
 
-    <para>The Network Address Translation (NAT) service works in a similar way
-    to a home router, grouping the systems using it into a network and
-    preventing systems outside of this network from directly accessing systems
-    inside it, but letting systems inside communicate with each other and with
-    systems outside using TCP and UDP over IPv4 and IPv6.</para>
-
-    <para>A NAT service is attached to an internal network. Virtual machines
-    which are to make use of it should be attached to that internal network.
-    The name of internal network is chosen when the NAT service is created and
-    the internal network will be created if it does not already exist.  An
-    example command to create a NAT network is:
-    </para>
-    <para><screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen></para>
-    <para>
-    Here, "natnet1" is the name of the internal network to be used and
-    "192.168.15.0/24" is the network address and mask of the NAT service
-    interface.  By default in this static configuration the gateway will be
-    assigned the address 192.168.15.1 (the address following the interface
-    address), though this is subject to change.  To attach a DHCP server to the
-    internal network, we modify the example as follows:</para>
-    <para><screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable --dhcp on</screen></para>
-    <para> or to add a DHCP server to the network after creation:</para>
-    <para><screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen></para>
-    <para>To disable it again, use:</para>
-    <para><screen>VBoxManage natnetwork modify --netname natnet1 --dhcp off</screen></para>
-    <para>DHCP server provides list of registered nameservers, but doesn't map
-    servers from 127/8 network.</para>
-    <para>To start the NAT service, use the following command:</para>
-    <para><screen>VBoxManage natnetwork start --netname natnet1</screen></para>
-    <para>If the network has a DHCP server attached then it will start together
-    with the NAT network service.</para>
-    <para><screen>VBoxManage natnetwork stop --netname natnet1</screen> stops
-    the NAT network service, together with DHCP server if any.</para>
-    <para>To delete the NAT network service use:</para>
-    <para><screen>VBoxManage natnetwork remove --netname natnet1</screen></para>
-    <para>This command does not remove the DHCP server if one is enabled on the
-    internal network.</para>
-    <para>Port-forwarding is supported (using the
-    <computeroutput>--port-forward-4</computeroutput> switch for IPv4 and
-    <computeroutput>--port-forward-6</computeroutput>
-    for IPv6):</para>
-    <para><screen>VBoxManage natnetwork modify --netname natnet1 --port-forward-4 "ssh:tcp:[]:1022:[192.168.15.5]:22"</screen></para>
-    <para>This adds a port-forwarding rule from the host's TCP 1022 port to
-    the port 22 on the guest with IP address 192.168.15.5. Host port, guest port and guest IP
-    are mandatory. To delete the rule, use:</para>
-    <para><screen>VBoxManage natnetwork modify --netname natnet1 --port-forward-4 delete ssh</screen></para>
-    <para>It's possible to bind NAT service to specified interface:</para>
-    <screen>VBoxManage setextradata global "NAT/win-nat-test-0/SourceIp4" 192.168.1.185</screen>
-    <para>To see the list of registered NAT networks, use:</para>
-    <para><screen>VBoxManage list natnetworks</screen></para>
+    <para>
+      The Network Address Translation (NAT) service works in a similar
+      way to a home router, grouping the systems using it into a network
+      and preventing systems outside of this network from directly
+      accessing systems inside it, but letting systems inside
+      communicate with each other and with systems outside using TCP and
+      UDP over IPv4 and IPv6.
+    </para>
+
+    <para>
+      A NAT service is attached to an internal network. Virtual machines
+      which are to make use of it should be attached to that internal
+      network. The name of internal network is chosen when the NAT
+      service is created and the internal network will be created if it
+      does not already exist. An example command to create a NAT network
+      is:
+    </para>
+
+    <para>
+<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen>
+    </para>
+
+    <para>
+      Here, natnet1 is the name of the internal network to be used and
+      192.168.15.0/24 is the network address and mask of the NAT service
+      interface. By default in this static configuration the gateway
+      will be assigned the address 192.168.15.1, the address following
+      the interface address, though this is subject to change. To attach
+      a DHCP server to the internal network, we modify the example as
+      follows:
+    </para>
+
+    <para>
+<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable --dhcp on</screen>
+    </para>
+
+    <para>
+      To add a DHCP server to an existing network:
+    </para>
+
+    <para>
+<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen>
+    </para>
+
+    <para>
+      To disable the DHCP server:
+    </para>
+
+    <para>
+<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp off</screen>
+    </para>
+
+    <para>
+      A DHCP server provides a list of registered nameservers, but does
+      not map servers from the 127/8 network.
+    </para>
+
+    <para>
+      To start the NAT service, use the following command:
+    </para>
+
+    <para>
+<screen>VBoxManage natnetwork start --netname natnet1</screen>
+    </para>
+
+    <para>
+      If the network has a DHCP server attached then it will start
+      together with the NAT network service.
+    </para>
+
+    <para>
+      To stops the NAT network service, together with any DHCP server:
+    </para>
+
+    <para>
+<screen>VBoxManage natnetwork stop --netname natnet1</screen>
+    </para>
+
+    <para>
+      To delete the NAT network service:
+    </para>
+
+    <para>
+<screen>VBoxManage natnetwork remove --netname natnet1</screen>
+    </para>
+
+    <para>
+      This command does not remove the DHCP server if one is enabled on
+      the internal network.
+    </para>
+
+    <para>
+      Port-forwarding is supported, using the
+      <computeroutput>--port-forward-4</computeroutput> switch for IPv4
+      and <computeroutput>--port-forward-6</computeroutput> for IPv6.
+      For example:
+    </para>
+
+    <para>
+<screen>VBoxManage natnetwork modify \
+  --netname natnet1 --port-forward-4 "ssh:tcp:[]:1022:[192.168.15.5]:22"</screen>
+    </para>
+
+    <para>
+      This adds a port-forwarding rule from the host's TCP 1022 port to
+      the port 22 on the guest with IP address 192.168.15.5. Host port,
+      guest port and guest IP are mandatory. To delete the rule, use:
+    </para>
+
+    <para>
+<screen>VBoxManage natnetwork modify --netname natnet1 --port-forward-4 delete ssh</screen>
+    </para>
+
+    <para>
+      It is possible to bind a NAT service to specified interface. For
+      example:
+    </para>
+
+<screen>VBoxManage setextradata global "NAT/win-nat-test-0/SourceIp4" 192.168.1.185</screen>
+
+    <para>
+      To see the list of registered NAT networks, use:
+    </para>
+
+    <para>
+<screen>VBoxManage list natnetworks</screen>
+    </para>
+
   </sect1>
 
   <sect1 id="network_bridged">
-    <title>Bridged networking</title>
-
-    <para>With bridged networking, VirtualBox uses a device driver on your
-    <emphasis>host</emphasis> system that filters data from your physical
-    network adapter. This driver is therefore called a "net filter" driver.
-    This allows VirtualBox to intercept data from the physical network and
-    inject data into it, effectively creating a new network interface in
-    software. When a guest is using such a new software interface, it looks to
-    the host system as though the guest were physically connected to the
-    interface using a network cable: the host can send data to the guest
-    through that interface and receive data from it. This means that you can
-    set up routing or bridging between the guest and the rest of your
-    network.</para>
-
-    <para>For this to work, VirtualBox needs a device driver on your host
-    system. The way bridged networking works has been completely rewritten
-    with VirtualBox 2.0 and 2.1, depending on the host operating system. From
-    the user perspective, the main difference is that complex configuration is
-    no longer necessary on any of the supported host operating
-    systems.<footnote>
-        <para>For Mac OS X and Solaris hosts, net filter drivers were already
-        added in VirtualBox 2.0 (as initial support for Host Interface
-        Networking on these platforms). With VirtualBox 2.1, net filter
-        drivers were also added for the Windows and Linux hosts, replacing the
-        mechanisms previously present in VirtualBox for those platforms;
-        especially on Linux, the earlier method required creating TAP
-        interfaces and bridges, which was complex and varied from one
-        distribution to the next. None of this is necessary anymore. Bridged
-        network was formerly called "Host Interface Networking" and has been
-        renamed with version 2.2 without any change in functionality.</para>
-      </footnote></para>
-
-    <para><note>
-        <para>Even though TAP is no longer necessary on Linux with bridged
-        networking, you <emphasis>can</emphasis> still use TAP interfaces for
-        certain advanced setups, since you can connect a VM to any host
-        interface -- which could also be a TAP interface.</para>
-      </note>To enable bridged networking, all you need to do is to open the
-    Settings dialog of a virtual machine, go to the "Network" page and select
-    "Bridged network" in the drop down list for the "Attached to" field.
-    Finally, select desired host interface from the list at the bottom of the
-    page, which contains the physical network interfaces of your systems. On a
-    typical MacBook, for example, this will allow you to select between "en1:
-    AirPort" (which is the wireless interface) and "en0: Ethernet", which
-    represents the interface with a network cable.</para>
-
-    <note><para>Bridging to a wireless interface is done differently from
-        bridging to a wired interface, because most wireless adapters do not
-        support promiscuous mode. All traffic has to use the MAC address of the
-        host's wireless adapter, and therefore VirtualBox needs to replace the
-        source MAC address in the Ethernet header of an outgoing packet to make
-        sure the reply will be sent to the host interface. When VirtualBox sees
-        an incoming packet with a destination IP address that belongs to one of
-        the virtual machine adapters it replaces the destination MAC address in
-        the Ethernet header with the VM adapter's MAC address and passes it on.
-        VirtualBox examines ARP and DHCP packets in order to learn the IP
-        addresses of virtual machines.</para></note>
-
-    <para>Depending on your host operating system, the following limitations
-    should be kept in mind:<itemizedlist>
-        <listitem>
-          <para>On <emphasis role="bold">Macintosh</emphasis> hosts,
-          functionality is limited when using AirPort (the Mac's wireless
-          networking) for bridged networking. Currently, VirtualBox supports
-          only IPv4 and IPv6 over AirPort. For other protocols (such as IPX),
-          you must choose a wired interface.</para>
-        </listitem>
-
-        <listitem>
-          <para>On <emphasis role="bold">Linux</emphasis> hosts, functionality
-          is limited when using wireless interfaces for bridged networking.
-          Currently, VirtualBox supports only IPv4 and IPv6 over wireless.
-          For other protocols (such as IPX), you must choose a wired
-          interface.</para>
-
-          <para>Also, setting the MTU to less than 1500 bytes on wired
-          interfaces provided by the sky2 driver on the Marvell Yukon II EC
-          Ultra Ethernet NIC is known to cause packet losses under certain
-          conditions.</para>
-
-          <para>Some adapters strip VLAN tags in hardware. This does not allow
+
+    <title>Bridged Networking</title>
+
+    <para>
+      With bridged networking, VirtualBox uses a device driver on your
+      <emphasis>host</emphasis> system that filters data from your
+      physical network adapter. This driver is therefore called a
+      <emphasis>net filter</emphasis> driver. This allows VirtualBox to
+      intercept data from the physical network and inject data into it,
+      effectively creating a new network interface in software. When a
+      guest is using such a new software interface, it looks to the host
+      system as though the guest were physically connected to the
+      interface using a network cable. The host can send data to the
+      guest through that interface and receive data from it. This means
+      that you can set up routing or bridging between the guest and the
+      rest of your network.
+    </para>
+
+    <para>
+      For this to work, VirtualBox needs a device driver on your host
+      system. The way bridged networking works has been completely
+      rewritten with VirtualBox 2.0 and 2.1, depending on the host
+      operating system. From the user perspective, the main difference
+      is that complex configuration is no longer necessary on any of the
+      supported host operating systems.
+
+      <footnote>
+
+        <para>
+          For Mac OS X and Solaris hosts, net filter drivers were
+          already added in VirtualBox 2.0, as initial support for Host
+          Interface Networking on these platforms. With VirtualBox 2.1,
+          net filter drivers were also added for the Windows and Linux
+          hosts, replacing the mechanisms previously present in
+          VirtualBox for those platforms; especially on Linux, the
+          earlier method required creating TAP interfaces and bridges,
+          which was complex and varied from one distribution to the
+          next. None of this is necessary anymore. Bridged network was
+          formerly called Host Interface Networking and has been renamed
+          with version 2.2 without any change in functionality.
+        </para>
+
+      </footnote>
+    </para>
+
+    <note>
+      <para>
+        Even though TAP is no longer necessary on Linux with bridged
+        networking, you <emphasis>can</emphasis> still use TAP
+        interfaces for certain advanced setups, since you can connect a
+        VM to any host interface.
+      </para>
+    </note>
+
+    <para>
+      To enable bridged networking, open the Settings dialog of a
+      virtual machine, go to the Network page and select
+      <emphasis role="bold">Bridged Network</emphasis> in the drop-down
+      list for the Attached To field. Select a host interface from the
+      list at the bottom of the page, which contains the physical
+      network interfaces of your systems. On a typical MacBook, for
+      example, this will allow you to select between en1: AirPort, which
+      is the wireless interface, and en0: Ethernet, which represents the
+      interface with a network cable.
+    </para>
+
+    <note>
+      <para>
+        Bridging to a wireless interface is done differently from
+        bridging to a wired interface, because most wireless adapters do
+        not support promiscuous mode. All traffic has to use the MAC
+        address of the host's wireless adapter, and therefore VirtualBox
+        needs to replace the source MAC address in the Ethernet header
+        of an outgoing packet to make sure the reply will be sent to the
+        host interface. When VirtualBox sees an incoming packet with a
+        destination IP address that belongs to one of the virtual
+        machine adapters it replaces the destination MAC address in the
+        Ethernet header with the VM adapter's MAC address and passes it
+        on. VirtualBox examines ARP and DHCP packets in order to learn
+        the IP addresses of virtual machines.
+      </para>
+    </note>
+
+    <para>
+      Depending on your host operating system, the following limitations
+      apply:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Mac OS X hosts.</emphasis> Functionality
+          is limited when using AirPort, the Mac's wireless networking
+          system, for bridged networking. Currently, VirtualBox supports
+          only IPv4 and IPv6 over AirPort. For other protocols, such as
+          IPX, you must choose a wired interface.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Linux hosts.</emphasis> Functionality is
+          limited when using wireless interfaces for bridged networking.
+          Currently, VirtualBox supports only IPv4 and IPv6 over
+          wireless. For other protocols, such as IPX, you must choose a
+          wired interface.
+        </para>
+
+        <para>
+          Also, setting the MTU to less than 1500 bytes on wired
+          interfaces provided by the sky2 driver on the Marvell Yukon II
+          EC Ultra Ethernet NIC is known to cause packet losses under
+          certain conditions.
+        </para>
+
+        <para>
+          Some adapters strip VLAN tags in hardware. This does not allow
           to use VLAN trunking between VM and the external network with
-          pre-2.6.27 Linux kernels nor with host operating systems other than
-          Linux.</para>
-        </listitem>
-
-        <listitem>
-          <para>On <emphasis role="bold">Solaris</emphasis> hosts, there is no
-          support for using wireless interfaces. Filtering guest traffic using
-          IPFilter is also not completely supported due to technical
-          restrictions of the Solaris networking subsystem. These issues would
-          be addressed in a future release of Solaris 11.</para>
-
-          <para>Starting with VirtualBox 4.1, on Solaris 11 hosts (build 159
-          and above), it is possible to use Solaris' Crossbow Virtual Network
-          Interfaces (VNICs) directly with VirtualBox without any additional
-          configuration other than each VNIC must be exclusive for every guest
-          network interface.</para>
-
-          <para>Starting with VirtualBox 2.0.4 and up to VirtualBox 4.0, VNICs
-          can be used but with the following caveats:</para>
-
-          <itemizedlist>
-            <listitem>
-              <para>A VNIC cannot be shared between multiple guest network
-              interfaces, i.e. each guest network interface must have its own,
-              exclusive VNIC.</para>
-            </listitem>
-
-            <listitem>
-              <para>The VNIC and the guest network interface that uses the
-              VNIC must be assigned identical MAC addresses.</para>
-            </listitem>
-          </itemizedlist>
-
-          <para>When using VLAN interfaces with VirtualBox, they must be named
-          according to the PPA-hack naming scheme (e.g. "e1000g513001"), as
-          otherwise the guest may receive packets in an unexpected
-          format.</para>
-        </listitem>
-      </itemizedlist></para>
+          pre-2.6.27 Linux kernels nor with host operating systems other
+          than Linux.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Solaris hosts.</emphasis> There is no
+          support for using wireless interfaces. Filtering guest traffic
+          using IPFilter is also not completely supported due to
+          technical restrictions of the Solaris networking subsystem.
+          These issues would be addressed in a future release of Solaris
+          11.
+        </para>
+
+        <para>
+          Starting with VirtualBox 4.1, on Solaris 11 hosts build 159
+          and above, it is possible to use Solaris Crossbow Virtual
+          Network Interfaces (VNICs) directly with VirtualBox without
+          any additional configuration other than each VNIC must be
+          exclusive for every guest network interface.
+        </para>
+
+        <para>
+          Starting with VirtualBox 2.0.4 and up to VirtualBox 4.0, VNICs
+          can be used, but with the following caveats:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              A VNIC cannot be shared between multiple guest network
+              interfaces. For example, each guest network interface must
+              have its own, exclusive VNIC.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              The VNIC and the guest network interface that uses the
+              VNIC must be assigned identical MAC addresses.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          When using VLAN interfaces with VirtualBox, they must be named
+          according to the PPA-hack naming scheme, such as e1000g513001.
+          Otherwise, the guest may receive packets in an unexpected
+          format.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
   <sect1 id="network_internal">
-    <title>Internal networking</title>
-
-    <para>Internal Networking is similar to bridged networking in that the VM
-    can directly communicate with the outside world. However, the "outside
-    world" is limited to other VMs on the same host which connect to the same
-    internal network.</para>
-
-    <para>Even though technically, everything that can be done using internal
-    networking can also be done using bridged networking, there are security
-    advantages with internal networking. In bridged networking mode, all
-    traffic goes through a physical interface of the host system. It is
-    therefore possible to attach a packet sniffer (such as Wireshark) to the
-    host interface and log all traffic that goes over it. If, for any reason,
-    you prefer two or more VMs on the same machine to communicate privately,
-    hiding their data from both the host system and the user, bridged
-    networking therefore is not an option.</para>
-
-    <para>Internal networks are created automatically as needed, i.e. there is
-    no central configuration. Every internal network is identified simply by
-    its name. Once there is more than one active virtual network card with the
-    same internal network ID, the VirtualBox support driver will automatically
-    "wire" the cards and act as a network switch. The VirtualBox support
-    driver implements a complete Ethernet switch and supports both
-    broadcast/multicast frames and promiscuous mode.</para>
-
-    <para>In order to attach a VM's network card to an internal network, set
-    its networking mode to "internal networking". There are two ways to
-    accomplish this:</para>
-
-    <para><itemizedlist>
-        <listitem>
-          <para>You can use a VM's "Settings" dialog in the VirtualBox
-          graphical user interface. In the "Networking" category of the
-          settings dialog, select "Internal Networking" from the drop-down
-          list of networking modes. Now select the name of an existing
-          internal network from the drop-down below or enter a new name into
-          the entry field.</para>
-        </listitem>
-
-        <listitem>
-          <para>You can use <screen>VBoxManage modifyvm "VM name" --nic&lt;x&gt; intnet</screen>
-          Optionally, you can specify a network name with the command <screen>VBoxManage modifyvm "VM name" --intnet&lt;x&gt; "network name"</screen>
+
+    <title>Internal Networking</title>
+
+    <para>
+      Internal Networking is similar to bridged networking in that the
+      VM can directly communicate with the outside world. However, the
+      outside world is limited to other VMs on the same host which
+      connect to the same internal network.
+    </para>
+
+    <para>
+      Even though technically, everything that can be done using
+      internal networking can also be done using bridged networking,
+      there are security advantages with internal networking. In bridged
+      networking mode, all traffic goes through a physical interface of
+      the host system. It is therefore possible to attach a packet
+      sniffer such as Wireshark to the host interface and log all
+      traffic that goes over it. If, for any reason, you prefer two or
+      more VMs on the same machine to communicate privately, hiding
+      their data from both the host system and the user, bridged
+      networking therefore is not an option.
+    </para>
+
+    <para>
+      Internal networks are created automatically as needed. There is no
+      central configuration. Every internal network is identified simply
+      by its name. Once there is more than one active virtual network
+      card with the same internal network ID, the VirtualBox support
+      driver will automatically <emphasis>wire</emphasis> the cards and
+      act as a network switch. The VirtualBox support driver implements
+      a complete Ethernet switch and supports both broadcast/multicast
+      frames and promiscuous mode.
+    </para>
+
+    <para>
+      In order to attach a VM's network card to an internal network, set
+      its networking mode to Internal Networking. There are two ways to
+      accomplish this:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Use the VM's Settings dialog in the VirtualBox graphical user
+          interface. In the Networking category of the settings dialog,
+          select <emphasis role="bold">Internal Networking</emphasis>
+          from the drop-down list of networking modes. Select the name
+          of an existing internal network from the drop-down list below,
+          or enter a new name into the entry field.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use the command line, for example:
+        </para>
+
+<screen>VBoxManage modifyvm "VM name" --nic&lt;x&gt; intnet</screen>
+
+        <para>
+          Optionally, you can specify a network name with the command:
+        </para>
+
+<screen>VBoxManage modifyvm "VM name" --intnet&lt;x&gt; "network name"</screen>
+
+        <para>
           If you do not specify a network name, the network card will be
-          attached to the network <computeroutput>intnet</computeroutput> by
-          default.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>Unless you configure the (virtual) network cards in the guest
-    operating systems that are participating in the internal network to use
-    static IP addresses, you may want to use the DHCP server that is built
-    into VirtualBox to manage IP addresses for the internal network. Please
-    see <xref linkend="vboxmanage-dhcpserver" /> for details.</para>
-
-    <para>As a security measure, by default, the Linux implementation of internal
-    networking only allows VMs running under the same user ID to establish an
-    internal network. However, it is possible to create a shared
-    internal networking interface, accessible by users with different UUIds.</para>
+          attached to the network
+          <computeroutput>intnet</computeroutput> by default.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Unless you configure the virtual network cards in the guest
+      operating systems that are participating in the internal network
+      to use static IP addresses, you may want to use the DHCP server
+      that is built into VirtualBox to manage IP addresses for the
+      internal network. See <xref linkend="vboxmanage-dhcpserver" />.
+    </para>
+
+    <para>
+      As a security measure, by default, the Linux implementation of
+      internal networking only allows VMs running under the same user ID
+      to establish an internal network. However, it is possible to
+      create a shared internal networking interface, accessible by users
+      with different user IDs.
+    </para>
+
   </sect1>
 
   <sect1 id="network_hostonly">
-    <title>Host-only networking</title>
-
-    <para>Host-only networking is another networking mode that was added with
-    version 2.2 of VirtualBox. It can be thought of as a hybrid between the
-    bridged and internal networking modes: as with bridged networking, the
-    virtual machines can talk to each other and the host as if they were
-    connected through a physical Ethernet switch. Similarly, as with internal
-    networking however, a physical networking interface need not be present,
-    and the virtual machines cannot talk to the world outside the host since
-    they are not connected to a physical networking interface.</para>
-
-    <para>Instead, when host-only networking is used, VirtualBox creates a new
-    software interface on the host which then appears next to your existing
-    network interfaces. In other words, whereas with bridged networking an
-    existing physical interface is used to attach virtual machines to, with
-    host-only networking a new "loopback" interface is created on the host.
-    And whereas with internal networking, the traffic between the virtual
-    machines cannot be seen, the traffic on the "loopback" interface on the
-    host can be intercepted.</para>
-
-    <para>Host-only networking is particularly useful for preconfigured
-    virtual appliances, where multiple virtual machines are shipped together
-    and designed to cooperate. For example, one virtual machine may contain a
-    web server and a second one a database, and since they are intended to
-    talk to each other, the appliance can instruct VirtualBox to set up a
-    host-only network for the two. A second (bridged) network would then
-    connect the web server to the outside world to serve data to, but the
-    outside world cannot connect to the database.</para>
-
-    <para>To change a virtual machine's virtual network interface to "host
-    only" mode:<itemizedlist>
-        <listitem>
-          <para>either go to the "Network" page in the virtual machine's
-          settings notebook in the graphical user interface and select
-          "Host-only networking", or</para>
-        </listitem>
-
-        <listitem>
-          <para>on the command line, type <computeroutput>VBoxManage modifyvm
-          "VM name" --nic&lt;x&gt; hostonly</computeroutput>; see <xref
-          linkend="vboxmanage-modifyvm" /> for details.</para>
-        </listitem>
-    </itemizedlist></para>
-
-    <para>Before you can attach a VM to a host-only network you have to
-      create at least one host-only interface, either from the GUI:
-      "File" &rarr; "Preferences" &rarr; "Network" &rarr; "Host-only network"
-      &rarr; "(+)Add host-only network", or via command line with</para>
-      <screen>VBoxManage hostonlyif create</screen>
-      <para>see <xref linkend="vboxmanage-hostonlyif" /> for details.</para>
-
-    <para>For host-only networking, like with internal networking, you may
-    find the DHCP server useful that is built into VirtualBox. This can be
-    enabled to then manage the IP addresses in the host-only network since
-    otherwise you would need to configure all IP addresses
-    statically.<itemizedlist>
-        <listitem>
-          <para>In the VirtualBox graphical user interface, you can configure
-          all these items in the global settings via "File" &rarr; "Preferences"
-          &rarr; "Network", which lists all host-only networks which are
-          presently in use. Click on the network name and then on the "Edit"
-          button to the right, and you can modify the adapter and DHCP
-          settings.</para>
-        </listitem>
-
-        <listitem>
-          <para>Alternatively, you can use <computeroutput>VBoxManage
-          dhcpserver</computeroutput> on the command line; please see <xref
-          linkend="vboxmanage-dhcpserver" /> for details.</para>
-        </listitem>
-      </itemizedlist>
-    </para>
-
-    <para><note><para>On Linux and Mac OS X hosts the number of host-only
-    interfaces is limited to 128. There is no such limit for Solaris and
-    Windows hosts.</para></note></para>
+
+    <title>Host-Only Networking</title>
+
+    <para>
+      Host-only networking is another networking mode that was added
+      with version 2.2 of VirtualBox. It can be thought of as a hybrid
+      between the bridged and internal networking modes. As with bridged
+      networking, the virtual machines can talk to each other and the
+      host as if they were connected through a physical Ethernet switch.
+      As with internal networking, a physical networking interface need
+      not be present, and the virtual machines cannot talk to the world
+      outside the host since they are not connected to a physical
+      networking interface.
+    </para>
+
+    <para>
+      When host-only networking is used, VirtualBox creates a new
+      software interface on the host which then appears next to your
+      existing network interfaces. In other words, whereas with bridged
+      networking an existing physical interface is used to attach
+      virtual machines to, with host-only networking a new
+      <emphasis>loopback</emphasis> interface is created on the host.
+      And whereas with internal networking, the traffic between the
+      virtual machines cannot be seen, the traffic on the loopback
+      interface on the host can be intercepted.
+    </para>
+
+    <para>
+      Host-only networking is particularly useful for preconfigured
+      virtual appliances, where multiple virtual machines are shipped
+      together and designed to cooperate. For example, one virtual
+      machine may contain a web server and a second one a database, and
+      since they are intended to talk to each other, the appliance can
+      instruct VirtualBox to set up a host-only network for the two. A
+      second, bridged, network would then connect the web server to the
+      outside world to serve data to, but the outside world cannot
+      connect to the database.
+    </para>
+
+    <para>
+      To change a virtual machine's virtual network interface to Host
+      Only mode, do either of the following:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Go to the Network page in the virtual machine's Settings
+          dialog and select <emphasis role="bold">Host-Only
+          Networking</emphasis>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          On the command line, type <computeroutput>VBoxManage modifyvm
+          "VM name" --nic&lt;x&gt; hostonly</computeroutput>. See
+          <xref
+          linkend="vboxmanage-modifyvm" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Before you can attach a VM to a host-only network you have to
+      create at least one host-only interface. You can use the GUI for
+      this. Choose <emphasis role="bold">File</emphasis>,
+      <emphasis role="bold">Preferences</emphasis>,
+      <emphasis role="bold">Network</emphasis>,
+      <emphasis role="bold">Host-Only Network</emphasis>,
+      <emphasis role="bold">(+)Add Host-Only Network</emphasis>.
+    </para>
+
+    <para>
+      Alternatively, you can use the command line:
+    </para>
+
+<screen>VBoxManage hostonlyif create</screen>
+
+    <para>
+      See <xref linkend="vboxmanage-hostonlyif" />.
+    </para>
+
+    <para>
+      For host-only networking, as with internal networking, you may
+      find the DHCP server useful that is built into VirtualBox. This
+      can be enabled to then manage the IP addresses in the host-only
+      network since otherwise you would need to configure all IP
+      addresses statically.
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          In the VirtualBox graphical user interface, you can configure
+          all these items in the global settings by choosing
+          <emphasis role="bold">File</emphasis>,
+          <emphasis role="bold">Preferences</emphasis>,
+          <emphasis role="bold">Network</emphasis>. This lists all
+          host-only networks which are presently in use. Click on the
+          network name and then on
+          <emphasis role="bold">Edit</emphasis>. You can then modify the
+          adapter and DHCP settings.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Alternatively, you can use <computeroutput>VBoxManage
+          dhcpserver</computeroutput> on the command line. See
+          <xref
+          linkend="vboxmanage-dhcpserver" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <note>
+      <para>
+        On Linux and Mac OS X hosts the number of host-only interfaces
+        is limited to 128. There is no such limit for Solaris and
+        Windows hosts.
+      </para>
+    </note>
+
   </sect1>
 
   <sect1 id="network_udp_tunnel">
-    <title>UDP Tunnel networking</title>
-
-    <para>This networking mode allows to interconnect virtual machines running
-    on different hosts.</para>
-
-    <para>Technically this is done by encapsulating Ethernet frames sent or
-    received by the guest network card into UDP/IP datagrams, and sending them
-    over any network available to the host.</para>
-
-    <para>UDP Tunnel mode has three parameters:<glosslist>
-        <glossentry>
-          <glossterm>Source UDP port</glossterm>
-
-          <glossdef>
-            <para>The port on which the host listens. Datagrams arriving on
-            this port from any source address will be forwarded to the
-            receiving part of the guest network card.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Destination address</glossterm>
-
-          <glossdef>
-            <para>IP address of the target host of the transmitted
-            data.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Destination UDP port</glossterm>
-
-          <glossdef>
-            <para>Port number to which the transmitted data is sent.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist></para>
-
-    <para>When interconnecting two virtual machines on two different hosts,
-    their IP addresses must be swapped. On single host, source and destination
-    UDP ports must be swapped.</para>
-
-    <para>In the following example host 1 uses the IP address 10.0.0.1 and
-    host 2 uses IP address 10.0.0.2. Configuration via command-line:<screen>        VBoxManage modifyvm "VM 01 on host 1" --nic&lt;x&gt; generic
+
+    <title>UDP Tunnel Networking</title>
+
+    <para>
+      This networking mode allows you to interconnect virtual machines
+      running on different hosts.
+    </para>
+
+    <para>
+      Technically this is done by encapsulating Ethernet frames sent or
+      received by the guest network card into UDP/IP datagrams, and
+      sending them over any network available to the host.
+    </para>
+
+    <para>
+      UDP Tunnel mode has the following parameters:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Source UDP port:</emphasis> The port on
+          which the host listens. Datagrams arriving on this port from
+          any source address will be forwarded to the receiving part of
+          the guest network card.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Destination address:</emphasis> IP
+          address of the target host of the transmitted data.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Destination UDP port:</emphasis> Port
+          number to which the transmitted data is sent.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      When interconnecting two virtual machines on two different hosts,
+      their IP addresses must be swapped. On a single host, source and
+      destination UDP ports must be swapped.
+    </para>
+
+    <para>
+      In the following example, host 1 uses the IP address 10.0.0.1 and
+      host 2 uses IP address 10.0.0.2. To configure using the
+      command-line:
+    </para>
+
+<screen>        VBoxManage modifyvm "VM 01 on host 1" --nic&lt;x&gt; generic
         VBoxManage modifyvm "VM 01 on host 1" --nicgenericdrv&lt;x&gt; UDPTunnel
         VBoxManage modifyvm "VM 01 on host 1" --nicproperty&lt;x&gt; dest=10.0.0.2
         VBoxManage modifyvm "VM 01 on host 1" --nicproperty&lt;x&gt; sport=10001
         VBoxManage modifyvm "VM 01 on host 1" --nicproperty&lt;x&gt; dport=10002</screen>
-    and <screen>        VBoxManage modifyvm "VM 02 on host 2" --nic&lt;y&gt; generic
+
+<screen>        VBoxManage modifyvm "VM 02 on host 2" --nic&lt;y&gt; generic
         VBoxManage modifyvm "VM 02 on host 2" --nicgenericdrv&lt;y&gt; UDPTunnel
         VBoxManage modifyvm "VM 02 on host 2" --nicproperty&lt;y&gt; dest=10.0.0.1
         VBoxManage modifyvm "VM 02 on host 2" --nicproperty&lt;y&gt; sport=10002
-        VBoxManage modifyvm "VM 02 on host 2" --nicproperty&lt;y&gt; dport=10001</screen></para>
-
-    <para>Of course, you can always interconnect two virtual machines on the
-    same host, by setting the destination address parameter to 127.0.0.1 on
-    both. It will act similarly to "Internal network" in this case, however
-    the host can see the network traffic which it could not in the normal
-    Internal network case.</para>
-
-    <para><note><para>On Unix-based hosts (e.g. Linux, Solaris, Mac OS X) it is
-    not possible to bind to ports below 1024 from applications that are not run
-    by <computeroutput>root</computeroutput>. As a result, if you try to
-    configure such a source UDP port, the VM will refuse to
-    start.</para></note></para>
+        VBoxManage modifyvm "VM 02 on host 2" --nicproperty&lt;y&gt; dport=10001</screen>
+
+    <para>
+      Of course, you can always interconnect two virtual machines on the
+      same host, by setting the destination address parameter to
+      127.0.0.1 on both. It will act similarly to an internal network in
+      this case. However, the host can see the network traffic which it
+      could not in the normal internal network case.
+    </para>
+
+    <note>
+      <para>
+        On Unix-based hosts, such as Linux, Solaris, and Mac OS X, it is
+        not possible to bind to ports below 1024 from applications that
+        are not run by <computeroutput>root</computeroutput>. As a
+        result, if you try to configure such a source UDP port, the VM
+        will refuse to start.
+      </para>
+    </note>
+
   </sect1>
 
   <sect1 id="network_vde">
-    <title>VDE networking</title>
-
-    <para>Virtual Distributed Ethernet (VDE<footnote>
-        <para>VDE is a project developed by Renzo Davoli, Associate Professor
-        at the University of Bologna, Italy.</para>
-      </footnote>) is a flexible, virtual network infrastructure system,
-    spanning across multiple hosts in a secure way. It allows for L2/L3
-    switching, including spanning-tree protocol, VLANs, and WAN emulation. It
-    is an optional part of VirtualBox which is only included in the source
-    code.</para>
-
-    <para>The basic building blocks of the infrastructure are VDE switches,
-    VDE plugs and VDE wires which inter-connect the switches.</para>
-
-    <para>The VirtualBox VDE driver has one parameter:<glosslist>
-        <glossentry>
-          <glossterm>VDE network</glossterm>
-
-          <glossdef>
-            <para>The name of the VDE network switch socket to which the VM
-            will be connected.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist></para>
-
-    <para>The following basic example shows how to connect a virtual machine
-    to a VDE switch:</para>
-
-    <para><orderedlist>
-        <listitem>
-          <para>Create a VDE switch: <screen>vde_switch -s /tmp/switch1</screen></para>
-        </listitem>
-
-        <listitem>
-          <para>Configuration via command-line: <screen>VBoxManage modifyvm "VM name" --nic&lt;x&gt; generic</screen>
-          <screen>VBoxManage modifyvm "VM name" --nicgenericdrv&lt;x&gt; VDE</screen>
-          To connect to automatically allocated switch port, use: <screen>VBoxManage modifyvm "VM name" --nicproperty&lt;x&gt; network=/tmp/switch1</screen>
-          To connect to specific switch port &lt;n&gt;, use: <screen>VBoxManage modifyvm "VM name" --nicproperty&lt;x&gt; network=/tmp/switch1[&lt;n&gt;]</screen>
-          The latter option can be useful for VLANs.</para>
-        </listitem>
-
-        <listitem>
-          <para>Optionally map between VDE switch port and VLAN: (from switch
-          CLI) <screen>vde$ vlan/create &lt;VLAN&gt;</screen> <screen>vde$ port/setvlan &lt;port&gt; &lt;VLAN&gt;</screen></para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>VDE is available on Linux and FreeBSD hosts only. It is only
-    available if the VDE software and the VDE plugin library from the
-    VirtualSquare project are installed on the host system<footnote>
-        <para>For Linux hosts, the shared library libvdeplug.so must be
-        available in the search path for shared libraries</para>
-      </footnote>. For more information on setting up VDE networks, please see
-    the documentation accompanying the software.<footnote>
-        <para><ulink
-        url="http://wiki.virtualsquare.org/wiki/index.php/VDE_Basic_Networking">http://wiki.virtualsquare.org/wiki/index.php/VDE_Basic_Networking</ulink>.</para>
-      </footnote></para>
+
+    <title>VDE Networking</title>
+
+    <para>
+      Virtual Distributed Ethernet (VDE)
+
+      <footnote>
+
+        <para>
+          VDE is a project developed by Renzo Davoli, Associate
+          Professor at the University of Bologna, Italy.
+        </para>
+
+      </footnote>
+
+      is a flexible, virtual network infrastructure system, spanning
+      across multiple hosts in a secure way. It allows for L2/L3
+      switching, including spanning-tree protocol, VLANs, and WAN
+      emulation. It is an optional part of VirtualBox which is only
+      included in the source code.
+    </para>
+
+    <para>
+      The basic building blocks of the infrastructure are VDE switches,
+      VDE plugs and VDE wires which inter-connect the switches.
+    </para>
+
+    <para>
+      The VirtualBox VDE driver has a single parameter: VDE network.
+      This is the name of the VDE network switch socket to which the VM
+      will be connected.
+    </para>
+
+    <para>
+      The following basic example shows how to connect a virtual machine
+      to a VDE switch.
+    </para>
+
+    <orderedlist>
+
+      <listitem>
+        <para>
+          Create a VDE switch:
+        </para>
+
+<screen>vde_switch -s /tmp/switch1</screen>
+      </listitem>
+
+      <listitem>
+        <para>
+          Configure VMs using the command-line:
+        </para>
+
+<screen>VBoxManage modifyvm "VM name" --nic&lt;x&gt; generic</screen>
+
+<screen>VBoxManage modifyvm "VM name" --nicgenericdrv&lt;x&gt; VDE</screen>
+
+        <para>
+          To connect to an automatically allocated switch port:
+        </para>
+
+<screen>VBoxManage modifyvm "VM name" --nicproperty&lt;x&gt; network=/tmp/switch1</screen>
+
+        <para>
+          To connect to a specific switch port
+          <replaceable>n</replaceable>:
+        </para>
+
+<screen>VBoxManage modifyvm "VM name" --nicproperty&lt;x&gt; network=/tmp/switch1[&lt;n&gt;]</screen>
+
+        <para>
+          This command can be useful for VLANs.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          (Optional) Map between a VDE switch port and a VLAN.
+        </para>
+
+        <para>
+          Using the switch command line:
+        </para>
+
+<screen>vde$ vlan/create &lt;VLAN&gt;</screen>
+
+<screen>vde$ port/setvlan &lt;port&gt; &lt;VLAN&gt;</screen>
+      </listitem>
+
+    </orderedlist>
+
+    <para>
+      VDE is available on Linux and FreeBSD hosts only. It is only
+      available if the VDE software and the VDE plugin library from the
+      VirtualSquare project are installed on the host system
+
+      <footnote>
+
+        <para>
+          For Linux hosts, the shared library libvdeplug.so must be
+          available in the search path for shared libraries
+        </para>
+
+      </footnote>
+
+      . For more information on setting up VDE networks, please see the
+      documentation accompanying the software.
+
+      <footnote>
+
+        <para>
+          <ulink
+        url="http://wiki.virtualsquare.org/wiki/index.php/VDE_Basic_Networking">http://wiki.virtualsquare.org/wiki/index.php/VDE_Basic_Networking</ulink>.
+        </para>
+
+      </footnote>
+    </para>
+
   </sect1>
 
   <sect1 id="network_bandwidth_limit">
-    <title>Limiting bandwidth for network I/O</title>
-
-    <para>Starting with version 4.2, VirtualBox allows for limiting the
-    maximum bandwidth used for network transmission. Several network adapters
-    of one VM may share limits through bandwidth groups. It is possible
-    to have more than one such limit.</para>
-    <note><para>VirtualBox shapes VM traffic only in the transmit direction,
-        delaying the packets being sent by virtual machines. It does not limit
-        the traffic being received by virtual machines.</para>
+
+    <title>Limiting Bandwidth for Network I/O</title>
+
+    <para>
+      Starting with version 4.2, VirtualBox allows for limiting the
+      maximum bandwidth used for network transmission. Several network
+      adapters of one VM may share limits through bandwidth groups. It
+      is possible to have more than one such limit.
+    </para>
+
+    <note>
+      <para>
+        VirtualBox shapes VM traffic only in the transmit direction,
+        delaying the packets being sent by virtual machines. It does not
+        limit the traffic being received by virtual machines.
+      </para>
     </note>
 
-    <para>Limits are configured through
-    <computeroutput>VBoxManage</computeroutput>. The example below creates a
-    bandwidth group named "Limit", sets the limit to 20 Mbit/s and assigns the
-    group to the first and second adapters of the VM:<screen>VBoxManage bandwidthctl "VM name" add Limit --type network --limit 20m
+    <para>
+      Limits are configured through
+      <computeroutput>VBoxManage</computeroutput>. The example below
+      creates a bandwidth group named Limit, sets the limit to 20 Mbps
+      and assigns the group to the first and second adapters of the VM:
+
+<screen>VBoxManage bandwidthctl "VM name" add Limit --type network --limit 20m
 VBoxManage modifyvm "VM name" --nicbandwidthgroup1 Limit
-VBoxManage modifyvm "VM name" --nicbandwidthgroup2 Limit</screen></para>
-
-    <para>All adapters in a group share the bandwidth limit, meaning that in the
-    example above the bandwidth of both adapters combined can never exceed 20
-    Mbit/s. However, if one adapter doesn't require bandwidth the other can use the
-    remaining bandwidth of its group.</para>
-
-    <para>The limits for each group can be changed while the VM is running,
-    with changes being picked up immediately. The example below changes the
-    limit for the group created in the example above to 100 Kbit/s:<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 100k</screen></para>
-
-    <para>To completely disable shaping for the first adapter of VM use the
+VBoxManage modifyvm "VM name" --nicbandwidthgroup2 Limit</screen>
+    </para>
+
+    <para>
+      All adapters in a group share the bandwidth limit, meaning that in
+      the example above the bandwidth of both adapters combined can
+      never exceed 20 Mbps. However, if one adapter does not require
+      bandwidth the other can use the remaining bandwidth of its group.
+    </para>
+
+    <para>
+      The limits for each group can be changed while the VM is running,
+      with changes being picked up immediately. The example below
+      changes the limit for the group created in the example above to
+      100 Kbps:
+
+<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 100k</screen>
+    </para>
+
+    <para>
+      To completely disable shaping for the first adapter of VM use the
       following command:
-      <screen>VBoxManage modifyvm "VM name" --nicbandwidthgroup1 none</screen></para>
-
-    <para>It is also possible to disable shaping for all adapters assigned to a
-      bandwidth group while VM is running, by specifying the zero limit for the
-      group. For example, for the bandwidth group named "Limit" use:
-      <screen>VBoxManage bandwidthctl "VM name" set Limit --limit 0</screen></para>
+
+<screen>VBoxManage modifyvm "VM name" --nicbandwidthgroup1 none</screen>
+    </para>
+
+    <para>
+      It is also possible to disable shaping for all adapters assigned
+      to a bandwidth group while VM is running, by specifying the zero
+      limit for the group. For example, for the bandwidth group named
+      Limit use:
+
+<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 0</screen>
+    </para>
+
   </sect1>
+
   <sect1 id="network_performance">
-    <title>Improving network performance</title>
-
-    <para>VirtualBox provides a variety of virtual network adapters that can be
-      "attached" to the host's network in a number of ways. Depending on which
-      types of adapters and attachments are used the network performance will
-      be different. Performance-wise the <emphasis>virtio</emphasis> network
-      adapter is preferable over <emphasis>Intel PRO/1000</emphasis> emulated
-      adapters, which are preferred over <emphasis>PCNet</emphasis> family of
-      adapters. Both <emphasis>virtio</emphasis> and <emphasis>Intel PRO/1000
-      </emphasis> adapters enjoy the benefit of segmentation and checksum
-      offloading. Segmentation offloading is essential for high performance as
-      it allows for less context switches, dramatically increasing the sizes
-      of packets that cross VM/host boundary.</para>
-    <note><para>Neither <emphasis>virtio</emphasis> nor <emphasis>Intel PRO/1000
-        </emphasis> drivers for Windows XP support segmentation
-        offloading. Therefore Windows XP guests never reach the same
-        transmission rates as other guest types. Refer to MS Knowledge base
-        article 842264 for additional information.</para>
+
+    <title>Improving Network Performance</title>
+
+    <para>
+      VirtualBox provides a variety of virtual network adapters that can
+      be attached to the host's network in a number of ways. Depending
+      on which types of adapters and attachments are used the network
+      performance will be different. Performance-wise the virtio network
+      adapter is preferable over Intel PRO/1000 emulated adapters, which
+      are preferred over the PCNet family of adapters. Both virtio and
+      Intel PRO/1000 adapters enjoy the benefit of segmentation and
+      checksum offloading. Segmentation offloading is essential for high
+      performance as it allows for less context switches, dramatically
+      increasing the sizes of packets that cross the VM/host boundary.
+    </para>
+
+    <note>
+      <para>
+        Neither virtio nor Intel PRO/1000 drivers for Windows XP support
+        segmentation offloading. Therefore Windows XP guests never reach
+        the same transmission rates as other guest types. Refer to MS
+        Knowledge base article 842264 for additional information.
+      </para>
     </note>
-    <para>Three attachment types: <emphasis>internal</emphasis>,
-      <emphasis>bridged</emphasis> and <emphasis>host-only</emphasis>, have
-      nearly identical performance, the <emphasis>internal</emphasis> type
-      being a little bit faster and using less CPU cycles as the packets never
-      reach the host's network stack. The <emphasis>NAT</emphasis> attachment
-      is the slowest (and safest) of all attachment types as it provides
-      network address translation. The generic driver attachment is special and
-      cannot be considered as an alternative to other attachment types.</para>
-    <para>The number of CPUs assigned to VM does not improve network
-      performance and in some cases may hurt it due to increased concurrency in
-      the guest.</para>
-    <para>Here is the short summary of things to check in order to improve
-      network performance:</para>
-    <para><orderedlist>
-        <listitem>
-          <para>Whenever possible use <emphasis>virtio</emphasis> network
-            adapter, otherwise use one of <emphasis>Intel PRO/1000</emphasis>
-            adapters;</para>
-        </listitem>
-        <listitem>
-          <para>Use <emphasis>bridged</emphasis> attachment instead of
-            <emphasis>NAT</emphasis>;</para>
-        </listitem>
-        <listitem>
-          <para>Make sure segmentation offloading is enabled in the guest OS.
-            Usually it will be enabled by default. You can check and modify
-            offloading settings using <computeroutput>ethtool</computeroutput>
-            command in Linux guests.</para>
-        </listitem>
-        <listitem>
-          <para>Perform a full, detailed analysis of network traffic on
-            the VM's network adaptor using a 3rd party tool such as Wireshark.
-            To do this, a promiscuous mode policy needs to be used on the
-            VM's network adaptor. Use of this mode is only possible on
-            networks: NAT Network, Bridged Adapter, Internal Network and Host-only Adapter.</para>
-          <para>To setup a promiscuous mode policy, either select from the drop down list
-            located in the Network Settings dialog for the network adaptor
-            or use the command line tool <computeroutput>VBoxManage</computeroutput>;
-            for details, refer to <xref linkend="vboxmanage-modifyvm" />.</para>
-          <para>Promiscuous mode policies are: </para>
-          <para><orderedlist>
-            <listitem>
-              <para><computeroutput>deny</computeroutput> (default setting) which hides
-              any traffic not intended for this VM's network adaptor.</para>
-            </listitem>
-            <listitem>
-              <para><computeroutput>allow-vms</computeroutput> which hides all host
-              traffic from this VM's network adaptor, but allows it to see traffic from/to other
-              VMs.</para>
-            </listitem>
-            <listitem>
-              <para><computeroutput>allow-all</computeroutput> which removes all
-              restrictions - this VM's network adaptor sees all traffic.</para>
-            </listitem>
-          </orderedlist></para>
-        </listitem>
-        </orderedlist></para>
+
+    <para>
+      Three attachment types: Internal, Bridged, and Host-Only, have
+      nearly identical performance. The Internal type is a little bit
+      faster and uses less CPU cycles as the packets never reach the
+      host's network stack. The NAT attachment type is the slowest and
+      most secure of all attachment types, as it provides network
+      address translation. The generic driver attachment is special and
+      cannot be considered as an alternative to other attachment types.
+    </para>
+
+    <para>
+      The number of CPUs assigned to VM does not improve network
+      performance and in some cases may hurt it due to increased
+      concurrency in the guest.
+    </para>
+
+    <para>
+      Here is a short summary of things to check in order to improve
+      network performance:
+    </para>
+
+    <orderedlist>
+
+      <listitem>
+        <para>
+          Whenever possible use the virtio network adapter. Otherwise,
+          use one of the Intel PRO/1000 adapters.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use a Bridged attachment instead of NAT.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Make sure segmentation offloading is enabled in the guest OS.
+          Usually it will be enabled by default. You can check and
+          modify offloading settings using the
+          <computeroutput>ethtool</computeroutput> command on Linux
+          guests.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Perform a full, detailed analysis of network traffic on the
+          VM's network adaptor using a third party tool such as
+          Wireshark. To do this, a promiscuous mode policy needs to be
+          used on the VM's network adaptor. Use of this mode is only
+          possible on the following network types: NAT Network, Bridged
+          Adapter, Internal Network, and Host-Only Adapter.
+        </para>
+
+        <para>
+          To setup a promiscuous mode policy, either select from the
+          drop down list located in the Network Settings dialog for the
+          network adaptor or use the command line tool
+          <computeroutput>VBoxManage</computeroutput>. See
+          <xref linkend="vboxmanage-modifyvm" />.
+        </para>
+
+        <para>
+          Promiscuous mode policies are as follows:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <computeroutput>deny</computeroutput>, which hides any
+              traffic not intended for the VM's network adaptor. This is
+              the default setting.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>allow-vms</computeroutput>, which hides
+              all host traffic from the VM's network adaptor, but allows
+              it to see traffic from and to other VMs.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>allow-all</computeroutput>, which removes
+              all restrictions. The VM's network adaptor sees all
+              traffic.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+    </orderedlist>
+
   </sect1>
+
 </chapter>
Index: /trunk/doc/manual/en_US/user_PrivacyPolicy.xml
===================================================================
--- /trunk/doc/manual/en_US/user_PrivacyPolicy.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_PrivacyPolicy.xml	(revision 73276)
@@ -1,7 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
+
 <appendix id="privacy">
-  <title>VirtualBox privacy information</title>
+  <title>VirtualBox Privacy Information</title>
 
   <para>Version 5, Dec 13, 2012</para>
Index: /trunk/doc/manual/en_US/user_Security.xml
===================================================================
--- /trunk/doc/manual/en_US/user_Security.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_Security.xml	(revision 73276)
@@ -1,173 +1,213 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="Security">
-  <title>Security guide</title>
-
-  <sect1>
+
+  <title>Security Guide</title>
+
+  <sect1 id="security-general">
+
     <title>General Security Principles</title>
 
-    <para>The following principles are fundamental to using any application
+    <para>
+      The following principles are fundamental to using any application
       securely.
-      <glosslist>
-        <glossentry>
-          <glossterm>Keep Software Up To Date</glossterm>
-          <glossdef>
-            <para>
-              One of the principles of good security practise is to keep all
-              software versions and patches up to date. Activate the VirtualBox
-              update notification to get notified when a new VirtualBox release
-              is available. When updating VirtualBox, do not forget to update
-              the Guest Additions. Keep the host operating system as well as the
-              guest operating system up to date.
-            </para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Restrict Network Access to Critical Services</glossterm>
-          <glossdef>
-            <para>
-              Use proper means, for instance a firewall, to protect your computer
-              and your guest(s) from accesses from the outside. Choosing the proper
-              networking mode for VMs helps to separate host networking from the
-              guest and vice versa.
-            </para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Follow the Principle of Least Privilege</glossterm>
-          <glossdef>
-            <para>
-              The principle of least privilege states that users should be given the
-              least amount of privilege necessary to perform their jobs. Always execute VirtualBox
-              as a regular user. We strongly discourage anyone from executing
-              VirtualBox with system privileges.
-            </para>
-            <para>
-              Choose restrictive permissions when creating configuration files,
-              for instance when creating /etc/default/virtualbox, see
-              <xref linkend="linux_install_opts"/>. Mode 0600 would be preferred.
-            </para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Monitor System Activity</glossterm>
-          <glossdef>
-            <para>
-              System security builds on three pillars: good security protocols, proper
-              system configuration and system monitoring. Auditing and reviewing audit
-              records address the third requirement. Each component within a system
-              has some degree of monitoring capability. Follow audit advice in this
-              document and regularly monitor audit records.
-            </para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm>Keep Up To Date on Latest Security Information</glossterm>
-          <glossdef>
-            <para>
-              Oracle continually improves its software and documentation. Check this
-              note yearly for revisions.
-            </para>
-          </glossdef>
-        </glossentry>
-
-      </glosslist>
     </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="strong">Keep software up to date</emphasis>.
+          One of the principles of good security practise is to keep all
+          software versions and patches up to date. Activate the
+          VirtualBox update notification to get notified when a new
+          VirtualBox release is available. When updating VirtualBox, do
+          not forget to update the Guest Additions. Keep the host
+          operating system as well as the guest operating system up to
+          date.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="strong">Restrict network access to critical
+          services.</emphasis> Use proper means, for instance a
+          firewall, to protect your computer and your guests from
+          accesses from the outside. Choosing the proper networking mode
+          for VMs helps to separate host networking from the guest and
+          vice versa.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="strong">Follow the principle of least
+          privilege.</emphasis> The principle of least privilege states
+          that users should be given the least amount of privilege
+          necessary to perform their jobs. Always execute VirtualBox as
+          a regular user. We strongly discourage anyone from executing
+          VirtualBox with system privileges.
+        </para>
+
+        <para>
+          Choose restrictive permissions when creating configuration
+          files, for instance when creating /etc/default/virtualbox, see
+          <xref linkend="linux_install_opts"/>. Mode 0600 is preferred.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="strong"> Monitor system activity.</emphasis>
+          System security builds on three pillars: good security
+          protocols, proper system configuration and system monitoring.
+          Auditing and reviewing audit records address the third
+          requirement. Each component within a system has some degree of
+          monitoring capability. Follow audit advice in this document
+          and regularly monitor audit records.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="strong">Keep up to date on latest security
+          information.</emphasis> Oracle continually improves its
+          software and documentation. Check this note yearly for
+          revisions.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
-  <sect1>
+  <sect1 id="security-secure-install">
+
     <title>Secure Installation and Configuration</title>
 
-    <sect2>
+    <sect2 id="security-secure-install-overview">
+
       <title>Installation Overview</title>
-      <para>
-        The VirtualBox base package should be downloaded only from a trusted source,
-        for instance the official website
+
+      <para>
+        The VirtualBox base package should be downloaded only from a
+        trusted source, for instance the official website
         <ulink url="http://www.virtualbox.org">http://www.virtualbox.org</ulink>.
-        The integrity of the package should be verified with the provided SHA256
-        checksum which can be found on the official website.
-      </para>
-      <para>
-        General VirtualBox installation instructions for the supported hosts
-        can be found in <xref linkend="installation"/>.
-      </para>
-      <para>
-        On Windows hosts, the installer allows for disabling USB support, support
-        for bridged networking, support for host-only networking and the Python
-        language bindings, see <xref linkend="installation_windows"/>.
-        All these features are enabled by default but disabling some
-        of them could be appropriate if the corresponding functionality is not
-        required by any virtual machine. The Python language bindings are only
+        The integrity of the package should be verified with the
+        provided SHA256 checksum which can be found on the official
+        website.
+      </para>
+
+      <para>
+        General VirtualBox installation instructions for the supported
+        hosts can be found in <xref linkend="installation"/>.
+      </para>
+
+      <para>
+        On Windows hosts, the installer allows for disabling USB
+        support, support for bridged networking, support for host-only
+        networking and the Python language binding. See
+        <xref linkend="installation_windows"/>. All these features are
+        enabled by default but disabling some of them could be
+        appropriate if the corresponding functionality is not required
+        by any virtual machine. The Python language bindings are only
         required if the VirtualBox API is to be used by external Python
-        applications. In particular USB support and support
-        for the two networking modes require the installation of Windows kernel
-        drivers on the host. Therefore disabling those selected features can
-        not only be used to restrict the user to certain functionality but
-        also to minimize the surface provided to a potential attacker.     </para>
-      <para>
-        The general case is to install the complete VirtualBox package. The
-        installation must be done with system privileges. All VirtualBox binaries
-        should be executed as a regular user and never as a privileged user.
-      </para>
-      <para>
-        The Oracle VM VirtualBox extension pack provides additional features
-        and must be downloaded and installed separately, see
-        <xref linkend="intro-installing"/>. As for the base package, the SHA256
-        checksum of the extension pack should be verified. As the installation
-        requires system privileges, VirtualBox will ask for the system
-        password during the installation of the extension pack.
-      </para>
-    </sect2>
-
-    <sect2>
+        applications. In particular USB support and support for the two
+        networking modes require the installation of Windows kernel
+        drivers on the host. Therefore disabling those selected features
+        can not only be used to restrict the user to certain
+        functionality but also to minimize the surface provided to a
+        potential attacker.
+      </para>
+
+      <para>
+        The general case is to install the complete VirtualBox package.
+        The installation must be done with system privileges. All
+        VirtualBox binaries should be executed as a regular user and
+        never as a privileged user.
+      </para>
+
+      <para>
+        The Oracle VM VirtualBox extension pack provides additional
+        features and must be downloaded and installed separately, see
+        <xref linkend="intro-installing"/>. As for the base package, the
+        SHA256 checksum of the extension pack should be verified. As the
+        installation requires system privileges, VirtualBox will ask for
+        the system password during the installation of the extension
+        pack.
+      </para>
+
+    </sect2>
+
+    <sect2 id="security-secure-install-postinstall">
+
       <title>Post Installation Configuration</title>
-      <para>
-        Normally there is no post installation configuration of VirtualBox components
-        required. However, on Solaris and Linux hosts it is necessary to configure
-        the proper permissions for users executing VMs and who should be able to
-        access certain host resources. For instance, Linux users must be member of
-        the <emphasis>vboxusers</emphasis> group to be able to pass USB devices to a
-        guest. If a serial host interface should be accessed from a VM, the proper
-        permissions must be granted to the user to be able to access that device.
-        The same applies to other resources like raw partitions, DVD/CD drives
-        and sound devices.
-      </para>
-    </sect2>
+
+      <para>
+        Normally there is no post installation configuration of
+        VirtualBox components required. However, on Solaris and Linux
+        hosts it is necessary to configure the proper permissions for
+        users executing VMs and who should be able to access certain
+        host resources. For instance, Linux users must be member of the
+        <emphasis>vboxusers</emphasis> group to be able to pass USB
+        devices to a guest. If a serial host interface should be
+        accessed from a VM, the proper permissions must be granted to
+        the user to be able to access that device. The same applies to
+        other resources like raw partitions, DVD/CD drives, and sound
+        devices.
+      </para>
+
+    </sect2>
+
   </sect1>
 
-  <sect1>
+  <sect1 id="security-features">
+
     <title>Security Features</title>
-    <para>This section outlines the specific security mechanisms offered
-      by VirtualBox.</para>
-
-    <sect2>
+
+    <para>
+      This section outlines the specific security mechanisms offered by
+      VirtualBox.
+    </para>
+
+    <sect2 id="security-model">
+
       <title>The Security Model</title>
-      <para>
-        One property of virtual machine monitors (VMMs) like VirtualBox is to encapsulate
-        a guest by executing it in a protected environment, a virtual machine,
-        running as a user process on the host operating system. The guest cannot
-        communicate directly with the hardware or other computers but only through
-        the VMM. The VMM provides emulated physical resources and devices to the
-        guest which are accessed by the guest operating system to perform the required
-        tasks. The VM settings control the resources provided to the guest, for example
-        the amount of guest memory or the number of guest processors, (see
-        <xref linkend="generalsettings"/>) and the enabled features for that guest
-        (for example remote control, certain screen settings and others).
-      </para>
-    </sect2>
-
-    <sect2>
+
+      <para>
+        One property of virtual machine monitors (VMMs) like VirtualBox
+        is to encapsulate a guest by executing it in a protected
+        environment, a virtual machine, running as a user process on the
+        host operating system. The guest cannot communicate directly
+        with the hardware or other computers but only through the VMM.
+        The VMM provides emulated physical resources and devices to the
+        guest which are accessed by the guest operating system to
+        perform the required tasks. The VM settings control the
+        resources provided to the guest, for example the amount of guest
+        memory or the number of guest processors and the enabled
+        features for that guest. For example remote control, certain
+        screen settings and others. See
+        <xref linkend="generalsettings"/>.
+      </para>
+
+    </sect2>
+
+    <sect2 id="secure-config-vms">
+
       <title>Secure Configuration of Virtual Machines</title>
-      <para>
-        Several aspects of a virtual machine configuration are subject to security
-        considerations.</para>
-
-      <sect3>
+
+      <para>
+        Several aspects of a virtual machine configuration are subject
+        to security considerations.
+      </para>
+
+      <sect3 id="security-networking">
+
         <title>Networking</title>
+
         <para>
           The default networking mode for VMs is NAT which means that
@@ -175,216 +215,302 @@
           <xref linkend="network_nat"/>. The guest is part of a private
           subnet belonging to this VM and the guest IP is not visible
-          from the outside. This networking mode works without
-          any additional setup and is sufficient for many purposes.
-        </para>
-        <para>
-          If bridged networking is used, the VM acts like a computer inside
-          the same network as the host, see <xref linkend="network_bridged"/>.
-          In this case, the guest has the same network access as the host and
-          a firewall might be necessary to protect other computers on the
-          subnet from a potential malicious guest as well as to protect the
-          guest from a direct access from other computers. In some cases it is
-          worth considering using a forwarding rule for a specific port in NAT
-          mode instead of using bridged networking.
-        </para>
-        <para>
-          Some setups do not require a VM to be connected to the public network
-          at all. Internal networking (see <xref linkend="network_internal"/>)
-          or host-only networking (see <xref linkend="network_hostonly"/>)
-          are often sufficient to connect VMs among each other or to connect
-          VMs only with the host but not with the public network.
-        </para>
-      </sect3>
-
-      <sect3>
-        <title>VRDP remote desktop authentication</title>
-        <para>When using the VirtualBox extension pack provided by Oracle
-          for VRDP remote desktop support, you can optionally use various
-          methods to configure RDP authentication. The "null" method is
-          very insecure and should be avoided in a public network.
-          See <xref linkend="vbox-auth" /> for details.</para>
+          from the outside. This networking mode works without any
+          additional setup and is sufficient for many purposes.
+        </para>
+
+        <para>
+          If bridged networking is used, the VM acts like a computer
+          inside the same network as the host, see
+          <xref linkend="network_bridged"/>. In this case, the guest has
+          the same network access as the host and a firewall might be
+          necessary to protect other computers on the subnet from a
+          potential malicious guest as well as to protect the guest from
+          a direct access from other computers. In some cases it is
+          worth considering using a forwarding rule for a specific port
+          in NAT mode instead of using bridged networking.
+        </para>
+
+        <para>
+          Some setups do not require a VM to be connected to the public
+          network at all. Internal networking, see
+          <xref linkend="network_internal"/>, or host-only networking,
+          see <xref linkend="network_hostonly"/>, are often sufficient
+          to connect VMs among each other or to connect VMs only with
+          the host but not with the public network.
+        </para>
+
+      </sect3>
+
+      <sect3 id="security-vrdp-auth">
+
+        <title>VRDP Remote Desktop Authentication</title>
+
+        <para>
+          When using the VirtualBox extension pack provided by Oracle
+          for VRDP remote desktop support, you can optionally use
+          various methods to configure RDP authentication. The "null"
+          method is very insecure and should be avoided in a public
+          network. See <xref linkend="vbox-auth" />.
+        </para>
+
       </sect3>
 
       <sect3 id="security_clipboard">
+
         <title>Clipboard</title>
-        <para>
-          The shared clipboard allows users to share data between the host and
-          the guest. Enabling the clipboard in "Bidirectional" mode allows
-          the guest to read and write the host clipboard. The "Host to guest"
-          mode and the "Guest to host" mode limit the access to one
-          direction. If the guest is able to access the host clipboard it
-          can also potentially access sensitive data from the host which is
-          shared over the clipboard.
-        </para>
-        <para>
-          If the guest is able to read from and/or write to the host clipboard
-          then a remote user connecting to the guest over the network will also
-          gain this ability, which may not be desirable. As a consequence, the
-          shared clipboard is disabled for new machines.
-        </para>
-      </sect3>
-
-      <sect3>
-        <title>Shared folders</title>
-        <para>If any host folder is shared with the guest then a remote
-          user connected to the guest over the network can access
-          these files too as the folder sharing mechanism cannot be
-          selectively disabled for remote users.
-        </para>
-      </sect3>
-
-      <sect3>
-        <title>3D graphics acceleration</title>
-        <para>Enabling 3D graphics via the Guest Additions exposes the host
-          to additional security risks; see <xref
-          linkend="guestadd-3d" />.</para>
-      </sect3>
-
-      <sect3>
-        <title>CD/DVD passthrough</title>
-        <para>Enabling CD/DVD passthrough allows the guest to perform advanced
-          operations on the CD/DVD drive, see <xref linkend="storage-cds"/>.
-          This could induce a security risk as a guest could overwrite data
-          on a CD/DVD medium.
-        </para>
-      </sect3>
-
-      <sect3>
-        <title>USB passthrough</title>
-        <para>
-          Passing USB devices to the guest provides the guest full access
-          to these devices, see <xref linkend="settings-usb"/>. For instance,
-          in addition to reading and writing the content of the partitions
-          of an external USB disk the guest will be also able to read and
-          write the partition table and hardware data of that disk.
-        </para>
-      </sect3>
-
-    </sect2>
-
-    <sect2>
+
+        <para>
+          The shared clipboard allows users to share data between the
+          host and the guest. Enabling the clipboard in Bidirectional
+          mode allows the guest to read and write the host clipboard.
+          The Host to Guest mode and the Guest to Host mode limit the
+          access to one direction. If the guest is able to access the
+          host clipboard it can also potentially access sensitive data
+          from the host which is shared over the clipboard.
+        </para>
+
+        <para>
+          If the guest is able to read from and/or write to the host
+          clipboard then a remote user connecting to the guest over the
+          network will also gain this ability, which may not be
+          desirable. As a consequence, the shared clipboard is disabled
+          for new machines.
+        </para>
+
+      </sect3>
+
+      <sect3 id="security-shared-folders">
+
+        <title>Shared Folders</title>
+
+        <para>
+          If any host folder is shared with the guest then a remote user
+          connected to the guest over the network can access these files
+          too as the folder sharing mechanism cannot be selectively
+          disabled for remote users.
+        </para>
+
+      </sect3>
+
+      <sect3 id="security-3d-graphics">
+
+        <title>3D Graphics Acceleration</title>
+
+        <para>
+          Enabling 3D graphics via the Guest Additions exposes the host
+          to additional security risks. See
+          <xref
+          linkend="guestadd-3d" />.
+        </para>
+
+      </sect3>
+
+      <sect3 id="security-cd-dvd-passthrough">
+
+        <title>CD/DVD Passthrough</title>
+
+        <para>
+          Enabling CD/DVD passthrough allows the guest to perform
+          advanced operations on the CD/DVD drive, see
+          <xref linkend="storage-cds"/>. This could induce a security
+          risk as a guest could overwrite data on a CD/DVD medium.
+        </para>
+
+      </sect3>
+
+      <sect3 id="security-usb-passthrough">
+
+        <title>USB Passthrough</title>
+
+        <para>
+          Passing USB devices to the guest provides the guest full
+          access to these devices, see <xref linkend="settings-usb"/>.
+          For instance, in addition to reading and writing the content
+          of the partitions of an external USB disk the guest will be
+          also able to read and write the partition table and hardware
+          data of that disk.
+        </para>
+
+      </sect3>
+
+    </sect2>
+
+    <sect2 id="auth-config-using">
+
       <title>Configuring and Using Authentication</title>
 
-      <para>The following components of VirtualBox can use passwords for
-        authentication:<itemizedlist>
-
-        <listitem>
-          <para>When using remote iSCSI storage and the storage server
-          requires authentication, an initiator secret can optionally be supplied
-          with the <computeroutput>VBoxManage storageattach</computeroutput>
-          command. As long as no settings password is provided (command line
-          option <screen>--settingspwfile</screen>, this secret is
-          stored <emphasis role="bold">unencrypted</emphasis> in the machine
-          configuration and is therefore potentially readable on the host.
-          See <xref
-          linkend="storage-iscsi" /> and <xref
-          linkend="vboxmanage-storageattach" />.</para>
-        </listitem>
-
-        <listitem>
-          <para>When using the VirtualBox web service to control a VirtualBox
-          host remotely, connections to the web service are authenticated in
-          various ways. This is described in detail in the VirtualBox Software
-          Development Kit (SDK) reference; please see <xref
-          linkend="VirtualBoxAPI" />.</para>
-        </listitem>
-      </itemizedlist></para>
-    </sect2>
-
-    <!--
-    <sect2>
+      <para>
+        The following components of VirtualBox can use passwords for
+        authentication:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            When using remote iSCSI storage and the storage server
+            requires authentication, an initiator secret can optionally
+            be supplied with the <computeroutput>VBoxManage
+            storageattach</computeroutput> command. As long as no
+            settings password is provided, by using the command line
+            option <option>--settingspwfile</option>, then this secret
+            is stored <emphasis>unencrypted</emphasis> in the machine
+            configuration and is therefore potentially readable on the
+            host. See <xref
+          linkend="storage-iscsi" /> and
+            <xref
+          linkend="vboxmanage-storageattach" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            When using the VirtualBox web service to control a
+            VirtualBox host remotely, connections to the web service are
+            authenticated in various ways. This is described in detail
+            in the VirtualBox Software Development Kit (SDK) reference.
+            See <xref
+          linkend="VirtualBoxAPI" />.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
+<!--
+    <sect2 id="access-control-config-using">
       <title>Configuring and Using Access Control</title>
     </sect2>
 
-    <sect2>
+    <sect2 id="security-audit-config-using">
       <title>Configuring and Using Security Audit</title>
     </sect2>
 
-    <sect2>
-      <title>Congiguring and Using Other Security Features</title>
+    <sect2 id="security-other-features-config-using">
+      <title>Configuring and Using Other Security Features</title>
     </sect2>
     -->
 
     <sect2 id="pot-insecure">
-    <title>Potentially insecure operations</title>
-
-      <para>The following features of VirtualBox can present security
-        problems:<itemizedlist>
-        <listitem>
-          <para>Enabling 3D graphics via the Guest Additions exposes the host
-          to additional security risks; see <xref
-          linkend="guestadd-3d" />.</para>
-        </listitem>
-
-        <listitem>
-          <para>When teleporting a machine, the data stream through which the
-          machine's memory contents are transferred from one host to another
-          is not encrypted. A third party with access to the network through
-          which the data is transferred could therefore intercept that
-          data. An SSH tunnel could be used to secure the connection between
-          the two hosts. But when considering teleporting a VM over an untrusted
-          network the first question to answer is how both VMs can securely
-          access the same virtual disk image(s) with a reasonable performance. </para>
-        </listitem>
-
-        <listitem>
-          <para>When Page Fusion (see <xref linkend="guestadd-pagefusion"/>)
-          is enabled, it is possible that a side-channel opens up that allows
-          a malicious guest to determine the address space layout (i.e. where
-          DLLs are typically loaded) of one other VM running on the same host.
-          This information leak in it self is harmless, however the malicious
-          guest may use it to optimize attack against that VM via unrelated
-          attack vectors.  It is recommended to only enable Page Fusion if you
-          do not think this is a concern in your setup.</para>
-        </listitem>
-
-        <listitem>
-          <para>When using the VirtualBox web service to control a VirtualBox
-          host remotely, connections to the web service (through which the API
-          calls are transferred via SOAP XML) are not encrypted, but use plain
-          HTTP by default. This is a potential security risk! For details about
-          the web service, please see <xref linkend="VirtualBoxAPI" />.</para>
-          <para>The web services are not started by default. Please refer to
-          <xref linkend="vboxwebsrv-daemon"/> to find out how to start this
-          service and how to enable SSL/TLS support. It has to be started as
-          a regular user and only the VMs of that user can be controlled. By
-          default, the service binds to localhost preventing any remote connection.</para>
-        </listitem>
-
-        <listitem>
-          <para>Traffic sent over a UDP Tunnel network attachment is not
-          encrypted. You can either encrypt it on the host network level (with
-          IPsec), or use encrypted protocols in the guest network (such as
-          SSH). The security properties are similar to bridged Ethernet.</para>
-        </listitem>
-
-        <listitem>
-          <para>Because of shortcomings in older Windows versions, using
-          VirtualBox on Windows versions older than Vista with Service Pack 1
-          is not recommended.</para>
-        </listitem>
-
-      </itemizedlist></para>
-    </sect2>
-
-    <sect2>
+
+      <title>Potentially Insecure Operations</title>
+
+      <para>
+        The following features of VirtualBox can present security
+        problems:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Enabling 3D graphics via the Guest Additions exposes the
+            host to additional security risks. See
+            <xref
+          linkend="guestadd-3d" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            When teleporting a machine, the data stream through which
+            the machine's memory contents are transferred from one host
+            to another is not encrypted. A third party with access to
+            the network through which the data is transferred could
+            therefore intercept that data. An SSH tunnel could be used
+            to secure the connection between the two hosts. But when
+            considering teleporting a VM over an untrusted network the
+            first question to answer is how both VMs can securely access
+            the same virtual disk image with a reasonable performance.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            When Page Fusion, see <xref linkend="guestadd-pagefusion"/>,
+            is enabled, it is possible that a side-channel opens up that
+            allows a malicious guest to determine the address space of
+            another VM running on the same host layout. For example,
+            where DLLs are typically loaded. This information leak in
+            itself is harmless, however the malicious guest may use it
+            to optimize attack against that VM via unrelated attack
+            vectors. It is recommended to only enable Page Fusion if you
+            do not think this is a concern in your setup.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            When using the VirtualBox web service to control a
+            VirtualBox host remotely, connections to the web service,
+            over which the API calls are transferred using SOAP XML, are
+            not encrypted. They use plain HTTP by default. This is a
+            potential security risk. For details about the web service,
+            see <xref linkend="VirtualBoxAPI" />.
+          </para>
+
+          <para>
+            The web services are not started by default. See
+            <xref linkend="vboxwebsrv-daemon"/> to find out how to start
+            this service and how to enable SSL/TLS support. It has to be
+            started as a regular user and only the VMs of that user can
+            be controlled. By default, the service binds to localhost
+            preventing any remote connection.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Traffic sent over a UDP Tunnel network attachment is not
+            encrypted. You can either encrypt it on the host network
+            level, with IPsec, or use encrypted protocols in the guest
+            network, such as SSH. The security properties are similar to
+            bridged Ethernet.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Because of shortcomings in older Windows versions, using
+            VirtualBox on Windows versions older than Vista with Service
+            Pack 1 is not recommended.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="security-encryption">
+
       <title>Encryption</title>
 
-      <para>The following components of VirtualBox use encryption to protect
-        sensitive data:<itemizedlist>
-        <listitem>
-          <para>When using the VirtualBox extension pack provided by Oracle
-          for VRDP remote desktop support, RDP data can optionally be
-          encrypted. See <xref linkend="vrde-crypt" /> for details. Only
-          the Enhanced RDP Security method (RDP5.2) with TLS protocol
-          provides a secure connection. Standard RDP Security (RDP4 and
-          RDP5.1) is vulnerable to a man-in-the-middle attack.</para>
-        </listitem>
-      </itemizedlist></para>
-    </sect2>
+      <para>
+        The following components of VirtualBox use encryption to protect
+        sensitive data:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            When using the VirtualBox extension pack provided by Oracle
+            for VRDP remote desktop support, RDP data can optionally be
+            encrypted. See <xref linkend="vrde-crypt" />. Only the
+            Enhanced RDP Security method (RDP5.2) with TLS protocol
+            provides a secure connection. Standard RDP Security (RDP4
+            and RDP5.1) is vulnerable to a man-in-the-middle attack.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
   </sect1>
 
-  <!--
-  <sect1>
+<!--
+  <sect1 id="security-devel">
     <title>Security Considerations for Developers</title>
   </sect1>
Index: /trunk/doc/manual/en_US/user_Storage.xml
===================================================================
--- /trunk/doc/manual/en_US/user_Storage.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_Storage.xml	(revision 73276)
@@ -1,986 +1,1485 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="storage">
-  <title>Virtual storage</title>
-
-  <para>As the virtual machine will most probably expect to see a hard disk
-  built into its virtual computer, VirtualBox must be able to present "real"
-  storage to the guest as a virtual hard disk. There are presently three
-  methods in which to achieve this:</para>
-
-  <orderedlist>
+
+  <title>Virtual Storage</title>
+
+  <para>
+    As the virtual machine will most probably expect to see a hard disk
+    built into its virtual computer, VirtualBox must be able to present
+    real storage to the guest as a virtual hard disk. There are
+    presently three methods by which to achieve this:
+  </para>
+
+  <itemizedlist>
+
     <listitem>
-      <para>Most commonly, VirtualBox will use large image files on a real
-      hard disk and present them to a guest as a virtual hard disk. This is
-      described in <xref linkend="vdidetails" />.</para>
+      <para>
+        VirtualBox can use large image files on a real hard disk and
+        present them to a guest as a virtual hard disk. This is the most
+        common method, described in <xref linkend="vdidetails" />.
+      </para>
     </listitem>
 
     <listitem>
-      <para>Alternatively, if you have iSCSI storage servers, you can attach
-      such a server to VirtualBox as well; this is described in <xref
-      linkend="storage-iscsi" />.</para>
+      <para>
+        iSCSI storage servers can be attached to VirtualBox. This is
+        described in <xref
+      linkend="storage-iscsi" />.
+      </para>
     </listitem>
 
     <listitem>
-      <para>Finally, as an advanced feature, you can allow a virtual
-      machine to access one of your host disks directly; this advanced feature
-      is described in <xref linkend="rawdisk" />.</para>
+      <para>
+        You can allow a virtual machine to access one of your host disks
+        directly. This is an advanced feature, described in
+        <xref linkend="rawdisk" />.
+      </para>
     </listitem>
-  </orderedlist>
-
-  <para>Each such virtual storage device (image file, iSCSI target or physical
-  hard disk) will need to be connected to the virtual hard disk controller
-  that VirtualBox presents to a virtual machine. This is explained in the next
-  section.</para>
+
+  </itemizedlist>
+
+  <para>
+    Each such virtual storage device, such as an image file, iSCSI
+    target, or physical hard disk, needs to be connected to the virtual
+    hard disk controller that VirtualBox presents to a virtual machine.
+    This is explained in the next section.
+  </para>
 
   <sect1 id="harddiskcontrollers">
-    <title>Hard disk controllers: IDE, SATA (AHCI), SCSI, SAS, USB MSD, NVMe</title>
-
-    <para>In a real PC, hard disks and CD/DVD drives are connected to a device
-    called hard disk controller which drives hard disk operation and data
-    transfers. VirtualBox can emulate the five most common types of hard disk
-    controllers typically found in today's PCs: IDE, SATA (AHCI), SCSI,
-    SAS, USB-based and NVMe mass storage devices.<footnote>
-        <para>SATA support was added with VirtualBox 1.6; experimental SCSI
-        support was added with 2.1 and fully implemented with 2.2. Generally,
-        storage attachments were made much more flexible with VirtualBox 3.1;
-        see below. Support for the LSI Logic SAS controller was added with
-        VirtualBox 3.2; USB mass storage devices are supported since
-        VirtualBox 5.0; NVMe controller support was added with VirtualBox 5.1.</para>
-      </footnote><itemizedlist>
-        <listitem>
-          <para><emphasis role="bold">IDE (ATA)</emphasis> controllers are a
+
+    <title>Hard Disk Controllers: IDE, SATA (AHCI), SCSI, SAS, USB MSD, NVMe</title>
+
+    <para>
+      In a real PC, hard disks and CD/DVD drives are connected to a
+      device called hard disk controller which drives hard disk
+      operation and data transfers. VirtualBox can emulate the five most
+      common types of hard disk controllers typically found in today's
+      PCs: IDE, SATA (AHCI), SCSI, SAS, USB-based, and NVMe mass storage
+      devices.
+
+      <footnote>
+
+        <para>
+          SATA support was added with VirtualBox 1.6; experimental SCSI
+          support was added with 2.1 and fully implemented with 2.2.
+          Generally, storage attachments were made much more flexible
+          with VirtualBox 3.1. Support for the LSI Logic SAS controller
+          was added with VirtualBox 3.2. USB mass storage devices are
+          supported since VirtualBox 5.0. NVMe controller support was
+          added with VirtualBox 5.1.
+        </para>
+
+      </footnote>
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">IDE (ATA)</emphasis> controllers are a
           backwards compatible yet very advanced extension of the disk
           controller in the IBM PC/AT (1984). Initially, this interface
-          worked only with hard disks, but was later extended to also support
-          CD-ROM drives and other types of removable media. In physical PCs,
-          this standard uses flat ribbon parallel cables with 40 or 80 wires.
-          Each such cable can connect two devices to a controller, which have
-          traditionally been called "master" and "slave". Typical PCs had
-          two connectors for such cables; as a result, support for up to four
-          IDE devices was most common.</para>
-
-          <para>In VirtualBox, each virtual machine may have one IDE
+          worked only with hard disks, but was later extended to also
+          support CD-ROM drives and other types of removable media. In
+          physical PCs, this standard uses flat ribbon parallel cables
+          with 40 or 80 wires. Each such cable can connect two devices
+          to a controller, which have traditionally been called
+          <emphasis>master</emphasis> and <emphasis>slave</emphasis>.
+          Typical PCs had two connectors for such cables. As a result,
+          support for up to four IDE devices was most common.
+        </para>
+
+        <para>
+          In VirtualBox, each virtual machine may have one IDE
           controller enabled, which gives you up to four virtual storage
-          devices that you can attach to the machine. (By default, one of
-          these four -- the secondary master -- is preconfigured to be the
-          machine's virtual CD/DVD drive, but this can be changed.<footnote>
-              <para>The assignment of the machine's CD/DVD drive to the
-              secondary master was fixed before VirtualBox 3.1; it is now
-              changeable, and the drive can be at other slots of the IDE
-              controller, and there can be more than one such drive.</para>
-            </footnote>)</para>
-
-          <para>So even if your guest operating system has no support for SCSI
-          or SATA devices, it should always be able to see an IDE controller.
+          devices that you can attach to the machine. By default, one of
+          these four, the secondary master, is preconfigured to be the
+          machine's virtual CD/DVD drive, but this can be changed.
+
+          <footnote>
+
+            <para>
+              The assignment of the machine's CD/DVD drive to the
+              secondary master was fixed before VirtualBox 3.1. It is
+              now changeable, and the drive can be at other slots of the
+              IDE controller, and there can be more than one such drive.
+            </para>
+
+          </footnote>
+
+          )
+        </para>
+
+        <para>
+          Even if your guest operating system has no support for SCSI or
+          SATA devices, it should always be able to see an IDE
+          controller.
+        </para>
+
+        <para>
+          You can also select which exact type of IDE controller
+          hardware VirtualBox should present to the virtual machine:
+          PIIX3, PIIX4, or ICH6. This makes no difference in terms of
+          performance, but if you import a virtual machine from another
+          virtualization product, the operating system in that machine
+          may expect a particular controller type and crash if it is not
+          found.
+        </para>
+
+        <para>
+          After you have created a new virtual machine with the New
+          Virtual Machine wizard of the graphical user interface, you
+          will typically see one IDE controller in the machine's Storage
+          settings. The virtual CD/DVD drive will be attached to one of
+          the four ports of this controller.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Serial ATA (SATA)</emphasis> is a newer
+          standard introduced in 2003. Compared to IDE, it supports both
+          much higher speeds and more devices per controller. Also, with
+          physical hardware, devices can be added and removed while the
+          system is running. The standard interface for SATA controllers
+          is called Advanced Host Controller Interface (AHCI).
+        </para>
+
+        <para>
+          Like a real SATA controller, VirtualBox's virtual SATA
+          controller operates faster and also consumes fewer CPU
+          resources than the virtual IDE controller. Also, this allows
+          you to connect up to 30 virtual hard disks to one machine
+          instead of just three, when compared to the VirtualBox IDE
+          controller with a DVD drive attached.
+        </para>
+
+        <para>
+          For this reason, starting with version 3.2 and depending on
+          the selected guest operating system, VirtualBox uses SATA as
+          the default for newly created virtual machines. One virtual
+          SATA controller is created by default, and the default disk
+          that is created with a new VM is attached to this controller.
+        </para>
+
+        <warning>
+          <para>
+            The entire SATA controller and the virtual disks attached to
+            it, including those in IDE compatibility mode, will not be
+            seen by operating systems that do not have device support
+            for AHCI. In particular, <emphasis>there is no support for
+            AHCI in Windows before Windows Vista</emphasis>, so Windows
+            XP (even SP3) will not see such disks unless you install
+            additional drivers. It is possible to switch from IDE to
+            SATA after installation by installing the SATA drivers and
+            changing the controller type in the VM settings dialog.
+
+            <footnote>
+
+              <para>
+                VirtualBox recommends the Intel Matrix Storage drivers,
+                which can be downloaded from
+                <ulink
+                  url="http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101">http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101</ulink>.
+              </para>
+
+            </footnote>
           </para>
-
-          <para>You can also select which exact type of IDE controller
-          hardware VirtualBox should present to the virtual machine (PIIX3,
-          PIIX4 or ICH6). This makes no difference in terms of performance,
-          but if you import a virtual machine from another virtualization
-          product, the operating system in that machine may expect a
-          particular controller type and crash if it isn't found.</para>
-
-          <para>After you have created a new virtual machine with the "New
-          Virtual Machine" wizard of the graphical user interface, you will
-          typically see one IDE controller in the machine's "Storage" settings
-          where the virtual CD/DVD drive will be attached to one of the four
-          ports of this controller.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Serial ATA (SATA)</emphasis> is a newer
-          standard introduced in 2003. Compared to IDE, it supports both much
-          higher speeds and more devices per controller. Also, with
-          physical hardware, devices can be added and removed while the system
-          is running. The standard interface for SATA controllers is called
-          Advanced Host Controller Interface (<emphasis
-          role="bold">AHCI</emphasis>).</para>
-
-          <para>Like a real SATA controller, VirtualBox's virtual SATA
-          controller operates faster and also consumes fewer CPU resources than
-          the virtual IDE controller. Also, this allows you to connect up to
-          30 virtual hard disks to one machine instead of just three, as with
-          the VirtualBox IDE controller (with the DVD drive already attached).</para>
-
-          <para>For this reason, starting with version 3.2 and depending on
-          the selected guest operating system, VirtualBox uses SATA as the
-          default for newly created virtual machines. One virtual SATA
-          controller is created by default, and the default disk that is
-          created with a new VM is attached to this controller.<warning>
-              <para>The entire SATA controller and the virtual disks attached
-              to it (including those in IDE compatibility mode) will not be
-              seen by operating systems that do not have device support for
-              AHCI. In particular, <emphasis role="bold">there is no support
-              for AHCI in Windows before Windows Vista</emphasis>, so Windows
-              XP (even SP3) will not see such disks unless you install
-              additional drivers. It is possible to switch from IDE to SATA
-              after installation by installing the SATA drivers and changing
-              the controller type in the VM settings dialog.<footnote>
-                  <para>VirtualBox recommends the Intel Matrix Storage drivers
-                  which can be downloaded from <ulink
-                  url="http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101">http://downloadcenter.intel.com/Product_Filter.aspx?ProductID=2101</ulink>.</para>
-                </footnote></para>
-            </warning></para>
-
-          <para>To add a SATA controller to a machine for which it has not
-          been enabled by default (either because it was created by an earlier
-          version of VirtualBox, or because SATA is not supported by default
-          by the selected guest operating system), go to the "Storage" page of
-          the machine's settings dialog, click on the "Add Controller" button
-          under the "Storage Tree" box and then select "Add SATA Controller".
-          After this, the additional controller will appear as a separate PCI
-          device in the virtual machine, and you can add virtual disks to
-          it.</para>
-
-          <para>To change the IDE compatibility mode settings for the SATA
-          controller, please see <xref
-          linkend="vboxmanage-storagectl" />.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">SCSI</emphasis> is another established
-          industry standard, standing for "Small Computer System Interface".
-          SCSI was standardized as early as 1986 as a generic interface for
-          data transfer between all kinds of devices, including storage
-          devices. Today SCSI is still used for connecting hard disks and tape
-          devices, but it has mostly been displaced in commodity hardware. It
-          is still in common use in high-performance workstations and
-          servers.</para>
-
-          <para>Primarily for compatibility with other virtualization
-          software, VirtualBox optionally supports LSI Logic and BusLogic SCSI
-          controllers, to each of which up to 15 virtual hard disks can be
-          attached.</para>
-
-          <para>To enable a SCSI controller, on the "Storage" page of a
-          virtual machine's settings dialog, click on the "Add Controller"
-          button under the "Storage Tree" box and then select "Add SCSI
-          Controller". After this, the additional controller will appear as a
-          separate PCI device in the virtual machine.<warning>
-              <para>As with the other controller types, a SCSI controller will
-              only be seen by operating systems with device support for it.
-              Windows 2003 and later ships with drivers for the LSI Logic
-              controller, while Windows NT 4.0 and Windows 2000 ships with
-              drivers for the BusLogic controller. Windows XP ships with
-              drivers for neither.</para>
-            </warning></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Serial Attached SCSI (SAS)</emphasis> is
-          another bus standard which uses the SCSI command set. As opposed to
-          SCSI, however, with physical devices, serial cables are used instead
-          of parallel ones, which simplifies physical device connections. In
-          some ways, therefore, SAS is to SCSI what SATA is to IDE: it allows
-          for more reliable and faster connections.</para>
-
-          <para>To support high-end guests which require SAS controllers,
-          VirtualBox emulates a LSI Logic SAS controller, which can be enabled
-          much the same way as a SCSI controller. At this time, up to eight
-          devices can be connected to the SAS controller.</para>
+        </warning>
+
+        <para>
+          To add a SATA controller to a machine for which it has not
+          been enabled by default, either because it was created by an
+          earlier version of VirtualBox, or because SATA is not
+          supported by default by the selected guest operating system,
+          do the following. Go to the Storage page of the machine's
+          settings dialog, click <emphasis role="bold">Add
+          Controller</emphasis> under the Storage Tree box and then
+          select <emphasis role="bold">Add SATA Controller</emphasis>.
+          The new controller appears as a separate PCI device in the
+          virtual machine, and you can add virtual disks to it.
+        </para>
+
+        <para>
+          To change the IDE compatibility mode settings for the SATA
+          controller, see
+          <xref
+          linkend="vboxmanage-storagectl" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">SCSI</emphasis> is another established
+          industry standard, standing for Small Computer System
+          Interface. SCSI was standardized as early as 1986 as a generic
+          interface for data transfer between all kinds of devices,
+          including storage devices. Today SCSI is still used for
+          connecting hard disks and tape devices, but it has mostly been
+          displaced in commodity hardware. It is still in common use in
+          high-performance workstations and servers.
+        </para>
+
+        <para>
+          Primarily for compatibility with other virtualization
+          software, VirtualBox optionally supports LSI Logic and
+          BusLogic SCSI controllers, to each of which up to 15 virtual
+          hard disks can be attached.
+        </para>
+
+        <para>
+          To enable a SCSI controller, on the Storage page of a virtual
+          machine's settings dialog, click <emphasis role="bold">Add
+          Controller</emphasis> under the Storage Tree box and then
+          select <emphasis role="bold">Add SCSI Controller</emphasis>.
+          The new controller appears as a separate PCI device in the
+          virtual machine.
+        </para>
+
+        <warning>
+          <para>
+            As with the other controller types, a SCSI controller will
+            only be seen by operating systems with device support for
+            it. Windows 2003 and later ships with drivers for the LSI
+            Logic controller, while Windows NT 4.0 and Windows 2000
+            ships with drivers for the BusLogic controller. Windows XP
+            ships with drivers for neither.
+          </para>
+        </warning>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Serial Attached SCSI (SAS)</emphasis> is
+          another bus standard which uses the SCSI command set. As
+          opposed to SCSI, however, with physical devices, serial cables
+          are used instead of parallel ones, which simplifies physical
+          device connections. In some ways, therefore, SAS is to SCSI
+          what SATA is to IDE: it allows for more reliable and faster
+          connections.
+        </para>
+
+        <para>
+          To support high-end guests which require SAS controllers,
+          VirtualBox emulates a LSI Logic SAS controller, which can be
+          enabled much the same way as a SCSI controller. At this time,
+          up to eight devices can be connected to the SAS controller.
+        </para>
+
+        <warning>
+          <para>
+            As with SATA, the SAS controller will only be seen by
+            operating systems with device support for it. In particular,
+            <emphasis>there is no support for SAS in Windows before
+            Windows Vista</emphasis>, so Windows XP (even SP3) will not
+            see such disks unless you install additional drivers.
+          </para>
+        </warning>
+      </listitem>
+
+      <listitem>
+        <para>
+          The <emphasis role="bold">USB mass storage device
+          class</emphasis> is a standard to connect external storage
+          devices like hard disks or flash drives to a host through USB.
+          All major operating systems support these devices for a long
+          time and ship generic drivers making third-party drivers
+          superfluous. In particular, legacy operating systems without
+          support for SATA controllers may benefit from USB mass storage
+          devices.
+        </para>
+
+        <para>
+          The virtual USB storage controller offered by VirtualBox works
+          differently to the other storage controller types. While most
+          storage controllers appear as a single PCI device to the guest
+          with multiple disks attached to it, the USB-based storage
+          controller does not appear as virtual storage controller. Each
+          disk attached to the controller appears as a dedicated USB
+          device to the guest.
+        </para>
+
+        <warning>
+          <para>
+            Booting from drives attached via USB is when EFI is used as
+            the BIOS lacks USB support.
+          </para>
+        </warning>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Non volatile memory express
+          (NVMe)</emphasis> is a very recent standard which emerged in
+          2011 connecting non volatile memory (NVM) directly over PCI
+          express to lift the bandwidth limitation of the previously
+          used SATA protocol for SSDs. Unlike other standards the
+          command set is very simple to achieve maximum throughput and
+          is not compatible with ATA or SCSI. Operating systems need to
+          support NVMe devices to make use of them. For example, Windows
+          8.1 added native NVMe support. For Windows 7, native support
+          was added with an update.
+
+          <footnote>
+
+            <para>
+              The NVMe controller is part of the extension pack.
+            </para>
+
+          </footnote>
+        </para>
+
+        <warning>
+          <para>
+            Booting from drives attached via NVMe is only supported when
+            EFI is used as the BIOS lacks the appropriate driver.
+          </para>
+        </warning>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      In summary, VirtualBox gives you the following categories of
+      virtual storage slots:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Four slots attached to the traditional IDE controller, which
+          are always present. One of these is typically a virtual CD/DVD
+          drive.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          30 slots attached to the SATA controller, if enabled and
+          supported by the guest operating system.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          15 slots attached to the SCSI controller, if enabled and
+          supported by the guest operating system.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Eight slots attached to the SAS controller, if enabled and
+          supported by the guest operating system.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Eight slots attached to the virtual USB controller, if enabled
+          and supported by the guest operating system.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Up to 255 slots attached to the NVMe controller, if enabled
+          and supported by the guest operating system.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Given this large choice of storage controllers, you may not know
+      which one to choose. In general, you should avoid IDE unless it is
+      the only controller supported by your guest. Whether you use SATA,
+      SCSI, or SAS does not make any real difference. The variety of
+      controllers is only supplied by VirtualBox for compatibility with
+      existing hardware and other hypervisors.
+    </para>
+
+  </sect1>
+
+  <sect1 id="vdidetails">
+
+    <title>Disk Image Files (VDI, VMDK, VHD, HDD)</title>
+
+    <para>
+      Disk image files reside on the host system and are seen by the
+      guest systems as hard disks of a certain geometry. When a guest
+      operating system reads from or writes to a hard disk, VirtualBox
+      redirects the request to the image file.
+    </para>
+
+    <para>
+      Like a physical disk, a virtual disk has a size (capacity), which
+      must be specified when the image file is created. As opposed to a
+      physical disk however, VirtualBox allows you to expand an image
+      file after creation, even if it has data already. See
+      <xref
+    linkend="vboxmanage-modifyvdi" />.
+
+      <footnote>
+
+        <para>
+          Image resizing was added with VirtualBox 4.0.
+        </para>
+
+      </footnote>
+    </para>
+
+    <para>
+      VirtualBox supports the following types of disk image files:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">VDI.</emphasis> Normally, VirtualBox
+          uses its own container format for guest hard disks. This is
+          called a Virtual Disk Image (VDI) file. This format is used
+          when you create a new virtual machine with a new disk.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">VMDK.</emphasis> VirtualBox also fully
+          supports the popular and open VMDK container format that is
+          used by many other virtualization products, in particular, by
+          VMware.
+
+          <footnote>
+
+            <para>
+              Initial support for VMDK was added with VirtualBox 1.4.
+              Since version 2.1, VirtualBox supports VMDK fully, meaning
+              that you can create snapshots and use all the other
+              advanced features described above for VDI images with VMDK
+              also.
+            </para>
+
+          </footnote>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">VHD.</emphasis> VirtualBox also fully
+          supports the VHD format used by Microsoft.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">HDD.</emphasis> Image files of Parallels
+          version 2 (HDD format) are also supported.
+
+          <footnote>
+
+            <para>
+              Support was added with VirtualBox 3.1.
+            </para>
+
+          </footnote>
+
+          Due to lack of documentation of the format, newer versions
+          such as 3 and 4 are not supported. You can however convert
+          such image files to version 2 format using tools provided by
+          Parallels.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Irrespective of the disk capacity and format, as mentioned in
+      <xref linkend="gui-createvm" />, there are two options for
+      creating a disk image: fixed-size or dynamically allocated.
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Fixed-size.</emphasis> If you create a
+          fixed-size image, an image file will be created on your host
+          system which has roughly the same size as the virtual disk's
+          capacity. So, for a 10 GB disk, you will have a 10 GB file.
+          Note that the creation of a fixed-size image can take a long
+          time depending on the size of the image and the write
+          performance of your hard disk.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Dynamically allocated.</emphasis> For
+          more flexible storage management, use a dynamically allocated
+          image. This will initially be very small and not occupy any
+          space for unused virtual disk sectors, but will grow every
+          time a disk sector is written to for the first time, until the
+          drive reaches the maximum capacity chosen when the drive was
+          created. While this format takes less space initially, the
+          fact that VirtualBox needs to expand the image file consumes
+          additional computing resources, so until the disk file size
+          has stabilized, write operations may be slower than with fixed
+          size disks. However, after a time the rate of growth will slow
+          and the average penalty for write operations will be
+          negligible.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="vdis">
+
+    <title>The Virtual Media Manager</title>
+
+    <para>
+      VirtualBox keeps track of all the hard disk, CD/DVD-ROM, and
+      floppy disk images which are in use by virtual machines. These are
+      often referred to as <emphasis>known media</emphasis> and come
+      from two sources:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          All media currently attached to virtual machines.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Registered media, for compatibility with VirtualBox versions
+          older than version 4.0. For details about how media
+          registration has changed with version 4.0, see
+          <xref
+          linkend="vboxconfigdata" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      The known media can be viewed and changed in the
+      <emphasis
+    role="bold">Virtual Media Manager</emphasis>, which
+      you can access from the File menu in the VirtualBox main window.
+    </para>
+
+    <mediaobject>
+      <imageobject>
+        <imagedata align="center" fileref="images/virtual-disk-manager.png"
+                     width="12cm" />
+      </imageobject>
+    </mediaobject>
+
+    <para>
+      The known media are conveniently grouped in separate tabs for the
+      three possible formats. These formats are:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Hard disk images, either in VirtualBox's own Virtual Disk
+          Image (VDI) format, or in the third-party formats listed in
+          <xref linkend="vdidetails"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          CD/DVD images in standard ISO format.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Floppy images in standard RAW format.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      For each image, the Virtual Media Manager shows you the full path
+      of the image file and other information, such as the virtual
+      machine the image is currently attached to, if any.
+    </para>
+
+    <para>
+      The Virtual Media Manager enables you to do the following:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Remove</emphasis> an image from the
+          registry. You can optionally delete the image file when doing
+          so.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Release</emphasis> an image. Detach it
+          from a virtual machine, if it is currently attached to one as
+          a virtual hard disk.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Copy</emphasis> a virtual hard disk, to
+          create another one. The target type can be different.
+          Available options are: VDI, VHD, or VMDK.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Modify</emphasis> the attributes of the
+          disk image file. Available options are: Normal, Immutable,
+          Writethrough, Shareable, Multi-attach.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Refresh</emphasis> the values for the
+          displayed attributes of the currently-selected disk image.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      These commands are accessible once a medium has been selected
+      either by selecting from the options shown at the top of the
+      window, or by right-clicking the medium and selecting from the
+      options shown on the drop-down menu.
+    </para>
+
+    <para>
+      Starting with version 4.0, to create a new disk image, you use the
+      Storage page in a virtual machine's settings dialog. This is
+      because disk images are now by default stored in each machine's
+      own folder.
+    </para>
+
+    <para>
+      Hard disk image files can be copied to other host systems and
+      imported into virtual machines there, although certain guest
+      systems, notably Windows 2000 and XP, will require that the new
+      virtual machine be set up in a similar way to the old one.
+    </para>
+
+    <note>
+      <para>
+        Do not simply make copies of virtual disk images. If you import
+        such a second copy into a virtual machine, VirtualBox will
+        complain with an error, since VirtualBox assigns a unique
+        identifier (UUID) to each disk image to make sure it is only
+        used once. See <xref
+        linkend="cloningvdis" />. Also, if
+        you want to copy a virtual machine to another system, VirtualBox
+        has an import/export facility that might be better suited for
+        your needs. See <xref linkend="ovf" />.
+      </para>
+    </note>
+
+  </sect1>
+
+  <sect1 id="hdimagewrites">
+
+    <title>Special Image Write Modes</title>
+
+    <para>
+      For each virtual disk image supported by VirtualBox, you can
+      determine separately how it should be affected by write operations
+      from a virtual machine and snapshot operations. This applies to
+      all of the aforementioned image formats (VDI, VMDK, VHD, or HDD)
+      and irrespective of whether an image is fixed-size or dynamically
+      allocated.
+    </para>
+
+    <para>
+      By default, images are in <emphasis>normal</emphasis> mode. To
+      mark an existing image with one of the non-standard modes listed
+      below, use <computeroutput>VBoxManage modifyhd</computeroutput>.
+      See <xref
+    linkend="vboxmanage-modifyvdi" />. Alternatively,
+      use VBoxManage to attach the image to a VM and use the
+      <computeroutput>--mtype</computeroutput> argument. See
+      <xref linkend="vboxmanage-storageattach" />.
+    </para>
+
+    <para>
+      The available virtual disk image modes are as follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Normal images</emphasis> have no
+          restrictions on how guests can read from and write to the
+          disk. This is the default image mode.
+        </para>
+
+        <para>
+          When you take a snapshot of your virtual machine as described
+          in <xref linkend="snapshots" />, the state of a normal hard
+          disk is recorded together with the snapshot, and when
+          reverting to the snapshot, its state will be fully reset.
+        </para>
+
+        <para>
+          The image file itself is not reset. Instead, when a snapshot
+          is taken, VirtualBox "freezes" the image file and no longer
+          writes to it. For the write operations from the VM, a second,
+          <emphasis>differencing</emphasis> image file is created which
+          receives only the changes to the original image. See
+          <xref linkend="diffimages"/>.
+        </para>
+
+        <para>
+          While you can attach the same normal image to more than one
+          virtual machine, only one of these virtual machines attached
+          to the same image file can be executed simultaneously, as
+          otherwise there would be conflicts if several machines write
+          to the same image file.
+
+          <footnote>
+
+            <para>
+              This restriction is more lenient now than it was before
+              VirtualBox 2.2. Previously, each normal disk image could
+              only be <emphasis>attached</emphasis> to one single
+              machine. Now it can be attached to more than one machine
+              so long as only one of these machines is running.
+            </para>
+
+          </footnote>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Write-through hard disks</emphasis> are
+          completely unaffected by snapshots. Their state is
+          <emphasis>not</emphasis> saved when a snapshot is taken, and
+          not restored when a snapshot is restored.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Shareable hard disks</emphasis> are a
+          variant of write-through hard disks. In principle they behave
+          exactly the same. Their state is <emphasis>not</emphasis>
+          saved when a snapshot is taken, and not restored when a
+          snapshot is restored. The difference only shows if you attach
+          such disks to several VMs. Shareable disks may be attached to
+          several VMs which may run concurrently. This makes them
+          suitable for use by cluster filesystems between VMs and
+          similar applications which are explicitly prepared to access a
+          disk concurrently. Only fixed size images can be used in this
+          way, and dynamically allocated images are rejected.
 
           <warning>
-            <para>As with SATA, the SAS controller will only be seen by
-            operating systems with device support for it. In particular,
-            <emphasis role="bold">there is no support for SAS in Windows
-            before Windows Vista</emphasis>, so Windows XP (even SP3) will not
-            see such disks unless you install additional drivers.</para>
+            <para>
+              This is an expert feature, and misuse can lead to data
+              loss, as regular filesystems are not prepared to handle
+              simultaneous changes by several parties.
+            </para>
           </warning>
-        </listitem>
-
-        <listitem>
-          <para>The <emphasis role="bold">USB mass storage device class</emphasis>
-          is a standard to connect external storage devices like hard disks or flash
-          drives to a host through USB. All major operating systems support these
-          devices for a long time and ship generic drivers making third-party
-          drivers superfluous. In particular legacy operating systems without
-          support for SATA controllers may benefit from USB mass storage devices.</para>
-          <para>The virtual USB storage controller offered by VirtualBox works
-          different than the other storage controller types: When storage
-          controllers appear as a single PCI device to the guest with multiple
-          disks attached to it, the USB-based storage controller does not appear
-          as virtual storage controller. Each disk attached to the controller
-          appears as a dedicated USB device to the guest.</para>
-          <warning>
-            <para>Booting from drives attached via USB is when EFI is used as the
-              BIOS lacks USB support.</para>
-          </warning>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Non volatile memory express (NVMe)</emphasis>
-          is a very recent standard which emerged in 2011 connecting non volatile
-          memory (NVM) directly over PCI express to lift the bandwidth limitation
-          of the previously used SATA protocol for SSDs. Unlike other standards
-          the command set is very simple to achieve maximum throughput and is
-          not compatible with ATA or SCSI. Operating systems need to support NVMe
-          devices to make use of them. For example Windows 8.1 added native NVMe
-          support, for Windows 7 native support was added with an update.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Immutable images</emphasis> only
+          remember write accesses temporarily while the virtual machine
+          is running. All changes are lost when the virtual machine is
+          powered on the next time. As a result, as opposed to Normal
+          images, the same immutable image can be used with several
+          virtual machines without restrictions.
+        </para>
+
+        <para>
+          Creating an immutable image makes little sense since it would
+          be initially empty and lose its contents with every machine
+          restart. You would have a disk that is always unformatted when
+          the machine starts up. Instead, you can first create a normal
+          image and then later mark it as immutable when you decide that
+          the contents are useful.
+        </para>
+
+        <para>
+          If you take a snapshot of a machine with immutable images,
+          then on every machine power-up, those images are reset to the
+          state of the last (current) snapshot, instead of the state of
+          the original immutable image.
+        </para>
+
+        <note>
+          <para>
+            As a special exception, immutable images are
+            <emphasis>not</emphasis> reset if they are attached to a
+            machine in a saved state or whose last snapshot was taken
+            while the machine was running. This is called an
+            <emphasis>online snapshot</emphasis>. As a result, if the
+            machine's current snapshot is an online snapshot, its
+            immutable images behave exactly like the a normal image. To
+            reenable the automatic resetting of such images, delete the
+            current snapshot of the machine.
+          </para>
+        </note>
+
+        <para>
+          VirtualBox never writes to an immutable image directly at all.
+          All write operations from the machine are directed to a
+          differencing image. The next time the VM is powered on, the
+          differencing image is reset so that every time the VM starts,
+          its immutable images have exactly the same content.
+
           <footnote>
-            <para>The NVMe controller is part of the extension pack.</para>
-          </footnote></para>
-          <warning>
-            <para>Booting from drives attached via NVMe is only supported when
-            EFI is used as the BIOS lacks the appropriate driver.</para>
-          </warning>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>In summary, VirtualBox gives you the following categories of virtual
-    storage slots:<orderedlist>
-        <listitem>
-          <para>four slots attached to the traditional IDE controller, which
-          are always present (one of which typically is a virtual CD/DVD
-          drive);</para>
-        </listitem>
-
-        <listitem>
-          <para>30 slots attached to the SATA controller, if enabled and
-          supported by the guest operating system;</para>
-        </listitem>
-
-        <listitem>
-          <para>15 slots attached to the SCSI controller, if enabled and
-          supported by the guest operating system;</para>
-        </listitem>
-
-        <listitem>
-          <para>eight slots attached to the SAS controller, if enabled and
-          supported by the guest operating system.</para>
-        </listitem>
-
-        <listitem>
-          <para>eight slots attached to the virtual USB controller, if enabled and
-          supported by the guest operating system.</para>
-        </listitem>
-
-        <listitem>
-          <para>up to 255 slots attached to the NVMe controller, if enabled and
-          supported by the guest operating system.</para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>Given this large choice of storage controllers, you may ask yourself
-    which one to choose. In general, you should avoid IDE unless it is the
-    only controller supported by your guest. Whether you use SATA, SCSI or SAS
-    does not make any real difference. The variety of controllers is only
-    supplied for VirtualBox for compatibility with existing hardware and other
-    hypervisors.</para>
+
+            <para>
+              This behavior also changed with VirtualBox 2.2.
+              Previously, the differencing images were discarded when
+              the machine session <emphasis>ended</emphasis>; now they
+              are discarded every time the machine is powered on.
+            </para>
+
+          </footnote>
+
+          The differencing image is only reset when the machine is
+          powered on from within VirtualBox, not when you reboot by
+          requesting a reboot from within the machine. This is also why
+          immutable images behave as described above when snapshots are
+          also present, which use differencing images as well.
+        </para>
+
+        <para>
+          If the automatic discarding of the differencing image on VM
+          startup does not fit your needs, you can turn it off using the
+          <computeroutput>autoreset</computeroutput> parameter of
+          <computeroutput>VBoxManage modifyhd</computeroutput>. See
+          <xref
+        linkend="vboxmanage-modifyvdi"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Multiattach mode images</emphasis> can
+          be attached to more than one virtual machine at the same time,
+          even if these machines are running simultaneously. For each
+          virtual machine to which such an image is attached, a
+          differencing image is created. As a result, data that is
+          written to such a virtual disk by one machine is not seen by
+          the other machines to which the image is attached. Each
+          machine creates its own write history of the multiattach
+          image.
+        </para>
+
+        <para>
+          Technically, a multiattach image behaves identically to an
+          immutable image except the differencing image is not reset
+          every time the machine starts.
+        </para>
+
+        <para>
+          This mode is useful for sharing files which are almost never
+          written, for instance picture galleries, where every guest
+          changes only a small amount of data and the majority of the
+          disk content remains unchanged. The modified blocks are stored
+          in differencing images which remain relatively small and the
+          shared content is stored only once at the host.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Read-only images</emphasis> are used
+          automatically for CD/DVD images, since CDs/DVDs can never be
+          written to.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      The following scenario illustrates the differences between the
+      various image modes, with respect to snapshots.
+    </para>
+
+    <para>
+      Assume you have installed your guest operating system in your VM,
+      and you have taken a snapshot. Later, your VM is infected with a
+      virus and you would like to go back to the snapshot. With a normal
+      hard disk image, you simply restore the snapshot, and the earlier
+      state of your hard disk image will be restored as well and your
+      virus infection will be undone. With an immutable hard disk, all
+      it takes is to shut down and power on your VM, and the virus
+      infection will be discarded. With a write-through image however,
+      you cannot easily undo the virus infection by means of
+      virtualization, but will have to disinfect your virtual machine
+      like a real computer.
+    </para>
+
+    <para>
+      You might find write-through images useful if you want to preserve
+      critical data irrespective of snapshots. As you can attach more
+      than one image to a VM, you may want to have one immutable image
+      for the operating system and one write-through image for your data
+      files.
+    </para>
+
   </sect1>
 
-  <sect1 id="vdidetails">
-    <title>Disk image files (VDI, VMDK, VHD, HDD)</title>
-
-    <para>Disk image files reside on the host system and are seen by the guest
-    systems as hard disks of a certain geometry. When a guest operating system
-    reads from or writes to a hard disk, VirtualBox redirects the request to
-    the image file.</para>
-
-    <para>Like a physical disk, a virtual disk has a size (capacity), which
-    must be specified when the image file is created. As opposed to a physical
-    disk however, VirtualBox allows you to expand an image file after
-    creation, even if it has data already; see <xref
-    linkend="vboxmanage-modifyvdi" /> for details.<footnote>
-        <para>Image resizing was added with VirtualBox 4.0.</para>
-      </footnote></para>
-
-    <para>VirtualBox supports four variants of disk image files:<itemizedlist>
-        <listitem>
-          <para>Normally, VirtualBox uses its own container format for guest
-          hard disks -- Virtual Disk Image (VDI) files. In particular, this
-          format will be used when you create a new virtual machine with a new
-          disk.</para>
-        </listitem>
-
-        <listitem>
-          <para>VirtualBox also fully supports the popular and open VMDK
-          container format that is used by many other virtualization products,
-          in particular, by VMware.<footnote>
-              <para>Initial support for VMDK was added with VirtualBox 1.4;
-              since version 2.1, VirtualBox supports VMDK fully, meaning that
-              you can create snapshots and use all the other advanced features
-              described above for VDI images with VMDK also.</para>
-            </footnote></para>
-        </listitem>
-
-        <listitem>
-          <para>VirtualBox also fully supports the VHD format used by
-          Microsoft.</para>
-        </listitem>
-
-        <listitem>
-          <para>Image files of Parallels version 2 (HDD format) are also
-          supported.<footnote>
-              <para>Support was added with VirtualBox 3.1.</para>
-            </footnote> For lack of documentation of the format, newer formats
-          (3 and 4) are not supported. You can however convert such image
-          files to version 2 format using tools provided by Parallels.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>Irrespective of the disk capacity and format, as briefly mentioned
-    in <xref linkend="gui-createvm" />, there are two options of how to create
-    a disk image: fixed-size or dynamically allocated.</para>
+  <sect1 id="diffimages">
+
+    <title>Differencing Images</title>
+
+    <para>
+      The previous section mentioned differencing images and how they
+      are used with snapshots, immutable images, and multiple disk
+      attachments. This section describes in more detail how
+      differencing images work.
+    </para>
+
+    <para>
+      A differencing image is a special disk image that only holds the
+      differences to another image. A differencing image by itself is
+      useless, it must always refer to another image. The differencing
+      image is then typically referred to as a
+      <emphasis>child</emphasis>, which holds the differences to its
+      <emphasis>parent</emphasis>.
+    </para>
+
+    <para>
+      When a differencing image is active, it receives all write
+      operations from the virtual machine instead of its parent. The
+      differencing image only contains the sectors of the virtual hard
+      disk that have changed since the differencing image was created.
+      When the machine reads a sector from such a virtual hard disk, it
+      looks into the differencing image first. If the sector is present,
+      it is returned from there. If not, VirtualBox looks into the
+      parent. In other words, the parent becomes
+      <emphasis>read-only</emphasis>. It is never written to again, but
+      it is read from if a sector has not changed.
+    </para>
+
+    <para>
+      Differencing images can be chained. If another differencing image
+      is created for a virtual disk that already has a differencing
+      image, then it becomes a <emphasis>grandchild</emphasis> of the
+      original parent. The first differencing image then becomes
+      read-only as well, and write operations only go to the
+      second-level differencing image. When reading from the virtual
+      disk, VirtualBox needs to look into the second differencing image
+      first, then into the first if the sector was not found, and then
+      into the original image.
+    </para>
+
+    <para>
+      There can be an unlimited number of differencing images, and each
+      image can have more than one child. As a result, the differencing
+      images can form a complex tree with parents, siblings, and
+      children, depending on how complex your machine configuration is.
+      Write operations always go to the one <emphasis>active</emphasis>
+      differencing image that is attached to the machine, and for read
+      operations, VirtualBox may need to look up all the parents in the
+      chain until the sector in question is found. You can view such a
+      tree in the Virtual Media Manager:
+    </para>
+
+    <mediaobject>
+      <imageobject>
+        <imagedata align="center" fileref="images/virtual-disk-manager2.png"
+                     width="12cm" />
+      </imageobject>
+    </mediaobject>
+
+    <para>
+      In all of these situations, from the point of view of the virtual
+      machine, the virtual hard disk behaves like any other disk. While
+      the virtual machine is running, there is a slight run-time I/O
+      overhead because VirtualBox might need to look up sectors several
+      times. This is not noticeable however since the tables with sector
+      information are always kept in memory and can be looked up
+      quickly.
+    </para>
+
+    <para>
+      Differencing images are used in the following situations:
+    </para>
 
     <itemizedlist>
-      <listitem>
-        <para>If you create a <emphasis role="bold">fixed-size
-        image</emphasis>, an image file will be created on your host system
-        which has roughly the same size as the virtual disk's capacity. So,
-        for a 10G disk, you will have a 10G file. Note that the creation of a
-        fixed-size image can take a long time depending on the size of the
-        image and the write performance of your hard disk.</para>
-      </listitem>
-
-      <listitem>
-        <para>For more flexible storage management, use a <emphasis
-        role="bold">dynamically allocated image</emphasis>. This will
-        initially be very small and not occupy any space for unused virtual
-        disk sectors, but will grow every time a disk sector is written to for
-        the first time, until the drive reaches the maximum capacity chosen
-        when the drive was created. While this format takes less space
-        initially, the fact that VirtualBox needs to expand the image file
-        consumes additional computing resources, so until the disk file size has
-        stabilized, write operations may be slower than with fixed size disks.
-        However, after a time the rate of growth will slow and the average penalty
-        for write operations will be negligible.</para>
-      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Snapshots.</emphasis> When you create a
+          snapshot, as explained in the previous section, VirtualBox
+          "freezes" the images attached to the virtual machine and
+          creates differencing images for each image that is not in
+          "write-through" mode. From the point of view of the virtual
+          machine, the virtual disks continue to operate before, but all
+          write operations go into the differencing images. Each time
+          you create another snapshot, for each hard disk attachment,
+          another differencing image is created and attached, forming a
+          chain or tree.
+        </para>
+
+        <para>
+          In the above screenshot, you see that the original disk image
+          is now attached to a snapshot, representing the state of the
+          disk when the snapshot was taken.
+        </para>
+
+        <para>
+          If you <emphasis>restore</emphasis> a snapshot, and want to go
+          back to the exact machine state that was stored in the
+          snapshot, the following happens:
+        </para>
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              VirtualBox copies the virtual machine settings that were
+              copied into the snapshot back to the virtual machine. As a
+              result, if you have made changes to the machine
+              configuration since taking the snapshot, they are undone.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              If the snapshot was taken while the machine was running,
+              it contains a saved machine state, and that state is
+              restored as well. After restoring the snapshot, the
+              machine will then be in Saved state and resume execution
+              from there when it is next started. Otherwise the machine
+              will be in Powered Off state and do a full boot.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              For each disk image attached to the machine, the
+              differencing image holding all the write operations since
+              the current snapshot was taken is thrown away, and the
+              original parent image is made active again. If you
+              restored the root snapshot, then this will be the root
+              disk image for each attachment. Otherwise, some other
+              differencing image descended from it. This effectively
+              restores the old machine state.
+            </para>
+          </listitem>
+
+        </orderedlist>
+
+        <para>
+          If you later <emphasis>delete</emphasis> a snapshot in order
+          to free disk space, for each disk attachment, one of the
+          differencing images becomes obsolete. In this case, the
+          differencing image of the disk attachment cannot simply be
+          deleted. Instead, VirtualBox needs to look at each sector of
+          the differencing image and needs to copy it back into its
+          parent. This is called "merging" images and can be a
+          potentially lengthy process, depending on how large the
+          differencing image is. It can also temporarily need a
+          considerable amount of extra disk space, before the
+          differencing image obsoleted by the merge operation is
+          deleted.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Immutable images.</emphasis> When an
+          image is switched to immutable mode, a differencing image is
+          created as well. As with snapshots, the parent image then
+          becomes read-only, and the differencing image receives all the
+          write operations. Every time the virtual machine is started,
+          all the immutable images which are attached to it have their
+          respective differencing image thrown away, effectively
+          resetting the virtual machine's virtual disk with every
+          restart.
+        </para>
+      </listitem>
+
     </itemizedlist>
+
   </sect1>
 
-  <sect1 id="vdis">
-    <title>The Virtual Media Manager</title>
-
-    <para>VirtualBox keeps track of all the hard disk, CD/DVD-ROM and floppy
-    disk images which are in use by virtual machines. These are often referred
-    to as "known media" and come from two sources:<itemizedlist>
-        <listitem>
-          <para>all media currently attached to virtual machines;</para>
-        </listitem>
-
-        <listitem>
-          <para>"registered" media for compatibility with VirtualBox versions
-          older than version 4.0. For details about how media registration has
-          changed with version 4.0, please refer to <xref
-          linkend="vboxconfigdata" />.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>The known media can be viewed and changed in the <emphasis
-    role="bold">Virtual Media Manager</emphasis>, which you can access from
-    the "File" menu in the VirtualBox main window:</para>
-
-    <para><mediaobject>
-        <imageobject>
-          <imagedata align="center" fileref="images/virtual-disk-manager.png"
-                     width="12cm" />
-        </imageobject>
-      </mediaobject>The known media are conveniently grouped in three tabs for
-    the three possible formats. These formats are:</para>
+  <sect1 id="cloningvdis">
+
+    <title>Cloning Disk Images</title>
+
+    <para>
+      You can duplicate hard disk image files on the same host to
+      quickly produce a second virtual machine with the same operating
+      system setup. However, you should <emphasis>only</emphasis> make
+      copies of virtual disk images using the utility supplied with
+      VirtualBox. See <xref
+    linkend="vboxmanage-clonevdi" />. This
+      is because VirtualBox assigns a unique identity number (UUID) to
+      each disk image, which is also stored inside the image, and
+      VirtualBox will refuse to work with two images that use the same
+      number. If you do accidentally try to reimport a disk image which
+      you copied normally, you can make a second copy using VirtualBox's
+      utility and import that instead.
+    </para>
+
+    <para>
+      Note that newer Linux distributions identify the boot hard disk
+      from the ID of the drive. The ID VirtualBox reports for a drive is
+      determined from the UUID of the virtual disk image. So if you
+      clone a disk image and try to boot the copied image the guest
+      might not be able to determine its own boot disk as the UUID
+      changed. In this case you have to adapt the disk ID in your boot
+      loader script, for example
+      <computeroutput>/boot/grub/menu.lst</computeroutput>. The disk ID
+      looks like this:
+    </para>
+
+<screen>scsi-SATA_VBOX_HARDDISK_VB5cfdb1e2-c251e503</screen>
+
+    <para>
+      The ID for the copied image can be determined with:
+    </para>
+
+<screen>hdparm -i /dev/sda</screen>
+
+  </sect1>
+
+  <sect1 id="iocaching">
+
+    <title>Host I/O Caching</title>
+
+    <para>
+      Starting with version 3.2, VirtualBox can optionally disable the
+      I/O caching that the host operating system would otherwise perform
+      on disk image files.
+    </para>
+
+    <para>
+      Traditionally, VirtualBox has opened disk image files as normal
+      files, which results in them being cached by the host operating
+      system like any other file. The main advantage of this is speed:
+      when the guest OS writes to disk and the host OS cache uses
+      delayed writing, the write operation can be reported as completed
+      to the guest OS quickly while the host OS can perform the
+      operation asynchronously. Also, when you start a VM a second time
+      and have enough memory available for the OS to use for caching,
+      large parts of the virtual disk may be in system memory, and the
+      VM can access the data much faster.
+    </para>
+
+    <para>
+      Note that this applies only to image files. Buffering does not
+      occur for virtual disks residing on remote iSCSI storage, which is
+      the more common scenario in enterprise-class setups. See
+      <xref
+    linkend="storage-iscsi" />.
+    </para>
+
+    <para>
+      While buffering is a useful default setting for virtualizing a few
+      machines on a desktop computer, there are some disadvantages to
+      this approach:
+    </para>
 
     <itemizedlist>
-      <listitem>
-        <para>Hard disk images, either in VirtualBox's own Virtual Disk Image
-        (VDI) format or in the third-party formats listed in the previous
-        chapter;</para>
-      </listitem>
-
-      <listitem>
-        <para>CD/DVD images in standard ISO format;</para>
-      </listitem>
-
-      <listitem>
-        <para>floppy images in standard RAW format.</para>
-      </listitem>
+
+      <listitem>
+        <para>
+          Delayed writing through the host OS cache is less secure. When
+          the guest OS writes data, it considers the data written even
+          though it has not yet arrived on a physical disk. If for some
+          reason the write does not happen, such as power failure or
+          host crash, the likelihood of data loss increases.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Disk image files tend to be very large. Caching them can
+          therefore quickly use up the entire host OS cache. Depending
+          on the efficiency of the host OS caching, this may slow down
+          the host immensely, especially if several VMs run at the same
+          time. For example, on Linux hosts, host caching may result in
+          Linux delaying all writes until the host cache is nearly full
+          and then writing out all these changes at once, possibly
+          stalling VM execution for minutes. This can result in I/O
+          errors in the guest as I/O requests time out there.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Physical memory is often wasted as guest operating systems
+          typically have their own I/O caches, which may result in the
+          data being cached twice, in both the guest and the host
+          caches, for little effect.
+        </para>
+      </listitem>
+
     </itemizedlist>
 
-    <para>As you can see in the screenshot above, for each image, the Virtual
-    Media Manager shows you the full path of the image file and other
-    information, such as the virtual machine the image is currently attached
-    to, if any.</para>
-
-    <para>The Virtual Media Manager allows you to</para>
-
-    <itemizedlist>
-      <listitem>
-        <para><emphasis role="bold">remove</emphasis> an image from the
-        registry (and optionally delete the image file when doing so);</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">"release"</emphasis> an image, that is,
-        detach it from a virtual machine if it is currently attached to one as
-        a virtual hard disk.</para>
-      </listitem>
-
-     <listitem>
-        <para><emphasis role="bold">copy</emphasis> a virtual hard disk, to
-        another one - target type can be different, options are - VDI, VHD or VMDK.</para>
-     </listitem>
-
-     <listitem>
-        <para><emphasis role="bold">modify</emphasis> the attributes of the
-        disk image file - available options are : Normal, Immutable,
-        Writethrough, Shareable, Multi-attach.</para>
-     </listitem>
-
-     <listitem>
-        <para><emphasis role="bold">refresh</emphasis> the values for the displayed
-        attributes of the disk image currently selected in the window.</para>
-     </listitem>
-
-    </itemizedlist>
-
-    <para>These commands are accessible once a medium has been selected either by selecting
-    from the options shown at the top of the window, or by right-clicking the medium
-    and selecting from the options shown on the drop-down menu.</para>
-
-    <para>Starting with version 4.0, to <emphasis role="bold">create new disk
-    images,</emphasis> please use the "Storage" page in a virtual machine's
-    settings dialog because disk images are now by default stored in each
-    machine's own folder.</para>
-
-    <para>Hard disk image files can be copied onto other host systems and
-    imported into virtual machines there, although certain guest systems
-    (notably Windows 2000 and XP) will require that the new virtual machine be
-    set up in a similar way to the old one.<note>
-        <para>Do not simply make copies of virtual disk images. If you import
-        such a second copy into a virtual machine, VirtualBox will complain
-        with an error, since VirtualBox assigns a unique identifier (UUID) to
-        each disk image to make sure it is only used once. See <xref
-        linkend="cloningvdis" /> for instructions on this matter. Also, if you
-        want to copy a virtual machine to another system, VirtualBox has an
-        import/export facility that might be better suited for your needs; see
-        <xref linkend="ovf" />.</para>
-      </note></para>
+    <para>
+      If you decide to disable host I/O caching for the above reasons,
+      VirtualBox uses its own small cache to buffer writes, but no read
+      caching since this is typically already performed by the guest OS.
+      In addition, VirtualBox fully supports asynchronous I/O for its
+      virtual SATA, SCSI and SAS controllers through multiple I/O
+      threads.
+    </para>
+
+    <para>
+      Since asynchronous I/O is not supported by IDE controllers, for
+      performance reasons, you may want to leave host caching enabled
+      for your VM's virtual IDE controllers.
+    </para>
+
+    <para>
+      For this reason, VirtualBox allows you to configure whether the
+      host I/O cache is used for each I/O controller separately. Either
+      select the <emphasis role="bold">Use Host I/O Cache</emphasis>
+      check box in the Storage settings for a given virtual storage
+      controller, or use the following VBoxManage command to disable the
+      host I/O cache for a virtual storage controller:
+    </para>
+
+<screen>VBoxManage storagectl "VM name" --name &lt;controllername&gt; --hostiocache off</screen>
+
+    <para>
+      See <xref linkend="vboxmanage-storagectl" />.
+    </para>
+
+    <para>
+      For the above reasons, VirtualBox now uses SATA controllers by
+      default for new virtual machines.
+    </para>
+
   </sect1>
 
-  <sect1 id="hdimagewrites">
-    <title>Special image write modes</title>
-
-    <para>For each virtual disk image supported by VirtualBox, you can
-    determine separately how it should be affected by write operations from a
-    virtual machine and snapshot operations. This applies to all of the
-    aforementioned image formats (VDI, VMDK, VHD or HDD) and irrespective of
-    whether an image is fixed-size or dynamically allocated.</para>
-
-    <para>By default, images are in "normal" mode. To mark an existing image
-    with one of the non-standard modes listed below, use
-    <computeroutput>VBoxManage modifyhd</computeroutput>; see <xref
-    linkend="vboxmanage-modifyvdi" />. Alternatively, use VBoxManage to attach
-    the image to a VM and use the <computeroutput>--mtype</computeroutput>
-    argument; see <xref linkend="vboxmanage-storageattach" />.</para>
-
-    <orderedlist>
-      <listitem>
-        <para>With <emphasis role="bold">normal images</emphasis> (the default
-        setting), there are no restrictions on how guests can read from and
-        write to the disk.</para>
-
-        <para>When you take a snapshot of your virtual machine as described in
-        <xref linkend="snapshots" />, the state of such a "normal hard disk"
-        will be recorded together with the snapshot, and when reverting to the
-        snapshot, its state will be fully reset.</para>
-
-        <para>(Technically, strictly speaking, the image file itself is not
-        "reset". Instead, when a snapshot is taken, VirtualBox "freezes" the
-        image file and no longer writes to it. For the write operations from
-        the VM, a second, "differencing" image file is created which receives
-        only the changes to the original image; see the next section for
-        details.)</para>
-
-        <para>While you can attach the same "normal" image to more than one
-        virtual machine, only one of these virtual machines attached to the
-        same image file can be executed simultaneously, as otherwise there
-        would be conflicts if several machines write to the same image
-        file.<footnote>
-            <para>This restriction is more lenient now than it was before
-            VirtualBox 2.2. Previously, each "normal" disk image could only be
-            <emphasis>attached</emphasis> to one single machine. Now it can be
-            attached to more than one machine so long as only one of these
-            machines is running.</para>
-          </footnote></para>
-      </listitem>
-
-      <listitem>
-        <para>By contrast, <emphasis role="bold">write-through hard
-        disks</emphasis> are completely unaffected by snapshots: their state
-        is <emphasis>not</emphasis> saved when a snapshot is taken, and not
-        restored when a snapshot is restored.</para>
-      </listitem>
-
-      <listitem>
-        <para><emphasis role="bold">Shareable hard disks</emphasis> are a
-        variant of write-through hard disks. In principle they behave exactly
-        the same, i.e. their state is <emphasis>not</emphasis> saved when a
-        snapshot is taken, and not restored when a snapshot is restored. The
-        difference only shows if you attach such disks to several VMs.
-        Shareable disks may be attached to several VMs which may run
-        concurrently. This makes them suitable for use by cluster filesystems
-        between VMs and similar applications which are explicitly prepared to
-        access a disk concurrently. Only fixed size images can be used in this
-        way, and dynamically allocated images are rejected.<warning>
-            <para>This is an expert feature, and misuse can lead to data loss
-            -- regular filesystems are not prepared to handle simultaneous
-            changes by several parties.</para>
-          </warning></para>
-      </listitem>
-
-      <listitem>
-        <para>Next, <emphasis role="bold">immutable images</emphasis> only
-        remember write accesses temporarily while the virtual machine is
-        running; all changes are lost when the virtual machine is powered on
-        the next time. As a result, as opposed to "normal" images, the same
-        immutable image can be used with several virtual machines without
-        restrictions.</para>
-
-        <para><emphasis>Creating</emphasis> an immutable image makes little
-        sense since it would be initially empty and lose its contents with
-        every machine restart (unless you really want to have a disk that is
-        always unformatted when the machine starts up). As a result, normally,
-        you would first create a "normal" image and then, when you deem its
-        contents useful, later mark it immutable.</para>
-
-        <para>If you take a snapshot of a machine with immutable images, then
-        on every machine power-up, those images are reset to the state of the
-        last (current) snapshot (instead of the state of the original
-        immutable image).</para>
-
-        <note>
-          <para>As a special exception, immutable images are
-          <emphasis>not</emphasis> reset if they are attached to a machine
-          in saved state or whose last snapshot was taken while the machine
-          was running (a so-called "online" snapshot). As a result, if the
-          machine's current snapshot is such an "online" snapshot, its
-          immutable images behave exactly like the "normal" images described
-          previously. To re-enable the automatic resetting of such images,
-          delete the current snapshot of the machine.</para>
-        </note>
-
-        <para>Again, technically, VirtualBox never writes to an immutable
-        image directly at all. All write operations from the machine will be
-        directed to a differencing image; the next time the VM is powered on,
-        the differencing image is reset so that every time the VM starts, its
-        immutable images have exactly the same content.<footnote>
-            <para>This behavior also changed with VirtualBox 2.2. Previously,
-            the differencing images were discarded when the machine session
-            <emphasis>ended</emphasis>; now they are discarded every time the
-            machine is powered on.</para>
-          </footnote> The differencing image is only reset when the machine is
-        powered on from within VirtualBox, not when you reboot by requesting a
-        reboot from within the machine. This is also why immutable images
-        behave as described above when snapshots are also present, which use
-        differencing images as well.</para>
-
-        <para>If the automatic discarding of the differencing image on VM
-        startup does not fit your needs, you can turn it off using the
-        <computeroutput>autoreset</computeroutput> parameter of
-        <computeroutput>VBoxManage modifyhd</computeroutput>; see <xref
-        linkend="vboxmanage-modifyvdi" /> for details.</para>
-      </listitem>
-
-      <listitem>
-        <para>An image in <emphasis role="bold">multiattach mode</emphasis>
-        can be attached to more than one virtual machine at the same time,
-        even if these machines are running simultaneously. For each virtual
-        machine to which such an image is attached, a differencing image is
-        created. As a result, data that is written to such a virtual disk by
-        one machine is not seen by the other machines to which the image is
-        attached; each machine creates its own write history of the
-        multiattach image.</para>
-
-        <para>Technically, a "multiattach" image behaves identically to an
-        "immutable" image except the differencing image is not reset every
-        time the machine starts.</para>
-      <para>This mode is useful for sharing files which are almost never
-        written, for instance picture galleries, where every guest changes
-        only a small amount of data and the majority of the disk content
-        remains unchanged. The modified blocks are stored in differencing
-        images which remain relatively small and the shared content is stored
-        only once at the host.</para>
-      </listitem>
-
-      <listitem>
-        <para>Finally, the <emphasis role="bold">read-only image</emphasis> is
-        used automatically for CD/DVD images, since CDs/DVDs can never be
-        written to.</para>
-      </listitem>
-    </orderedlist>
-
-    <para>To illustrate the differences between the various types with respect
-    to snapshots: Assume you have installed your guest operating system in
-    your VM, and you have taken a snapshot. Imagine you have accidentally
-    infected your VM with a virus and would like to go back to the snapshot.
-    With a normal hard disk image, you simply restore the snapshot, and the
-    earlier state of your hard disk image will be restored as well (and your
-    virus infection will be undone). With an immutable hard disk, all it takes
-    is to shut down and power on your VM, and the virus infection will be
-    discarded. With a write-through image however, you cannot easily undo the
-    virus infection by means of virtualization, but will have to disinfect
-    your virtual machine like a real computer.</para>
-
-    <para>Still, you might find write-through images useful if you want to
-    preserve critical data irrespective of snapshots, and since you can attach
-    more than one image to a VM, you may want to have one immutable for the
-    operating system and one write-through for your data files.</para>
-  </sect1>
-
-  <sect1 id="diffimages">
-    <title>Differencing images</title>
-
-    <para>The previous section hinted at differencing images and how they are
-    used with snapshots, immutable images and multiple disk attachments. For
-    the inquisitive VirtualBox user, this section describes in more detail how
-    they work.</para>
-
-    <para>A differencing image is a special disk image that only holds the
-    differences to another image. A differencing image by itself is useless,
-    it must always refer to another image. The differencing image is then
-    typically referred to as a "child", which holds the differences to its
-    "parent".</para>
-
-    <para>When a differencing image is active, it receives all write
-    operations from the virtual machine instead of its parent. The
-    differencing image only contains the sectors of the virtual hard disk that
-    have changed since the differencing image was created. When the machine
-    reads a sector from such a virtual hard disk, it looks into the
-    differencing image first. If the sector is present, it is returned from
-    there; if not, VirtualBox looks into the parent. In other words, the
-    parent becomes "read-only"; it is never written to again, but it is read
-    from if a sector has not changed.</para>
-
-    <para>Differencing images can be chained. If another differencing image is
-    created for a virtual disk that already has a differencing image, then it
-    becomes a "grandchild" of the original parent. The first differencing
-    image then becomes read-only as well, and write operations only go to the
-    second-level differencing image. When reading from the virtual disk,
-    VirtualBox needs to look into the second differencing image first, then
-    into the first if the sector was not found, and then into the original
-    image.</para>
-
-    <para>There can be an unlimited number of differencing images, and each
-    image can have more than one child. As a result, the differencing images
-    can form a complex tree with parents, "siblings" and children, depending
-    on how complex your machine configuration is. Write operations always go
-    to the one "active" differencing image that is attached to the machine,
-    and for read operations, VirtualBox may need to look up all the parents in
-    the chain until the sector in question is found. You can look at such a
-    tree in the Virtual Media Manager:<mediaobject>
-        <imageobject>
-          <imagedata align="center" fileref="images/virtual-disk-manager2.png"
-                     width="12cm" />
-        </imageobject>
-      </mediaobject></para>
-
-    <para>In all of these situations, from the point of view of the virtual
-    machine, the virtual hard disk behaves like any other disk. While the
-    virtual machine is running, there is a slight run-time I/O overhead
-    because VirtualBox might need to look up sectors several times. This is
-    not noticeable however since the tables with sector information are always
-    kept in memory and can be looked up quickly.</para>
-
-    <para>Differencing images are used in the following
-    situations:<orderedlist>
-        <listitem>
-          <para><emphasis role="bold">Snapshots.</emphasis> When you create a
-          snapshot, as explained in the previous section, VirtualBox "freezes"
-          the images attached to the virtual machine and creates differencing
-          images for each of them (to be precise: one for each image that is
-          not in "write-through" mode). From the point of view of the virtual
-          machine, the virtual disks continue to operate before, but all write
-          operations go into the differencing images. Each time you create
-          another snapshot, for each hard disk attachment, another
-          differencing image is created and attached, forming a chain or
-          tree.</para>
-
-          <para>In the above screenshot, you see that the original disk image
-          is now attached to a snapshot, representing the state of the disk
-          when the snapshot was taken.</para>
-
-          <para>If you now <emphasis role="bold">restore</emphasis> a snapshot
-          -- that is, if you want to go back to the exact machine state that
-          was stored in the snapshot --, the following happens:<orderedlist>
-              <listitem>
-                <para>VirtualBox copies the virtual machine settings that were
-                copied into the snapshot back to the virtual machine. As a
-                result, if you have made changes to the machine configuration
-                since taking the snapshot, they are undone.</para>
-              </listitem>
-
-              <listitem>
-                <para>If the snapshot was taken while the machine was running,
-                it contains a saved machine state, and that state is restored
-                as well; after restoring the snapshot, the machine will then
-                be in "Saved" state and resume execution from there when it is
-                next started. Otherwise the machine will be in "Powered Off"
-                state and do a full boot.</para>
-              </listitem>
-
-              <listitem>
-                <para>For each disk image attached to the machine, the
-                differencing image holding all the write operations since the
-                current snapshot was taken is thrown away, and the original
-                parent image is made active again. (If you restored the "root"
-                snapshot, then this will be the root disk image for each
-                attachment; otherwise, some other differencing image descended
-                from it.) This effectively restores the old machine
-                state.</para>
-              </listitem>
-            </orderedlist></para>
-
-          <para>If you later <emphasis role="bold">delete</emphasis> a
-          snapshot in order to free disk space, for each disk attachment, one
-          of the differencing images becomes obsolete. In this case, the
-          differencing image of the disk attachment cannot simply be deleted.
-          Instead, VirtualBox needs to look at each sector of the differencing
-          image and needs to copy it back into its parent; this is called
-          "merging" images and can be a potentially lengthy process, depending
-          on how large the differencing image is. It can also temporarily need
-          a considerable amount of extra disk space, before the differencing
-          image obsoleted by the merge operation is deleted.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Immutable images.</emphasis> When an
-          image is switched to "immutable" mode, a differencing image is
-          created as well. As with snapshots, the parent image then becomes
-          read-only, and the differencing image receives all the write
-          operations. Every time the virtual machine is started, all the
-          immutable images which are attached to it have their respective
-          differencing image thrown away, effectively resetting the virtual
-          machine's virtual disk with every restart.</para>
-        </listitem>
-      </orderedlist></para>
-  </sect1>
-
-  <sect1 id="cloningvdis">
-    <title>Cloning disk images</title>
-
-    <para>You can duplicate hard disk image files on the same host to quickly
-    produce a second virtual machine with the same operating system setup.
-    However, you should <emphasis>only</emphasis> make copies of virtual disk
-    images using the utility supplied with VirtualBox; see <xref
-    linkend="vboxmanage-clonevdi" />. This is because VirtualBox assigns a
-    unique identity number (UUID) to each disk image, which is also stored
-    inside the image, and VirtualBox will refuse to work with two images that
-    use the same number. If you do accidentally try to re-import a disk image
-    which you copied normally, you can make a second copy using VirtualBox's
-    utility and import that instead.</para>
-
-    <para>Note that newer Linux distributions identify the boot hard disk from
-    the ID of the drive. The ID VirtualBox reports for a drive is determined
-    from the UUID of the virtual disk image. So if you clone a disk image and
-    try to boot the copied image the guest might not be able to determine its
-    own boot disk as the UUID changed. In this case you have to adapt the disk
-    ID in your boot loader script (for example
-    <computeroutput>/boot/grub/menu.lst</computeroutput>). The disk ID looks
-    like this:<screen>scsi-SATA_VBOX_HARDDISK_VB5cfdb1e2-c251e503</screen></para>
-
-    <para>The ID for the copied image can be determined with <screen>hdparm -i /dev/sda</screen></para>
-  </sect1>
-
-  <sect1 id="iocaching">
-    <title>Host I/O caching</title>
-
-    <para>Starting with version 3.2, VirtualBox can optionally disable the I/O
-    caching that the host operating system would otherwise perform on disk
-    image files.</para>
-
-    <para>Traditionally, VirtualBox has opened disk image files as normal
-    files, which results in them being cached by the host operating system
-    like any other file. The main advantage of this is speed: when the guest
-    OS writes to disk and the host OS cache uses delayed writing, the write
-    operation can be reported as completed to the guest OS quickly while the
-    host OS can perform the operation asynchronously. Also, when you start a
-    VM a second time and have enough memory available for the OS to use for
-    caching, large parts of the virtual disk may be in system memory, and the
-    VM can access the data much faster.</para>
-
-    <para>Note that this applies only to image files; buffering never occurred
-    for virtual disks residing on remote iSCSI storage, which is the more common
-    scenario in enterprise-class setups (see <xref
-    linkend="storage-iscsi" />).</para>
-
-    <para>While buffering is a useful default setting for virtualizing a few
-    machines on a desktop computer, there are some disadvantages to this
-    approach:<orderedlist>
-        <listitem>
-          <para>Delayed writing through the host OS cache is less secure. When
-          the guest OS writes data, it considers the data written even though
-          it has not yet arrived on a physical disk. If for some reason the
-          write does not happen (power failure, host crash), the likelihood of
-          data loss increases.</para>
-        </listitem>
-
-        <listitem>
-          <para>Disk image files tend to be very large. Caching them can
-          therefore quickly use up the entire host OS cache. Depending on the
-          efficiency of the host OS caching, this may slow down the host
-          immensely, especially if several VMs run at the same time. For
-          example, on Linux hosts, host caching may result in Linux delaying
-          all writes until the host cache is nearly full and then writing out
-          all these changes at once, possibly stalling VM execution for
-          minutes. This can result in I/O errors in the guest as I/O requests
-          time out there.</para>
-        </listitem>
-
-        <listitem>
-          <para>Physical memory is often wasted as guest operating systems
-          typically have their own I/O caches, which may result in the data
-          being cached twice (in both the guest and the host caches) for
-          little effect.</para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>If you decide to disable host I/O caching for the above reasons,
-    VirtualBox uses its own small cache to buffer writes, but no read caching
-    since this is typically already performed by the guest OS. In addition,
-    VirtualBox fully supports asynchronous I/O for its virtual SATA, SCSI and
-    SAS controllers through multiple I/O threads.</para>
-
-    <para>Since asynchronous I/O is not supported by IDE controllers, for
-    performance reasons, you may want to leave host caching enabled for your
-    VM's virtual IDE controllers.</para>
-
-    <para>For this reason, VirtualBox allows you to configure whether the host
-    I/O cache is used for each I/O controller separately. Either uncheck the
-    "Use host I/O cache" box in the "Storage" settings for a given virtual
-    storage controller, or use the following VBoxManage command to disable the
-    host I/O cache for a virtual storage controller:<screen>VBoxManage storagectl "VM name" --name &lt;controllername&gt; --hostiocache off</screen></para>
-
-    <para>See <xref linkend="vboxmanage-storagectl" /> for details.</para>
-
-    <para>For the above reasons also, VirtualBox now uses SATA controllers by
-    default for new virtual machines.</para>
-  </sect1>
-
   <sect1 id="storage-bandwidth-limit">
-    <title>Limiting bandwidth for disk images</title>
-
-    <para>Starting with version 4.0, VirtualBox allows for limiting the
-    maximum bandwidth used for asynchronous I/O. Additionally it supports
-    sharing limits through bandwidth groups for several images. It is possible
-    to have more than one such limit.</para>
-
-    <para>Limits are configured through
-    <computeroutput>VBoxManage</computeroutput>. The example below creates a
-    bandwidth group named "Limit", sets the limit to 20 MB/s and assigns the
-    group to the attached disks of the VM:<screen>VBoxManage bandwidthctl "VM name" add Limit --type disk --limit 20M
+
+    <title>Limiting Bandwidth for Disk Images</title>
+
+    <para>
+      Starting with version 4.0, VirtualBox allows for limiting the
+      maximum bandwidth used for asynchronous I/O. Additionally it
+      supports sharing limits through bandwidth groups for several
+      images. It is possible to have more than one such limit.
+    </para>
+
+    <para>
+      Limits are configured using
+      <computeroutput>VBoxManage</computeroutput>. The example below
+      creates a bandwidth group named Limit, sets the limit to 20 MB per
+      second, and assigns the group to the attached disks of the VM:
+    </para>
+
+<screen>VBoxManage bandwidthctl "VM name" add Limit --type disk --limit 20M
 VBoxManage storageattach "VM name" --storagectl "SATA" --port 0 --device 0 --type hdd
                                    --medium disk1.vdi --bandwidthgroup Limit
 VBoxManage storageattach "VM name" --storagectl "SATA" --port 1 --device 0 --type hdd
-                                   --medium disk2.vdi --bandwidthgroup Limit</screen></para>
-
-    <para>All disks in a group share the bandwidth limit, meaning that in the
-    example above the bandwidth of both images combined can never exceed 20
-    MB/s. However, if one disk doesn't require bandwidth the other can use the
-    remaining bandwidth of its group.</para>
-
-    <para>The limits for each group can be changed while the VM is running,
-    with changes being picked up immediately. The example below changes the
-    limit for the group created in the example above to 10 MB/s:<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 10M</screen></para>
+                                   --medium disk2.vdi --bandwidthgroup Limit</screen>
+
+    <para>
+      All disks in a group share the bandwidth limit, meaning that in
+      the example above the bandwidth of both images combined can never
+      exceed 20 MBps. However, if one disk does not require bandwidth
+      the other can use the remaining bandwidth of its group.
+    </para>
+
+    <para>
+      The limits for each group can be changed while the VM is running,
+      with changes being picked up immediately. The example below
+      changes the limit for the group created in the example above to 10
+      MBps:
+    </para>
+
+<screen>VBoxManage bandwidthctl "VM name" set Limit --limit 10M</screen>
+
   </sect1>
 
   <sect1 id="storage-cds">
-    <title>CD/DVD support</title>
-
-    <para>The virtual CD/DVD drive(s) by default support only reading. The
-    medium configuration is changeable at runtime. You can select between
-    three options to provide the medium data:<itemizedlist>
-        <listitem>
-          <para><emphasis role="bold">Host Drive</emphasis> defines that the
-          guest can read from the medium in the host drive.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Image file</emphasis> (typically an ISO
-          file) gives the guest read-only access to the data in the
-          image.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Empty</emphasis> stands for a drive
-          without an inserted medium.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>Changing between the above, or changing a medium in the host drive
-    that is accessed by a machine, or changing an image file will signal a
-    medium change to the guest operating system, which can then react to the
-    change (e.g. by starting an installation program).</para>
-
-    <para>Medium changes can be prevented by the guest, and VirtualBox
-    reflects that by locking the host drive if appropriate. You can force a
-    medium removal in such situations via the VirtualBox GUI or the VBoxManage
-    command line tool. Effectively this is the equivalent of the emergency
-    eject which many CD/DVD drives provide, with all associated side effects:
-    the guest OS can issue error messages, just like on real hardware, and
-    guest applications may misbehave. Use this with caution.<note>
-        <para>The identification string of the drive provided to the guest
-        (which, in the guest, would be displayed by configuration tools such
-        as the Windows Device Manager) is always "VBOX CD-ROM", irrespective
-        of the current configuration of the virtual drive. This is to prevent
-        hardware detection from being triggered in the guest operating system
-        every time the configuration is changed.</para>
-      </note></para>
-
-    <para>The standard CD/DVD emulation allows for reading standard data CD
-    and DVD formats only. As an experimental feature, for additional
-    capabilities, it is possible to give the guest direct access to the CD/DVD
-    host drive by enabling "passthrough" mode. Depending on the host hardware,
-    this may enable three things to work, potentially:<itemizedlist>
-        <listitem>
-          <para>CD/DVD writing from within the guest, if the host DVD drive is
-          a CD/DVD writer;</para>
-        </listitem>
-
-        <listitem>
-          <para>playing audio CDs;</para>
-        </listitem>
-
-        <listitem>
-          <para>playing encrypted DVDs.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>There is a "Passthrough" checkbox in the GUI dialog for configuring
-    the media attached to a storage controller, or you can use the
-    <computeroutput>--passthrough</computeroutput> option with
-    <computeroutput>VBoxManage storageattach</computeroutput>; see <xref
-    linkend="vboxmanage-storageattach" /> for details.</para>
-
-    <para>Even if pass-through is enabled, unsafe commands, such as updating
-    the drive firmware, will be blocked. Video CD formats are never supported,
-    not even in passthrough mode, and cannot be played from a virtual
-    machine.</para>
-
-    <para>On Solaris hosts, pass-through requires running VirtualBox with real
-    root permissions due to security measures enforced by the host.</para>
+
+    <title>CD/DVD Support</title>
+
+    <para>
+      Virtual CD/DVD drives by default support only reading. The medium
+      configuration is changeable at runtime. You can select between the
+      following options to provide the medium data:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Host Drive</emphasis> defines that the
+          guest can read from the medium in the host drive.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Image file</emphasis> gives the guest
+          read-only access to the data in the image. This is typically
+          an ISO file.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Empty</emphasis> means a drive without
+          an inserted medium.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Changing between the above, or changing a medium in the host drive
+      that is accessed by a machine, or changing an image file will
+      signal a medium change to the guest operating system. The guest OS
+      can then react to the change, for example by starting an
+      installation program.
+    </para>
+
+    <para>
+      Medium changes can be prevented by the guest, and VirtualBox
+      reflects that by locking the host drive if appropriate. You can
+      force a medium removal in such situations via the VirtualBox GUI
+      or the VBoxManage command line tool. Effectively this is the
+      equivalent of the emergency eject which many CD/DVD drives
+      provide, with all associated side effects. The guest OS can issue
+      error messages, just like on real hardware, and guest applications
+      may misbehave. Use this with caution.
+    </para>
+
+    <note>
+      <para>
+        The identification string of the drive provided to the guest,
+        displayed by configuration tools such as the Windows Device
+        Manager, is always VBOX CD-ROM, irrespective of the current
+        configuration of the virtual drive. This is to prevent hardware
+        detection from being triggered in the guest operating system
+        every time the configuration is changed.
+      </para>
+    </note>
+
+    <para>
+      The standard CD/DVD emulation allows for reading standard data CD
+      and DVD formats only. As an experimental feature, for additional
+      capabilities, it is possible to give the guest direct access to
+      the CD/DVD host drive by enabling <emphasis>passthrough</emphasis>
+      mode. Depending on the host hardware, this may potentially enable
+      the following things to work:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          CD/DVD writing from within the guest, if the host DVD drive is
+          a CD/DVD writer
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Playing audio CDs
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Playing encrypted DVDs
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      There is a Passthrough check box in the GUI dialog for configuring
+      the media attached to a storage controller, or you can use the
+      <computeroutput>--passthrough</computeroutput> option with
+      <computeroutput>VBoxManage storageattach</computeroutput>. See
+      <xref
+    linkend="vboxmanage-storageattach" />.
+    </para>
+
+    <para>
+      Even if passthrough is enabled, unsafe commands, such as updating
+      the drive firmware, will be blocked. Video CD formats are never
+      supported, not even in passthrough mode, and cannot be played from
+      a virtual machine.
+    </para>
+
+    <para>
+      On Solaris hosts, passthrough requires running VirtualBox with
+      real root permissions due to security measures enforced by the
+      host.
+    </para>
+
   </sect1>
 
   <sect1 id="storage-iscsi">
-    <title>iSCSI servers</title>
-
-    <para>iSCSI stands for "Internet SCSI" and is a standard that allows for
-    using the SCSI protocol over Internet (TCP/IP) connections. Especially
-    with the advent of Gigabit Ethernet, it has become affordable to attach
-    iSCSI storage servers simply as remote hard disks to a computer network.
-    In iSCSI terminology, the server providing storage resources is called an
-    "iSCSI target", while the client connecting to the server and accessing
-    its resources is called "iSCSI initiator".</para>
-
-    <para>VirtualBox can transparently present iSCSI remote storage to a
-    virtual machine as a virtual hard disk. The guest operating system will
-    not see any difference between a virtual disk image (VDI file) and an
-    iSCSI target. To achieve this, VirtualBox has an integrated iSCSI
-    initiator.</para>
-
-    <para>VirtualBox's iSCSI support has been developed according to the iSCSI
-    standard and should work with all standard-conforming iSCSI targets. To
-    use an iSCSI target with VirtualBox, you must use the command line; see
-    <xref linkend="vboxmanage-storageattach" />.</para>
+
+    <title>iSCSI Servers</title>
+
+    <para>
+      iSCSI stands for "Internet SCSI" and is a standard that allows for
+      using the SCSI protocol over Internet (TCP/IP) connections.
+      Especially with the advent of Gigabit Ethernet, it has become
+      affordable to attach iSCSI storage servers simply as remote hard
+      disks to a computer network. In iSCSI terminology, the server
+      providing storage resources is called an <emphasis>iSCSI
+      target</emphasis>, while the client connecting to the server and
+      accessing its resources is called an <emphasis>iSCSI
+      initiator</emphasis>.
+    </para>
+
+    <para>
+      VirtualBox can transparently present iSCSI remote storage to a
+      virtual machine as a virtual hard disk. The guest operating system
+      will not see any difference between a virtual disk image (VDI
+      file) and an iSCSI target. To achieve this, VirtualBox has an
+      integrated iSCSI initiator.
+    </para>
+
+    <para>
+      VirtualBox's iSCSI support has been developed according to the
+      iSCSI standard and should work with all standard-conforming iSCSI
+      targets. To use an iSCSI target with VirtualBox, you must use the
+      command line. See <xref linkend="vboxmanage-storageattach" />.
+    </para>
+
   </sect1>
+
 </chapter>
Index: /trunk/doc/manual/en_US/user_Technical.xml
===================================================================
--- /trunk/doc/manual/en_US/user_Technical.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_Technical.xml	(revision 73276)
@@ -1,216 +1,309 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="TechnicalBackground">
-  <title>Technical background</title>
-
-  <para>The contents of this chapter are not required to use VirtualBox
-  successfully. The following is provided as additional information for
-  readers who are more familiar with computer architecture and technology and
-  wish to find out more about how VirtualBox works "under the hood".</para>
+
+  <title>Technical Background</title>
+
+  <para>
+    The contents of this chapter are not required to use VirtualBox
+    successfully. The following is provided as additional information
+    for readers who are more familiar with computer architecture and
+    technology and wish to find out more about how VirtualBox works
+    "under the hood".
+  </para>
 
   <sect1 id="vboxconfigdata">
-    <title>Where VirtualBox stores its files</title>
-
-    <para>In VirtualBox, a virtual machine and its settings are described in a
-    virtual machine settings file in XML format. In addition, most virtual
-    machine have one or more virtual hard disks, which are typically
-    represented by disk images (e.g. in VDI format). Where all these files are
-    stored depends on which version of VirtualBox created the machine.</para>
-
-    <sect2>
-      <title>Machines created by VirtualBox version 4.0 or later</title>
-
-      <para>Starting with version 4.0, by default, each virtual machine has
-      one directory on your host computer where all the files of that machine
-      are stored -- the XML settings file (with a
-      <computeroutput>.vbox</computeroutput> file extension) and its disk
-      images.</para>
-
-      <para>By default, this "machine folder" is placed in a common folder
-      called "VirtualBox VMs", which VirtualBox creates in the current system
-      user's home directory. The location of this home directory depends on
-      the conventions of the host operating system:</para>
+
+    <title>Where VirtualBox Stores its Files</title>
+
+    <para>
+      In VirtualBox, a virtual machine and its settings are described in
+      a virtual machine settings file in XML format. In addition, most
+      virtual machine have one or more virtual hard disks, which are
+      typically represented by disk images, such as those in VDI format.
+      Where all these files are stored depends on which version of
+      VirtualBox created the machine.
+    </para>
+
+    <sect2 id="vboxconfigdata-pre-version-four">
+
+      <title>Machines Created by VirtualBox Version 4.0 or Later</title>
+
+      <para>
+        Starting with version 4.0, by default, each virtual machine has
+        one directory on your host computer where all the files of that
+        machine are stored: the XML settings file, with a
+        <computeroutput>.vbox</computeroutput> file extension, and its
+        disk images.
+      </para>
+
+      <para>
+        By default, this <replaceable>machine folder</replaceable> is
+        placed in a common folder called <computeroutput>VirtualBox
+        VMs</computeroutput>, which VirtualBox creates in the current
+        system user's home directory. The location of this home
+        directory depends on the conventions of the host operating
+        system:
+      </para>
 
       <itemizedlist>
+
         <listitem>
-          <para>On Windows, this is the location returned by the
-          <computeroutput>SHGetFolderPath</computeroutput> function of the
-          Windows system library Shell32.dll, asking for the user profile. Only
-          on very old Windows versions which don't have this function
-          or where it unexpectedly returns an error, there is a fallback based
-          on environment variables: first
-          <computeroutput>%USERPROFILE%</computeroutput> is checked, if it
-          doesn't exist then an attempt with
-          <computeroutput>%HOMEDRIVE%%HOMEPATH%</computeroutput> is made.
-          Typical value is
-          <computeroutput>C:\Users\username</computeroutput>.</para>
+          <para>
+            On Windows, this is the location returned by the
+            <computeroutput>SHGetFolderPath</computeroutput> function of
+            the Windows system library Shell32.dll, asking for the user
+            profile. On very old Windows versions which do not have this
+            function or where it unexpectedly returns an error, there is
+            a fallback based on environment variables. First,
+            <computeroutput>%USERPROFILE%</computeroutput> is checked.
+            If it does not exist then an attempt with
+            <computeroutput>%HOMEDRIVE%%HOMEPATH%</computeroutput> is
+            made. A typical location is
+            <computeroutput>C:\Users\username</computeroutput>.
+          </para>
         </listitem>
 
         <listitem>
-          <para>On Linux, Mac OS X and Solaris, this is generally taken from
-          the environment variable <computeroutput>$HOME</computeroutput>,
-          except for the user
-          <computeroutput>root</computeroutput> for which it's taken from the
-          account database (as a workaround for the frequent trouble caused
-          by users using VirtualBox in combination with the tool
-          <computeroutput>sudo</computeroutput> which by default doesn't reset
-          the environment variable <computeroutput>$HOME</computeroutput>).
-          Typical value on Linux and Solaris is
-          <computeroutput>/home/username</computeroutput> and on Mac OS X
-          <computeroutput>/Users/username</computeroutput>.</para>
+          <para>
+            On Linux, Mac OS X and Solaris, this is generally taken from
+            the environment variable
+            <computeroutput>$HOME</computeroutput>, except for the user
+            <computeroutput>root</computeroutput> where it is taken from
+            the account database. This is a workaround for the frequent
+            trouble caused by users using VirtualBox in combination with
+            the tool <computeroutput>sudo</computeroutput> which by
+            default does not reset the environment variable
+            <computeroutput>$HOME</computeroutput>. A typical location
+            on Linux and Solaris is
+            <computeroutput>/home/username</computeroutput> and on Mac
+            OS X <computeroutput>/Users/username</computeroutput>.
+          </para>
         </listitem>
+
       </itemizedlist>
 
-      <para>For simplicity, we will abbreviate this as
-      <computeroutput>$HOME</computeroutput> below. Using that convention, the
-      common folder for all virtual machines is
-      <computeroutput>$HOME/VirtualBox VMs</computeroutput>.</para>
-
-      <para>As an example, when you create a virtual machine called "Example
-      VM", you will find that VirtualBox creates<orderedlist>
-          <listitem>
-            <para>the folder <computeroutput>$HOME/VirtualBox VMs/Example
-            VM/</computeroutput> and, in that folder,</para>
-          </listitem>
-
-          <listitem>
-            <para>the settings file <computeroutput>Example
-            VM.vbox</computeroutput> and</para>
-          </listitem>
-
-          <listitem>
-            <para>the virtual disk image <computeroutput>Example
-            VM.vdi</computeroutput>.</para>
-          </listitem>
-        </orderedlist></para>
-
-      <para>This is the default layout if you use the "Create new virtual
-      machine" wizard as described in <xref linkend="gui-createvm" />. Once
-      you start working with the VM, additional files will show up: you will
-      find log files in a subfolder called
-      <computeroutput>Logs</computeroutput>, and once you have taken
-      snapshots, they will appear in a
-      <computeroutput>Snapshots</computeroutput> subfolder. For each VM, you
-      can change the location of its snapshots folder in the VM
-      settings.</para>
-
-      <para>You can change the default machine folder by selecting
-      "Preferences" from the "File" menu in the VirtualBox main window. Then,
-      in the window that pops up, click on the "General" tab. Alternatively,
-      use <computeroutput>VBoxManage setproperty
-      machinefolder</computeroutput>; see <xref
-      linkend="vboxmanage-setproperty" />.</para>
+      <para>
+        For simplicity, we will abbreviate the location of the home
+        directory as <computeroutput>$HOME</computeroutput>. Using that
+        convention, the common folder for all virtual machines is
+        <computeroutput>$HOME/VirtualBox VMs</computeroutput>.
+      </para>
+
+      <para>
+        As an example, when you create a virtual machine called "Example
+        VM", you will find that VirtualBox creates the following:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            A machine folder <computeroutput>$HOME/VirtualBox
+            VMs/Example VM/</computeroutput>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            In the machine folder, a settings file:
+            <computeroutput>Example VM.vbox</computeroutput>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            In the machine folder, a virtual disk image:
+            <computeroutput>Example VM.vdi</computeroutput>.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        This is the default layout if you use the Create New Virtual
+        Machine wizard described in <xref linkend="gui-createvm" />.
+        Once you start working with the VM, additional files are added.
+        Log files are in a subfolder called
+        <computeroutput>Logs</computeroutput>, and if you have taken
+        snapshots, they are in a
+        <computeroutput>Snapshots</computeroutput> subfolder. For each
+        VM, you can change the location of its snapshots folder in the
+        VM settings.
+      </para>
+
+      <para>
+        You can change the default machine folder by selecting
+        <emphasis role="bold">Preferences</emphasis> from the File menu
+        in the VirtualBox main window. Then, in the displayed window,
+        click on the <emphasis role="bold">General</emphasis> tab.
+        Alternatively, use <computeroutput>VBoxManage setproperty
+        machinefolder</computeroutput>. See
+        <xref
+      linkend="vboxmanage-setproperty" />.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Machines created by VirtualBox versions before 4.0</title>
-
-      <para>If you have upgraded to VirtualBox 4.0 from an earlier version of
-      VirtualBox, you probably have settings files and disks in the earlier
-      file system layout.</para>
-
-      <para>Before version 4.0, VirtualBox separated the machine settings
-      files from virtual disk images. The machine settings files had an
-      <computeroutput>.xml</computeroutput> file extension and resided in a
-      folder called "Machines" under the global VirtualBox configuration
-      directory (see the next section). So, for example, on Linux, this was
-      the hidden <computeroutput>$HOME/.VirtualBox/Machines</computeroutput>
-      directory. The default hard disks folder was called "HardDisks" and
-      resided in the <computeroutput>.VirtualBox</computeroutput> folder as
-      well. Both locations could be changed by the user in the global
-      preferences. (The concept of a "default hard disk folder" has been
-      abandoned with VirtualBox 4.0, since disk images now reside in each
-      machine's folder by default.)</para>
-
-      <para>The old layout had several severe disadvantages.<orderedlist>
-          <listitem>
-            <para>It was very difficult to move a virtual machine from one
-            host to another because the files involved did not reside in the
-            same folder. In addition, the virtual media of all machines were
-            registered with a global registry in the central VirtualBox
-            settings file
-            (<computeroutput>$HOME/.VirtualBox/VirtualBox.xml</computeroutput>).</para>
-
-            <para>To move a machine to another host, it was therefore not
-            enough to move the XML settings file and the disk images (which
-            were in different locations), but the hard disk entries from the
-            global media registry XML had to be meticulously copied as well,
-            which was close to impossible if the machine had snapshots and
-            therefore differencing images.</para>
-          </listitem>
-
-          <listitem>
-            <para>Storing virtual disk images, which can grow very large,
-            under the hidden <computeroutput>.VirtualBox</computeroutput>
-            directory (at least on Linux and Solaris hosts) made many users
-            wonder where their disk space had gone.</para>
-          </listitem>
-        </orderedlist></para>
-
-      <para>Whereas new VMs created with VirtualBox 4.0 or later will conform
-      to the new layout, for maximum compatibility, old VMs are
-      <emphasis>not</emphasis> converted to the new layout. Otherwise machine
-      settings would be irrevocably broken if a user downgraded from 4.0 back
-      to an older version of VirtualBox.</para>
+    <sect2 id="vboxconfigdata-post-version-four">
+
+      <title>Machines Created by VirtualBox Versions Before 4.0</title>
+
+      <para>
+        If you have upgraded to VirtualBox 4.0 from an earlier version
+        of VirtualBox, you probably have settings files and disks in the
+        earlier file system layout.
+      </para>
+
+      <para>
+        Before version 4.0, VirtualBox separated the machine settings
+        files from virtual disk images. The machine settings files had
+        an <computeroutput>.xml</computeroutput> file extension and
+        resided in a folder called "Machines" under the global
+        VirtualBox configuration directory. See
+        <xref linkend="vboxconfigdata-global"/>. On Linux, for example,
+        this was the hidden
+        <computeroutput>$HOME/.VirtualBox/Machines</computeroutput>
+        directory. The default hard disks folder was called "HardDisks"
+        and resided in the <computeroutput>.VirtualBox</computeroutput>
+        folder as well. Both locations could be changed by the user in
+        the global preferences. The concept of a default hard disk
+        folder has been abandoned with VirtualBox 4.0, since disk images
+        now reside in each machine's folder by default.
+      </para>
+
+      <para>
+        The old layout had the following severe disadvantages:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            It was very difficult to move a virtual machine from one
+            host to another because the files involved did not reside in
+            the same folder. In addition, the virtual media of all
+            machines were registered with a global registry in the
+            central VirtualBox settings file,
+            <computeroutput>$HOME/.VirtualBox/VirtualBox.xml</computeroutput>.
+          </para>
+
+          <para>
+            To move a machine to another host, it was therefore not
+            enough to move the XML settings file and the disk images,
+            which were in different locations, but the hard disk entries
+            from the global media registry XML had to be meticulously
+            copied as well. This was close to impossible if the machine
+            had snapshots and therefore differencing images.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Storing virtual disk images, which can grow very large,
+            under the hidden
+            <computeroutput>.VirtualBox</computeroutput> directory, at
+            least on Linux and Solaris hosts, made many users wonder
+            where their disk space had gone.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Whereas new VMs created with VirtualBox 4.0 or later will
+        conform to the new layout, for maximum compatibility, old VMs
+        are <emphasis>not</emphasis> converted to the new layout.
+        Otherwise machine settings would be irrevocably broken if a user
+        downgraded from 4.0 back to an older version of VirtualBox.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Global configuration data</title>
-
-      <para>In addition to the files of the virtual machines, VirtualBox
-      maintains global configuration data. On Linux and Solaris as of VirtualBox 4.3, this
-      is in the hidden directory <computeroutput>$HOME/.config/VirtualBox</computeroutput>, although <computeroutput>$HOME/.VirtualBox</computeroutput> will be used if it exists for compatibility with earlier versions; on Windows (and on Linux and Solaris with VirtualBox 4.2 and earlier) this is in <computeroutput>$HOME/.VirtualBox</computeroutput>; on a Mac it resides in
-      <computeroutput>$HOME/Library/VirtualBox</computeroutput>.</para>
-
-      <para>VirtualBox creates this configuration directory automatically if
-      necessary. Optionally, you can supply an alternate configuration
-      directory by setting the
-      <computeroutput><literal>VBOX_USER_HOME</literal></computeroutput>
-      environment variable, or additionally on Linux or Solaris by using the standard <computeroutput><literal>XDG_CONFIG_HOME</literal></computeroutput> variable. (Since the global
-      <computeroutput>VirtualBox.xml</computeroutput> settings file points to
-      all other configuration files, this allows for switching between several
-      VirtualBox configurations entirely.)</para>
-
-      <para>Most importantly, in this directory, VirtualBox stores its global
-      settings file, another XML file called
-      <computeroutput>VirtualBox.xml</computeroutput>. This includes global
-      configuration options and the list of registered virtual machines with
-      pointers to their XML settings files. (Neither the location of this file
-      nor its directory has changed with VirtualBox 4.0.)</para>
-
-      <para>Before VirtualBox 4.0, all virtual media (disk image files) were
-      also contained in a global registry in this settings file. For
-      compatibility, this media registry still exists if you upgrade
-      VirtualBox and there are media from machines which were created with a
-      version before 4.0. If you have no such machines, then there will be no
-      global media registry; with VirtualBox 4.0, each machine XML file has
-      its own media registry.</para>
-
-      <para>Also before VirtualBox 4.0, the default "Machines" folder and the
-      default "HardDisks" folder resided under the VirtualBox configuration
-      directory (e.g.
-      <computeroutput>$HOME/.VirtualBox/Machines</computeroutput> on Linux).
-      If you are upgrading from a VirtualBox version before 4.0, files in
-      these directories are not automatically moved in order not to break
-      backwards compatibility.</para>
+    <sect2 id="vboxconfigdata-global">
+
+      <title>Global Configuration Data</title>
+
+      <para>
+        In addition to the files of the virtual machines, VirtualBox
+        maintains global configuration data. On Linux and Solaris as of
+        VirtualBox 4.3, this is in the hidden directory
+        <computeroutput>$HOME/.config/VirtualBox</computeroutput>,
+        although <computeroutput>$HOME/.VirtualBox</computeroutput> will
+        be used if it exists for compatibility with earlier versions. On
+        Windows, and on Linux and Solaris with VirtualBox 4.2 and
+        earlier, this is in
+        <computeroutput>$HOME/.VirtualBox</computeroutput>. On Mac OS X,
+        it resides in
+        <computeroutput>$HOME/Library/VirtualBox</computeroutput>.
+      </para>
+
+      <para>
+        VirtualBox creates this configuration directory automatically if
+        necessary. Optionally, you can supply an alternate configuration
+        directory by setting the
+        <computeroutput><literal>VBOX_USER_HOME</literal></computeroutput>
+        environment variable, or additionally on Linux or Solaris by
+        using the standard
+        <computeroutput><literal>XDG_CONFIG_HOME</literal></computeroutput>
+        variable. Since the global
+        <computeroutput>VirtualBox.xml</computeroutput> settings file
+        points to all other configuration files, this allows for
+        switching between several VirtualBox configurations entirely.
+      </para>
+
+      <para>
+        Most importantly, in this directory, VirtualBox stores its
+        global settings file, another XML file called
+        <computeroutput>VirtualBox.xml</computeroutput>. This includes
+        global configuration options and the list of registered virtual
+        machines with pointers to their XML settings files. Neither the
+        location of this file nor its directory has changed with
+        VirtualBox 4.0.
+      </para>
+
+      <para>
+        Before VirtualBox 4.0, all virtual media (disk image files) were
+        also contained in a global registry in this settings file. For
+        compatibility, this media registry still exists if you upgrade
+        VirtualBox and there are media from machines which were created
+        with a version before 4.0. If you have no such machines, then
+        there will be no global media registry. With VirtualBox 4.0,
+        each machine XML file has its own media registry.
+      </para>
+
+      <para>
+        Also before VirtualBox 4.0, the default "Machines" folder and
+        the default "HardDisks" folder resided under the VirtualBox
+        configuration directory, such as
+        <computeroutput>$HOME/.VirtualBox/Machines</computeroutput> on
+        Linux. If you are upgrading from a VirtualBox version before
+        4.0, files in these directories are not automatically moved in
+        order not to break backwards compatibility.
+      </para>
+
     </sect2>
 
-    <sect2>
-      <title>Summary of 4.0 configuration changes</title>
-
-      <para>The following table gives a brief overview of the configuration
-      changes between older versions and version 4.0 or above:</para>
-
-      <table>
-        <title>Configuration changes in version 4.0 or above</title>
-
+    <sect2 id="vboxconfigdata-summary-version-four">
+
+      <title>Summary of 4.0 Configuration Changes</title>
+
+      <para>
+        <xref linkend="table-version4-config-changes"/> gives a brief
+        overview of the configuration changes between legacy versions
+        and version 4.0 or later.
+      </para>
+
+      <table id="table-version4-config-changes">
+        <title>Configuration Changes in Version 4.0 or Above</title>
         <tgroup cols="3">
           <thead>
             <row>
               <entry><emphasis role="bold">Setting</emphasis></entry>
-
               <entry><emphasis role="bold">Before 4.0</emphasis></entry>
-
               <entry><emphasis role="bold">4.0 or above</emphasis></entry>
             </row>
@@ -219,41 +312,25 @@
             <row>
               <entry>Default machines folder</entry>
-
               <entry><computeroutput>$HOME/.VirtualBox/Machines</computeroutput></entry>
-
-              <entry><computeroutput>$HOME/VirtualBox
-              VMs</computeroutput></entry>
+              <entry><computeroutput>$HOME/VirtualBox VMs</computeroutput></entry>
             </row>
-
             <row>
               <entry>Default disk image location</entry>
-
               <entry><computeroutput>$HOME/.VirtualBox/HardDisks</computeroutput></entry>
-
               <entry>In each machine's folder</entry>
             </row>
-
             <row>
               <entry>Machine settings file extension</entry>
-
               <entry><computeroutput>.xml</computeroutput></entry>
-
               <entry><computeroutput>.vbox</computeroutput></entry>
             </row>
-
             <row>
               <entry>Media registry</entry>
-
-              <entry>Global <computeroutput>VirtualBox.xml</computeroutput>
-              file</entry>
-
+              <entry>Global <computeroutput>VirtualBox.xml</computeroutput> file</entry>
               <entry>Each machine settings file</entry>
             </row>
-
             <row>
               <entry>Media registration</entry>
-
               <entry>Explicit open/close required</entry>
-
               <entry>Automatic on attach</entry>
             </row>
@@ -261,702 +338,978 @@
         </tgroup>
       </table>
+
     </sect2>
 
-    <sect2>
-      <title>VirtualBox XML files</title>
-
-      <para>VirtualBox uses XML for both the machine settings files and the
-      global configuration file,
-      <computeroutput>VirtualBox.xml</computeroutput>.</para>
-
-      <para>All VirtualBox XML files are versioned. When a new settings file
-      is created (e.g. because a new virtual machine is created), VirtualBox
-      automatically uses the settings format of the current VirtualBox
-      version. These files may not be readable if you downgrade to an earlier
-      version of VirtualBox. However, when VirtualBox encounters a settings
-      file from an earlier version (e.g. after upgrading VirtualBox), it
-      attempts to preserve the settings format as much as possible. It will
-      only silently upgrade the settings format if the current settings cannot
-      be expressed in the old format, for example because you enabled a
-      feature that was not present in an earlier version of
-      VirtualBox.<footnote>
-          <para>As an example, before VirtualBox 3.1, it was only possible to
-          enable or disable a single DVD drive in a virtual machine. If it was
-          enabled, then it would always be visible as the secondary master of
-          the IDE controller. With VirtualBox 3.1, DVD drives can be attached
-          to arbitrary slots of arbitrary controllers, so they could be the
-          secondary slave of an IDE controller or in a SATA slot. If you have
-          a machine settings file from an earlier version and upgrade
-          VirtualBox to 3.1 and then move the DVD drive from its default
-          position, this cannot be expressed in the old settings format; the
-          XML machine file would get written in the new format, and a backup
-          file of the old format would be kept.</para>
-        </footnote> In such cases, VirtualBox backs up the old settings file
-      in the virtual machine's configuration directory. If you need to go back
-      to the earlier version of VirtualBox, then you will need to manually
-      copy these backup files back.</para>
-
-      <para>We intentionally do not document the specifications of the
-      VirtualBox XML files, as we must reserve the right to modify them in the
-      future. We therefore strongly suggest that you do not edit these files
-      manually. VirtualBox provides complete access to its configuration data
-      through its the <computeroutput>VBoxManage</computeroutput> command line
-      tool (see <xref linkend="vboxmanage" />) and its API (see <xref
-      linkend="VirtualBoxAPI" />).</para>
+    <sect2 id="vboxconfigdata-XML-files">
+
+      <title>VirtualBox XML Files</title>
+
+      <para>
+        VirtualBox uses XML for both the machine settings files and the
+        global configuration file,
+        <computeroutput>VirtualBox.xml</computeroutput>.
+      </para>
+
+      <para>
+        All VirtualBox XML files are versioned. When a new settings file
+        is created, for example because a new virtual machine is
+        created, VirtualBox automatically uses the settings format of
+        the current VirtualBox version. These files may not be readable
+        if you downgrade to an earlier version of VirtualBox. However,
+        when VirtualBox encounters a settings file from an earlier
+        version, such as after upgrading VirtualBox, it attempts to
+        preserve the settings format as much as possible. It will only
+        silently upgrade the settings format if the current settings
+        cannot be expressed in the old format, for example because you
+        enabled a feature that was not present in an earlier version of
+        VirtualBox.
+
+        <footnote>
+
+          <para>
+            As an example, before VirtualBox 3.1, it was only possible
+            to enable or disable a single DVD drive in a virtual
+            machine. If it was enabled, then it would always be visible
+            as the secondary master of the IDE controller. With
+            VirtualBox 3.1, DVD drives can be attached to arbitrary
+            slots of arbitrary controllers, so they could be the
+            secondary slave of an IDE controller or in a SATA slot. If
+            you have a machine settings file from an earlier version and
+            upgrade VirtualBox to 3.1 and then move the DVD drive from
+            its default position, this cannot be expressed in the old
+            settings format; the XML machine file would get written in
+            the new format, and a backup file of the old format would be
+            kept.
+          </para>
+
+        </footnote>
+
+        In such cases, VirtualBox backs up the old settings file in the
+        virtual machine's configuration directory. If you need to go
+        back to the earlier version of VirtualBox, then you will need to
+        manually copy these backup files back.
+      </para>
+
+      <para>
+        We intentionally do not document the specifications of the
+        VirtualBox XML files, as we must reserve the right to modify
+        them in the future. We therefore strongly suggest that you do
+        not edit these files manually. VirtualBox provides complete
+        access to its configuration data through its the
+        <computeroutput>VBoxManage</computeroutput> command line tool,
+        see <xref linkend="vboxmanage" /> and its API, see
+        <xref
+      linkend="VirtualBoxAPI" />.
+      </para>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="technical-components">
-    <title>VirtualBox executables and components</title>
-
-    <para>VirtualBox was designed to be modular and flexible. When the
-    VirtualBox graphical user interface (GUI) is opened and a VM is started,
-    at least three processes are running:<orderedlist>
-        <listitem>
-          <para><computeroutput>VBoxSVC</computeroutput>, the VirtualBox
-          service process which always runs in the background. This process is
-          started automatically by the first VirtualBox client process (the
-          GUI, <computeroutput>VBoxManage</computeroutput>,
-          <computeroutput>VBoxHeadless</computeroutput>, the web service or
-          others) and exits a short time after the last client exits. The
-          service is responsible for bookkeeping, maintaining the state of all
-          VMs, and for providing communication between VirtualBox components.
-          This communication is implemented via COM/XPCOM.<note>
-              <para>When we refer to "clients" here, we mean the local clients
-              of a particular <computeroutput>VBoxSVC</computeroutput> server
-              process, not clients in a network. VirtualBox employs its own
-              client/server design to allow its processes to cooperate, but
-              all these processes run under the same user account on the host
-              operating system, and this is totally transparent to the
-              user.</para>
-            </note></para>
-        </listitem>
-
-        <listitem>
-          <para>The GUI process, <computeroutput>VirtualBox</computeroutput>,
-          a client application based on the cross-platform Qt library. When
-          started without the <computeroutput>--startvm</computeroutput>
-          option, this application acts as the VirtualBox manager, displaying
-          the VMs and their settings. It then communicates settings and state
+
+    <title>VirtualBox Executables and Components</title>
+
+    <para>
+      VirtualBox was designed to be modular and flexible. When the
+      VirtualBox graphical user interface (GUI) is opened and a VM is
+      started, at least the following three processes are running:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxSVC</computeroutput>, the VirtualBox
+          service process which always runs in the background. This
+          process is started automatically by the first VirtualBox
+          client process and exits a short time after the last client
+          exits. The first VirtualBox service can be the GUI,
+          <computeroutput>VBoxManage</computeroutput>,
+          <computeroutput>VBoxHeadless</computeroutput>, the web service
+          amongst others. The service is responsible for bookkeeping,
+          maintaining the state of all VMs, and for providing
+          communication between VirtualBox components. This
+          communication is implemented via COM/XPCOM.
+        </para>
+
+        <note>
+          <para>
+            When we refer to "clients" here, we mean the local clients
+            of a particular <computeroutput>VBoxSVC</computeroutput>
+            server process, not clients in a network. VirtualBox employs
+            its own client/server design to allow its processes to
+            cooperate, but all these processes run under the same user
+            account on the host operating system, and this is totally
+            transparent to the user.
+          </para>
+        </note>
+      </listitem>
+
+      <listitem>
+        <para>
+          The GUI process, <computeroutput>VirtualBox</computeroutput>,
+          a client application based on the cross-platform Qt library.
+          When started without the
+          <computeroutput>--startvm</computeroutput> option, this
+          application acts as the VirtualBox manager, displaying the VMs
+          and their settings. It then communicates settings and state
           changes to <computeroutput>VBoxSVC</computeroutput> and also
-          reflects changes effected through other means, e.g.,
-          <computeroutput>VBoxManage</computeroutput>.</para>
-        </listitem>
-
-        <listitem>
-          <para>If the <computeroutput>VirtualBox</computeroutput> client
+          reflects changes effected through other means, such as
+          <computeroutput>VBoxManage</computeroutput>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          If the <computeroutput>VirtualBox</computeroutput> client
           application is started with the
-          <computeroutput>--startvm</computeroutput> argument, it loads the
-          VMM library which includes the actual hypervisor and then runs a
-          virtual machine and provides the input and output for the
-          guest.</para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>Any VirtualBox front-end (client) will communicate with the service
-    process and can both control and reflect the current state. For example,
-    either the VM selector or the VM window or VBoxManage can be used to pause
-    the running VM, and other components will always reflect the changed
-    state.</para>
-
-    <para>The VirtualBox GUI application is only one of several available
-    front ends (clients). The complete list shipped with VirtualBox
-    is:<orderedlist>
-        <listitem>
-          <para><computeroutput>VirtualBox</computeroutput>, the Qt front end
-          implementing the manager and running VMs;</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxManage</computeroutput>, a less
-          user-friendly but more powerful alternative, described in <xref
-          linkend="vboxmanage" />.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxSDL</computeroutput>, a simple graphical
-          front end based on the SDL library; see <xref
-          linkend="vboxsdl" />.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxHeadless</computeroutput>, a VM front end
-          which does not directly provide any video output and keyboard/mouse
-          input, but allows redirection via VirtualBox Remote Desktop Extension;
-          see <xref linkend="vboxheadless" />.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>vboxwebsrv</computeroutput>, the VirtualBox
-          web service process which allows for controlling a VirtualBox host
-          remotely. This is described in detail in the VirtualBox Software
-          Development Kit (SDK) reference; please see <xref
-          linkend="VirtualBoxAPI" /> for details.</para>
-        </listitem>
-
-        <listitem>
-          <para>The VirtualBox Python shell, a Python alternative to
-          VBoxManage. This is also described in the SDK reference.</para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>Internally, VirtualBox consists of many more or less separate
-    components. You may encounter these when analyzing VirtualBox internal
-    error messages or log files. These include:</para>
+          <computeroutput>--startvm</computeroutput> argument, it loads
+          the VMM library which includes the actual hypervisor and then
+          runs a virtual machine and provides the input and output for
+          the guest.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Any VirtualBox front-end, or client, will communicate with the
+      service process and can both control and reflect the current
+      state. For example, either the VM selector or the VM window or
+      VBoxManage can be used to pause the running VM, and other
+      components will always reflect the changed state.
+    </para>
+
+    <para>
+      The VirtualBox GUI application is only one of several available
+      front ends, or clients. The complete list shipped with VirtualBox
+      is as follows:
+    </para>
 
     <itemizedlist>
-      <listitem>
-        <para>IPRT, a portable runtime library which abstracts file access,
-        threading, string manipulation, etc. Whenever VirtualBox accesses host
-        operating features, it does so through this library for cross-platform
-        portability.</para>
-      </listitem>
-
-      <listitem>
-        <para>VMM (Virtual Machine Monitor), the heart of the
-        hypervisor.</para>
-      </listitem>
-
-      <listitem>
-        <para>EM (Execution Manager), controls execution of guest code.</para>
-      </listitem>
-
-      <listitem>
-        <para>REM (Recompiled Execution Monitor), provides software emulation
-        of CPU instructions.</para>
-      </listitem>
-
-      <listitem>
-        <para>TRPM (Trap Manager), intercepts and processes guest traps and
-        exceptions.</para>
-      </listitem>
-
-      <listitem>
-        <para>HM (Hardware Acceleration Manager), provides support for VT-x
-        and AMD-V.</para>
-      </listitem>
-
-      <listitem>
-        <para>GIM (Guest Interface Manager), provides support for various
-        paravirtualization interfaces to the guest.</para>
-      </listitem>
-
-      <listitem>
-        <para>PDM (Pluggable Device Manager), an abstract interface between
-        the VMM and emulated devices which separates device implementations
-        from VMM internals and makes it easy to add new emulated devices.
-        Through PDM, third-party developers can add new virtual devices to
-        VirtualBox without having to change VirtualBox itself.</para>
-      </listitem>
-
-      <listitem>
-        <para>PGM (Page Manager), a component controlling guest paging.</para>
-      </listitem>
-
-      <listitem>
-        <para>PATM (Patch Manager), patches guest code to improve and speed up
-        software virtualization.</para>
-      </listitem>
-
-      <listitem>
-        <para>TM (Time Manager), handles timers and all aspects of time inside
-        guests.</para>
-      </listitem>
-
-      <listitem>
-        <para>CFGM (Configuration Manager), provides a tree structure which
-        holds configuration settings for the VM and all emulated
-        devices.</para>
-      </listitem>
-
-      <listitem>
-        <para>SSM (Saved State Manager), saves and loads VM state.</para>
-      </listitem>
-
-      <listitem>
-        <para>VUSB (Virtual USB), a USB layer which separates emulated USB
-        controllers from the controllers on the host and from USB devices;
-        this also enables remote USB.</para>
-      </listitem>
-
-      <listitem>
-        <para>DBGF (Debug Facility), a built-in VM debugger.</para>
-      </listitem>
-
-      <listitem>
-        <para>VirtualBox emulates a number of devices to provide the hardware
-        environment that various guests need. Most of these are standard
-        devices found in many PC compatible machines and widely supported by
-        guest operating systems. For network and storage devices in
-        particular, there are several options for the emulated devices to
-        access the underlying hardware. These devices are managed by
-        PDM.</para>
-      </listitem>
-
-      <listitem>
-        <para>Guest Additions for various guest operating systems. This is
-        code that is installed from within a virtual machine; see <xref
-        linkend="guestadditions" />.</para>
-      </listitem>
-
-      <listitem>
-        <para>The "Main" component is special: it ties all the above bits
-        together and is the only public API that VirtualBox provides. All the
-        client processes listed above use only this API and never access the
-        hypervisor components directly. As a result, third-party applications
-        that use the VirtualBox Main API can rely on the fact that it is
-        always well-tested and that all capabilities of VirtualBox are fully
-        exposed. It is this API that is described in the VirtualBox SDK
-        mentioned above (again, see <xref linkend="VirtualBoxAPI" />).</para>
-      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VirtualBox</computeroutput>: The Qt front end
+          implementing the manager and running VMs.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxManage</computeroutput>: A less
+          user-friendly but more powerful alternative. See
+          <xref
+          linkend="vboxmanage" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxSDL</computeroutput>: A simple graphical
+          front end based on the SDL library. See
+          <xref
+          linkend="vboxsdl" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxHeadless</computeroutput>: A VM front end
+          which does not directly provide any video output and
+          keyboard/mouse input, but allows redirection via VirtualBox
+          Remote Desktop Extension. See <xref linkend="vboxheadless" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>vboxwebsrv</computeroutput>: The VirtualBox
+          web service process which allows for controlling a VirtualBox
+          host remotely. This is described in detail in the VirtualBox
+          Software Development Kit (SDK) reference. See
+          <xref
+          linkend="VirtualBoxAPI" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The VirtualBox Python shell: A Python alternative to
+          VBoxManage. This is also described in the SDK reference.
+        </para>
+      </listitem>
+
     </itemizedlist>
+
+    <para>
+      Internally, VirtualBox consists of many more or less separate
+      components. You may encounter these when analyzing VirtualBox
+      internal error messages or log files. These include the following:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          IPRT: A portable runtime library which abstracts file access,
+          threading, and string manipulation. Whenever VirtualBox
+          accesses host operating features, it does so through this
+          library for cross-platform portability.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          VMM (Virtual Machine Monitor): The heart of the hypervisor.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          EM (Execution Manager): Controls execution of guest code.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          REM (Recompiled Execution Monitor): Provides software
+          emulation of CPU instructions.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          TRPM (Trap Manager): Intercepts and processes guest traps and
+          exceptions.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          HM (Hardware Acceleration Manager): Provides support for VT-x
+          and AMD-V.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          GIM (Guest Interface Manager): Provides support for various
+          paravirtualization interfaces to the guest.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          PDM (Pluggable Device Manager): An abstract interface between
+          the VMM and emulated devices which separates device
+          implementations from VMM internals and makes it easy to add
+          new emulated devices. Through PDM, third-party developers can
+          add new virtual devices to VirtualBox without having to change
+          VirtualBox itself.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          PGM (Page Manager): A component that controls guest paging.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          PATM (Patch Manager): Patches guest code to improve and speed
+          up software virtualization.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          TM (Time Manager): Handles timers and all aspects of time
+          inside guests.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          CFGM (Configuration Manager): Provides a tree structure which
+          holds configuration settings for the VM and all emulated
+          devices.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          SSM (Saved State Manager): Saves and loads VM state.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          VUSB (Virtual USB): A USB layer which separates emulated USB
+          controllers from the controllers on the host and from USB
+          devices. This component also enables remote USB.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          DBGF (Debug Facility): A built-in VM debugger.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          VirtualBox emulates a number of devices to provide the
+          hardware environment that various guests need. Most of these
+          are standard devices found in many PC compatible machines and
+          widely supported by guest operating systems. For network and
+          storage devices in particular, there are several options for
+          the emulated devices to access the underlying hardware. These
+          devices are managed by PDM.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Guest Additions for various guest operating systems. This is
+          code that is installed from within a virtual machine. See
+          <xref
+        linkend="guestadditions" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The "Main" component is special. It ties all the above bits
+          together and is the only public API that VirtualBox provides.
+          All the client processes listed above use only this API and
+          never access the hypervisor components directly. As a result,
+          third-party applications that use the VirtualBox Main API can
+          rely on the fact that it is always well-tested and that all
+          capabilities of VirtualBox are fully exposed. It is this API
+          that is described in the VirtualBox SDK. See
+          <xref linkend="VirtualBoxAPI" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
   <sect1 id="hwvirt">
-    <title>Hardware vs. software virtualization</title>
-
-    <para>VirtualBox allows software in the virtual machine to run directly on
-    the processor of the host, but an array of complex techniques is employed
-    to intercept operations that would interfere with your host. Whenever the
-    guest attempts to do something that could be harmful to your computer and
-    its data, VirtualBox steps in and takes action. In particular, for lots of
-    hardware that the guest believes to be accessing, VirtualBox simulates a
-    certain "virtual" environment according to how you have configured a
-    virtual machine. For example, when the guest attempts to access a hard
-    disk, VirtualBox redirects these requests to whatever you have configured
-    to be the virtual machine's virtual hard disk -- normally, an image file
-    on your host.</para>
-
-    <para>Unfortunately, the x86 platform was never designed to be
-    virtualized. Detecting situations in which VirtualBox needs to take
-    control over the guest code that is executing, as described above, is
-    difficult. There are two ways in which to achieve this:<itemizedlist>
-        <listitem>
-          <para>Since 2006, Intel and AMD processors have had support for
-          so-called <emphasis role="bold">"hardware
-          virtualization"</emphasis>. This means that these processors can
-          help VirtualBox to intercept potentially dangerous operations that a
-          guest operating system may be attempting and also makes it easier to
-          present virtual hardware to a virtual machine.</para>
-
-          <para>These hardware features differ between Intel and AMD
-          processors. Intel named its technology <emphasis
-          role="bold">VT-x</emphasis>; AMD calls theirs <emphasis
-          role="bold">AMD-V</emphasis>. The Intel and AMD support for
-          virtualization is very different in detail, but not very different
-          in principle.<note>
-              <para>On many systems, the hardware virtualization features
-              first need to be enabled in the BIOS before VirtualBox can use
-              them.</para>
-            </note></para>
-        </listitem>
-
-        <listitem>
-          <para>As opposed to other virtualization software, for many usage
-          scenarios, VirtualBox does not <emphasis>require</emphasis> hardware
-          virtualization features to be present. Through sophisticated
-          techniques, VirtualBox virtualizes many guest operating systems
-          entirely in <emphasis role="bold">software</emphasis>. This means
-          that you can run virtual machines even on older processors which do
-          not support hardware virtualization.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>Even though VirtualBox does not always require hardware
-    virtualization, enabling it is <emphasis>required</emphasis> in the
-    following scenarios:<itemizedlist>
-        <listitem>
-          <para>Certain rare guest operating systems like OS/2 make use of
-          very esoteric processor instructions that are not supported with our
-          software virtualization. For virtual machines that are configured to
-          contain such an operating system, hardware virtualization is enabled
-          automatically.</para>
-        </listitem>
-
-        <listitem>
-          <para>VirtualBox's 64-bit guest support (added with version 2.0) and
-          multiprocessing (SMP, added with version 3.0) both require hardware
-          virtualization to be enabled. (This is not much of a limitation
-          since the vast majority of today's 64-bit and multicore CPUs ship
-          with hardware virtualization anyway; the exceptions to this rule are
-          e.g. older Intel Celeron and AMD Opteron CPUs.)</para>
-        </listitem>
-      </itemizedlist></para>
+
+    <title>Hardware vs. Software Virtualization</title>
+
+    <para>
+      VirtualBox allows software in the virtual machine to run directly
+      on the processor of the host, but an array of complex techniques
+      is employed to intercept operations that would interfere with your
+      host. Whenever the guest attempts to do something that could be
+      harmful to your computer and its data, VirtualBox steps in and
+      takes action. In particular, for lots of hardware that the guest
+      believes to be accessing, VirtualBox simulates a certain "virtual"
+      environment according to how you have configured a virtual
+      machine. For example, when the guest attempts to access a hard
+      disk, VirtualBox redirects these requests to whatever you have
+      configured to be the virtual machine's virtual hard disk. This is
+      normally an image file on your host.
+    </para>
+
+    <para>
+      Unfortunately, the x86 platform was never designed to be
+      virtualized. Detecting situations in which VirtualBox needs to
+      take control over the guest code that is executing, as described
+      above, is difficult. There are two ways in which to achieve this:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Since 2006, Intel and AMD processors have had support for
+          so-called <emphasis>hardware virtualization</emphasis>. This
+          means that these processors can help VirtualBox to intercept
+          potentially dangerous operations that a guest operating system
+          may be attempting and also makes it easier to present virtual
+          hardware to a virtual machine.
+        </para>
+
+        <para>
+          These hardware features differ between Intel and AMD
+          processors. Intel named its technology >VT-x. AMD calls theirs
+          AMD-V. The Intel and AMD support for virtualization is very
+          different in detail, but not very different in principle.
+        </para>
+
+        <note>
+          <para>
+            On many systems, the hardware virtualization features first
+            need to be enabled in the BIOS before VirtualBox can use
+            them.
+          </para>
+        </note>
+      </listitem>
+
+      <listitem>
+        <para>
+          As opposed to other virtualization software, for many usage
+          scenarios, VirtualBox does not <emphasis>require</emphasis>
+          hardware virtualization features to be present. Through
+          sophisticated techniques, VirtualBox virtualizes many guest
+          operating systems entirely in <emphasis>software</emphasis>.
+          This means that you can run virtual machines even on older
+          processors which do not support hardware virtualization.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Even though VirtualBox does not always require hardware
+      virtualization, enabling it is <emphasis>required</emphasis> in
+      the following scenarios:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Certain rare guest operating systems like OS/2 make use of
+          very esoteric processor instructions that are not supported
+          with our software virtualization. For virtual machines that
+          are configured to contain such an operating system, hardware
+          virtualization is enabled automatically.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          VirtualBox's 64-bit guest support (added with version 2.0) and
+          multiprocessing (SMP, added with version 3.0) both require
+          hardware virtualization to be enabled. This is not much of a
+          limitation since the vast majority of today's 64-bit and
+          multicore CPUs ship with hardware virtualization anyway. The
+          exceptions to this rule are older Intel Celeron and AMD
+          Opteron CPUs, for example.
+        </para>
+      </listitem>
+
+    </itemizedlist>
 
     <warning>
-      <para>Do not run other hypervisors (open-source or commercial
-      virtualization products) together with VirtualBox! While several
-      hypervisors can normally be <emphasis>installed</emphasis> in parallel,
-      do not attempt to <emphasis>run</emphasis> several virtual machines from
-      competing hypervisors at the same time. VirtualBox cannot track what
-      another hypervisor is currently attempting to do on the same host, and
-      especially if several products attempt to use hardware virtualization
-      features such as VT-x, this can crash the entire host. Also, within
-      VirtualBox, you can mix software and hardware virtualization when
-      running multiple VMs. In certain cases a small performance penalty will
-      be unavoidable when mixing VT-x and software virtualization VMs. We
-      recommend not mixing virtualization modes if maximum performance and low
-      overhead are essential. This does <emphasis>not</emphasis> apply to
-      AMD-V.</para>
+      <para>
+        Do not run other hypervisors, either open source or commercial
+        virtualization products, together with VirtualBox. While several
+        hypervisors can normally be <emphasis>installed</emphasis> in
+        parallel, do not attempt to <emphasis>run</emphasis> several
+        virtual machines from competing hypervisors at the same time.
+        VirtualBox cannot track what another hypervisor is currently
+        attempting to do on the same host, and especially if several
+        products attempt to use hardware virtualization features such as
+        VT-x, this can crash the entire host. Also, within VirtualBox,
+        you can mix software and hardware virtualization when running
+        multiple VMs. In certain cases a small performance penalty will
+        be unavoidable when mixing VT-x and software virtualization VMs.
+        We recommend not mixing virtualization modes if maximum
+        performance and low overhead are essential. This does
+        <emphasis>not</emphasis> apply to AMD-V.
+      </para>
     </warning>
+
   </sect1>
 
   <sect1 id="gimproviders">
-    <title>Paravirtualization providers</title>
-
-    <para>VirtualBox allows exposing a paravirtualization interface to
-    facilitate accurate and efficient execution of software within a
-    virtual machine. These interfaces require the guest operating system
-    to recognize their presence and make use of them in order to leverage
-    the benefits of communicating with the VirtualBox hypervisor.</para>
-
-    <para>Most modern mainstream guest operating systems, including
-    Windows and Linux, ship with support for one or more paravirtualization
-    interfaces. Hence, there is typically no need to install additional software
-    in the guest to take advantage of this feature.
-    </para>
-
-    <para>Exposing a paravirtualization provider to the guest operating
-    system does not rely on the choice of host platforms. For example, the
-    <emphasis>Hyper-V</emphasis> paravirtualization provider can be
-    used for VMs to run on any host platform (supported by VirtualBox) and
-    not just Windows.</para>
-
-    <para>VirtualBox provides the following interfaces:</para>
-      <itemizedlist>
-        <listitem>
-          <para><emphasis role="bold">Minimal</emphasis>: Announces the
-          presence of a virtualized environment. Additionally, reports the
-          TSC and APIC frequency to the guest operating system. This provider
-          is mandatory for running any Mac OS X guests.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">KVM</emphasis>: Presents a Linux KVM
-          hypervisor interface which is recognized by Linux kernels starting
-          with version 2.6.25. VirtualBox's implementation currently supports
-          paravirtualized clocks and SMP spinlocks. This provider is
-          recommended for Linux guests.</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold">Hyper-V</emphasis>: Presents a Microsoft
-          Hyper-V hypervisor interface which is recognized by Windows 7 and newer
-          operating systems. VirtualBox's implementation currently supports
-          paravirtualized clocks, APIC frequency reporting, guest debugging,
-          guest crash reporting and relaxed timer checks. This provider is
-          recommended for Windows guests.
-          </para>
-        </listitem>
-     </itemizedlist>
+
+    <title>Paravirtualization Providers</title>
+
+    <para>
+      VirtualBox allows exposing a paravirtualization interface to
+      facilitate accurate and efficient execution of software within a
+      virtual machine. These interfaces require the guest operating
+      system to recognize their presence and make use of them in order
+      to leverage the benefits of communicating with the VirtualBox
+      hypervisor.
+    </para>
+
+    <para>
+      Most modern mainstream guest operating systems, including Windows
+      and Linux, ship with support for one or more paravirtualization
+      interfaces. Hence, there is typically no need to install
+      additional software in the guest to take advantage of this
+      feature.
+    </para>
+
+    <para>
+      Exposing a paravirtualization provider to the guest operating
+      system does not rely on the choice of host platforms. For example,
+      the <emphasis>Hyper-V</emphasis> paravirtualization provider can
+      be used for VMs to run on any host platform supported by
+      VirtualBox and not just Windows.
+    </para>
+
+    <para>
+      VirtualBox provides the following interfaces:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Minimal</emphasis>: Announces the
+          presence of a virtualized environment. Additionally, reports
+          the TSC and APIC frequency to the guest operating system. This
+          provider is mandatory for running any Mac OS X guests.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">KVM</emphasis>: Presents a Linux KVM
+          hypervisor interface which is recognized by Linux kernels
+          starting with version 2.6.25. VirtualBox's implementation
+          currently supports paravirtualized clocks and SMP spinlocks.
+          This provider is recommended for Linux guests.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold">Hyper-V</emphasis>: Presents a Microsoft
+          Hyper-V hypervisor interface which is recognized by Windows 7
+          and newer operating systems. VirtualBox's implementation
+          currently supports paravirtualized clocks, APIC frequency
+          reporting, guest debugging, guest crash reporting and relaxed
+          timer checks. This provider is recommended for Windows guests.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
-  <sect1>
-    <title>Details about software virtualization</title>
-
-    <para>Implementing virtualization on x86 CPUs with no hardware
-    virtualization support is an extraordinarily complex task because the CPU
-    architecture was not designed to be virtualized. The problems can usually
-    be solved, but at the cost of reduced performance. Thus, there is a
-    constant clash between virtualization performance and accuracy.</para>
-
-    <para>The x86 instruction set was originally designed in the 1970s and
-    underwent significant changes with the addition of protected mode in the
-    1980s with the 286 CPU architecture and then again with the Intel 386 and
-    its 32-bit architecture. Whereas the 386 did have limited virtualization
-    support for real mode operation (V86 mode, as used by the "DOS Box" of
-    Windows 3.x and OS/2 2.x), no support was provided for virtualizing the
-    entire architecture.</para>
-
-    <para>In theory, software virtualization is not overly complex. In
-    addition to the four privilege levels ("rings") provided by the hardware
-    (of which typically only two are used: ring 0 for kernel mode and ring 3
-    for user mode), one needs to differentiate between "host context" and
-    "guest context".</para>
-
-    <para>In "host context", everything is as if no hypervisor was active.
-    This might be the active mode if another application on your host has been
-    scheduled CPU time; in that case, there is a host ring 3 mode and a host
-    ring 0 mode. The hypervisor is not involved.</para>
-
-    <para>In "guest context", however, a virtual machine is active. So long as
-    the guest code is running in ring 3, this is not much of a problem since a
-    hypervisor can set up the page tables properly and run that code natively
-    on the processor. The problems mostly lie in how to intercept what the
-    guest's kernel does.</para>
-
-    <para>There are several possible solutions to these problems. One approach
-    is full software emulation, usually involving recompilation. That is, all
-    code to be run by the guest is analyzed, transformed into a form which
-    will not allow the guest to either modify or see the true state of the
-    CPU, and only then executed. This process is obviously highly complex and
-    costly in terms of performance. (VirtualBox contains a recompiler based on
-    QEMU which can be used for pure software emulation, but the recompiler is
-    only activated in special situations, described below.)</para>
-
-    <para>Another possible solution is paravirtualization, in which only
-    specially modified guest OSes are allowed to run. This way, most of the
-    hardware access is abstracted and any functions which would normally
-    access the hardware or privileged CPU state are passed on to the
-    hypervisor instead. Paravirtualization can achieve good functionality and
-    performance on standard x86 CPUs, but it can only work if the guest OS can
-    actually be modified, which is obviously not always the case.</para>
-
-    <para>VirtualBox chooses a different approach. When starting a virtual
-    machine, through its ring-0 support kernel driver, VirtualBox has set up
-    the host system so that it can run most of the guest code natively, but it
-    has inserted itself at the "bottom" of the picture. It can then assume
-    control when needed -- if a privileged instruction is executed, the guest
-    traps (in particular because an I/O register was accessed and a device
-    needs to be virtualized) or external interrupts occur. VirtualBox may then
-    handle this and either route a request to a virtual device or possibly
-    delegate handling such things to the guest or host OS. In guest context,
-    VirtualBox can therefore be in one of three states:</para>
-
-    <para><itemizedlist>
-        <listitem>
-          <para>Guest ring 3 code is run unmodified, at full speed, as much as
-          possible. The number of faults will generally be low (unless the
-          guest allows port I/O from ring 3, something we cannot do as we
-          don't want the guest to be able to access real ports). This is also
-          referred to as "raw mode", as the guest ring-3 code runs
-          unmodified.</para>
-        </listitem>
-
-        <listitem>
-          <para>For guest code in ring 0, VirtualBox employs a nasty trick: it
-          actually reconfigures the guest so that its ring-0 code is run in
-          ring 1 instead (which is normally not used in x86 operating
-          systems). As a result, when guest ring-0 code (actually running in
-          ring 1) such as a guest device driver attempts to write to an I/O
-          register or execute a privileged instruction, the VirtualBox
-          hypervisor in "real" ring 0 can take over.</para>
-        </listitem>
-
-        <listitem>
-          <para>The hypervisor (VMM) can be active. Every time a fault occurs,
-          VirtualBox looks at the offending instruction and can relegate it to
-          a virtual device or the host OS or the guest OS or run it in the
-          recompiler.</para>
-
-          <para>In particular, the recompiler is used when guest code disables
+  <sect1 id="swvirt-details">
+
+    <title>Details About Software Virtualization</title>
+
+    <para>
+      Implementing virtualization on x86 CPUs with no hardware
+      virtualization support is an extraordinarily complex task because
+      the CPU architecture was not designed to be virtualized. The
+      problems can usually be solved, but at the cost of reduced
+      performance. Thus, there is a constant clash between
+      virtualization performance and accuracy.
+    </para>
+
+    <para>
+      The x86 instruction set was originally designed in the 1970s and
+      underwent significant changes with the addition of protected mode
+      in the 1980s with the 286 CPU architecture and then again with the
+      Intel 386 and its 32-bit architecture. Whereas the 386 did have
+      limited virtualization support for real mode operation (V86 mode,
+      as used by the "DOS Box" of Windows 3.x and OS/2 2.x), no support
+      was provided for virtualizing the entire architecture.
+    </para>
+
+    <para>
+      In theory, software virtualization is not overly complex. There
+      are four privilege levels, called <emphasis>rings</emphasis>,
+      provided by the hardware. Typically only two rings are used: ring
+      0 for kernel mode and ring 3 for user mode. Additionally, one
+      needs to differentiate between <emphasis>host context</emphasis>
+      and <emphasis>guest context</emphasis>.
+    </para>
+
+    <para>
+      In host context, everything is as if no hypervisor was active.
+      This might be the active mode if another application on your host
+      has been scheduled CPU time. In that case, there is a host ring 3
+      mode and a host ring 0 mode. The hypervisor is not involved.
+    </para>
+
+    <para>
+      In guest context, however, a virtual machine is active. So long as
+      the guest code is running in ring 3, this is not much of a problem
+      since a hypervisor can set up the page tables properly and run
+      that code natively on the processor. The problems mostly lie in
+      how to intercept what the guest's kernel does.
+    </para>
+
+    <para>
+      There are several possible solutions to these problems. One
+      approach is full software emulation, usually involving
+      recompilation. That is, all code to be run by the guest is
+      analyzed, transformed into a form which will not allow the guest
+      to either modify or see the true state of the CPU, and only then
+      executed. This process is obviously highly complex and costly in
+      terms of performance. VirtualBox contains a recompiler based on
+      QEMU which can be used for pure software emulation, but the
+      recompiler is only activated in special situations, described
+      below.
+    </para>
+
+    <para>
+      Another possible solution is paravirtualization, in which only
+      specially modified guest OSes are allowed to run. This way, most
+      of the hardware access is abstracted and any functions which would
+      normally access the hardware or privileged CPU state are passed on
+      to the hypervisor instead. Paravirtualization can achieve good
+      functionality and performance on standard x86 CPUs, but it can
+      only work if the guest OS can actually be modified, which is
+      obviously not always the case.
+    </para>
+
+    <para>
+      VirtualBox chooses a different approach. When starting a virtual
+      machine, through its ring-0 support kernel driver, VirtualBox has
+      set up the host system so that it can run most of the guest code
+      natively, but it has inserted itself at the "bottom" of the
+      picture. It can then assume control when needed. If a privileged
+      instruction is executed, the guest traps, in particular because an
+      I/O register was accessed and a device needs to be virtualized, or
+      external interrupts occur. VirtualBox may then handle this and
+      either route a request to a virtual device or possibly delegate
+      handling such things to the guest or host OS. In guest context,
+      VirtualBox can therefore be in one of three states:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Guest ring 3 code is run unmodified, at full speed, as much as
+          possible. The number of faults will generally be low, unless
+          the guest allows port I/O from ring 3. This is something we
+          cannot do as we do not want the guest to be able to access
+          real ports. This is also referred to as <emphasis>raw
+          mode</emphasis>, as the guest ring-3 code runs unmodified.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          For guest code in ring 0, VirtualBox employs a clever trick.
+          It actually reconfigures the guest so that its ring-0 code is
+          run in ring 1 instead, which is normally not used in x86
+          operating systems). As a result, when guest ring-0 code,
+          actually running n ring 1, such as a guest device driver
+          attempts to write to an I/O register or execute a privileged
+          instruction, the VirtualBox hypervisor in the "real" ring 0
+          can take over.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The hypervisor (VMM) can be active. Every time a fault occurs,
+          VirtualBox looks at the offending instruction and can relegate
+          it to a virtual device or the host OS or the guest OS or run
+          it in the recompiler.
+        </para>
+
+        <para>
+          In particular, the recompiler is used when guest code disables
           interrupts and VirtualBox cannot figure out when they will be
-          switched back on (in these situations, VirtualBox actually analyzes
-          the guest code using its own disassembler). Also, certain privileged
-          instructions such as LIDT need to be handled specially. Finally, any
-          real-mode or protected-mode code (e.g. BIOS code, a DOS guest, or
-          any operating system startup) is run in the recompiler
-          entirely.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>Unfortunately this only works to a degree. Among others, the
-    following situations require special handling:</para>
-
-    <para><orderedlist>
-        <listitem>
-          <para>Running ring 0 code in ring 1 causes a lot of additional
+          switched back on. In these situations, VirtualBox actually
+          analyzes the guest code using its own disassembler. Also,
+          certain privileged instructions such as LIDT need to be
+          handled specially. Finally, any real-mode or protected-mode
+          code, such as BIOS code, a DOS guest, or any operating system
+          startup, is run in the recompiler entirely.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Unfortunately this only works to a degree. Among others, the
+      following situations require special handling:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Running ring 0 code in ring 1 causes a lot of additional
           instruction faults, as ring 1 is not allowed to execute any
-          privileged instructions (of which guest's ring-0 contains plenty).
-          With each of these faults, the VMM must step in and emulate the code
-          to achieve the desired behavior. While this works, emulating
-          thousands of these faults is very expensive and severely hurts the
-          performance of the virtualized guest.</para>
-        </listitem>
-
-        <listitem>
-          <para>There are certain flaws in the implementation of ring 1 in the
-          x86 architecture that were never fixed. Certain instructions that
-          <emphasis>should</emphasis> trap in ring 1 don't. This affects, for
-          example, the LGDT/SGDT, LIDT/SIDT, or POPF/PUSHF instruction pairs.
-          Whereas the "load" operation is privileged and can therefore be
-          trapped, the "store" instruction always succeed. If the guest is
-          allowed to execute these, it will see the true state of the CPU, not
-          the virtualized state. The CPUID instruction also has the same
-          problem.</para>
-        </listitem>
-
-        <listitem>
-          <para>A hypervisor typically needs to reserve some portion of the
-          guest's address space (both linear address space and selectors) for
-          its own use. This is not entirely transparent to the guest OS and
-          may cause clashes.</para>
-        </listitem>
-
-        <listitem>
-          <para>The SYSENTER instruction (used for system calls) executed by
-          an application running in a guest OS always transitions to ring 0.
-          But that is where the hypervisor runs, not the guest OS. In this
-          case, the hypervisor must trap and emulate the instruction even when
-          it is not desirable.</para>
-        </listitem>
-
-        <listitem>
-          <para>The CPU segment registers contain a "hidden" descriptor cache
-          which is not software-accessible. The hypervisor cannot read, save,
-          or restore this state, but the guest OS may use it.</para>
-        </listitem>
-
-        <listitem>
-          <para>Some resources must (and can) be trapped by the hypervisor,
+          privileged instructions, of which guest's ring-0 contains
+          plenty. With each of these faults, the VMM must step in and
+          emulate the code to achieve the desired behavior. While this
+          works, emulating thousands of these faults is very expensive
+          and severely hurts the performance of the virtualized guest.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          There are certain flaws in the implementation of ring 1 in the
+          x86 architecture that were never fixed. Certain instructions
+          that <emphasis>should</emphasis> trap in ring 1 do not. This
+          affects, for example, the LGDT/SGDT, LIDT/SIDT, or POPF/PUSHF
+          instruction pairs. Whereas the "load" operation is privileged
+          and can therefore be trapped, the "store" instruction always
+          succeed. If the guest is allowed to execute these, it will see
+          the true state of the CPU, not the virtualized state. The
+          CPUID instruction also has the same problem.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          A hypervisor typically needs to reserve some portion of the
+          guest's address space, both linear address space and
+          selectors, for its own use. This is not entirely transparent
+          to the guest OS and may cause clashes.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The SYSENTER instruction, used for system calls, executed by
+          an application running in a guest OS always transitions to
+          ring 0. But that is where the hypervisor runs, not the guest
+          OS. In this case, the hypervisor must trap and emulate the
+          instruction even when it is not desirable.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The CPU segment registers contain a "hidden" descriptor cache
+          which is not software-accessible. The hypervisor cannot read,
+          save, or restore this state, but the guest OS may use it.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Some resources must, and can, be trapped by the hypervisor,
           but the access is so frequent that this creates a significant
-          performance overhead. An example is the TPR (Task Priority) register
-          in 32-bit mode. Accesses to this register must be trapped by the
-          hypervisor, but certain guest operating systems (notably Windows and
-          Solaris) write this register very often, which adversely affects
-          virtualization performance.</para>
-        </listitem>
-      </orderedlist></para>
-
-    <para>To fix these performance and security issues, VirtualBox contains a
-    Code Scanning and Analysis Manager (CSAM), which disassembles guest code,
-    and the Patch Manager (PATM), which can replace it at runtime.</para>
-
-    <para>Before executing ring 0 code, CSAM scans it recursively to discover
-    problematic instructions. PATM then performs <emphasis>in-situ
-    </emphasis>patching, i.e. it replaces the instruction with a jump to
-    hypervisor memory where an integrated code generator has placed a more
-    suitable implementation. In reality, this is a very complex task as there
-    are lots of odd situations to be discovered and handled correctly. So,
-    with its current complexity, one could argue that PATM is an advanced
-    <emphasis>in-situ</emphasis> recompiler.</para>
-
-    <para>In addition, every time a fault occurs, VirtualBox analyzes the
-    offending code to determine if it is possible to patch it in order to
-    prevent it from causing more faults in the future. This approach works
-    well in practice and dramatically improves software virtualization
-    performance.</para>
+          performance overhead. An example is the TPR (Task Priority)
+          register in 32-bit mode. Accesses to this register must be
+          trapped by the hypervisor. But certain guest operating
+          systems, notably Windows and Solaris, write this register very
+          often, which adversely affects virtualization performance.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      To fix these performance and security issues, VirtualBox contains
+      a Code Scanning and Analysis Manager (CSAM), which disassembles
+      guest code, and the Patch Manager (PATM), which can replace it at
+      runtime.
+    </para>
+
+    <para>
+      Before executing ring 0 code, CSAM scans it recursively to
+      discover problematic instructions. PATM then performs
+      <emphasis>in-situ </emphasis>patching. It replaces the instruction
+      with a jump to hypervisor memory where an integrated code
+      generator has placed a more suitable implementation. In reality,
+      this is a very complex task as there are lots of odd situations to
+      be discovered and handled correctly. So, with its current
+      complexity, one could argue that PATM is an advanced
+      <emphasis>in-situ</emphasis> recompiler.
+    </para>
+
+    <para>
+      In addition, every time a fault occurs, VirtualBox analyzes the
+      offending code to determine if it is possible to patch it in order
+      to prevent it from causing more faults in the future. This
+      approach works well in practice and dramatically improves software
+      virtualization performance.
+    </para>
+
   </sect1>
 
-  <sect1>
-    <title>Details about hardware virtualization</title>
-
-    <para>With Intel VT-x, there are two distinct modes of CPU operation: VMX
-    root mode and non-root mode.<itemizedlist>
-        <listitem>
-          <para>In root mode, the CPU operates much like older generations of
-          processors without VT-x support. There are four privilege levels
-          ("rings"), and the same instruction set is supported, with the
-          addition of several virtualization specific instruction. Root mode
-          is what a host operating system without virtualization uses, and it
-          is also used by a hypervisor when virtualization is active.</para>
-        </listitem>
-
-        <listitem>
-          <para>In non-root mode, CPU operation is significantly different.
-          There are still four privilege rings and the same instruction set,
-          but a new structure called VMCS (Virtual Machine Control Structure)
-          now controls the CPU operation and determines how certain
-          instructions behave. Non-root mode is where guest systems
-          run.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>Switching from root mode to non-root mode is called "VM entry", the
-    switch back is "VM exit". The VMCS includes a guest and host state area
-    which is saved/restored at VM entry and exit. Most importantly, the VMCS
-    controls which guest operations will cause VM exits.</para>
-
-    <para>The VMCS provides fairly fine-grained control over what the guests
-    can and can't do. For example, a hypervisor can allow a guest to write
-    certain bits in shadowed control registers, but not others. This enables
-    efficient virtualization in cases where guests can be allowed to write
-    control bits without disrupting the hypervisor, while preventing them from
-    altering control bits over which the hypervisor needs to retain full
-    control. The VMCS also provides control over interrupt delivery and
-    exceptions.</para>
-
-    <para>Whenever an instruction or event causes a VM exit, the VMCS contains
-    information about the exit reason, often with accompanying detail. For
-    example, if a write to the CR0 register causes an exit, the offending
-    instruction is recorded, along with the fact that a write access to a
-    control register caused the exit, and information about source and
-    destination register. Thus the hypervisor can efficiently handle the
-    condition without needing advanced techniques such as CSAM and PATM
-    described above.</para>
-
-    <para>VT-x inherently avoids several of the problems which software
-    virtualization faces. The guest has its own completely separate address
-    space not shared with the hypervisor, which eliminates potential clashes.
-    Additionally, guest OS kernel code runs at privilege ring 0 in VMX
-    non-root mode, obviating the problems by running ring 0 code at less
-    privileged levels. For example the SYSENTER instruction can transition to
-    ring 0 without causing problems. Naturally, even at ring 0 in VMX non-root
-    mode, any I/O access by guest code still causes a VM exit, allowing for
-    device emulation.</para>
-
-    <para>The biggest difference between VT-x and AMD-V is that AMD-V provides
-    a more complete virtualization environment. VT-x requires the VMX non-root
-    code to run with paging enabled, which precludes hardware virtualization
-    of real-mode code and non-paged protected-mode software. This typically
-    only includes firmware and OS loaders, but nevertheless complicates VT-x
-    hypervisor implementation. AMD-V does not have this restriction.</para>
-
-    <para>Of course hardware virtualization is not perfect. Compared to
-    software virtualization, the overhead of VM exits is relatively high. This
-    causes problems for devices whose emulation requires high number of traps.
-    One example is the VGA device in 16-color modes, where not only every I/O
-    port access but also every access to the framebuffer memory must be
-    trapped.</para>
+  <sect1 id="hwvirt-details">
+
+    <title>Details About Hardware Virtualization</title>
+
+    <para>
+      With Intel VT-x, there are two distinct modes of CPU operation:
+      VMX root mode and non-root mode.
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          In root mode, the CPU operates much like older generations of
+          processors without VT-x support. There are four privilege
+          levels, called rings, and the same instruction set is
+          supported, with the addition of several virtualization
+          specific instruction. Root mode is what a host operating
+          system without virtualization uses, and it is also used by a
+          hypervisor when virtualization is active.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          In non-root mode, CPU operation is significantly different.
+          There are still four privilege rings and the same instruction
+          set, but a new structure called VMCS (Virtual Machine Control
+          Structure) now controls the CPU operation and determines how
+          certain instructions behave. Non-root mode is where guest
+          systems run.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Switching from root mode to non-root mode is called "VM entry",
+      the switch back is "VM exit". The VMCS includes a guest and host
+      state area which is saved/restored at VM entry and exit. Most
+      importantly, the VMCS controls which guest operations will cause
+      VM exits.
+    </para>
+
+    <para>
+      The VMCS provides fairly fine-grained control over what the guests
+      can and cannot do. For example, a hypervisor can allow a guest to
+      write certain bits in shadowed control registers, but not others.
+      This enables efficient virtualization in cases where guests can be
+      allowed to write control bits without disrupting the hypervisor,
+      while preventing them from altering control bits over which the
+      hypervisor needs to retain full control. The VMCS also provides
+      control over interrupt delivery and exceptions.
+    </para>
+
+    <para>
+      Whenever an instruction or event causes a VM exit, the VMCS
+      contains information about the exit reason, often with
+      accompanying detail. For example, if a write to the CR0 register
+      causes an exit, the offending instruction is recorded, along with
+      the fact that a write access to a control register caused the
+      exit, and information about source and destination register. Thus
+      the hypervisor can efficiently handle the condition without
+      needing advanced techniques such as CSAM and PATM described above.
+    </para>
+
+    <para>
+      VT-x inherently avoids several of the problems which software
+      virtualization faces. The guest has its own completely separate
+      address space not shared with the hypervisor, which eliminates
+      potential clashes. Additionally, guest OS kernel code runs at
+      privilege ring 0 in VMX non-root mode, obviating the problems by
+      running ring 0 code at less privileged levels. For example the
+      SYSENTER instruction can transition to ring 0 without causing
+      problems. Naturally, even at ring 0 in VMX non-root mode, any I/O
+      access by guest code still causes a VM exit, allowing for device
+      emulation.
+    </para>
+
+    <para>
+      The biggest difference between VT-x and AMD-V is that AMD-V
+      provides a more complete virtualization environment. VT-x requires
+      the VMX non-root code to run with paging enabled, which precludes
+      hardware virtualization of real-mode code and non-paged
+      protected-mode software. This typically only includes firmware and
+      OS loaders, but nevertheless complicates VT-x hypervisor
+      implementation. AMD-V does not have this restriction.
+    </para>
+
+    <para>
+      Of course hardware virtualization is not perfect. Compared to
+      software virtualization, the overhead of VM exits is relatively
+      high. This causes problems for devices whose emulation requires
+      high number of traps. One example is the VGA device in 16-color
+      modes, where not only every I/O port access but also every access
+      to the framebuffer memory must be trapped.
+    </para>
+
   </sect1>
 
   <sect1 id="nestedpaging">
-    <title>Nested paging and VPIDs</title>
-
-    <para>In addition to "plain" hardware virtualization, your processor may
-    also support additional sophisticated techniques:<footnote>
-        <para>VirtualBox 2.0 added support for AMD's nested paging; support
-        for Intel's EPT and VPIDs was added with version 2.1.</para>
-      </footnote><itemizedlist>
-        <listitem>
-          <para>A newer feature called <emphasis role="bold">"nested
-          paging"</emphasis> implements some memory management in hardware,
-          which can greatly accelerate hardware virtualization since these
-          tasks no longer need to be performed by the virtualization
-          software.</para>
-
-          <para>With nested paging, the hardware provides another level of
-          indirection when translating linear to physical addresses. Page
-          tables function as before, but linear addresses are now translated
-          to "guest physical" addresses first and not physical addresses
-          directly. A new set of paging registers now exists under the
-          traditional paging mechanism and translates from guest physical
-          addresses to host physical addresses, which are used to access
-          memory.</para>
-
-          <para>Nested paging eliminates the overhead caused by VM exits and
-          page table accesses. In essence, with nested page tables the guest
-          can handle paging without intervention from the hypervisor. Nested
-          paging thus significantly improves virtualization
-          performance.</para>
-
-          <para>On AMD processors, nested paging has been available starting
-          with the Barcelona (K10) architecture -- they call it now "rapid
+
+    <title>Nested Paging and VPIDs</title>
+
+    <para>
+      In addition to normal hardware virtualization, your processor may
+      also support the following additional sophisticated techniques:
+
+      <footnote>
+
+        <para>
+          VirtualBox 2.0 added support for AMD's nested paging; support
+          for Intel's EPT and VPIDs was added with version 2.1.
+        </para>
+
+      </footnote>
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          A newer feature called <emphasis>nested paging</emphasis>
+          implements some memory management in hardware, which can
+          greatly accelerate hardware virtualization since these tasks
+          no longer need to be performed by the virtualization software.
+        </para>
+
+        <para>
+          With nested paging, the hardware provides another level of
+          indirection when translating linear to physical addresses.
+          Page tables function as before, but linear addresses are now
+          translated to "guest physical" addresses first and not
+          physical addresses directly. A new set of paging registers now
+          exists under the traditional paging mechanism and translates
+          from guest physical addresses to host physical addresses,
+          which are used to access memory.
+        </para>
+
+        <para>
+          Nested paging eliminates the overhead caused by VM exits and
+          page table accesses. In essence, with nested page tables the
+          guest can handle paging without intervention from the
+          hypervisor. Nested paging thus significantly improves
+          virtualization performance.
+        </para>
+
+        <para>
+          On AMD processors, nested paging has been available starting
+          with the Barcelona (K10) architecture. They now call it "rapid
           virtualization indexing" (RVI). Intel added support for nested
-          paging, which they call "extended page tables" (EPT), with their
-          Core i7 (Nehalem) processors.</para>
-
-          <para>If nested paging is enabled, the VirtualBox hypervisor can
-          also use <emphasis role="bold">large pages</emphasis> to reduce TLB
-          usage and overhead. This can yield a performance improvement of up
-          to 5%. To enable this feature for a VM, you need to use the
-          <computeroutput>VBoxManage modifyvm
+          paging, which they call extended page tables (EPT), with their
+          Core i7 (Nehalem) processors.
+        </para>
+
+        <para>
+          If nested paging is enabled, the VirtualBox hypervisor can
+          also use <emphasis role="bold">large pages</emphasis> to
+          reduce TLB usage and overhead. This can yield a performance
+          improvement of up to 5%. To enable this feature for a VM, you
+          need to use the <computeroutput>VBoxManage modifyvm
           </computeroutput><computeroutput>--largepages</computeroutput>
-          command; see <xref linkend="vboxmanage-modifyvm" />.</para>
-        </listitem>
-
-        <listitem>
-          <para>On Intel CPUs, another hardware feature called <emphasis
-          role="bold">"Virtual Processor Identifiers" (VPIDs)</emphasis> can
-          greatly accelerate context switching by reducing the need for
-          expensive flushing of the processor's Translation Lookaside Buffers
-          (TLBs).</para>
-
-          <para>To enable these features for a VM, you need to use the
-          <computeroutput>VBoxManage modifyvm --vtxvpid</computeroutput> and
-          <computeroutput>--largepages</computeroutput> commands; see <xref
-          linkend="vboxmanage-modifyvm" />.</para>
-        </listitem>
-      </itemizedlist></para>
+          command. See <xref linkend="vboxmanage-modifyvm" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          On Intel CPUs, another hardware feature called Virtual
+          Processor Identifiers" (VPIDs) can greatly accelerate context
+          switching by reducing the need for expensive flushing of the
+          processor's Translation Lookaside Buffers (TLBs).
+        </para>
+
+        <para>
+          To enable these features for a VM, you need to use the
+          <computeroutput>VBoxManage modifyvm --vtxvpid</computeroutput>
+          and <computeroutput>--largepages</computeroutput> commands.
+          See <xref
+          linkend="vboxmanage-modifyvm" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
+
 </chapter>
Index: /trunk/doc/manual/en_US/user_ThirdParty.xml
===================================================================
--- /trunk/doc/manual/en_US/user_ThirdParty.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_ThirdParty.xml	(revision 73276)
@@ -1,7 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
+
 <appendix id="ThirdParty">
-  <title>Third-party materials and licenses</title>
+  <title>Third-Party Materials and Licenses</title>
 
   <para>VirtualBox incorporates materials from several Open Source software
@@ -18,6 +22,6 @@
   tarballs for particular releases and as a live SVN repository.</para>
 
-  <sect1>
-    <title>Materials</title>
+  <sect1 id="third-party-materials">
+    <title>Third-Party Materials</title>
 
     <itemizedlist>
@@ -362,6 +366,6 @@
   </sect1>
 
-  <sect1>
-    <title>Licenses</title>
+  <sect1 id="third-party-licenses">
+    <title>Third-Party Licenses</title>
 
     <sect2 id="licGPL">
@@ -1608,5 +1612,5 @@
 
     <sect2 id="licZLIB">
-      <title>zlib license</title>
+      <title>zlib License</title>
 
       <para>This software is provided 'as-is', without any express or implied
@@ -1634,5 +1638,5 @@
 
     <sect2 id="licSSL">
-      <title>OpenSSL license</title>
+      <title>OpenSSL License</title>
 
       <para>This package is an SSL implementation written by Eric Young
@@ -1697,5 +1701,5 @@
 
     <sect2 id="licSlirp">
-      <title>Slirp license</title>
+      <title>Slirp License</title>
 
       <para>Copyright (c) 1995,1996 Danny Gasparovski.  All rights reserved.</para>
@@ -1731,5 +1735,5 @@
 
     <sect2 id="licLZF">
-      <title>liblzf license</title>
+      <title>liblzf License</title>
 
       <para>Redistribution and use in source and binary forms, with or without
@@ -1762,6 +1766,6 @@
     </sect2>
 
-    <sect2>
-      <title>libpng license</title>
+    <sect2 id="liclibping">
+      <title>libpng License</title>
 
       <para>The PNG Reference Library is supplied "AS IS". The Contributing
@@ -1795,5 +1799,5 @@
 
     <sect2 id="licLWIP">
-      <title>lwIP license</title>
+      <title>lwIP License</title>
 
       <para>Redistribution and use in source and binary forms, with or without
@@ -1827,5 +1831,5 @@
 
     <sect2 id="licLibXML">
-      <title>libxml license</title>
+      <title>libxml License</title>
 
       <para>Except where otherwise noted in the source code (e.g. the files
@@ -1862,5 +1866,5 @@
 
     <sect2 id="licLibXSLT">
-      <title>libxslt licenses</title>
+      <title>libxslt Licenses</title>
 
       <para>Licence for libxslt except libexslt:</para>
@@ -2343,8 +2347,8 @@
 
     <sect2 id="licChromium">
-      <title>Chromium licenses</title>
+      <title>Chromium Licenses</title>
 
       <sect3>
-        <title>Main license</title>
+        <title>Main License</title>
 
         <para>Copyright (c) 2002, Stanford University All rights
@@ -2357,5 +2361,6 @@
         <para>Redistribution and use in source and binary forms, with or
         without modification, are permitted provided that the following
-        conditions are met:<itemizedlist>
+        conditions are met:</para>
+        <itemizedlist>
             <listitem>
               <para>Redistributions of source code must retain the above
@@ -2377,5 +2382,5 @@
               permission.</para>
             </listitem>
-          </itemizedlist></para>
+          </itemizedlist>
 
         <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
@@ -2394,5 +2399,5 @@
 
       <sect3>
-        <title>COPYRIGHT.LLNL file</title>
+        <title>COPYRIGHT.LLNL File</title>
 
         <para>This Chromium distribution contains information and code which
@@ -2462,5 +2467,5 @@
 
       <sect3>
-        <title>COPYRIGHT.REDHAT file</title>
+        <title>COPYRIGHT.REDHAT File</title>
 
         <para>This Chromium distribution contains information and code which
@@ -2494,5 +2499,5 @@
 
     <sect2 id="licLibCurl">
-      <title>curl license</title>
+      <title>curl License</title>
 
       <para>COPYRIGHT AND PERMISSION NOTICE</para>
@@ -2523,5 +2528,5 @@
 
     <sect2 id="licLibgd">
-      <title>libgd license</title>
+      <title>libgd License</title>
 
       <para>Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
@@ -2579,5 +2584,5 @@
 
     <sect2 id="licBsdIntel">
-      <title>BSD license from Intel</title>
+      <title>BSD License from Intel</title>
 
       <para>All rights reserved.</para>
@@ -2681,5 +2686,5 @@
 
     <sect2 id="licJPEGSIMD">
-      <title>x86 SIMD extension for IJG JPEG library license</title>
+      <title>x86 SIMD Extension for IJG JPEG Library License</title>
 
       <para>Copyright 2009 Pierre Ossman &lt;ossman@cendio.se&gt; for Cendio AB</para>
@@ -2709,5 +2714,5 @@
 
     <sect2 id="licFreeBsd">
-      <title>FreeBSD license</title>
+      <title>FreeBSD License</title>
 
       <para>The compilation of software known as FreeBSD is distributed under the
@@ -2749,5 +2754,5 @@
 
     <sect2 id="licNetBsd">
-      <title>NetBSD license</title>
+      <title>NetBSD License</title>
 
       <para>Copyright (c) 1992, 1993 The Regents of the University of California.
@@ -2805,5 +2810,5 @@
 
     <sect2 id="licPcre">
-      <title>PCRE license</title>
+      <title>PCRE License</title>
 
       <para>
@@ -2884,5 +2889,5 @@
 
     <sect2 id="licLibffi">
-      <title>libffi license</title>
+      <title>libffi License</title>
 
       <para>
@@ -2912,5 +2917,5 @@
 
     <sect2 id="licFltk">
-      <title>FLTK license</title>
+      <title>FLTK License</title>
 
       <para>
@@ -2981,5 +2986,5 @@
 
     <sect2 id="licExpat">
-      <title>Expat license</title>
+      <title>Expat License</title>
       <para>
         Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
@@ -3014,5 +3019,5 @@
 
     <sect2 id="licFontconfig">
-      <title>Fontconfig license</title>
+      <title>Fontconfig License</title>
       <para>
         Copyright (C) 2001, 2003 Keith Packard
@@ -3041,5 +3046,5 @@
 
     <sect2 id="licFreetype">
-      <title>Freetype license</title>
+      <title>Freetype License</title>
       <para>
         2006-Jan-27
@@ -3112,6 +3117,6 @@
       <sect3>
         <title>Legal Terms</title>
-        <sect4>
-          <title>0. Definitions</title>
+       
+          <para>0. Definitions</para>
           <para>
             Throughout this license,  the terms `package', `FreeType Project',
@@ -3141,7 +3146,7 @@
             specified below.
           </para>
-        </sect4>
-        <sect4>
-          <title>1. No Warranty</title>
+        
+       
+          <para>1. No Warranty</para>
           <para>
             THE FREETYPE PROJECT  IS PROVIDED `AS IS' WITHOUT  WARRANTY OF ANY
@@ -3152,7 +3157,7 @@
             USE, OF THE FREETYPE PROJECT.
           </para>
-        </sect4>
-        <sect4>
-          <title>2. Redistribution</title>
+        
+       
+          <para>2. Redistribution</para>
           <para>
             This  license  grants  a  worldwide, royalty-free,  perpetual  and
@@ -3191,7 +3196,7 @@
             to us.
           </para>
-        </sect4>
-         <sect4>
-           <title>3. Advertising</title>
+        
+        
+           <para>3. Advertising</para>
            <para>
             Neither the  FreeType authors and  contributors nor you  shall use
@@ -3214,7 +3219,7 @@
             of this license.
           </para>
-        </sect4>
-        <sect4>
-          <title>4. Contacts</title>
+        
+        
+          <para>4. Contacts</para>
           <para>
             There are two mailing lists related to FreeType:
@@ -3248,5 +3253,5 @@
             http://www.freetype.org
           </para>
-        </sect4>
+        
       </sect3>
     </sect2>
Index: /trunk/doc/manual/en_US/user_Troubleshooting.xml
===================================================================
--- /trunk/doc/manual/en_US/user_Troubleshooting.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_Troubleshooting.xml	(revision 73276)
@@ -1,423 +1,609 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="Troubleshooting">
+
   <title>Troubleshooting</title>
 
-  <para>This chapter provides answers to commonly asked questions. In order to
-  improve your user experience with VirtualBox, it is recommended to read this
-  section to learn more about common pitfalls and get recommendations on how
-  to use the product.</para>
-
-  <sect1>
-    <title>Procedures and tools</title>
-
-    <sect2>
-      <title>Categorizing and isolating problems</title>
-
-      <para>More often than not, a virtualized guest behaves like a physical
-      system. Any problems that a physical machine would encounter, a virtual
-      machine will encounter as well. If, for example, Internet connectivity
-      is lost due to external issues, virtual machines will be affected just
-      as much as physical ones.</para>
-
-      <para>If a true VirtualBox problem is encountered, it helps to
-      categorize and isolate the problem first. Here are some of the questions
-      that should be answered before reporting a problem:<orderedlist>
-          <listitem>
-            <para>Is the problem specific to a certain guest OS? Specific
+  <para>
+    This chapter provides answers to commonly asked questions. In order
+    to improve your user experience with VirtualBox, it is recommended
+    to read this section to learn more about common pitfalls and get
+    recommendations on how to use the product.
+  </para>
+
+  <sect1 id="ts_procs-tools">
+
+    <title>Procedures and Tools</title>
+
+    <sect2 id="ts_categorize-isolate">
+
+      <title>Categorizing and Isolating Problems</title>
+
+      <para>
+        More often than not, a virtualized guest behaves like a physical
+        system. Any problems that a physical machine would encounter, a
+        virtual machine will encounter as well. If, for example,
+        Internet connectivity is lost due to external issues, virtual
+        machines will be affected just as much as physical ones.
+      </para>
+
+      <para>
+        If a true VirtualBox problem is encountered, it helps to
+        categorize and isolate the problem first. Here are some of the
+        questions that should be answered before reporting a problem:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Is the problem specific to a certain guest OS? Or a specific
             release of a guest OS? Especially with Linux guest related
-            problems, the issue may be specific to a certain distribution and
-            version of Linux.</para>
-          </listitem>
-
-          <listitem>
-            <para>Is the problem specific to a certain host OS? Problems are
-            usually not host OS specific (because most of the VirtualBox code
-            base is shared across all supported platforms), but especially in
-            the areas of networking and USB support, there are significant
-            differences between host platforms. Some GUI related issues are
-            also host specific.</para>
-          </listitem>
-
-          <listitem>
-            <para>Is the problem specific to certain host hardware? This
-            category of issues is typically related to the host CPU. Because
-            of significant differences between VT-x and AMD-V, problems may be
-            specific to one or the other technology. The exact CPU model may
-            also make a difference (even for software virtualization) because
-            different CPUs support different features, which may affect
-            certain aspects of guest CPU operation.</para>
-          </listitem>
-
-          <listitem>
-            <para>Is the problem specific to a certain virtualization mode?
-            Some problems may only occur in software virtualization mode,
-            others may be specific to hardware virtualization.</para>
-          </listitem>
-
-          <listitem>
-            <para>Is the problem specific to guest SMP? That is, is it related
-            to the number of virtual CPUs (VCPUs) in the guest? Using more
-            than one CPU usually significantly affects the internal operation
-            of a guest OS.</para>
-          </listitem>
-
-          <listitem>
-            <para>Is the problem specific to the Guest Additions? In some
-            cases, this is a given (e.g., a shared folders problem), in other
-            cases it may be less obvious (for example, display problems). And
-            if the problem is Guest Additions specific, is it also specific to
-            a certain version of the Additions?</para>
-          </listitem>
-
-          <listitem>
-            <para>Is the problem specific to a certain environment? Some
-            problems are related to a particular environment external to the
-            VM; this usually involves network setup. Certain configurations of
-            external servers such as DHCP or PXE may expose problems which do
-            not occur with other, similar servers.</para>
-          </listitem>
-
-          <listitem>
-            <para>Is the problem a regression? Knowing that an issue is a
+            problems, the issue may be specific to a certain
+            distribution and version of Linux.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Is the problem specific to a certain host OS? Problems are
+            usually not host OS specific, because most of the VirtualBox
+            code base is shared across all supported platforms, but
+            especially in the areas of networking and USB support, there
+            are significant differences between host platforms. Some GUI
+            related issues are also host specific.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Is the problem specific to certain host hardware? This
+            category of issues is typically related to the host CPU.
+            Because of significant differences between VT-x and AMD-V,
+            problems may be specific to one or the other technology. The
+            exact CPU model may also make a difference, even for
+            software virtualization, because different CPUs support
+            different features, which may affect certain aspects of
+            guest CPU operation.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Is the problem specific to a certain virtualization mode?
+            Some problems may only occur in software virtualization
+            mode, others may be specific to hardware virtualization.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Is the problem specific to guest SMP? That is, is it related
+            to the number of virtual CPUs (VCPUs) in the guest? Using
+            more than one CPU usually significantly affects the internal
+            operation of a guest OS.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Is the problem specific to the Guest Additions? In some
+            cases, this is obvious, such as a shared folders problem. In
+            other cases such as display problems, it may be less
+            obvious. If the problem is Guest Additions specific, is it
+            also specific to a certain version of the Guest Additions?
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Is the problem specific to a certain environment? Some
+            problems are related to a particular environment external to
+            the VM; this usually involves network setup. Certain
+            configurations of external servers such as DHCP or PXE may
+            expose problems which do not occur with other, similar
+            servers.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Is the problem a regression? Knowing that an issue is a
             regression usually makes it significantly easier to find the
-            solution. In this case, it is crucial to know which version is
-            affected and which is not.</para>
-          </listitem>
-        </orderedlist></para>
+            solution. In this case, it is crucial to know which version
+            is affected and which is not.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </sect2>
 
     <sect2 id="collect-debug-info">
-      <title>Collecting debugging information</title>
-
-      <para>For problem determination, it is often important to collect
-      debugging information which can be analyzed by VirtualBox support. This
-      section contains information about what kind of information can be
-      obtained.</para>
-
-      <para>Every time VirtualBox starts up a VM, a so-called <emphasis
-      role="bold">"release log file"</emphasis> is created containing lots of
-      information about the VM configuration and runtime events. The log file
-      is called <computeroutput><literal>VBox.log</literal></computeroutput>
-      and resides in the VM log file folder. Typically this will be a
-      directory like this:<screen>$HOME/VirtualBox VMs/{machinename}/Logs</screen></para>
-
-      <para>When starting a VM, the configuration file of the last run will be
-      renamed to <computeroutput>.1</computeroutput>, up to
-      <computeroutput>.3</computeroutput>. Sometimes when there is a problem,
-      it is useful to have a look at the logs. Also when requesting support
-      for VirtualBox, supplying the corresponding log file is
-      mandatory.</para>
-
-      <para>For convenience, for each virtual machine, the VirtualBox main
-      window can show these logs in a window. To access it, select a virtual
-      machine from the list on the left and select "Show logs..." from the
-      "Machine" window.</para>
-
-      <para>The release log file (VBox.log) contains a wealth of diagnostic
-      information, such as Host OS type and version, VirtualBox version and
-      build (32-bit or 64-bit), a complete dump of the guest's configuration
-      (CFGM), detailed information about the host CPU type and supported
-      features, whether hardware virtualization is enabled, information about
-      VT-x/AMD-V setup, state transitions (creating, running, paused,
-      stopping, etc.), guest BIOS messages, Guest Additions messages,
-      device-specific log entries and, at the end of execution, final guest
-      state and condensed statistics.</para>
-
-      <para>In case of crashes, it is very important to collect <emphasis
-      role="bold">crash dumps</emphasis>. This is true for both host and guest
-      crashes. For information about enabling core dumps on Linux, Solaris,
-      and OS X systems, refer to the core dump article on the VirtualBox
-      website.<footnote>
-          <para><ulink
-          url="http://www.virtualbox.org/wiki/Core_dump">http://www.virtualbox.org/wiki/Core_dump</ulink>.</para>
-        </footnote></para>
-
-      <para>You can also use <computeroutput>VBoxManage
-      debugvm</computeroutput> to create a dump of a complete virtual machine;
-      see <xref linkend="vboxmanage-debugvm" />.</para>
-
-      <para>For network related problems, it is often helpful to capture a
-      trace of network traffic. If the traffic is routed through an adapter on
-      the host, it is possible to use Wireshark or a similar tool to capture
-      the traffic there. However, this often also includes a lot of traffic
-      unrelated to the VM.</para>
-
-      <para>VirtualBox provides an ability to capture network traffic only on
-      a specific VM's network adapter. Refer to the network tracing article on
-      the VirtualBox website<footnote>
-          <para><ulink
-          url="http://www.virtualbox.org/wiki/Network_tips">http://www.virtualbox.org/wiki/Network_tips</ulink>.</para>
-        </footnote> for information on enabling this capture. The trace files
-      created by VirtualBox are in <computeroutput>.pcap</computeroutput>
-      format and can be easily analyzed with Wireshark.</para>
+
+      <title>Collecting Debugging Information</title>
+
+      <para>
+        For problem determination, it is often important to collect
+        debugging information which can be analyzed by VirtualBox
+        support. This section contains information about what kind of
+        information can be obtained.
+      </para>
+
+      <para>
+        Every time VirtualBox starts up a VM, a so-called
+        <emphasis>release log file</emphasis> is created, containing
+        lots of information about the VM configuration and runtime
+        events. The log file is called
+        <computeroutput><literal>VBox.log</literal></computeroutput> and
+        resides in the VM log file folder. Typically this will be a
+        directory as follows:
+
+<screen>$HOME/VirtualBox VMs/{machinename}/Logs</screen>
+      </para>
+
+      <para>
+        When starting a VM, the configuration file of the last run will
+        be renamed to <computeroutput>.1</computeroutput>, up to
+        <computeroutput>.3</computeroutput>. Sometimes when there is a
+        problem, it is useful to have a look at the logs. Also when
+        requesting support for VirtualBox, supplying the corresponding
+        log file is mandatory.
+      </para>
+
+      <para>
+        For convenience, for each virtual machine, the VirtualBox main
+        window can show these logs in a window. To access it, select a
+        virtual machine from the list on the left and select
+        <emphasis role="bold">Show logs...</emphasis> from the Machine
+        menu.
+      </para>
+
+      <para>
+        The release log file (VBox.log) contains a wealth of diagnostic
+        information, such as Host OS type and version, VirtualBox
+        version and build (32-bit or 64-bit), a complete dump of the
+        guest's configuration (CFGM), detailed information about the
+        host CPU type and supported features, whether hardware
+        virtualization is enabled, information about VT-x/AMD-V setup,
+        state transitions (such as creating, running, paused, stopping),
+        guest BIOS messages, Guest Additions messages, device-specific
+        log entries and, at the end of execution, final guest state and
+        condensed statistics.
+      </para>
+
+      <para>
+        In case of crashes, it is very important to collect
+        <emphasis>crash dumps</emphasis>. This is true for both host and
+        guest crashes. For information about enabling core dumps on
+        Linux, Solaris, and OS X systems, refer to the following core
+        dump article on the VirtualBox website:
+      </para>
+
+      <para>
+        <ulink
+          url="http://www.virtualbox.org/wiki/Core_dump">http://www.virtualbox.org/wiki/Core_dump</ulink>.
+      </para>
+
+      <para>
+        You can also use <computeroutput>VBoxManage
+        debugvm</computeroutput> to create a dump of a complete virtual
+        machine. See <xref linkend="vboxmanage-debugvm" />.
+      </para>
+
+      <para>
+        For network related problems, it is often helpful to capture a
+        trace of network traffic. If the traffic is routed through an
+        adapter on the host, it is possible to use Wireshark or a
+        similar tool to capture the traffic there. However, this often
+        also includes a lot of traffic unrelated to the VM.
+      </para>
+
+      <para>
+        VirtualBox provides an ability to capture network traffic only
+        on a specific VM's network adapter. Refer to the following
+        network tracing article on the VirtualBox website for
+        information on enabling this capture:
+      </para>
+
+      <para>
+        <ulink
+          url="http://www.virtualbox.org/wiki/Network_tips">http://www.virtualbox.org/wiki/Network_tips</ulink>.
+      </para>
+
+      <para>
+        The trace files created by VirtualBox are in
+        <computeroutput>.pcap</computeroutput> format and can be easily
+        analyzed with Wireshark.
+      </para>
+
     </sect2>
 
     <sect2 id="ts_debugger">
-      <title>The built-in VM debugger</title>
-
-      <para>VirtualBox includes a built-in VM debugger, which advanced users
-      may find useful. This debugger allows for examining and, to some extent,
-      controlling the VM state.<warning>
-          <para>Use the VM debugger at your own risk. There is no support for
+
+      <title>The Built-In VM Debugger</title>
+
+      <para>
+        VirtualBox includes a built-in VM debugger, which advanced users
+        may find useful. This debugger allows for examining and, to some
+        extent, controlling the VM state.
+      </para>
+
+      <warning>
+        <para>
+          Use the VM debugger at your own risk. There is no support for
           it, and the following documentation is only made available for
           advanced users with a very high level of familiarity with the
-          x86/AMD64 machine instruction set, as well as detailed knowledge of
-          the PC architecture. A degree of familiarity with the internals of
-          the guest OS in question may also be very helpful.</para>
-        </warning></para>
-
-      <para>The VM debugger is available in all regular production versions of
-      VirtualBox, but it is disabled by default because the average user will
-      have little use for it. There are two ways to access the
-      debugger:<itemizedlist>
-          <listitem>
-            <para>A debugger console window displayed alongside the VM</para>
-          </listitem>
-
-          <listitem>
-            <para>Via the <computeroutput>telnet</computeroutput> protocol at
-            port 5000</para>
-          </listitem>
-        </itemizedlist></para>
-
-      <para>The debugger can be enabled in three ways:<itemizedlist>
-          <listitem>
-            <para>Start the VM directly using <computeroutput>VirtualBox
+          x86/AMD64 machine instruction set, as well as detailed
+          knowledge of the PC architecture. A degree of familiarity with
+          the internals of the guest OS in question may also be very
+          helpful.
+        </para>
+      </warning>
+
+      <para>
+        The VM debugger is available in all regular production versions
+        of VirtualBox, but it is disabled by default because the average
+        user will have little use for it. There are two ways to access
+        the debugger:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Using a debugger console window displayed alongside the VM
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Using the <computeroutput>telnet</computeroutput> protocol
+            on port 5000
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        The debugger can be enabled in the following ways:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Start the VM directly using <computeroutput>VirtualBox
             --startvm</computeroutput>, with an additional
             <computeroutput>--dbg</computeroutput>,
             <computeroutput>--debug</computeroutput>, or
-            <computeroutput>--debug-command-line</computeroutput> argument.
-            See the VirtualBox usage help for details.</para>
-          </listitem>
-
-          <listitem>
-            <para>Set the
+            <computeroutput>--debug-command-line</computeroutput>
+            argument. See the VirtualBox usage help for details.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Set the
             <computeroutput>VBOX_GUI_DBG_ENABLED</computeroutput> or
             <computeroutput>VBOX_GUI_DBG_AUTO_SHOW</computeroutput>
-            environment variable to <computeroutput>true</computeroutput>
-            before launching the VirtualBox process. Setting these variables
-            (only their presence is checked) is effective even when the first
-            VirtualBox process is the VM selector window. VMs subsequently
-            launched from the selector will have the debugger enabled.</para>
-          </listitem>
-
-          <listitem>
-            <para>Set the <computeroutput>GUI/Dbg/Enabled</computeroutput>
-            extra data item to <computeroutput>true</computeroutput> before
-            launching the VM. This can be set globally or on a per VM
-            basis.</para>
-          </listitem>
-        </itemizedlist></para>
-
-      <para>A new 'Debug' menu entry will be added to the VirtualBox
-      application. This menu allows the user to open the debugger
-      console.</para>
-
-      <para>The VM debugger command syntax is loosely modeled on Microsoft and
-      IBM debuggers used on DOS, OS/2 and Windows. Users familiar with symdeb,
-      CodeView, or the OS/2 kernel debugger will find the VirtualBox VM
-      debugger familiar.</para>
-
-      <para>The most important command is
-      <computeroutput>help</computeroutput>. This will print brief usage help
-      for all debugger commands. The set of commands supported by the VM
-      debugger changes frequently and the
-      <computeroutput>help</computeroutput> command is always
-      up-to-date.</para>
-
-      <para>A brief summary of frequently used commands follows:<itemizedlist>
-          <listitem>
-            <para><computeroutput>stop</computeroutput> -- stops the VM
-            execution and enables single stepping</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>g</computeroutput> -- continue VM
-            execution</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>t</computeroutput> -- single step an
-            instruction</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>rg/rh/r</computeroutput> -- print the
-            guest/hypervisor/current registers</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>kg/kh/k</computeroutput> -- print the
-            guest/hypervisor/current call stack</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>da/db/dw/dd/dq</computeroutput> -- print
-            memory contents as ASCII/bytes/words/dwords/qwords</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>u</computeroutput> -- unassemble
-            memory</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>dg</computeroutput> -- print the guest's
-            GDT</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>di</computeroutput> -- print the guest's
-            IDT</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>dl</computeroutput> -- print the guest's
-            LDT</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>dt</computeroutput> -- print the guest's
-            TSS</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>dp*</computeroutput> -- print the guest's
-            page table structures</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>bp/br</computeroutput> -- set a
-            normal/recompiler breakpoint</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>bl</computeroutput> -- list
-            breakpoints</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>bc</computeroutput> -- clear a
-            breakpoint</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>writecore</computeroutput> -- writes a VM
-            core file to disk, refer <xref linkend="ts_guest-core-format" /></para>
-          </listitem>
-        </itemizedlist></para>
-
-      <para>See the built-in <computeroutput>help</computeroutput> for other
-      available commands.</para>
-
-      <para>The VM debugger supports symbolic debugging, although symbols for
-      guest code are often not available. For Solaris guests, the
-      <computeroutput>detect</computeroutput> command automatically determines
-      the guest OS version and locates kernel symbols in guest's memory.
-      Symbolic debugging is then available. For Linux guests, the
-      <computeroutput>detect</computeroutput> commands also determines the
-      guest OS version, but there are no symbols in the guest's memory. Kernel
-      symbols are available in the file
-      <computeroutput>/proc/kallsyms</computeroutput> on Linux guests. This
-      file must be copied to the host, for example using
-      <computeroutput>scp</computeroutput>. The
-      <computeroutput>loadmap</computeroutput> debugger command can be used to
-      make the symbol information available to the VM debugger. Note that the
-      <computeroutput>kallsyms</computeroutput> file contains the symbols for
-      the currently loaded modules; if the guest's configuration changes, the
-      symbols will change as well and must be updated.</para>
-
-      <para>For all guests, a simple way to verify that the correct symbols
-      are loaded is the <computeroutput>k</computeroutput> command. The guest
-      is normally idling and it should be clear from the symbolic information
-      that the guest operating system's idle loop is being executed.</para>
-
-      <para>Another group of debugger commands is the set of
-      <computeroutput>info</computeroutput> commands. Running
-      <computeroutput>info help</computeroutput> provides complete usage
-      information. The information commands provide ad-hoc data pertinent to
-      various emulated devices and aspects of the VMM. There is no general
-      guideline for using the <computeroutput>info</computeroutput> commands,
-      the right command to use depends entirely on the problem being
-      investigated. Some of the info commands are:<itemizedlist>
-          <listitem>
-            <para><computeroutput>cfgm</computeroutput> -- print a branch of
-            the configuration tree</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>cpuid</computeroutput> -- display the guest
-            CPUID leaves</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>ioport</computeroutput> -- print registered
-            I/O port ranges</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>mmio</computeroutput> -- print registered
-            MMIO ranges</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>mode</computeroutput> -- print the current
-            paging mode</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>pit</computeroutput> -- print the i8254 PIT
-            state</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>pic</computeroutput> -- print the i8259A PIC
-            state</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>ohci/ehci/xhci</computeroutput> -- print a subset
-            of the OHCI/EHCI/xHCI USB controller state</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>pcnet0</computeroutput> -- print the PCnet
-            state</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>vgatext</computeroutput> -- print the
-            contents of the VGA framebuffer formatted as standard text
-            mode</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>timers</computeroutput> -- print all VM
-            timers</para>
-          </listitem>
-        </itemizedlist></para>
-
-      <para>The output of the <computeroutput>info</computeroutput> commands
-      generally requires in-depth knowledge of the emulated device and/or
-      VirtualBox VMM internals. However, when used properly, the information
-      provided can be invaluable.</para>
+            environment variable to
+            <computeroutput>true</computeroutput> before launching the
+            VirtualBox process. Setting these variables, only their
+            presence is checked, is effective even when the first
+            VirtualBox process is the VM selector window. VMs
+            subsequently launched from the selector will have the
+            debugger enabled.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Set the <computeroutput>GUI/Dbg/Enabled</computeroutput>
+            extra data item to <computeroutput>true</computeroutput>
+            before launching the VM. This can be set globally or on a
+            per VM basis.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        A new Debug menu entry is added to the VirtualBox application.
+        This menu allows the user to open the debugger console.
+      </para>
+
+      <para>
+        The VM debugger command syntax is loosely modeled on Microsoft
+        and IBM debuggers used on DOS, OS/2, and Windows. Users familiar
+        with symdeb, CodeView, or the OS/2 kernel debugger will find the
+        VirtualBox VM debugger familiar.
+      </para>
+
+      <para>
+        The most important command is
+        <computeroutput>help</computeroutput>. This will print brief
+        usage help for all debugger commands. The set of commands
+        supported by the VM debugger changes frequently and the
+        <computeroutput>help</computeroutput> command is always
+        up-to-date.
+      </para>
+
+      <para>
+        A brief summary of frequently used commands is as follows:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <computeroutput>stop</computeroutput>: Stops the VM
+            execution and enables single stepping
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>g</computeroutput>: Continue VM execution
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>t</computeroutput>: Single step an
+            instruction
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>rg/rh/r</computeroutput>: Print the
+            guest/hypervisor/current registers
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>kg/kh/k</computeroutput>: Print the
+            guest/hypervisor/current call stack
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>da/db/dw/dd/dq</computeroutput>: Print
+            memory contents as ASCII/bytes/words/dwords/qwords
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>u</computeroutput>: Unassemble memory
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>dg</computeroutput>: Print the guest's GDT
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>di</computeroutput>: Print the guest's IDT
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>dl</computeroutput>: Print the guest's LDT
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>dt</computeroutput>: Print the guest's TSS
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>dp*</computeroutput>: Print the guest's page
+            table structures
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>bp/br</computeroutput>: Set a
+            normal/recompiler breakpoint
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>bl</computeroutput>: List breakpoints
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>bc</computeroutput>: Clear a breakpoint
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>writecore</computeroutput>: Write a VM core
+            file to disk. See <xref linkend="ts_guest-core-format" />
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        See the built-in <computeroutput>help</computeroutput> for other
+        available commands.
+      </para>
+
+      <para>
+        The VM debugger supports symbolic debugging, although symbols
+        for guest code are often not available. For Solaris guests, the
+        <computeroutput>detect</computeroutput> command automatically
+        determines the guest OS version and locates kernel symbols in
+        guest's memory. Symbolic debugging is then available. For Linux
+        guests, the <computeroutput>detect</computeroutput> commands
+        also determines the guest OS version, but there are no symbols
+        in the guest's memory. Kernel symbols are available in the file
+        <computeroutput>/proc/kallsyms</computeroutput> on Linux guests.
+        This file must be copied to the host, for example using
+        <computeroutput>scp</computeroutput>. The
+        <computeroutput>loadmap</computeroutput> debugger command can be
+        used to make the symbol information available to the VM
+        debugger. Note that the
+        <computeroutput>kallsyms</computeroutput> file contains the
+        symbols for the currently loaded modules. If the guest's
+        configuration changes, the symbols will change as well and must
+        be updated.
+      </para>
+
+      <para>
+        For all guests, a simple way to verify that the correct symbols
+        are loaded is the <computeroutput>k</computeroutput> command.
+        The guest is normally idling and it should be clear from the
+        symbolic information that the guest operating system's idle loop
+        is being executed.
+      </para>
+
+      <para>
+        Another group of debugger commands is the set of
+        <computeroutput>info</computeroutput> commands. Running
+        <computeroutput>info help</computeroutput> provides complete
+        usage information. The information commands provide ad-hoc data
+        pertinent to various emulated devices and aspects of the VMM.
+        There is no general guideline for using the
+        <computeroutput>info</computeroutput> commands, the right
+        command to use depends entirely on the problem being
+        investigated. Some of the <computeroutput>info</computeroutput>
+        commands are as follows:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <computeroutput>cfgm</computeroutput>: Print a branch of the
+            configuration tree
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>cpuid</computeroutput>: Display the guest
+            CPUID leaves
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>ioport</computeroutput>: Print registered
+            I/O port ranges
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>mmio</computeroutput>: Print registered MMIO
+            ranges
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>mode</computeroutput> -- print the current
+            paging mode
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>pit</computeroutput>: Print the i8254 PIT
+            state
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>pic</computeroutput>: Print the i8259A PIC
+            state
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>ohci/ehci/xhci</computeroutput>: Print a
+            subset of the OHCI/EHCI/xHCI USB controller state
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>pcnet0</computeroutput>: Print the PCnet
+            state
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>vgatext</computeroutput>: Print the contents
+            of the VGA framebuffer formatted as standard text mode
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>timers</computeroutput>: Print all VM timers
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        The output of the <computeroutput>info</computeroutput> commands
+        generally requires in-depth knowledge of the emulated device
+        and/or VirtualBox VMM internals. However, when used properly,
+        the information provided can be invaluable.
+      </para>
+
     </sect2>
 
     <sect2 id="ts_guest-core-format">
-      <title>VM core format</title>
-
-      <para>VirtualBox uses the 64-bit ELF format for its VM core files
-      created by <computeroutput>VBoxManage debugvm</computeroutput>; see
-      <xref linkend="vboxmanage-debugvm" />. The VM core file contain the
-      memory and CPU dumps of the VM and can be useful for debugging your
-      guest OS. The 64-bit ELF object format specification can be obtained
-      here: <literal><ulink
-      url="http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf">http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf</ulink></literal>.</para>
-
-      <para>The overall layout of the VM core format is as follows:</para>
-
-      <para><screen>[ ELF 64 Header]
+
+      <title>VM Core Format</title>
+
+      <para>
+        VirtualBox uses the 64-bit ELF format for its VM core files
+        created by <computeroutput>VBoxManage debugvm</computeroutput>,
+        see <xref linkend="vboxmanage-debugvm" />. The VM core file
+        contain the memory and CPU dumps of the VM and can be useful for
+        debugging your guest OS. The 64-bit ELF object format
+        specification can be obtained at:
+      </para>
+
+      <para>
+        <ulink
+      url="http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf">http://downloads.openwatcom.org/ftp/devel/docs/elf-64-gen.pdf</ulink>.
+      </para>
+
+      <para>
+        The overall layout of the VM core format is as follows:
+      </para>
+
+      <para>
+<screen>[ ELF 64 Header]
 [ Program Header, type PT_NOTE ]
   &rarr; offset to COREDESCRIPTOR
@@ -435,576 +621,863 @@
   [ DBGFCORECPU - vCPU 1 dump ]
 [ Additional Notes + Data ] - currently unused
-[ Memory dump ]</screen></para>
-
-      <para>The memory descriptors contain physical addresses relative to the
-      guest and not virtual addresses. Regions of memory such as MMIO regions
-      are not included in the core file.</para>
-
-      <para>The relevant data structures and definitions can be found in the
-      VirtualBox sources under the following header files:
-      <computeroutput>include/VBox/dbgfcorefmt.h</computeroutput>,
-      <computeroutput>include/iprt/x86.h</computeroutput> and
-      <computeroutput>src/VBox/Runtime/include/internal/ldrELFCommon.h</computeroutput>.</para>
-
-      <para>The VM core file can be inspected using
-      <computeroutput>elfdump</computeroutput> and GNU
-      <computeroutput>readelf</computeroutput> or other similar
-      utilities.</para>
-    </sect2>
+[ Memory dump ]</screen>
+      </para>
+
+      <para>
+        The memory descriptors contain physical addresses relative to
+        the guest and not virtual addresses. Regions of memory such as
+        MMIO regions are not included in the core file.
+      </para>
+
+      <para>
+        The relevant data structures and definitions can be found in the
+        VirtualBox sources under the following header files:
+        <computeroutput>include/VBox/dbgfcorefmt.h</computeroutput>,
+        <computeroutput>include/iprt/x86.h</computeroutput> and
+        <computeroutput>src/VBox/Runtime/include/internal/ldrELFCommon.h</computeroutput>.
+      </para>
+
+      <para>
+        The VM core file can be inspected using
+        <computeroutput>elfdump</computeroutput> and GNU
+        <computeroutput>readelf</computeroutput> or other similar
+        utilities.
+      </para>
+
+    </sect2>
+
   </sect1>
 
-  <sect1>
-    <title>General</title>
+  <sect1 id="ts_general">
+
+    <title>General Troubleshooting</title>
 
     <sect2 id="ts_config-periodic-flush">
-      <title>Guest shows IDE/SATA errors for file-based images on slow host
-      file system</title>
-
-      <para>Occasionally, some host file systems provide very poor writing
-      performance and as a consequence cause the guest to time out IDE/SATA
-      commands. This is normal behavior and should normally cause no real
-      problems, as the guest should repeat commands that have timed out.
-      However, some guests (e.g. some Linux versions) have severe problems if a
-      write to an image file takes longer than about 15 seconds. Some file
-      systems however require more than a minute to complete a single write,
-      if the host cache contains a large amount of data that needs to be
-      written.</para>
-
-      <para>The symptom for this problem is that the guest can no longer
-      access its files during large write or copying operations, usually
-      leading to an immediate hang of the guest.</para>
-
-      <para>In order to work around this problem (the true fix is to use a
-      faster file system that doesn't exhibit such unacceptable write
-      performance), it is possible to flush the image file after a certain
-      amount of data has been written. This interval is normally infinite, but
-      can be configured individually for each disk of a VM.</para>
-
-      <para>For IDE disks use the following command:</para>
-
-      <screen>VBoxManage setextradata "VM name"
+
+      <title>Guest Shows IDE/SATA Errors for File-Based Images on Slow Host File
+        System</title>
+
+      <para>
+        Occasionally, some host file systems provide very poor writing
+        performance and as a consequence cause the guest to time out
+        IDE/SATA commands. This is normal behavior and should normally
+        cause no real problems, as the guest should repeat commands that
+        have timed out. However, guests such as some Linux versions have
+        severe problems if a write to an image file takes longer than
+        about 15 seconds. Some file systems however require more than a
+        minute to complete a single write, if the host cache contains a
+        large amount of data that needs to be written.
+      </para>
+
+      <para>
+        The symptom for this problem is that the guest can no longer
+        access its files during large write or copying operations,
+        usually leading to an immediate hang of the guest.
+      </para>
+
+      <para>
+        In order to work around this problem, the true fix is to use a
+        faster file system that does not exhibit such unacceptable write
+        performance, it is possible to flush the image file after a
+        certain amount of data has been written. This interval is
+        normally infinite, but can be configured individually for each
+        disk of a VM.
+      </para>
+
+      <para>
+        For IDE disks use the following command:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/FlushInterval" [b]</screen>
 
-      <para>For SATA disks use the following command:</para>
-
-      <screen>VBoxManage setextradata "VM name"
+      <para>
+        For SATA disks use the following command:
+      </para>
+
+<screen>VBoxManage setextradata "VM name"
       "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/FlushInterval" [b]</screen>
 
-      <para>The value [x] that selects the disk for IDE is 0 for the master
-      device on the first channel, 1 for the slave device on the first
-      channel, 2 for the master device on the second channel or 3 for the
-      slave device on the second channel. For SATA use values between 0 and
-      29. Only disks support this configuration option; it must not be set for
-      CD/DVD drives.</para>
-
-      <para>The unit of the interval [b] is the number of bytes written since
-      the last flush. The value for it must be selected so that the occasional
-      long write delays do not occur. Since the proper flush interval depends
-      on the performance of the host and the host filesystem, finding the
-      optimal value that makes the problem disappear requires some
-      experimentation. Values between 1000000 and 10000000 (1 to 10 megabytes)
-      are a good starting point. Decreasing the interval both decreases the
-      probability of the problem and the write performance of the guest.
-      Setting the value unnecessarily low will cost performance without
-      providing any benefits. An interval of 1 will cause a flush for each
-      write operation and should solve the problem in any case, but has a
-      severe write performance penalty.</para>
-
-      <para>Providing a value of 0 for [b] is treated as an infinite flush
-      interval, effectively disabling this workaround. Removing the extra data
-      key by specifying no value for [b] has the same effect.</para>
-    </sect2>
-
-    <sect2>
-      <title>Responding to guest IDE/SATA flush requests</title>
-
-      <para>If desired, the virtual disk images can be flushed when the guest
-      issues the IDE FLUSH CACHE command. Normally these requests are ignored
-      for improved performance. The parameters below are only accepted for
-      disk drives. They must not be set for DVD drives.</para>
-
-      <para>To enable flushing for IDE disks, issue the following
-      command:</para>
-
-      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/IgnoreFlush" 0</screen>
-
-      <para>The value [x] that selects the disk is 0 for the master device on
-      the first channel, 1 for the slave device on the first channel, 2 for
-      the master device on the second channel or 3 for the master device on
-      the second channel.</para>
-
-      <para>To enable flushing for SATA disks, issue the following
-      command:</para>
-
-      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/IgnoreFlush" 0</screen>
-
-      <para>The value [x] that selects the disk can be a value between 0 and
-      29.</para>
-
-      <para>Note that this doesn't affect the flushes performed according to
-      the configuration described in <xref linkend="ts_config-periodic-flush"
-      xrefstyle="template: %n" />. Restoring the default of ignoring flush
-      commands is possible by setting the value to 1 or by removing the
-      key.</para>
+      <para>
+        The value [x] that selects the disk for IDE is 0 for the master
+        device on the first channel, 1 for the slave device on the first
+        channel, 2 for the master device on the second channel or 3 for
+        the slave device on the second channel. For SATA use values
+        between 0 and 29. Only disks support this configuration option;
+        it must not be set for CD/DVD drives.
+      </para>
+
+      <para>
+        The unit of the interval [b] is the number of bytes written
+        since the last flush. The value for it must be selected so that
+        the occasional long write delays do not occur. Since the proper
+        flush interval depends on the performance of the host and the
+        host filesystem, finding the optimal value that makes the
+        problem disappear requires some experimentation. Values between
+        1000000 and 10000000 (1 to 10 megabytes) are a good starting
+        point. Decreasing the interval both decreases the probability of
+        the problem and the write performance of the guest. Setting the
+        value unnecessarily low will cost performance without providing
+        any benefits. An interval of 1 will cause a flush for each write
+        operation and should solve the problem in any case, but has a
+        severe write performance penalty.
+      </para>
+
+      <para>
+        Providing a value of 0 for [b] is treated as an infinite flush
+        interval, effectively disabling this workaround. Removing the
+        extra data key by specifying no value for [b] has the same
+        effect.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_ide-sata-flush">
+
+      <title>Responding to Guest IDE/SATA Flush Requests</title>
+
+      <para>
+        If desired, the virtual disk images can be flushed when the
+        guest issues the IDE FLUSH CACHE command. Normally these
+        requests are ignored for improved performance. The parameters
+        below are only accepted for disk drives. They must not be set
+        for DVD drives.
+      </para>
+
+      <para>
+        To enable flushing for IDE disks, issue the following command:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/IgnoreFlush" 0</screen>
+
+      <para>
+        The value [x] that selects the disk is 0 for the master device
+        on the first channel, 1 for the slave device on the first
+        channel, 2 for the master device on the second channel or 3 for
+        the master device on the second channel.
+      </para>
+
+      <para>
+        To enable flushing for SATA disks, issue the following command:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/ahci/0/LUN#[x]/Config/IgnoreFlush" 0</screen>
+
+      <para>
+        The value [x] that selects the disk can be a value between 0 and
+        29.
+      </para>
+
+      <para>
+        Note that this does not affect the flushes performed according
+        to the configuration described in
+        <xref linkend="ts_config-periodic-flush"
+      xrefstyle="template: %n" />.
+        Restoring the default of ignoring flush commands is possible by
+        setting the value to 1 or by removing the key.
+      </para>
+
     </sect2>
 
     <sect2 id="ts_host-freq-boost">
-      <title>Performance variation with frequency boosting</title>
-
-      <para>
-          Many newer multi-core processors support some form of frequency
-          boosting, which means that if only one core is utilized, it can run
-          faster (possibly 50% faster or even more) than the rated CPU frequency.
-          This causes measured performance to vary somewhat as a function of the
-          momentary overall system load. The exact behavior depends strongly
-          on the specific processor model.
-      </para>
-
-      <para>
-          As a consequence, benchmarking on systems which utilize frequency
-          boosting may produce unstable and non-repeatable results, especially
-          if benchmark runs are short (on the order of seconds). To obtain stable
-          results, benchmarks must be run over longer periods of time and with a
-          constant system load apart from the VM being tested.
-      </para>
+
+      <title>Performance Variation with Frequency Boosting</title>
+
+      <para>
+        Many newer multi-core processors support some form of frequency
+        boosting, which means that if only one core is utilized, it can
+        run possibly 50% faster or even more than the rated CPU
+        frequency. This causes measured performance to vary somewhat as
+        a function of the momentary overall system load. The exact
+        behavior depends strongly on the specific processor model.
+      </para>
+
+      <para>
+        As a consequence, benchmarking on systems which utilize
+        frequency boosting may produce unstable and non-repeatable
+        results. This is especially true if benchmark runs are short, of
+        the order of seconds. To obtain stable results, benchmarks must
+        be run over longer periods of time and with a constant system
+        load apart from the VM being tested.
+      </para>
+
     </sect2>
 
     <sect2 id="ts_host-freq-scaling">
-      <title>Frequency scaling effect on CPU usage</title>
-
-      <para>
-          On some hardware platforms and operating systems, CPU frequency
-          scaling may cause CPU usage reporting to be highly misleading. This
-          happens in situations when the host CPU load is significant but not
-          heavy, such as 15-30% of the maximum.
-      </para>
-
-      <para>
-          Most operating systems determine CPU usage in terms of time spent,
-          measuring for example how many nanoseconds the systems or a process
-          was active within one second. However, in order to save energy, modern
-          systems can significantly scale down CPU speed when the system is not
-          fully loaded. Naturally, when the CPU is running at (for example) one
-          half of its maximum speed, the same number of instructions will take
-          roughly twice as long to execute compared to running at full speed.
-      </para>
-
-      <para>
-          Depending on the specific hardware and host OS, this effect can very
-          significantly skew the CPU usage reported by the OS; the reported CPU
-          usage can be several times higher than what it would have been had the
-          CPU been running at full speed. The effect can be observed both on
-          the host OS and in a guest OS.
-      </para>
+
+      <title>Frequency Scaling Effect on CPU Usage</title>
+
+      <para>
+        On some hardware platforms and operating systems, CPU frequency
+        scaling may cause CPU usage reporting to be highly misleading.
+        This happens in situations when the host CPU load is significant
+        but not heavy, such as 15-30% of the maximum.
+      </para>
+
+      <para>
+        Most operating systems determine CPU usage in terms of time
+        spent, measuring for example how many nanoseconds the systems or
+        a process was active within one second. However, in order to
+        save energy, modern systems can significantly scale down CPU
+        speed when the system is not fully loaded. Naturally, when the
+        CPU is running at for example one half of its maximum speed, the
+        same number of instructions will take roughly twice as long to
+        execute compared to running at full speed.
+      </para>
+
+      <para>
+        Depending on the specific hardware and host OS, this effect can
+        very significantly skew the CPU usage reported by the OS; the
+        reported CPU usage can be several times higher than what it
+        would have been had the CPU been running at full speed. The
+        effect can be observed both on the host OS and in a guest OS.
+      </para>
+
     </sect2>
 
     <sect2 id="ts_win-cpu-usage-rept">
-      <title>Inaccurate Windows CPU usage reporting</title>
-
-      <para>
-          CPU usage reporting tools which come with Windows (Task Manager, Resource
-          Monitor) do not take the time spent processing hardware interrupts into
-          account. If the interrupt load is heavy (thousands of interrupts per second),
-          CPU usage may be significantly underreported.
-      </para>
-
-      <para>
-          This problem affects Windows as both host and guest OS. Sysinternals tools
-          (e.g. Process Explorer) do not suffer from this problem.
-      </para>
+
+      <title>Inaccurate Windows CPU Usage Reporting</title>
+
+      <para>
+        CPU usage reporting tools which come with Windows, such as Task
+        Manager or Resource Monitor, do not take the time spent
+        processing hardware interrupts into account. If the interrupt
+        load is heavy, with thousands of interrupts per second, CPU
+        usage may be significantly underreported.
+      </para>
+
+      <para>
+        This problem affects Windows as both host and guest OS.
+        Sysinternals tools, such as Process Explorer, do not suffer from
+        this problem.
+      </para>
+
     </sect2>
 
     <sect2 id="ts_host-powermgmt">
-      <title>Poor performance caused by host power management</title>
-
-      <para>On some hardware platforms and operating systems, virtualization
-      performance is negatively affected by host CPU power management. The
-      symptoms may be choppy audio in the guest or erratic guest clock
-      behavior.</para>
-
-      <para>Some of the problems may be caused by firmware and/or host
-      operating system bugs. Therefore, updating the firmware and applying
-      operating systems fixes is recommended.</para>
-
-      <para>For optimal virtualization performance, the C1E power state
-      support in the system's BIOS should be disabled, if such a setting is
-      available (not all systems support the C1E power state). On Intel
-      systems the <computeroutput>Intel C State</computeroutput> setting
-      should be disabled. Disabling other power management settings
-      may also improve performance. However, a balance between performance
-      and power consumption must always be considered.</para>
+
+      <title>Poor Performance Caused by Host Power Management</title>
+
+      <para>
+        On some hardware platforms and operating systems, virtualization
+        performance is negatively affected by host CPU power management.
+        The symptoms may be choppy audio in the guest or erratic guest
+        clock behavior.
+      </para>
+
+      <para>
+        Some of the problems may be caused by firmware and/or host
+        operating system bugs. Therefore, updating the firmware and
+        applying operating systems fixes is recommended.
+      </para>
+
+      <para>
+        For optimal virtualization performance, the C1E power state
+        support in the system's BIOS should be disabled, if such a
+        setting is available. Not all systems support the C1E power
+        state. On Intel systems, the <computeroutput>Intel C
+        State</computeroutput> setting should be disabled. Disabling
+        other power management settings may also improve performance.
+        However, a balance between performance and power consumption
+        must always be considered.
+      </para>
+
     </sect2>
 
     <sect2 id="ts_gui-2d-grayed-out">
-      <title>GUI: 2D Video Acceleration option is grayed out</title>
-
-      <para>To use 2D Video Acceleration within VirtualBox, your host's video
-      card should support certain OpenGL extensions. On startup, VirtualBox
-      checks for those extensions, and, if the test fails, this option is
-      silently grayed out.</para>
-
-      <para>To find out why it has failed, you can manually execute the
-      following command:</para>
-
-      <screen>VBoxTestOGL --log "log_file_name" --test 2D</screen>
-
-      <para>It will list the required OpenGL extensions one by one and will
-      show you which one failed the test. This usually means that you are
-      running an outdated or misconfigured OpenGL driver on your host. It can
-      also mean that your video chip is lacking required functionality.</para>
-    </sect2>
+
+      <title>GUI: 2D Video Acceleration Option is Grayed Out</title>
+
+      <para>
+        To use 2D Video Acceleration within VirtualBox, your host's
+        video card should support certain OpenGL extensions. On startup,
+        VirtualBox checks for those extensions, and, if the test fails,
+        this option is silently grayed out.
+      </para>
+
+      <para>
+        To find out why it has failed, you can manually execute the
+        following command:
+      </para>
+
+<screen>VBoxTestOGL --log "log_file_name" --test 2D</screen>
+
+      <para>
+        It will list the required OpenGL extensions one by one and will
+        show you which one failed the test. This usually means that you
+        are running an outdated or misconfigured OpenGL driver on your
+        host. It can also mean that your video chip is lacking required
+        functionality.
+      </para>
+
+    </sect2>
+
   </sect1>
 
   <sect1 id="ts_win-guests">
-    <title>Windows guests</title>
-
-    <sect2>
-      <title>No USB 3.0 support in Windows 7 guests</title>
-
-      <para>If a Windows 7 or Windows Server 2008 R2 guest is configured for USB 3.0 (xHCI) support,
-      the guest OS will not have any USB support at all. This happens because Windows 7 predates
-      USB 3.0 and therefore does not ship with any xHCI drivers; Microsoft also does not offer any
-      vendor-provided xHCI drivers via Windows Update.
-      </para>
-
-      <para>To solve this problem, it is necessary to download and install the Intel xHCI driver
-      in the guest. Intel offers the driver as the USB 3.0 eXtensible Host Controller (xHCI) driver
-      for Intel 7 Series/C216 chipsets.
-      </para>
-
-      <para>Note that the driver only supports Windows 7 and Windows Server 2008 R2. The driver
-      package includes support for both 32-bit and 64-bit OS variants.
-      </para>
-    </sect2>
-
-    <sect2>
-      <title>Windows bluescreens after changing VM configuration</title>
-
-      <para>Changing certain virtual machine settings can cause Windows guests
-      to fail during start up with a bluescreen. This may happen if you change
-      VM settings after installing Windows, or if you copy a disk image with
-      an already installed Windows to a newly created VM which has settings
-      that differ from the original machine.</para>
-
-      <para>This applies in particular to the following settings:<itemizedlist>
-          <listitem>
-            <para>The ACPI and I/O APIC settings should never be changed after
-            installing Windows. Depending on the presence of these hardware
-            features, the Windows installation program chooses special kernel
-            and device driver versions and will fail to startup should these
-            hardware features be removed. (Enabling them for a Windows VM
-            which was installed without them does not cause any harm. However,
-            Windows will not use these features in this case.)</para>
-          </listitem>
-
-          <listitem>
-            <para>Changing the storage controller hardware will cause bootup
-            failures as well. This might also apply to you if you copy a disk
-            image from an older version of VirtualBox to a virtual machine
-            created with a newer VirtualBox version; the default subtype of
-            IDE controller hardware was changed from PIIX3 to PIIX4 with
-            VirtualBox 2.2. Make sure these settings are identical.</para>
-          </listitem>
-        </itemizedlist></para>
-    </sect2>
-
-    <sect2>
-      <title>Windows 0x101 bluescreens with SMP enabled (IPI timeout)</title>
-
-      <para>If a VM is configured to have more than one processor (symmetrical
-      multiprocessing, SMP), some configurations of Windows guests crash with
-      an 0x101 error message, indicating a timeout for inter-processor
-      interrupts (IPIs). These interrupts synchronize memory management
-      between processors.</para>
-
-      <para>According to Microsoft, this is due to a race condition in
-      Windows. A hotfix is available.<footnote>
-          <para>See <ulink
-          url="http://support.microsoft.com/kb/955076">http://support.microsoft.com/kb/955076</ulink>.</para>
-        </footnote> If this does not help, please reduce the number of virtual
-      processors to 1.</para>
-    </sect2>
-
-    <sect2>
-      <title>Windows 2000 installation failures</title>
-
-      <para>When installing Windows 2000 guests, you might run into one of the
-      following issues:</para>
+
+    <title>Windows Guests</title>
+
+    <sect2 id="ts_win7-guest-usb3-support">
+
+      <title>No USB 3.0 Support in Windows 7 Guests</title>
+
+      <para>
+        If a Windows 7 or Windows Server 2008 R2 guest is configured for
+        USB 3.0 (xHCI) support, the guest OS will not have any USB
+        support at all. This happens because Windows 7 predates USB 3.0
+        and therefore does not ship with any xHCI drivers. Microsoft
+        also does not offer any vendor-provided xHCI drivers via Windows
+        Update.
+      </para>
+
+      <para>
+        To solve this problem, it is necessary to download and install
+        the Intel xHCI driver in the guest. Intel offers the driver as
+        the USB 3.0 eXtensible Host Controller (xHCI) driver for Intel 7
+        Series/C216 chipsets.
+      </para>
+
+      <para>
+        Note that the driver only supports Windows 7 and Windows Server
+        2008 R2. The driver package includes support for both 32-bit and
+        64-bit OS variants.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win-guest-bluescreen">
+
+      <title>Windows Bluescreens After Changing VM Configuration</title>
+
+      <para>
+        Changing certain virtual machine settings can cause Windows
+        guests to fail during start up with a bluescreen. This may
+        happen if you change VM settings after installing Windows, or if
+        you copy a disk image with an already installed Windows to a
+        newly created VM which has settings that differ from the
+        original machine.
+      </para>
+
+      <para>
+        This applies in particular to the following settings:
+      </para>
 
       <itemizedlist>
-        <listitem>
-          <para>Installation reboots, usually during component
-          registration.</para>
-        </listitem>
-
-        <listitem>
-          <para>Installation fills the whole hard disk with empty log
-          files.</para>
-        </listitem>
-
-        <listitem>
-          <para>Installation complains about a failure installing
-          <literal>msgina.dll</literal>.</para>
-        </listitem>
+
+        <listitem>
+          <para>
+            The ACPI and I/O APIC settings should never be changed after
+            installing Windows. Depending on the presence of these
+            hardware features, the Windows installation program chooses
+            special kernel and device driver versions and will fail to
+            startup should these hardware features be removed. Enabling
+            them for a Windows VM which was installed without them does
+            not cause any harm. However, Windows will not use these
+            features in this case.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Changing the storage controller hardware will cause bootup
+            failures as well. This might also apply to you if you copy a
+            disk image from an older version of VirtualBox to a virtual
+            machine created with a newer VirtualBox version; the default
+            subtype of IDE controller hardware was changed from PIIX3 to
+            PIIX4 with VirtualBox 2.2. Make sure these settings are
+            identical.
+          </para>
+        </listitem>
+
       </itemizedlist>
 
-      <para>These problems are all caused by a bug in the hard disk driver of
-      Windows 2000. After issuing a hard disk request, there is a race
-      condition in the Windows driver code which leads to corruption if the
-      operation completes too fast, i.e. the hardware interrupt from the IDE
-      controller arrives too soon. With physical hardware, there is a
-      guaranteed delay in most systems so the problem is usually hidden there
-      (however it should be possible to reproduce it on physical hardware as
-      well). In a virtual environment, it is possible for the operation to be
-      done immediately (especially on very fast systems with multiple CPUs)
-      and the interrupt is signaled sooner than on a physical system. The
-      solution is to introduce an artificial delay before delivering such
-      interrupts. This delay can be configured for a VM using the following
-      command:</para>
-
-      <screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1</screen>
-
-      <para>This sets the delay to one millisecond. In case this doesn't help,
-      increase it to a value between 1 and 5 milliseconds. Please note that
-      this slows down disk performance. After installation, you should be able
-      to remove the key (or set it to 0).</para>
-    </sect2>
-
-    <sect2>
-      <title>How to record bluescreen information from Windows guests</title>
-
-      <para>When Windows guests run into a kernel crash, they display the
-      infamous bluescreen. Depending on how Windows is configured, the
-      information will remain on the screen until the machine is restarted or
-      it will reboot automatically. During installation, Windows is usually
-      configured to reboot automatically. With automatic reboots, there is no
-      chance to record the bluescreen information which might be important for
-      problem determination.</para>
-
-      <para>VirtualBox provides a method of halting a guest when it wants to
-      perform a reset. In order to enable this feature, issue the following
-      command:</para>
-
-      <para><screen>VBoxManage setextradata "VM name" "VBoxInternal/PDM/HaltOnReset" 1</screen></para>
-    </sect2>
-
-    <sect2>
-      <title>PCnet driver failure in 32-bit Windows Server 2003 guests</title>
-
-      <para>Certain editions of Windows 2000 and 2003 servers support more
-      than 4 GB RAM on 32-bit systems. The AMD PCnet network driver shipped with
-      Windows Server 2003 fails to load if the 32-bit guest OS uses paging
-      extensions (which will occur with more than approximately 3.5 GB RAM
-      assigned to the VM).</para>
-
-      <para>This problem is known to occur with version 4.38.0.0 of the PCnet
-      driver. The issue was fixed in version 4.51.0.0 of the driver, which
-      is available as a separate download. An alternative solution may be
-      changing the emulated NIC type to Intel PRO/1000 MT Desktop (82540EM),
-      or reducing the RAM assigned to the VM to approximately 3.5 GB or less.
-      </para>
-    </sect2>
-
-    <sect2>
-      <title>No networking in Windows Vista guests</title>
-
-      <para>With Windows Vista, Microsoft dropped support for the AMD PCNet
-      card that VirtualBox used to provide as the default virtual network card
-      before version 1.6.0. For Windows Vista guests, VirtualBox now uses an
-      Intel E1000 card by default.</para>
-
-      <para>If, for some reason, you still want to use the AMD card, you need
-      to download the PCNet driver from the AMD website (available for 32-bit
-      Windows only). You can transfer it into the virtual machine using a
-      shared folder, see (see <xref linkend="sharedfolders" />).</para>
-    </sect2>
-
-    <sect2>
-      <title>Windows guests may cause a high CPU load</title>
-
-      <para>Several background applications of Windows guests, especially
-      virus scanners, are known to increases the CPU load notably even if the
-      guest appears to be idle. We recommend to deactivate virus scanners
-      within virtualized guests if possible.</para>
-    </sect2>
-
-    <sect2>
-      <title>Long delays when accessing shared folders</title>
-
-      <para>The performance for accesses to shared folders from a Windows
-      guest might be decreased due to delays during the resolution of the
-      VirtualBox shared folders name service. To fix these delays, add the
-      following entries to the file
-      <computeroutput>\windows\system32\drivers\etc\lmhosts</computeroutput>
-      of the Windows guest:</para>
-
-      <screen>255.255.255.255        VBOXSVR #PRE
+    </sect2>
+
+    <sect2 id="ts_win-guest-bluescreen-smp">
+
+      <title>Windows 0x101 Bluescreens with SMP Enabled (IPI Timeout)</title>
+
+      <para>
+        If a VM is configured to have more than one processor
+        (symmetrical multiprocessing, SMP), some configurations of
+        Windows guests crash with an 0x101 error message, indicating a
+        timeout for inter-processor interrupts (IPIs). These interrupts
+        synchronize memory management between processors.
+      </para>
+
+      <para>
+        According to Microsoft, this is due to a race condition in
+        Windows. A hotfix is available. See
+        <ulink
+          url="http://support.microsoft.com/kb/955076">http://support.microsoft.com/kb/955076</ulink>.
+      </para>
+
+      <para>
+        If this does not help, please reduce the number of virtual
+        processors to 1.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win2k-guest-install">
+
+      <title>Windows 2000 Installation Failures</title>
+
+      <para>
+        When installing Windows 2000 guests, you might run into one of
+        the following issues:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Installation reboots, usually during component registration.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Installation fills the whole hard disk with empty log files.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Installation complains about a failure installing
+            <literal>msgina.dll</literal>.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        These problems are all caused by a bug in the hard disk driver
+        of Windows 2000. After issuing a hard disk request, there is a
+        race condition in the Windows driver code which leads to
+        corruption if the operation completes too fast. For example, the
+        hardware interrupt from the IDE controller arrives too soon.
+        With physical hardware, there is a guaranteed delay in most
+        systems so the problem is usually hidden there. However, it
+        should be possible to also reproduce it on physical hardware. In
+        a virtual environment, it is possible for the operation to be
+        done immediately, especially on very fast systems with multiple
+        CPUs, and the interrupt is signaled sooner than on a physical
+        system. The solution is to introduce an artificial delay before
+        delivering such interrupts. This delay can be configured for a
+        VM using the following command:
+      </para>
+
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/Devices/piix3ide/0/Config/IRQDelay" 1</screen>
+
+      <para>
+        This sets the delay to one millisecond. In case this does not
+        help, increase it to a value between 1 and 5 milliseconds.
+        Please note that this slows down disk performance. After
+        installation, you should be able to remove the key, or set it to
+        0.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win-guest-bluescreen-record-info">
+
+      <title>How to Record Bluescreen Information from Windows Guests</title>
+
+      <para>
+        When Windows guests run into a kernel crash, they display the
+        infamous bluescreen. Depending on how Windows is configured, the
+        information will remain on the screen until the machine is
+        restarted or it will reboot automatically. During installation,
+        Windows is usually configured to reboot automatically. With
+        automatic reboots, there is no chance to record the bluescreen
+        information which might be important for problem determination.
+      </para>
+
+      <para>
+        VirtualBox provides a method of halting a guest when it wants to
+        perform a reset. In order to enable this feature, issue the
+        following command:
+      </para>
+
+      <para>
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/PDM/HaltOnReset" 1</screen>
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_pcnet-driver-win-2003-server-guest">
+
+      <title>PCnet Driver Failure in 32-bit Windows Server 2003 Guests</title>
+
+      <para>
+        Certain editions of Windows 2000 and 2003 servers support more
+        than 4 GB RAM on 32-bit systems. The AMD PCnet network driver
+        shipped with Windows Server 2003 fails to load if the 32-bit
+        guest OS uses paging extensions, which will occur with more than
+        approximately 3.5 GB RAM assigned to the VM.
+      </para>
+
+      <para>
+        This problem is known to occur with version 4.38.0.0 of the
+        PCnet driver. The issue was fixed in version 4.51.0.0 of the
+        driver, which is available as a separate download. An
+        alternative solution may be changing the emulated NIC type to
+        Intel PRO/1000 MT Desktop (82540EM), or reducing the RAM
+        assigned to the VM to approximately 3.5 GB or less.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win-vista-guest-networking">
+
+      <title>No Networking in Windows Vista Guests</title>
+
+      <para>
+        With Windows Vista, Microsoft dropped support for the AMD PCNet
+        card that VirtualBox used to provide as the default virtual
+        network card before version 1.6.0. For Windows Vista guests,
+        VirtualBox now uses an Intel E1000 card by default.
+      </para>
+
+      <para>
+        If, for some reason, you still want to use the AMD card, you
+        need to download the PCNet driver from the AMD website. This
+        driver is available for 32-bit Windows only. You can transfer it
+        into the virtual machine using a shared folder. See
+        <xref linkend="sharedfolders" />.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win-guest-high-cpu">
+
+      <title>Windows Guests may Cause a High CPU Load</title>
+
+      <para>
+        Several background applications of Windows guests, especially
+        virus scanners, are known to increases the CPU load notably even
+        if the guest appears to be idle. We recommend to deactivate
+        virus scanners within virtualized guests if possible.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win-guest-shared-folders-access-delay">
+
+      <title>Long Delays When Accessing Shared Folders</title>
+
+      <para>
+        The performance for accesses to shared folders from a Windows
+        guest might be decreased due to delays during the resolution of
+        the VirtualBox shared folders name service. To fix these delays,
+        add the following entries to the file
+        <computeroutput>\windows\system32\drivers\etc\lmhosts</computeroutput>
+        of the Windows guest:
+      </para>
+
+<screen>255.255.255.255        VBOXSVR #PRE
 255.255.255.255        VBOXSRV #PRE</screen>
 
-      <para>After doing this change, a reboot of the guest is required.</para>
-    </sect2>
-
-    <sect2>
-      <title>USB tablet coordinates wrong in Windows 98 guests</title>
-
-      <para>If a Windows 98 VM is configured to use the emulated USB tablet
-      (absolute pointing device), the coordinate translation may be incorrect
-      and the pointer is restricted to the upper left quarter of the guest's
-      screen.
-      </para>
-
-      <para>The USB HID (Human Interface Device) drivers in Windows 98 are very
-          old and do not handle tablets the same way all more recent operating
-          systems do (Windows 2000 and later, Mac OS X, Solaris). To
-          work around the problem, issue the following command:
-      </para>
-
-      <para><screen>VBoxManage setextradata "VM name" "VBoxInternal/USB/HidMouse/0/Config/CoordShift" 0</screen></para>
-
-      <para>To restore the default behavior, remove the key or set its value
-          to 1.
-      </para>
-    </sect2>
-
-    <sect2>
-      <title>Windows guests are removed from an Active Directory domain after
-          restoring a snapshot</title>
-
-      <para>If a Windows guest is a member of an Active Directory domain and
-          the snapshot feature of VirtualBox is used, it could happen it loses
-          this status after you restore an older snapshot.
-      </para>
-
-      <para>The reason is the automatic machine password changing performed by
-          Windows in regular intervals for security purposes. You can disable
-          this feature by following the instruction of this <ulink
+      <para>
+        After doing this change, a reboot of the guest is required.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win98-guest-usb-tablet-coordinates">
+
+      <title>USB Tablet Coordinates Wrong in Windows 98 Guests</title>
+
+      <para>
+        If a Windows 98 VM is configured to use the emulated USB tablet
+        (absolute pointing device), the coordinate translation may be
+        incorrect and the pointer is restricted to the upper left
+        quarter of the guest's screen.
+      </para>
+
+      <para>
+        The USB HID (Human Interface Device) drivers in Windows 98 are
+        very old and do not handle tablets the same way all more recent
+        operating systems do (Windows 2000 and later, Mac OS X,
+        Solaris). To work around the problem, issue the following
+        command:
+      </para>
+
+      <para>
+<screen>VBoxManage setextradata "VM name" "VBoxInternal/USB/HidMouse/0/Config/CoordShift" 0</screen>
+      </para>
+
+      <para>
+        To restore the default behavior, remove the key or set its value
+        to 1.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win-guest-active-dir-domain">
+
+      <title>Windows Guests are Removed From an Active Directory Domain After
+        Restoring a Snapshot</title>
+
+      <para>
+        If a Windows guest is a member of an Active Directory domain and
+        the snapshot feature of VirtualBox is used, it could happen it
+        loses this status after you restore an older snapshot.
+      </para>
+
+      <para>
+        The reason is the automatic machine password changing performed
+        by Windows at regular intervals for security purposes. You can
+        disable this feature by following the instruction of the
+        following article from Microsoft:
+        <ulink
           url="http://support.microsoft.com/kb/154501">http://support.microsoft.com/kb/154501</ulink>
-          article from Microsoft.
-      </para>
+      </para>
+
     </sect2>
 
     <sect2 id="ts_d3d8-d3d9-restore">
+
       <title>Restoring d3d8.dll and d3d9.dll</title>
 
-      <para>VirtualBox Guest Additions for Windows prior to 4.1.8 did not properly
-          back up the original d3d8.dll and d3d9.dll system files when selecting
-          and installing the experimental Direct3D support. This process replaces
-          both system files with files from the VirtualBox Guest Additions so that
-          Direct3D calls can be handled correctly. Although this issue was fixed
-          with VirtualBox 4.1.8, there is no way the Windows Guest Additions
-          installer can repair these files.</para>
-
-      <para>Corruption of these files has no implications in case 3D acceleration
-          is enabled and basic Direct3D support is installed, that is, without WDDM
-          (on Windows Vista or higher) or on older Windows systems like Windows XP.
-          With the basic Direct3D support all Direct3D 8.0 and Direct3D 9.0
-          applications will utilize VirtualBox Direct3D files directly and thus
-          will run as expected.</para>
-
-      <para>For WDDM Direct3D support however, the originally shipped d3d8.dll and
-          d3d9.dll files are required in order to run Direct3D 8.0
-          and Direct3D 9.0 applications. As a result of the above mentioned system
-          files corruption these applications will not work anymore. See below for
-          a step-by-step guide for restoring the original d3d8.dll and d3d9.dll
-          system files in case the VirtualBox Guest Additions installer warned
-          about those incorrect files or when having trouble running Direct3D
-          applications.</para>
-
-      <note><para>Starting at Windows 7 the 3D desktop (aka Aero) uses DirectX 10
-          for rendering so that corrupted d3d8.dll and d3d9.dll system files will
-          have no effect on the actual rendering.</para></note>
-
-      <para>This is why such a detected file corruption is not considered as fatal
-          for the basic Direct3D installation on all supported Windows guests,
-          and for WDDM Direct3D installation on Windows 7 and later guests.</para>
-
-      <para>Extracting d3d8 and d3d9.dll from a Windows XP installation CD:</para>
+      <para>
+        VirtualBox Guest Additions for Windows prior to 4.1.8 did not
+        properly back up the original d3d8.dll and d3d9.dll system files
+        when selecting and installing the experimental Direct3D support.
+        This process replaces both system files with files from the
+        VirtualBox Guest Additions so that Direct3D calls can be handled
+        correctly. Although this issue was fixed with VirtualBox 4.1.8,
+        there is no way the Windows Guest Additions installer can repair
+        these files.
+      </para>
+
+      <para>
+        Corruption of these files has no implications in case 3D
+        acceleration is enabled and basic Direct3D support is installed,
+        that is, without WDDM (on Windows Vista or higher) or on older
+        Windows systems like Windows XP. With the basic Direct3D support
+        all Direct3D 8.0 and Direct3D 9.0 applications will utilize
+        VirtualBox Direct3D files directly and thus will run as
+        expected.
+      </para>
+
+      <para>
+        For WDDM Direct3D support however, the originally shipped
+        d3d8.dll and d3d9.dll files are required in order to run
+        Direct3D 8.0 and Direct3D 9.0 applications. As a result of the
+        above mentioned system files corruption these applications will
+        not work anymore. See below for a step-by-step guide for
+        restoring the original d3d8.dll and d3d9.dll system files in
+        case the VirtualBox Guest Additions installer warned about those
+        incorrect files or when having trouble running Direct3D
+        applications.
+      </para>
+
+      <note>
+        <para>
+          Starting at Windows 7 the 3D desktop, called Aero, uses
+          DirectX 10 for rendering so that corrupted d3d8.dll and
+          d3d9.dll system files will have no effect on the actual
+          rendering.
+        </para>
+      </note>
+
+      <para>
+        This is why such a detected file corruption is not considered as
+        fatal for the basic Direct3D installation on all supported
+        Windows guests, and for WDDM Direct3D installation on Windows 7
+        and later guests.
+      </para>
+
+      <para>
+        <emphasis role="bold">Extracting d3d8 and d3d9.dll from a
+        Windows XP installation CD:</emphasis>
+      </para>
 
       <orderedlist>
-        <listitem>
-          <para>Download and install the latest version of 7-Zip File Manager <ulink
-          url="http//www.7-zip.org">http//www.7-zip.org</ulink></para>
-        </listitem>
-
-        <listitem>
-          <para>Browse into the installation CD for example E:\i386 (or amd64 for the 64-bit version)</para>
-        </listitem>
-
-        <listitem>
-          <para>Locate file d3d8.dl_ and d3d9.dl_, double click on it and Extract d3d8.dll and d3d9.dll</para>
-        </listitem>
-
-        <listitem>
-          <para>Reboot Windows in Safe mode</para>
-        </listitem>
-
-        <listitem>
-          <para>Copy extracted d3d8.dll and d3d9.dll to C:\Windows\system32 and C:\Windows\system32\dllcache</para>
-        </listitem>
-
-        <listitem>
-          <para>Reboot</para>
-        </listitem>
+
+        <listitem>
+          <para>
+            Download and install the latest version of 7-Zip File
+            Manager. See
+            <ulink
+          url="http//www.7-zip.org">http//www.7-zip.org</ulink>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Browse into the installation CD. For example E:\i386, or
+            E:\amd64 for the 64-bit version.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Locate the entries d3d8.dl_ and d3d9.dl_. Double-click on
+            the file names and extract d3d8.dll and d3d9.dll.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Reboot Windows in Safe mode.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Copy the extracted d3d8.dll and d3d9.dll files to
+            C:\Windows\system32 and C:\Windows\system32\dllcache.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Reboot Windows.
+          </para>
+        </listitem>
+
       </orderedlist>
 
-      <para>Extracting d3d8 and d3d9.dll from Windows XP Service pack </para>
+      <para>
+        <emphasis role="bold">Extracting d3d8 and d3d9.dll from a
+        Windows XP Service pack:</emphasis>
+      </para>
 
       <orderedlist>
-        <listitem>
-          <para>1, 3-6 Same as installation CD</para>
-        </listitem>
-        <listitem>
-          <para>Use 'Open inside' to open WindowsXP-KB936929-SP3-x86.exe as archive and browse i386 directory.</para>
-        </listitem>
+
+        <listitem>
+          <para>
+            Download and install the latest version of 7-Zip File
+            Manager. See
+            <ulink
+              url="http//www.7-zip.org">http//www.7-zip.org</ulink>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Choose Open Inside, to open WindowsXP-KB936929-SP3-x86.exe
+            as an archive and browse the i386 directory.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Locate the entries d3d8.dl_ and d3d9.dl_. Double-click on
+            the file names and extract d3d8.dll and d3d9.dll.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Reboot Windows in Safe mode.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Copy the extracted d3d8.dll and d3d9.dll files to
+            C:\Windows\system32 and C:\Windows\system32\dllcache.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Reboot Windows.
+          </para>
+        </listitem>
+
       </orderedlist>
 
-      <para>Extracting d3d8 and d3d9.dll from Vista/Windows7 installation CD or Service Pack iso</para>
+      <para>
+        Extracting d3d8 and d3d9.dll from a Vista/Windows7 installation
+        CD or Service Pack ISO:
+      </para>
 
       <orderedlist>
-        <listitem>
-          <para>Download and install the latest version of 7-Zip File Manager <ulink
-          url="http//www.7-zip.org">http//www.7-zip.org</ulink></para>
-        </listitem>
-
-        <listitem>
-          <para>Browse into installation CD for example E:\sources</para>
-        </listitem>
-
-        <listitem>
-          <para>Locate file install.wim and double click it. After 7-Zip utility opens the file, you'll get a few numbered folders. Each numeric subfolder represents a different version of Windows (Starter, Home Basic, and so on)</para>
-        </listitem>
-
-        <listitem>
-          <para>After entering into the one of the numeric folders, browse into Windows\System32 (or C:\Windows\SysWOW64 for the 64-bit version) directory locate d3d8.dll and d3d9.dll and extract</para>
-        </listitem>
-
-        <listitem>
-          <para>Copy extracted d3d8.dll and d3d9.dll to C:\Windows\system32 or C:\Windows\SysWOW64 (files from system32 should go to system32, from SysWOW64 to SysWOW64)</para>
-        </listitem>
-
-        <listitem>
-          <para>Reboot</para>
-        </listitem>
+
+        <listitem>
+          <para>
+            Download and install the latest version of 7-Zip File
+            Manager. See
+            <ulink
+          url="http//www.7-zip.org">http//www.7-zip.org</ulink>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Browse into the installation CD. for example E:\sources.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Locate file install.wim and double-click the file. After the
+            7-Zip utility unzips the file, you will see a few numbered
+            folders. Each numeric subfolder represents a different
+            version of Windows such as Starter or Home Basic.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Open one of the numeric folders and browse to the
+            Windows\System32 directory, or C:\Windows\SysWOW64 for the
+            64-bit version. Locate and extract the d3d8.dll and d3d9.dll
+            files.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Copy extracted the d3d8.dll and d3d9.dll files to
+            C:\Windows\system32 or C:\Windows\SysWOW64. Files from
+            system32 should go to system32, from SysWOW64 to SysWOW64.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Reboot Windows.
+          </para>
+        </listitem>
+
       </orderedlist>
-    </sect2>
-
-    <sect2>
-      <title>Windows 3.x limited to 64 MB RAM</title>
-
-      <para>Windows 3.x guests are typically limited to 64 MB RAM, even if a VM is assigned
-      much more memory. While Windows 3.1 is theoretically capable of using up to 512 MB RAM,
-      it only uses memory available through the XMS interface. Versions of HIMEM.SYS (the
-      Microsoft XMS manager) shipped with MS-DOS and Microsoft Windows 3.x can only use
-      up to 64 MB on standard PCs.</para>
-
-      <para>This is a HIMEM.SYS limitation documented by Microsoft in Knowledge base
-      article KB 116256.
-      Windows 3.1 memory limits are described in detail in Microsoft Knowledge base
-      article KB 84388.</para>
-
-      <para>It is possible for Windows 3.x guests to utilize more than 64 MB RAM if a
-      different XMS provider is used. That could be a newer HIMEM.SYS version (such as
-      that shipped with Windows 98), or a more capable third-party memory manager
-      (such as QEMM).</para>
+
+    </sect2>
+
+    <sect2 id="ts_win31-ram-limitations">
+
+      <title>Windows 3.x Limited to 64 MB RAM</title>
+
+      <para>
+        Windows 3.x guests are typically limited to 64 MB RAM, even if a
+        VM is assigned much more memory. While Windows 3.1 is
+        theoretically capable of using up to 512 MB RAM, it only uses
+        memory available through the XMS interface. Versions of
+        HIMEM.SYS, the Microsoft XMS manager, shipped with MS-DOS and
+        Microsoft Windows 3.x can only use up to 64 MB on standard PCs.
+      </para>
+
+      <para>
+        This is a HIMEM.SYS limitation documented by Microsoft in
+        Knowledge base article KB 116256. Windows 3.1 memory limits are
+        described in detail in Microsoft Knowledge base article KB
+        84388.
+      </para>
+
+      <para>
+        It is possible for Windows 3.x guests to utilize more than 64 MB
+        RAM if a different XMS provider is used. That could be a newer
+        HIMEM.SYS version, such as that shipped with Windows 98, or a
+        more capable third-party memory manager, such as QEMM.
+      </para>
+
     </sect2>
 
@@ -1012,564 +1485,791 @@
 
   <sect1 id="ts_lin-x11-guests">
-    <title>Linux and X11 guests</title>
-
-    <sect2>
-      <title>Linux guests may cause a high CPU load</title>
-
-      <para>Some Linux guests may cause a high CPU load even if the guest
-      system appears to be idle. This can be caused by a high timer frequency
-      of the guest kernel. Some Linux distributions, for example Fedora, ship
-      a Linux kernel configured for a timer frequency of <emphasis
-      role="bold"> 1000Hz</emphasis>. We recommend to recompile the guest
-      kernel and to select a timer frequency of 100Hz.</para>
-
-      <para>Linux kernels shipped with Red Hat Enterprise Linux (RHEL) as of
-      release 4.7 and 5.1 as well as kernels of related Linux distributions
-      (for instance CentOS and Oracle Linux) support a kernel
-      parameter <emphasis>divider=N</emphasis>. Hence, such kernels support a
-      lower timer frequency without recompilation. We suggest to add the
-      kernel parameter <emphasis>divider=10</emphasis> to select a guest
-      kernel timer frequency of 100Hz.</para>
-    </sect2>
-
-    <sect2>
+
+    <title>Linux and X11 Guests</title>
+
+    <sect2 id="ts_linux-guest-high-cpu">
+
+      <title>Linux Guests May Cause a High CPU load</title>
+
+      <para>
+        Some Linux guests may cause a high CPU load even if the guest
+        system appears to be idle. This can be caused by a high timer
+        frequency of the guest kernel. Some Linux distributions, for
+        example Fedora, ship a Linux kernel configured for a timer
+        frequency of 1000Hz. We recommend to recompile the guest kernel
+        and to select a timer frequency of 100Hz.
+      </para>
+
+      <para>
+        Linux kernels shipped with Red Hat Enterprise Linux (RHEL) as of
+        release 4.7 and 5.1 as well as kernels of related Linux
+        distributions, such as CentOS and Oracle Linux, support a kernel
+        parameter <emphasis>divider=N</emphasis>. Hence, such kernels
+        support a lower timer frequency without recompilation. We
+        suggest you add the kernel parameter
+        <emphasis>divider=10</emphasis> to select a guest kernel timer
+        frequency of 100Hz.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_linux-guest-amd-barcelona">
+
       <title>AMD Barcelona CPUs</title>
 
-      <para>Most Linux-based guests will fail with AMD Phenoms or
-      Barcelona-level Opterons due to a bug in the Linux kernel. Enable the
-      I/O-APIC to work around the problem (see <xref
-      linkend="settings-system" />).</para>
+      <para>
+        Most Linux-based guests will fail with AMD Phenoms or
+        Barcelona-level Opterons due to a bug in the Linux kernel.
+        Enable the I/O-APIC to work around the problem. See
+        <xref
+      linkend="settings-system" />.
+      </para>
+
     </sect2>
 
     <sect2 id="ts_linux-buggy">
-      <title>Buggy Linux 2.6 kernel versions</title>
-
-      <para>The following bugs in Linux kernels prevent them from executing
-      correctly in VirtualBox, causing VM boot crashes:<itemizedlist>
-          <listitem>
-            <para>The Linux kernel version 2.6.18 (and some 2.6.17 versions)
+
+      <title>Buggy Linux 2.6 Kernel Versions</title>
+
+      <para>
+        The following bugs in Linux kernels prevent them from executing
+        correctly in VirtualBox, causing VM boot crashes:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            The Linux kernel version 2.6.18, and some 2.6.17 versions,
             introduced a race condition that can cause boot crashes in
-            VirtualBox. Please use a kernel version 2.6.19 or later.</para>
-          </listitem>
-
-          <listitem>
-            <para>With hardware virtualization and the I/O APIC enabled,
-            kernels before 2.6.24-rc6 may panic on boot with the following
-            message:<screen>Kernel panic - not syncing: IO-APIC + timer doesn't work!  Boot with
-apic=debug and send a report.  Then try booting with the 'noapic' option</screen></para>
-
-            <para>If you see this message, either disable hardware
-            virtualization or the I/O APIC (see <xref
-            linkend="settings-system" />), or upgrade the guest to a newer
-            kernel.<footnote>
-                <para>See <ulink
+            VirtualBox. Please use a kernel version 2.6.19 or later.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            With hardware virtualization and the I/O APIC enabled,
+            kernels before 2.6.24-rc6 may panic on boot with the
+            following message:
+          </para>
+
+<screen>Kernel panic - not syncing: IO-APIC + timer doesn't work!  Boot with
+apic=debug and send a report.  Then try booting with the 'noapic' option</screen>
+
+          <para>
+            If you see this message, either disable hardware
+            virtualization or the I/O APIC as described in
+            <xref
+            linkend="settings-system" />, or upgrade
+            the guest to a newer kernel.
+
+            <footnote>
+
+              <para>
+                See
+                <ulink
                 url="http://www.mail-archive.com/git-commits-head@vger.kernel.org/msg30813.html">http://www.mail-archive.com/git-commits-head@vger.kernel.org/msg30813.html</ulink>
-                for details about the kernel fix.</para>
-              </footnote></para>
-          </listitem>
-        </itemizedlist></para>
-    </sect2>
-
-    <sect2>
-      <title>Shared clipboard, auto-resizing and seamless desktop in X11
-      guests</title>
-
-      <para>Guest desktop services in guests running the X11 window system
-      (Solaris, Linux and others) are provided by a guest service called
-      <computeroutput>VBoxClient</computeroutput>, which runs under the ID of
-      the user who started the desktop session and is automatically started
-      using the following command lines <screen>VBoxClient --clipboard
+                for details about the kernel fix.
+              </para>
+
+            </footnote>
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="ts_linux-guest-x11-services">
+
+      <title>Shared Clipboard, Auto-Resizing, and Seamless Desktop in X11 Guests</title>
+
+      <para>
+        Guest desktop services in guests running the X11 window system
+        such as Solaris and Linux, are provided by a guest service
+        called <computeroutput>VBoxClient</computeroutput>, which runs
+        under the ID of the user who started the desktop session and is
+        automatically started using the following command lines when
+        your X11 user session is started if you are using a common
+        desktop environment (Gnome, KDE and others).
+      </para>
+
+<screen>VBoxClient --clipboard
 VBoxClient --display
-VBoxClient --seamless</screen> when your X11 user session is started if you
-      are using a common desktop environment (Gnome, KDE and others). If a
-      particular desktop service is not working correctly, it is worth
-      checking whether the process which should provide it is running.</para>
-
-      <para>The <computeroutput>VBoxClient</computeroutput> processes create
-      files in the user's home directory with names of the form
-      <computeroutput>.vboxclient-*.pid</computeroutput> when they are running
-      in order to prevent a given service from being started twice. It can
-      happen due to misconfiguration that these files are created owned by
-      root and not deleted when the services are stopped, which will prevent
-      them from being started in future sessions. If the services cannot be
-      started, you may wish to check whether these files still exist.</para>
-    </sect2>
+VBoxClient --seamless</screen>
+
+      <para>
+        If a particular desktop service is not working correctly, it is
+        worth checking whether the process which should provide it is
+        running.
+      </para>
+
+      <para>
+        The <computeroutput>VBoxClient</computeroutput> processes create
+        files in the user's home directory with names of the form
+        <computeroutput>.vboxclient-*.pid</computeroutput> when they are
+        running in order to prevent a given service from being started
+        twice. It can happen due to misconfiguration that these files
+        are created owned by root and not deleted when the services are
+        stopped, which will prevent them from being started in future
+        sessions. If the services cannot be started, you may wish to
+        check whether these files still exist.
+      </para>
+
+    </sect2>
+
   </sect1>
 
   <sect1 id="ts_sol-guests">
-    <title>Solaris guests</title>
-
-    <sect2>
-      <title>Older Solaris 10 releases crash in 64-bit mode</title>
-
-      <para>Solaris 10 releases up to and including Solaris 10 8/07 ("S10U4")
-          incorrectly detect newer Intel processors produced since 2007. This
-          problem leads to the 64-bit Solaris kernel crashing (and usually causing
-          a triple fault) almost immediately during startup, in both virtualized
-          and physical environments.
-      </para>
-      <para>
-          The recommended solution is upgrading to at least Solaris 10 5/08
-          ("S10U5"). Alternative solutions include forcing Solaris to always
-          boot the 32-bit kernel or applying a patch for bug 6574102 (while
-          Solaris is using the 32-bit kernel).
-      </para>
-
-    </sect2>
-
-    <sect2>
-      <title>Certain Solaris 10 releases may take long to boot with SMP</title>
-
-      <para>When using more than one CPU, Solaris 10 releases 5/08 ("S10U5"),
-          10/08 ("S10U6"), and 5/09 ("S10U7") may take a long time to boot and
-          may print warnings on the system console regarding failures to read
-          from disk. This is a bug in Solaris 10 which affects specific physical
-          and virtual configurations. It is caused by trying to read microcode
-          updates from the boot disk when the disk interrupt is reassigned to a
-          not yet fully initialized secondary CPU. Disk reads will time out and
-          fail, triggering delays (approx. 45 seconds) and warnings.
-      </para>
-      <para>
-          The recommended solution is upgrading to at least Solaris 10 10/09
-          ("S10U8") which includes a fix for this problem. Alternative solutions
-          include restricting the number of virtual CPUs to one or possibly
-          using a different storage controller.
-      </para>
-
-    </sect2>
-
-    <sect2>
-      <title>Solaris 8 5/01 and earlier may crash on startup</title>
-
-      <para>
-          Solaris 2.6, 7 and 8 releases up to and including Solaris 8 4/01 ("S8U4")
-          incorrectly set up Machine Check Exception (MCE) MSRs on Pentium 4 and
-          some later Intel CPUs. The problem leads to the Solaris kernel crashing
-          (and usually causing a triple fault) almost immediately during startup, in both
-          virtualized and physical environments. Solaris 9 and later releases are
-          not affected by this problem, and neither is Solaris 2.5.1 and earlier.
-      </para>
-      <para>
-          The recommended solution is upgrading to at least Solaris 8 7/01
-          ("S8U5"). Alternative solutions include applying a patch for bugs 4408508
-          and 4414557 (on an unaffected system).
-      </para>
-
-    </sect2>
+
+    <title>Solaris Guests</title>
+
+    <sect2 id="ts_solaris-10-guest-crash">
+
+      <title>Older Solaris 10 Releases Crash in 64-bit Mode</title>
+
+      <para>
+        Solaris 10 releases up to and including Solaris 10 8/07
+        ("S10U4") incorrectly detect newer Intel processors produced
+        since 2007. This problem leads to the 64-bit Solaris kernel
+        crashing, and usually causing a triple fault, almost immediately
+        during startup, in both virtualized and physical environments.
+      </para>
+
+      <para>
+        The recommended solution is upgrading to at least Solaris 10
+        5/08 ("S10U5"). Alternative solutions include forcing Solaris to
+        always boot the 32-bit kernel or applying a patch for bug
+        6574102 while Solaris is using the 32-bit kernel.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_solaris-10-guest-slow-boot-smp">
+
+      <title>Certain Solaris 10 Releases May Take a Long Time to Boot with SMP</title>
+
+      <para>
+        When using more than one CPU, Solaris 10 releases 5/08
+        ("S10U5"), 10/08 ("S10U6"), and 5/09 ("S10U7") may take a long
+        time to boot and may print warnings on the system console
+        regarding failures to read from disk. This is a bug in Solaris
+        10 which affects specific physical and virtual configurations.
+        It is caused by trying to read microcode updates from the boot
+        disk when the disk interrupt is reassigned to a not yet fully
+        initialized secondary CPU. Disk reads will time out and fail,
+        triggering delays of about 45 seconds and warnings.
+      </para>
+
+      <para>
+        The recommended solution is upgrading to at least Solaris 10
+        10/09 ("S10U8") which includes a fix for this problem.
+        Alternative solutions include restricting the number of virtual
+        CPUs to one or possibly using a different storage controller.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_solaris-8-guest-crash">
+
+      <title>Solaris 8 5/01 and Earlier May Crash on Startup</title>
+
+      <para>
+        Solaris 2.6, 7 and 8 releases up to and including Solaris 8 4/01
+        ("S8U4") incorrectly set up Machine Check Exception (MCE) MSRs
+        on Pentium 4 and some later Intel CPUs. The problem leads to the
+        Solaris kernel crashing, and usually causing a triple fault,
+        almost immediately during startup, in both virtualized and
+        physical environments. Solaris 9 and later releases are not
+        affected by this problem, and neither is Solaris 2.5.1 and
+        earlier.
+      </para>
+
+      <para>
+        The recommended solution is upgrading to at least Solaris 8 7/01
+        ("S8U5"). Alternative solutions include applying a patch for
+        bugs 4408508 and 4414557 on an unaffected system.
+      </para>
+
+    </sect2>
+
   </sect1>
 
   <sect1 id="ts_fbsd-guests">
-    <title>FreeBSD guests</title>
-
-    <sect2>
-        <title>FreeBSD 10.0 may hang with xHCI</title>
-
+
+    <title>FreeBSD Guests</title>
+
+    <sect2 id="ts_fbsd-guest-xhci">
+
+      <title>FreeBSD 10.0 May Hang with xHCI</title>
+
+      <para>
+        If xHCI (USB 3.0) emulation is enabled for FreeBSD 10.0 guests,
+        the guest OS will hang. This is caused by the guest OS
+        incorrectly handling systems where Message Signaled Interrupts
+        (MSIs) are not used with the xHCI device.
+      </para>
+
+      <para>
+        The problem does not exist in earlier FreeBSD releases and was
+        fixed in FreeBSD 10.1.
+      </para>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="ts_win-hosts">
+
+    <title>Windows Hosts</title>
+
+    <sect2 id="ts_win-host-com-server">
+
+      <title>VBoxSVC Out-of-Process COM Server Issues</title>
+
+      <para>
+        VirtualBox makes use of the Microsoft Component Object Model
+        (COM) for inter-process and intra-process communication. This
+        allows VirtualBox to share a common configuration among
+        different virtual machine processes and provide several user
+        interface options based on a common architecture. All global
+        status information and configuration is maintained by the
+        process <computeroutput>VBoxSVC.exe</computeroutput>, which is
+        an out-of-process COM server. Whenever a VirtualBox process is
+        started, it requests access to the COM server and Windows
+        automatically starts the process. Note that it should never be
+        started by the end user.
+      </para>
+
+      <para>
+        When the last process disconnects from the COM server, it will
+        terminate itself after some seconds. The VirtualBox
+        configuration (XML files) is maintained and owned by the COM
+        server and the files are locked whenever the server runs.
+      </para>
+
+      <para>
+        In some cases, such as when a virtual machine is terminated
+        unexpectedly, the COM server will not notice that the client is
+        disconnected and stay active for a longer period of 10 minutes
+        or so, keeping the configuration files locked. In other rare
+        cases the COM server might experience an internal error and
+        subsequently other processes fail to initialize it. In these
+        situations, it is recommended to use the Windows task manager to
+        kill the process <computeroutput>VBoxSVC.exe</computeroutput>.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win-host-cd-dvd-changes">
+
+      <title>CD/DVD Changes Not Recognized</title>
+
+      <para>
+        In case you have assigned a physical CD/DVD drive to a guest and
+        the guest does not notice when the medium changes, make sure
+        that the Windows media change notification (MCN) feature is not
+        turned off. This is represented by the following key in the
+        Windows registry:
+
+<screen><literal>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Cdrom\Autorun</literal></screen>
+
+        Certain applications may disable this key against Microsoft's
+        advice. If it is set to 0, change it to 1 and reboot your
+        system. VirtualBox relies on Windows notifying it of media
+        changes.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win-host-rdp-client">
+
+      <title>Sluggish Response When Using Microsoft RDP Client</title>
+
+      <para>
+        If connecting to a Virtual Machine via the Microsoft RDP client,
+        called a Remote Desktop Connection, there can be large delays
+        between input such as moving the mouse over a menu and output.
+        This is because this RDP client collects input for a certain
+        time before sending it to the RDP server.
+      </para>
+
+      <para>
+        The interval can be decreased by setting a Windows registry key
+        to smaller values than the default of 100. The key does not
+        exist initially and must be of type DWORD. The unit for its
+        values is milliseconds. Values around 20 are suitable for
+        low-bandwidth connections between the RDP client and server.
+        Values around 4 can be used for a gigabit Ethernet connection.
+        Generally values below 10 achieve a performance that is very
+        close to that of the local input devices and screen of the host
+        on which the Virtual Machine is running.
+      </para>
+
+      <para>
+        Depending whether the setting should be changed for an
+        individual user or for the system, set either of the following.
+      </para>
+
+<screen>HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Min Send Interval</screen>
+
+<screen>HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client\Min Send Interval</screen>
+
+    </sect2>
+
+    <sect2 id="ts_win-host-iscsi">
+
+      <title>Running an iSCSI Initiator and Target on a Single System</title>
+
+      <para>
+        Deadlocks can occur on a Windows host when attempting to access
+        an iSCSI target running in a guest virtual machine with an iSCSI
+        initiator, such as a Microsoft iSCSI Initiator, that is running
+        on the host. This is caused by a flaw in the Windows cache
+        manager component, and causes sluggish host system response for
+        several minutes, followed by a "Delayed Write Failed" error
+        message in the system tray or in a separate message window. The
+        guest is blocked during that period and may show error messages
+        or become unstable.
+      </para>
+
+      <para>
+        Setting the environment variable
+        <computeroutput>VBOX_DISABLE_HOST_DISK_CACHE</computeroutput> to
+        1 will enable a workaround for this problem until Microsoft
+        addresses the issue. For example, open a command prompt window
+        and start VirtualBox like this:
+      </para>
+
+<screen>set VBOX_DISABLE_HOST_DISK_CACHE=1
+VirtualBox</screen>
+
+      <para>
+        While this will decrease guest disk performance, especially
+        writes, it does not affect the performance of other applications
+        running on the host.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_win-host-bridged-network-adapters">
+
+      <title>Bridged Networking Adapters Missing</title>
+
+      <para>
+        If no bridged adapters show up in the Networking section of the
+        VM settings, this typically means that the bridged networking
+        driver was not installed properly on your host. This could be
+        due to the following reasons:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            The maximum allowed filter count was reached on the host. In
+            this case, the MSI log would mention the
+            <computeroutput>0x8004a029</computeroutput> error code
+            returned on NetFlt network component install:
+
+<screen>VBoxNetCfgWinInstallComponent: Install failed, hr (0x8004a029)</screen>
+          </para>
+
+          <para>
+            You can try to increase the maximum filter count in the
+            Windows registry at the following key:
+
+<screen>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\MaxNumFilters</screen>
+
+            The maximum number allowed is 14. After a reboot, try to
+            reinstall VirtualBox.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            The INF cache is corrupt. In this case, the install log
+            (<computeroutput>%windir%\inf\setupapi.log</computeroutput>
+            on XP or
+            <computeroutput>%windir%\inf\setupapi.dev.log</computeroutput>
+            on Vista or later) would typically mention the failure to
+            find a suitable driver package for either the
+            <computeroutput>sun_VBoxNetFlt</computeroutput> or
+            <computeroutput>sun_VBoxNetFltmp</computeroutput>
+            components. The solution then is to uninstall VirtualBox,
+            remove the INF cache
+            (<computeroutput>%windir%\inf\INFCACHE.1</computeroutput>),
+            reboot and try to reinstall VirtualBox
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="ts_win-host-host-only-network-adapters">
+
+      <title>Host-only Networking Adapters Cannot be Created</title>
+
+      <para>
+        If host-only adapter cannot be created, either via the Manager
+        or VBoxManage, then the INF cache is probably corrupt. In this
+        case, the install log
+        (<computeroutput>%windir%\inf\setupapi.log</computeroutput> on
+        XP or
+        <computeroutput>%windir%\inf\setupapi.dev.log</computeroutput>
+        on Vista or later) would typically mention the failure to find a
+        suitable driver package for the
+        <computeroutput>sun_VBoxNetAdp</computeroutput> component.
+        Again, as with the bridged networking problem described above,
+        the solution is to uninstall VirtualBox, remove the INF cache
+        (<computeroutput>%windir%\inf\INFCACHE.1</computeroutput>),
+        reboot and try to reinstall VirtualBox.
+      </para>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="ts_lin-hosts">
+
+    <title>Linux Hosts</title>
+
+    <sect2 id="ts_linux-kernelmodule-fails-to-load">
+
+      <title>Linux Kernel Module Refuses to Load</title>
+
+      <para>
+        If the VirtualBox kernel module,
+        <computeroutput>vboxdrv</computeroutput>, refuses to load you
+        may see an "Error inserting vboxdrv: Invalid argument" message.
+        As root, check the output of the
+        <computeroutput>dmesg</computeroutput> command to find out why
+        the load failed. Most probably the kernel disagrees with the
+        version of <computeroutput>gcc</computeroutput> used to compile
+        the module. Make sure that you use the same compiler as used to
+        build the kernel.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_linux-host-cd-dvd-not-found">
+
+      <title>Linux Host CD/DVD Drive Not Found</title>
+
+      <para>
+        If you have configured a virtual machine to use the host's
+        CD/DVD drive, but this does not appear to work, make sure that
+        the current user has permission to access the corresponding
+        Linux device file. This is
+        <computeroutput>/dev/hdc</computeroutput>,
+        <computeroutput>/dev/scd0</computeroutput>,
+        <computeroutput>/dev/cdrom</computeroutput> or similar. On most
+        distributions, the user must be added to a corresponding group,
+        usually called <computeroutput>cdrom</computeroutput> or
+        <computeroutput>cdrw</computeroutput>.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_linux-host-cd-dvd-not-found-legacy">
+
+      <title>Linux Host CD/DVD Drive Not Found (Older Distributions)</title>
+
+      <para>
+        On older Linux distributions, if your CD/DVD device has a
+        different name, VirtualBox may be unable to find it. On older
+        Linux hosts, VirtualBox performs the following steps to locate
+        your CD/DVD drives:
+      </para>
+
+      <orderedlist>
+
+        <listitem>
+          <para>
+            VirtualBox checks if the environment variable
+            <computeroutput>VBOX_CDROM</computeroutput> is defined. If
+            so, VirtualBox omits all the following checks.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            VirtualBox tests if
+            <computeroutput>/dev/cdrom</computeroutput> works.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            VirtualBox checks if any CD/DVD drives are currently mounted
+            by checking <computeroutput>/etc/mtab</computeroutput>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            VirtualBox checks if any of the entries in
+            <computeroutput>/etc/fstab</computeroutput> point to CD/DVD
+            devices.
+          </para>
+        </listitem>
+
+      </orderedlist>
+
+      <para>
+        You can set the VBOX_CDROM environment variable to contain a
+        list of your CD/DVD devices, separated by colons. For example:
+      </para>
+
+<screen>export VBOX_CDROM='/dev/cdrom0:/dev/cdrom1'</screen>
+
+      <para>
+        On modern Linux distributions, VirtualBox uses the hardware
+        abstraction layer (HAL) to locate CD and DVD hardware.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_linux-host-floppy-not-found">
+
+      <title>Linux Host Floppy Not Found</title>
+
+      <para>
+        <xref linkend="ts_linux-host-cd-dvd-not-found-legacy"/> appplies
+        also to floppy disks, except that on older distributions
+        VirtualBox tests for <computeroutput>/dev/fd*</computeroutput>
+        devices by default. This can be overridden with the
+        <computeroutput>VBOX_FLOPPY</computeroutput> environment
+        variable.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_linux-host-ide-messages">
+
+      <title>Strange Guest IDE Error Messages When Writing to CD/DVD</title>
+
+      <para>
+        If the experimental CD/DVD writer support is enabled with an
+        incorrect VirtualBox, host or guest configuration, it is
+        possible that any attempt to access the CD/DVD writer fails and
+        simply results in guest kernel error messages for Linux guests
+        or application error messages for Windows guests. VirtualBox
+        performs the usual consistency checks when a VM is powered up.
+        In particular, it aborts with an error message if the device for
+        the CD/DVD writer is not writable by the user starting the VM.
+        But VirtualBox cannot detect all misconfigurations. The
+        necessary host and guest OS configuration is not specific for
+        VirtualBox, but a few frequent problems are listed here which
+        occurred in connection with VirtualBox.
+      </para>
+
+      <para>
+        Special care must be taken to use the correct device. The
+        configured host CD/DVD device file name, in most cases
+        <literal>/dev/cdrom</literal>, must point to the device that
+        allows writing to the CD/DVD unit. For CD/DVD writer units
+        connected to a SCSI controller or to a IDE controller that
+        interfaces to the Linux SCSI subsystem (common for some SATA
+        controllers), this must refer to the SCSI device node, such as
+        <literal>/dev/scd0</literal>. Even for IDE CD/DVD writer units
+        this must refer to the appropriate SCSI CD-ROM device node, such
+        as <literal>/dev/scd0</literal>, if the
+        <literal>ide-scsi</literal> kernel module is loaded. This module
+        is required for CD/DVD writer support with all Linux 2.4 kernels
+        and some early 2.6 kernels. Many Linux distributions load this
+        module whenever a CD/DVD writer is detected in the system, even
+        if the kernel would support CD/DVD writers without the module.
+        VirtualBox supports the use of IDE device files, such as
+        <literal>/dev/hdc</literal>, provided the kernel supports this
+        and the <literal>ide-scsi</literal> module is not loaded.
+      </para>
+
+      <para>
+        Similar rules, except that within the guest the CD/DVD writer is
+        always an IDE device, apply to the guest configuration. Since
+        this setup is very common, it is likely that the default
+        configuration of the guest works as expected.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_linux-host-vboxsvc">
+
+      <title>VBoxSVC IPC Issues</title>
+
+      <para>
+        On Linux, VirtualBox makes use of a custom version of Mozilla
+        XPCOM (cross platform component object model) for inter-process
+        and intra-process communication (IPC). The process
+        <computeroutput>VBoxSVC</computeroutput> serves as a
+        communication hub between different VirtualBox processes and
+        maintains the global configuration, such as the XML database.
+        When starting a VirtualBox component, the processes
+        <computeroutput>VBoxSVC</computeroutput> and
+        <computeroutput>VBoxXPCOMIPCD</computeroutput> are started
+        automatically. They are only accessible from the user account
+        they are running under. <computeroutput>VBoxSVC</computeroutput>
+        owns the VirtualBox configuration database which normally
+        resides in
+        <computeroutput>~/.config/VirtualBox</computeroutput>, or the
+        appropriate configuration directory for your operating system.
+        While it is running, the configuration files are locked.
+        Communication between the various VirtualBox components and
+        <computeroutput>VBoxSVC</computeroutput> is performed through a
+        local domain socket residing in
+        <computeroutput>/tmp/.vbox-&lt;username&gt;-ipc</computeroutput>.
+        In case there are communication problems, such as a VirtualBox
+        application cannot communicate with
+        <computeroutput>VBoxSVC</computeroutput>, terminate the daemons
+        and remove the local domain socket directory.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_usb-linux">
+
+      <title>USB Not Working</title>
+
+      <para>
+        If USB is not working on your Linux host, make sure that the
+        current user is a member of the
+        <computeroutput>vboxusers</computeroutput> group. Please keep in
+        mind that group membership does not take effect immediately but
+        rather at the next login. If available, the
+        <computeroutput>newgrp</computeroutput> command may avoid the
+        need for logout/login.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_linux-host-grsec">
+
+      <title>PAX/grsec Kernels</title>
+
+      <para>
+        Linux kernels including the grsec patch, see
+        <ulink
+      url="http://www.grsecurity.net/">http://www.grsecurity.net/</ulink>,
+        and derivates have to disable PAX_MPROTECT for the VBox binaries
+        to be able to start a VM. The reason is that VBox has to create
+        executable code on anonymous memory.
+      </para>
+
+    </sect2>
+
+    <sect2 id="ts_linux-host-malloc">
+
+      <title>Linux Kernel vmalloc Pool Exhausted</title>
+
+      <para>
+        When running a large number of VMs with a lot of RAM on a Linux
+        system, say 20 VMs with 1 GB of RAM each, additional VMs might
+        fail to start with a kernel error saying that the vmalloc pool
+        is exhausted and should be extended. The error message also
+        tells you to specify
+        <computeroutput>vmalloc=256MB</computeroutput> in your kernel
+        parameter list. If adding this parameter to your GRUB or LILO
+        configuration makes the kernel fail to boot, with an error
+        message such as "failed to mount the root partition", then you
+        have probably run into a memory conflict of your kernel and
+        initial RAM disk. This can be solved by adding the following
+        parameter to your GRUB configuration:
+      </para>
+
+<screen>uppermem 524288</screen>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="ts_sol-hosts">
+
+    <title>Solaris Hosts</title>
+
+    <sect2 id="ts_sol-host-zfs">
+
+      <title>Cannot Start VM, Not Enough Contiguous Memory</title>
+
+      <para>
+        The ZFS file system is known to use nearly all available RAM as
+        cache if the default system settings are not changed. This may
+        lead to a heavy fragmentation of the host memory preventing
+        VirtualBox VMs from being started. We recommend to limit the ZFS
+        cache by adding the following line to /etc/system, where
+        <computeroutput>xxxx</computeroutput> bytes is the amount of
+        memory usable for the ZFS cache.
+      </para>
+
+<screen>set zfs:zfs_arc_max = xxxx</screen>
+
+    </sect2>
+
+    <sect2 id="ts_sol-host-swap-space">
+
+      <title>VM Aborts With Out of Memory Errors on Solaris 10 Hosts</title>
+
+      <para>
+        32-bit Solaris 10 hosts (bug 1225025) require swap space equal
+        to, or greater than the host's physical memory size. For
+        example, 8 GB physical memory would require at least 8 GB swap.
+        This can be configured during a Solaris 10 install by choosing a
+        Custom Install and changing the default partitions.
+      </para>
+
+      <note>
         <para>
-            If xHCI (USB 3.0) emulation is enabled for FreeBSD 10.0 guests, the guest
-            OS will hang. This is caused by the guest OS incorrectly handling systems
-            where MSIs (Message Signaled Interrupts) are not used with the xHCI device.
+          This restriction applies only to 32-bit Solaris hosts, 64-bit
+          hosts are not affected.
         </para>
-        <para>
-            The problem does not exist in earlier FreeBSD releases and was fixed in
-            FreeBSD 10.1.
-        </para>
-    </sect2>
+      </note>
+
+      <para>
+        For existing Solaris 10 installs, an additional swap image needs
+        to be mounted and used as swap. Hence if you have 1 GB swap and
+        8 GB of physical memory, you require to add 7 GB more swap. This
+        can be done as follows:
+      </para>
+
+      <para>
+        For ZFS, run the following as root user:
+      </para>
+
+<screen>zfs create -V 8gb /_&lt;ZFS volume&gt;_/swap
+swap -a /dev/zvol/dsk/_&lt;ZFS volume&gt;_/swap</screen>
+
+      <para>
+        To mount if after reboot, add the following line to /etc/vfstab:
+      </para>
+
+<screen>/dev/zvol/dsk/_&lt;ZFS volume&gt;_/swap - - swap - no -</screen>
+
+      <para>
+        Alternatively, you could grow the existing swap using:
+      </para>
+
+<screen>zfs set volsize=8G rpool/swap</screen>
+
+      <para>
+        And reboot the system for the changes to take effect.
+      </para>
+
+      <para>
+        For UFS (as root user):
+      </para>
+
+<screen>mkfile 7g /path/to/swapfile.img
+swap -a /path/to/swapfile.img</screen>
+
+      <para>
+        To mount it after reboot, add the following line to /etc/vfstab:
+      </para>
+
+<screen>/path/to/swap.img - - swap - no -</screen>
+
+    </sect2>
+
   </sect1>
 
-  <sect1 id="ts_win-hosts">
-    <title>Windows hosts</title>
-
-    <sect2>
-      <title>VBoxSVC out-of-process COM server issues</title>
-
-      <para>VirtualBox makes use of the Microsoft Component Object Model (COM)
-      for inter- and intra-process communication. This allows VirtualBox to
-      share a common configuration among different virtual machine processes
-      and provide several user interface options based on a common
-      architecture. All global status information and configuration is
-      maintained by the process <computeroutput>VBoxSVC.exe</computeroutput>,
-      which is an out-of-process COM server. Whenever a VirtualBox process is
-      started, it requests access to the COM server and Windows automatically
-      starts the process. Note that it should never be started by the end
-      user.</para>
-
-      <para>When the last process disconnects from the COM server, it will
-      terminate itself after some seconds. The VirtualBox configuration (XML
-      files) is maintained and owned by the COM server and the files are
-      locked whenever the server runs.</para>
-
-      <para>In some cases - such as when a virtual machine is terminated
-      unexpectedly - the COM server will not notice that the client is
-      disconnected and stay active for a longer period (10 minutes or so)
-      keeping the configuration files locked. In other rare cases the COM
-      server might experience an internal error and subsequently other
-      processes fail to initialize it. In these situations, it is recommended
-      to use the Windows task manager to kill the process
-      <computeroutput>VBoxSVC.exe</computeroutput>.</para>
-    </sect2>
-
-    <sect2>
-      <title>CD/DVD changes not recognized</title>
-
-      <para>In case you have assigned a physical CD/DVD drive to a guest and
-      the guest does not notice when the medium changes, make sure that the
-      Windows media change notification (MCN) feature is not turned off. This
-      is represented by the following key in the Windows registry:<screen><literal>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Cdrom\Autorun</literal></screen>Certain
-      applications may disable this key against Microsoft's advice. If it is
-      set to 0, change it to 1 and reboot your system. VirtualBox relies on
-      Windows notifying it of media changes.</para>
-    </sect2>
-
-    <sect2>
-      <title>Sluggish response when using Microsoft RDP client</title>
-
-      <para>If connecting to a Virtual Machine via the Microsoft RDP client
-      (called Remote Desktop Connection), there can be large delays between
-      input (moving the mouse over a menu is the most obvious situation) and
-      output. This is because this RDP client collects input for a certain
-      time before sending it to the RDP server.</para>
-
-      <para>The interval can be decreased by setting a Windows registry key to
-      smaller values than the default of 100. The key does not exist initially
-      and must be of type DWORD. The unit for its values is milliseconds.
-      Values around 20 are suitable for low-bandwidth connections between the
-      RDP client and server. Values around 4 can be used for a gigabit
-      Ethernet connection. Generally values below 10 achieve a performance
-      that is very close to that of the local input devices and screen of the
-      host on which the Virtual Machine is running.</para>
-
-      <para>Depending whether the setting should be changed for an individual
-      user or for the system, either</para>
-
-      <screen>HKEY_CURRENT_USER\Software\Microsoft\Terminal Server Client\Min Send Interval</screen>
-
-      <para>or</para>
-
-      <screen>HKEY_LOCAL_MACHINE\Software\Microsoft\Terminal Server Client\Min Send Interval</screen>
-
-      <para>can be set appropriately.</para>
-    </sect2>
-
-    <sect2>
-      <title>Running an iSCSI initiator and target on a single system</title>
-
-      <para>Deadlocks can occur on a Windows host when attempting to access an
-      iSCSI target running in a guest virtual machine with an iSCSI initiator
-      (e.g. Microsoft iSCSI Initiator) that is running on the host. This is
-      caused by a flaw in the Windows cache manager component, and causes
-      sluggish host system response for several minutes, followed by a
-      "Delayed Write Failed" error message in the system tray or in a separate
-      message window. The guest is blocked during that period and may show
-      error messages or become unstable.</para>
-
-      <para>Setting the environment variable
-      <computeroutput>VBOX_DISABLE_HOST_DISK_CACHE</computeroutput> to 1 will
-      enable a workaround for this problem until Microsoft addresses the
-      issue. For example, open a command prompt window and start VirtualBox
-      like this:</para>
-
-      <screen>set VBOX_DISABLE_HOST_DISK_CACHE=1
-VirtualBox</screen>
-
-      <para>While this will decrease guest disk performance (especially
-      writes), it does not affect the performance of other applications
-      running on the host.</para>
-    </sect2>
-
-    <sect2>
-      <title>Bridged networking adapters missing</title>
-
-      <para>If no bridged adapters show up in the "Networking" section of the
-      VM settings, this typically means that the bridged networking driver was
-      not installed properly on your host. This could be due to the following
-      reasons: <itemizedlist>
-          <listitem>
-            <para>The maximum allowed filter count was reached on the host. In
-            this case, the MSI log would mention the
-            <computeroutput>0x8004a029</computeroutput> error code returned on
-            NetFlt network component install:<screen>VBoxNetCfgWinInstallComponent: Install failed, hr (0x8004a029)</screen></para>
-
-            <para>You can try to increase the maximum filter count in the
-            Windows registry at the following key:<screen>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Network\MaxNumFilters</screen>The
-            maximum number allowed is 14. After a reboot, try to re-install
-            VirtualBox.</para>
-          </listitem>
-
-          <listitem>
-            <para>The INF cache is corrupt. In this case, the install log
-            (<computeroutput>%windir%\inf\setupapi.log</computeroutput> on XP
-            or <computeroutput>%windir%\inf\setupapi.dev.log</computeroutput>
-            on Vista or later) would typically mention the failure to find a
-            suitable driver package for either the
-            <computeroutput>sun_VBoxNetFlt</computeroutput> or
-            <computeroutput>sun_VBoxNetFltmp</computeroutput> components. The
-            solution then is to uninstall VirtualBox, remove the INF cache
-            (<computeroutput>%windir%\inf\INFCACHE.1</computeroutput>), reboot
-            and try to re-install VirtualBox</para>
-          </listitem>
-        </itemizedlist></para>
-    </sect2>
-
-    <sect2>
-      <title>Host-only networking adapters cannot be created</title>
-
-      <para>If host-only adapter cannot be created (either via the Manager or
-      VBoxManage), then the INF cache is probably corrupt. In this case, the
-      install log (<computeroutput>%windir%\inf\setupapi.log</computeroutput>
-      on XP or <computeroutput>%windir%\inf\setupapi.dev.log</computeroutput>
-      on Vista or later) would typically mention the failure to find a
-      suitable driver package for the
-      <computeroutput>sun_VBoxNetAdp</computeroutput> component. Again, as
-      with the bridged networking problem described above, the solution is to
-      uninstall VirtualBox, remove the INF cache
-      (<computeroutput>%windir%\inf\INFCACHE.1</computeroutput>), reboot and
-      try to re-install VirtualBox.</para>
-    </sect2>
-  </sect1>
-
-  <sect1 id="ts_lin-hosts">
-    <title>Linux hosts</title>
-
-    <sect2 id="ts_linux-kernelmodule-fails-to-load">
-      <title>Linux kernel module refuses to load</title>
-
-      <para>If the VirtualBox kernel module
-      (<computeroutput>vboxdrv</computeroutput>) refuses to load, i.e. you get
-      an "Error inserting vboxdrv: Invalid argument", check (as root) the
-      output of the <computeroutput>dmesg</computeroutput> command to find out
-      why the load failed. Most probably the kernel disagrees with the version
-      of the gcc used to compile the module. Make sure that you use the same
-      compiler as used to build the kernel.</para>
-    </sect2>
-
-    <sect2>
-      <title>Linux host CD/DVD drive not found</title>
-
-      <para>If you have configured a virtual machine to use the host's CD/DVD
-      drive, but this does not appear to work, make sure that the current user
-      has permission to access the corresponding Linux device file
-      (<computeroutput>/dev/hdc</computeroutput> or
-      <computeroutput>/dev/scd0</computeroutput> or
-      <computeroutput>/dev/cdrom</computeroutput> or similar). On most
-      distributions, the user must be added to a corresponding group (usually
-      called <computeroutput>cdrom</computeroutput> or
-      <computeroutput>cdrw</computeroutput>).</para>
-    </sect2>
-
-    <sect2>
-      <title>Linux host CD/DVD drive not found (older distributions)</title>
-
-      <para>On older Linux distributions, if your CD/DVD device has a
-      different name, VirtualBox may be unable to find it. On older Linux
-      hosts, VirtualBox performs the following steps to locate your CD/DVD
-      drives:</para>
-
-      <para><orderedlist>
-          <listitem>
-            <para>VirtualBox examines if the environment variable
-            <computeroutput>VBOX_CDROM</computeroutput> is defined (see
-            below). If so, VirtualBox omits all the following checks.</para>
-          </listitem>
-
-          <listitem>
-            <para>VirtualBox tests if
-            <computeroutput>/dev/cdrom</computeroutput> works.</para>
-          </listitem>
-
-          <listitem>
-            <para>In addition, VirtualBox checks if any CD/DVD drives are
-            currently mounted by checking
-            <computeroutput>/etc/mtab</computeroutput>.</para>
-          </listitem>
-
-          <listitem>
-            <para>In addition, VirtualBox checks if any of the entries in
-            <computeroutput>/etc/fstab</computeroutput> point to CD/DVD
-            devices.</para>
-          </listitem>
-        </orderedlist></para>
-
-      <para>In other words, you can try to set VBOX_CDROM to contain a list of
-      your CD/DVD devices, separated by colons, for example as follows:</para>
-
-      <para><screen>export VBOX_CDROM='/dev/cdrom0:/dev/cdrom1'</screen>On
-      modern Linux distributions, VirtualBox uses the hardware abstraction
-      layer (hal) to locate CD and DVD hardware.</para>
-    </sect2>
-
-    <sect2>
-      <title>Linux host floppy not found</title>
-
-      <para>The previous instructions (for CD and DVD drives) apply
-      accordingly to floppy disks, except that on older distributions
-      VirtualBox tests for <computeroutput>/dev/fd*</computeroutput> devices
-      by default, and this can be overridden with the
-      <computeroutput>VBOX_FLOPPY</computeroutput> environment
-      variable.</para>
-    </sect2>
-
-    <sect2>
-      <title>Strange guest IDE error messages when writing to CD/DVD</title>
-
-      <para>If the experimental CD/DVD writer support is enabled with an
-      incorrect VirtualBox, host or guest configuration, it is possible that
-      any attempt to access the CD/DVD writer fails and simply results in
-      guest kernel error messages (for Linux guests) or application error
-      messages (for Windows guests). VirtualBox performs the usual consistency
-      checks when a VM is powered up (in particular it aborts with an error
-      message if the device for the CD/DVD writer is not writable by the user
-      starting the VM), but it cannot detect all misconfigurations. The
-      necessary host and guest OS configuration is not specific for
-      VirtualBox, but a few frequent problems are listed here which occurred
-      in connection with VirtualBox.</para>
-
-      <para>Special care must be taken to use the correct device. The
-      configured host CD/DVD device file name (in most cases
-      <literal>/dev/cdrom</literal>) must point to the device that allows
-      writing to the CD/DVD unit. For CD/DVD writer units connected to a SCSI
-      controller or to a IDE controller that interfaces to the Linux SCSI
-      subsystem (common for some SATA controllers), this must refer to the
-      SCSI device node (e.g. <literal>/dev/scd0</literal>). Even for IDE
-      CD/DVD writer units this must refer to the appropriate SCSI CD-ROM
-      device node (e.g. <literal>/dev/scd0</literal>) if the
-      <literal>ide-scsi</literal> kernel module is loaded. This module is
-      required for CD/DVD writer support with all Linux 2.4 kernels and some
-      early 2.6 kernels. Many Linux distributions load this module whenever a
-      CD/DVD writer is detected in the system, even if the kernel would
-      support CD/DVD writers without the module. VirtualBox supports the use
-      of IDE device files (e.g. <literal>/dev/hdc</literal>), provided the
-      kernel supports this and the <literal>ide-scsi</literal> module is not
-      loaded.</para>
-
-      <para>Similar rules (except that within the guest the CD/DVD writer is
-      always an IDE device) apply to the guest configuration. Since this setup
-      is very common, it is likely that the default configuration of the guest
-      works as expected.</para>
-    </sect2>
-
-    <sect2>
-      <title>VBoxSVC IPC issues</title>
-
-      <para>On Linux, VirtualBox makes use of a custom version of Mozilla
-      XPCOM (cross platform component object model) for inter- and
-      intra-process communication (IPC). The process
-      <computeroutput>VBoxSVC</computeroutput> serves as a communication hub
-      between different VirtualBox processes and maintains the global
-      configuration, i.e. the XML database. When starting a VirtualBox
-      component, the processes <computeroutput>VBoxSVC</computeroutput> and
-      <computeroutput>VBoxXPCOMIPCD</computeroutput> are started
-      automatically. They are only accessible from the user account they are
-      running under. <computeroutput>VBoxSVC</computeroutput> owns the
-      VirtualBox configuration database which normally resides in
-      <computeroutput>~/.config/VirtualBox</computeroutput>, or the appropriate configuration directory for your operating system. While it is running, the
-      configuration files are locked. Communication between the various
-      VirtualBox components and <computeroutput>VBoxSVC</computeroutput> is
-      performed through a local domain socket residing in
-      <computeroutput>/tmp/.vbox-&lt;username&gt;-ipc</computeroutput>. In
-      case there are communication problems (i.e. a VirtualBox application
-      cannot communicate with <computeroutput>VBoxSVC</computeroutput>),
-      terminate the daemons and remove the local domain socket
-      directory.</para>
-    </sect2>
-
-    <sect2 id="ts_usb-linux">
-      <title>USB not working</title>
-
-      <para>If USB is not working on your Linux host, make sure that the
-      current user is a member of the
-      <computeroutput>vboxusers</computeroutput> group.
-      Please keep in mind that group membership does not take effect immediately
-      but rather at the next login. If available, the
-      <computeroutput>newgrp</computeroutput> command may avoid the need for
-      logout/login.</para>
-    </sect2>
-
-    <sect2>
-      <title>PAX/grsec kernels</title>
-
-      <para>Linux kernels including the grsec patch (see <literal><ulink
-      url="http://www.grsecurity.net/">http://www.grsecurity.net/</ulink></literal>)
-      and derivates have to disable PAX_MPROTECT for the VBox binaries to be
-      able to start a VM. The reason is that VBox has to create executable
-      code on anonymous memory.</para>
-    </sect2>
-
-    <sect2>
-      <title>Linux kernel vmalloc pool exhausted</title>
-
-      <para>When running a large number of VMs with a lot of RAM on a Linux
-      system (say 20 VMs with 1 GB of RAM each), additional VMs might fail to
-      start with a kernel error saying that the vmalloc pool is exhausted and
-      should be extended. The error message also tells you to specify
-      <computeroutput>vmalloc=256MB</computeroutput> in your kernel parameter
-      list. If adding this parameter to your GRUB or LILO configuration makes
-      the kernel fail to boot (with a weird error message such as "failed to
-      mount the root partition"), then you have probably run into a memory
-      conflict of your kernel and initial RAM disk. This can be solved by
-      adding the following parameter to your GRUB configuration:</para>
-
-      <screen>uppermem 524288</screen>
-    </sect2>
-  </sect1>
-
-  <sect1 id="ts_sol-hosts">
-    <title>Solaris hosts</title>
-
-    <sect2>
-      <title>Cannot start VM, not enough contiguous memory</title>
-
-      <para>The ZFS file system is known to use nearly all available RAM as cache if
-      the default system settings are not changed. This may lead to a heavy
-      fragmentation of the host memory preventing VirtualBox VMs from being
-      started. We recommend to limit the ZFS cache by adding a line<screen>set zfs:zfs_arc_max = xxxx</screen>
-      to /etc/system where <computeroutput>xxxx</computeroutput> bytes is the
-      amount of memory usable for the ZFS cache.</para>
-    </sect2>
-
-    <sect2>
-      <title>VM aborts with out of memory errors on Solaris 10 hosts</title>
-
-      <para>32-bit Solaris 10 hosts (bug 1225025) require swap space equal to,
-      or greater than the host's physical memory size. For example, 8 GB
-      physical memory would require at least 8 GB swap. This can be configured
-      during a Solaris 10 install by choosing a 'custom install' and changing
-      the default partitions.</para>
-
-      <note>
-        <para>This restriction applies only to 32-bit Solaris hosts, 64-bit
-        hosts are not affected!</para>
-      </note>
-
-      <para>For existing Solaris 10 installs, an additional swap image needs
-      to be mounted and used as swap. Hence if you have 1 GB swap and 8 GB of
-      physical memory, you require to add 7 GB more swap. This can be done as
-      follows:</para>
-
-      <para>For ZFS (as root user):</para>
-
-      <para><screen>zfs create -V 8gb /_&lt;ZFS volume&gt;_/swap
-swap -a /dev/zvol/dsk/_&lt;ZFS volume&gt;_/swap</screen></para>
-
-      <para>To mount if after reboot, add the following line to
-      /etc/vfstab:</para>
-
-      <screen>/dev/zvol/dsk/_&lt;ZFS volume&gt;_/swap - - swap - no -</screen>
-
-      <para>Alternatively, you could grow the existing swap using:</para>
-
-      <screen>zfs set volsize=8G rpool/swap</screen>
-
-      <para>And reboot the system for the changes to take effect.</para>
-
-      <para>For UFS (as root user):</para>
-
-      <screen>mkfile 7g /path/to/swapfile.img
-swap -a /path/to/swapfile.img</screen>
-
-      <para>To mount it after reboot, add the following line to
-      /etc/vfstab:</para>
-
-      <screen>/path/to/swap.img - - swap - no -</screen>
-    </sect2>
-  </sect1>
 </chapter>
Index: /trunk/doc/manual/en_US/user_VBoxManage.xml
===================================================================
--- /trunk/doc/manual/en_US/user_VBoxManage.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_VBoxManage.xml	(revision 73276)
@@ -17,84 +17,134 @@
     hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
  -->
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="vboxmanage">
+
   <title>VBoxManage</title>
 
-  <sect1>
+  <sect1 id="vboxmanage-intro">
+
     <title>Introduction</title>
 
-    <para>As briefly mentioned in <xref linkend="frontends" />, VBoxManage is
-    the command-line interface to VirtualBox. With it, you can completely
-    control VirtualBox from the command line of your host operating system.
-    VBoxManage supports all the features that the graphical user interface
-    gives you access to, but it supports a lot more than that. It exposes
-    really all the features of the virtualization engine, even those that
-    cannot (yet) be accessed from the GUI.</para>
-
-    <para>You will need to use the command line if you want to</para>
-
-    <para><itemizedlist>
-        <listitem>
-          <para>use a different user interface than the main GUI (for example,
-          VBoxSDL or the VBoxHeadless server);</para>
-        </listitem>
-
-        <listitem>
-          <para>control some of the more advanced and experimental
-          configuration settings for a VM.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>There are two main things to keep in mind when using
-    <computeroutput>VBoxManage</computeroutput>: First,
-    <computeroutput>VBoxManage</computeroutput> must always be used with a
-    specific "subcommand", such as "list" or "createvm" or "startvm". All the
-    subcommands that <computeroutput>VBoxManage</computeroutput> supports are
-    described in detail in <xref linkend="vboxmanage" />.</para>
-
-    <para>Second, most of these subcommands require that you specify a
-    particular virtual machine after the subcommand. There are two ways you
-    can do this:</para>
+    <para>
+      As briefly mentioned in <xref linkend="frontends" />, VBoxManage
+      is the command-line interface to VirtualBox. With it, you can
+      completely control VirtualBox from the command line of your host
+      operating system. VBoxManage supports all the features that the
+      graphical user interface gives you access to, but it supports a
+      lot more than that. It exposes really all the features of the
+      virtualization engine, even those that cannot (yet) be accessed
+      from the GUI.
+    </para>
+
+    <para>
+      You will need to use the command line if you want to do the
+      following:
+    </para>
 
     <itemizedlist>
-      <listitem>
-        <para>You can specify the VM name, as it is shown in the VirtualBox
-        GUI. Note that if that name contains spaces, then you must enclose the
-        entire name in double quotes (as it is always required with command
-        line arguments that contain spaces).</para>
-
-        <para>For example:<screen>VBoxManage startvm "Windows XP"</screen></para>
-      </listitem>
-
-      <listitem>
-        <para>You can specify the UUID, which is the internal unique
-        identifier that VirtualBox uses to refer to the virtual machine.
-        Assuming that the aforementioned VM called "Windows XP" has the UUID
-        shown below, the following command has the same effect as the
-        previous:<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen></para>
-      </listitem>
+
+      <listitem>
+        <para>
+          Use a different user interface than the main GUI. For example,
+          VBoxSDL or the VBoxHeadless server.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Control some of the more advanced and experimental
+          configuration settings for a VM.
+        </para>
+      </listitem>
+
     </itemizedlist>
 
-    <para>You can type <computeroutput>VBoxManage list vms</computeroutput> to
-    have all currently registered VMs listed with all their settings,
-    including their respective names and UUIDs.</para>
-
-    <para>Some typical examples of how to control VirtualBox from the command
-    line are listed below:</para>
+    <para>
+      There are two main things to keep in mind when using
+      <computeroutput>VBoxManage</computeroutput>: First,
+      <computeroutput>VBoxManage</computeroutput> must always be used
+      with a specific "subcommand", such as "list" or "createvm" or
+      "startvm". All the subcommands that
+      <computeroutput>VBoxManage</computeroutput> supports are described
+      in detail in <xref linkend="vboxmanage" />.
+    </para>
+
+    <para>
+      Second, most of these subcommands require that you specify a
+      particular virtual machine after the subcommand. There are two
+      ways you can do this:
+    </para>
 
     <itemizedlist>
-      <listitem>
-        <para>To create a new virtual machine from the command line and
-        immediately register it with VirtualBox, use
-        <computeroutput>VBoxManage createvm</computeroutput> with the
-        <computeroutput>--register</computeroutput> option,<footnote>
-            <para>For details, see <xref
-            linkend="vboxmanage-createvm" />.</para>
-          </footnote> like this:</para>
-
-        <screen>$ VBoxManage createvm --name "SUSE 10.2" --register
-VirtualBox Command Line Management Interface Version @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@
-(C) 2005-@VBOX_C_YEAR@ @VBOX_VENDOR@
+
+      <listitem>
+        <para>
+          You can specify the VM name, as it is shown in the VirtualBox
+          GUI. Note that if that name contains spaces, then you must
+          enclose the entire name in double quotes (as it is always
+          required with command line arguments that contain spaces).
+        </para>
+
+        <para>
+          For example:
+
+<screen>VBoxManage startvm "Windows XP"</screen>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          You can specify the UUID, which is the internal unique
+          identifier that VirtualBox uses to refer to the virtual
+          machine. Assuming that the aforementioned VM called "Windows
+          XP" has the UUID shown below, the following command has the
+          same effect as the previous:
+
+<screen>VBoxManage startvm 670e746d-abea-4ba6-ad02-2a3b043810a5</screen>
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      You can type <computeroutput>VBoxManage list vms</computeroutput>
+      to have all currently registered VMs listed with all their
+      settings, including their respective names and UUIDs.
+    </para>
+
+    <para>
+      Some typical examples of how to control VirtualBox from the
+      command line are listed below:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          To create a new virtual machine from the command line and
+          immediately register it with VirtualBox, use
+          <computeroutput>VBoxManage createvm</computeroutput> with the
+          <computeroutput>--register</computeroutput> option,
+
+          <footnote>
+
+            <para>
+              For details, see
+              <xref
+            linkend="vboxmanage-createvm" />.
+            </para>
+
+          </footnote>
+
+          like this:
+        </para>
+
+<screen>$ VBoxManage createvm --name "SUSE 10.2" --register
+VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
+(C) 2005-2018 Oracle Corporation
 All rights reserved.
 
@@ -103,250 +153,358 @@
 Settings file: '/home/username/.config/VirtualBox/Machines/SUSE 10.2/SUSE 10.2.xml'</screen>
 
-        <para>As can be seen from the above output, a new virtual machine has
-        been created with a new UUID and a new XML settings file.</para>
-      </listitem>
-
-      <listitem>
-        <para>To show the configuration of a particular VM, use
-        <computeroutput>VBoxManage showvminfo</computeroutput>; see <xref
-        linkend="vboxmanage-showvminfo" /> for details and an example.</para>
-      </listitem>
-
-      <listitem>
-        <para>To change settings while a VM is powered off, use
-        <computeroutput>VBoxManage modifyvm</computeroutput>, e.g. as
-        follows:<screen>VBoxManage modifyvm "Windows XP" --memory 512</screen></para>
-
-        <para>For details, see <xref linkend="vboxmanage-modifyvm" />.</para>
-      </listitem>
-
-      <listitem>
-        <para>To change the storage configuration (e.g. to add a storage
-        controller and then a virtual disk), use <computeroutput>VBoxManage
-        storagectl</computeroutput> and <computeroutput>VBoxManage
-        storageattach</computeroutput>; see <xref
-        linkend="vboxmanage-storagectl" /> and <xref
-        linkend="vboxmanage-storageattach" /> for details.</para>
-      </listitem>
-
-      <listitem>
-        <para>To control VM operation, use one of the following:<itemizedlist>
-            <listitem>
-              <para>To start a VM that is currently powered off, use
-              <computeroutput>VBoxManage startvm</computeroutput>; see <xref
-              linkend="vboxmanage-startvm" /> for details.</para>
-            </listitem>
-
-            <listitem>
-              <para>To pause or save a VM that is currently running or change
+        <para>
+          As can be seen from the above output, a new virtual machine
+          has been created with a new UUID and a new XML settings file.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          To show the configuration of a particular VM, use
+          <computeroutput>VBoxManage showvminfo</computeroutput>. See
+          <xref
+        linkend="vboxmanage-showvminfo" /> for details
+          and an example.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          To change settings while a VM is powered off, use
+          <computeroutput>VBoxManage modifyvm</computeroutput>. For
+          example:
+
+<screen>VBoxManage modifyvm "Windows XP" --memory 512</screen>
+        </para>
+
+        <para>
+          For details, see <xref linkend="vboxmanage-modifyvm" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          To change the storage configuration (e.g. to add a storage
+          controller and then a virtual disk), use
+          <computeroutput>VBoxManage storagectl</computeroutput> and
+          <computeroutput>VBoxManage storageattach</computeroutput>. See
+          <xref
+        linkend="vboxmanage-storagectl" /> and
+          <xref
+        linkend="vboxmanage-storageattach" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          To control VM operation, use one of the following:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              To start a VM that is currently powered off, use
+              <computeroutput>VBoxManage startvm</computeroutput>. See
+              <xref
+              linkend="vboxmanage-startvm" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              To pause or save a VM that is currently running or change
               some of its settings, use <computeroutput>VBoxManage
-              controlvm</computeroutput>; see <xref
-              linkend="vboxmanage-controlvm" /> for details.</para>
-            </listitem>
-          </itemizedlist></para>
-      </listitem>
+              controlvm</computeroutput>. See
+              <xref
+              linkend="vboxmanage-controlvm" />.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
     </itemizedlist>
+
   </sect1>
 
-  <sect1>
-    <title>Commands overview</title>
-
-    <para>When running VBoxManage without parameters or when supplying an
-    invalid command line, the below syntax diagram will be shown. Note that
-    the output will be slightly different depending on the host platform; when
-    in doubt, check the output of <computeroutput>VBoxManage</computeroutput>
-    for the commands available on your particular host.</para>
-
-    <xi:include href="../user_VBoxManage_CommandsOverview.xml" xpointer="xpointer(/sect1/*)"
+  <sect1 id="vboxmanage-cmd-overview">
+
+    <title>Commands Overview</title>
+
+    <para>
+      When running VBoxManage without parameters or when supplying an
+      invalid command line, the below syntax diagram will be shown. Note
+      that the output will be slightly different depending on the host
+      platform; when in doubt, check the output of
+      <computeroutput>VBoxManage</computeroutput> for the commands
+      available on your particular host.
+    </para>
+
+    <xi:include href="user_VBoxManage_CommandsOverview.xml" xpointer="xpointer(/sect1/*)"
       xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-    <para>Each time VBoxManage is invoked, only one command can be executed.
-    However, a command might support several subcommands which then can be
-    invoked in one single call. The following sections provide detailed
-    reference information on the different commands.</para>
+    <para>
+      Each time VBoxManage is invoked, only one command can be executed.
+      However, a command might support several subcommands which then
+      can be invoked in one single call. The following sections provide
+      detailed reference information on the different commands.
+    </para>
+
   </sect1>
 
   <sect1 id="vboxmanage-general">
-    <title>General options</title>
-    <para>
-      <itemizedlist>
-        <listitem>
-          <para><computeroutput>-v|--version</computeroutput>: show the version of
-            this tool and exit.</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--nologo</computeroutput>: suppress the output
-            of the logo information (useful for scripts)</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--settingspw</computeroutput>: specifiy a settings
-            password</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--settingspwfile</computeroutput>: specify a file
-            containing the settings password.</para>
-        </listitem>
-      </itemizedlist>
-      The settings password is used for certain settings which need to be
-      stored encrypted for security reasons. At the moment, the only encrypted
-      setting is the iSCSI initiator secret (see
-      <xref linkend="vboxmanage-storageattach" /> for details). As long as no
-      settings password is specified, this information is stored in
-      <emphasis role="bold">plain text</emphasis>. After using the
-      <computeroutput>--settingspw|--settingspwfile</computeroutput> option
-      once, it must be always used, otherwise the encrypted setting cannot
-      be unencrypted.
-    </para>
+
+    <title>General Options</title>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <computeroutput>-v|--version</computeroutput>: show the
+          version of this tool and exit.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--nologo</computeroutput>: suppress the output
+          of the logo information (useful for scripts)
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--settingspw</computeroutput>: specifiy a
+          settings password
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--settingspwfile</computeroutput>: specify a
+          file containing the settings password.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      The settings password is used for certain settings which need to
+      be stored encrypted for security reasons. At the moment, the only
+      encrypted setting is the iSCSI initiator secret (see
+      <xref linkend="vboxmanage-storageattach" /> for details). As long
+      as no settings password is specified, this information is stored
+      in <emphasis role="bold">plain text</emphasis>. After using the
+      <computeroutput>--settingspw|--settingspwfile</computeroutput>
+      option once, it must be always used, otherwise the encrypted
+      setting cannot be unencrypted.
+    </para>
+
   </sect1>
 
   <sect1 id="vboxmanage-list">
+
     <title>VBoxManage list</title>
 
-    <para>The <computeroutput>list</computeroutput> command gives relevant
-    information about your system and information about VirtualBox's current
-    settings.</para>
-
-    <para>The following subcommands are available with
-    <computeroutput>VBoxManage list</computeroutput>: <itemizedlist>
-        <listitem>
-          <para><computeroutput>vms</computeroutput> lists all virtual
+    <para>
+      The <computeroutput>list</computeroutput> command gives relevant
+      information about your system and information about VirtualBox's
+      current settings.
+    </para>
+
+    <para>
+      The following subcommands are available with
+      <computeroutput>VBoxManage list</computeroutput>:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <computeroutput>vms</computeroutput> lists all virtual
           machines currently registered with VirtualBox. By default this
-          displays a compact list with each VM's name and UUID; if you also
-          specify <computeroutput>--long</computeroutput> or
-          <computeroutput>-l</computeroutput>, this will be a detailed list as
-          with the <computeroutput>showvminfo</computeroutput> command (see
-          below).</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>runningvms</computeroutput> lists all
+          displays a compact list with each VM's name and UUID; if you
+          also specify <computeroutput>--long</computeroutput> or
+          <computeroutput>-l</computeroutput>, this will be a detailed
+          list as with the <computeroutput>showvminfo</computeroutput>
+          command (see below).
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>runningvms</computeroutput> lists all
           currently running virtual machines by their unique identifiers
           (UUIDs) in the same format as with
-          <computeroutput>vms</computeroutput>.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>ostypes</computeroutput> lists all guest
-          operating systems presently known to VirtualBox, along with the
-          identifiers used to refer to them with the
-          <computeroutput>modifyvm</computeroutput> command.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>hostdvds</computeroutput>,
-          <computeroutput>hostfloppies</computeroutput>, respectively, list
-          DVD, floppy, bridged networking and host-only networking interfaces
-          on the host, along with the name used to access them from within
-          VirtualBox.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>intnets</computeroutput> displays information
-          about the internal networks.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>bridgedifs</computeroutput>,
+          <computeroutput>vms</computeroutput>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>ostypes</computeroutput> lists all guest
+          operating systems presently known to VirtualBox, along with
+          the identifiers used to refer to them with the
+          <computeroutput>modifyvm</computeroutput> command.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>hostdvds</computeroutput>,
+          <computeroutput>hostfloppies</computeroutput>, respectively,
+          list DVD, floppy, bridged networking and host-only networking
+          interfaces on the host, along with the name used to access
+          them from within VirtualBox.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>intnets</computeroutput> displays information
+          about the internal networks.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>bridgedifs</computeroutput>,
           <computeroutput>hostonlyifs</computeroutput>,
           <computeroutput>natnets</computeroutput> and
-          <computeroutput>dhcpservers</computeroutput>, respectively, list
-          bridged network interfaces, host-only network interfaces,
-          NAT network interfaces and DHCP servers currently available on the
-          host. Please see <xref
-          linkend="networkingdetails" /> for details on these.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>hostinfo</computeroutput> displays information
+          <computeroutput>dhcpservers</computeroutput>, respectively,
+          list bridged network interfaces, host-only network interfaces,
+          NAT network interfaces and DHCP servers currently available on
+          the host. Please see
+          <xref
+          linkend="networkingdetails" /> for details on
+          these.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>hostinfo</computeroutput> displays information
           about the host system, such as CPUs, memory size and operating
-          system version.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>hostcpuids</computeroutput> dumps the CPUID
+          system version.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>hostcpuids</computeroutput> dumps the CPUID
           parameters for the host CPUs. This can be used for a more fine
-          grained analyis of the host's virtualization capabilities.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>hddbackends</computeroutput> lists all known
-          virtual disk back-ends of VirtualBox. For each such format (such as
-          VDI, VMDK or RAW), this lists the back-end's capabilities and
-          configuration.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>hdds</computeroutput>,
+          grained analyis of the host's virtualization capabilities.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>hddbackends</computeroutput> lists all known
+          virtual disk back-ends of VirtualBox. For each such format
+          (such as VDI, VMDK or RAW), this lists the back-end's
+          capabilities and configuration.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>hdds</computeroutput>,
           <computeroutput>dvds</computeroutput> and
-          <computeroutput>floppies</computeroutput> all give you information
-          about virtual disk images currently in use by VirtualBox, including
-          all their settings, the unique identifiers (UUIDs) associated with
-          them by VirtualBox and all files associated with them. This is the
-          command-line equivalent of the Virtual Media Manager; see <xref
-          linkend="vdis" />.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>usbhost</computeroutput> supplies information
-          about USB devices attached to the host, notably information useful
-          for constructing USB filters and whether they are currently in use
-          by the host.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>usbfilters</computeroutput> lists all global
+          <computeroutput>floppies</computeroutput> all give you
+          information about virtual disk images currently in use by
+          VirtualBox, including all their settings, the unique
+          identifiers (UUIDs) associated with them by VirtualBox and all
+          files associated with them. This is the command-line
+          equivalent of the Virtual Media Manager. See
+          <xref
+          linkend="vdis" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>usbhost</computeroutput> supplies information
+          about USB devices attached to the host, notably information
+          useful for constructing USB filters and whether they are
+          currently in use by the host.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>usbfilters</computeroutput> lists all global
           USB filters registered with VirtualBox -- that is, filters for
-          devices which are accessible to all virtual machines -- and displays
-          the filter parameters.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>systemproperties</computeroutput> displays
-          some global VirtualBox settings, such as minimum and maximum guest
-          RAM and virtual hard disk size, folder settings and the current
-          authentication library in use.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>extpacks</computeroutput> displays all
-          VirtualBox extension packs currently installed; see <xref
-          linkend="intro-installing" /> and <xref
-          linkend="vboxmanage-extpack" /> for more information.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>groups</computeroutput> displays
-          details of the VM Groups; see <xref linkend="gui-vmgroups" />
-          for more information.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>webcams</computeroutput> displays a list of
-          webcams attached to the running VM. The output format is a list of
-          absolute paths or aliases that were used for attaching the webcams
-          to the VM using the 'webcam attach' command.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>screenshotformats</computeroutput> displays a
-          list of available screenshot formats.</para>
-        </listitem>
-
-      </itemizedlist></para>
+          devices which are accessible to all virtual machines -- and
+          displays the filter parameters.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>systemproperties</computeroutput> displays
+          some global VirtualBox settings, such as minimum and maximum
+          guest RAM and virtual hard disk size, folder settings and the
+          current authentication library in use.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>extpacks</computeroutput> displays all
+          VirtualBox extension packs currently installed. See
+          <xref
+          linkend="intro-installing" /> and
+          <xref
+          linkend="vboxmanage-extpack" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>groups</computeroutput> displays details of
+          the VM Groups. See <xref linkend="gui-vmgroups" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>webcams</computeroutput> displays a list of
+          webcams attached to the running VM. The output format is a
+          list of absolute paths or aliases that were used for attaching
+          the webcams to the VM using the webcam attach command.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>screenshotformats</computeroutput> displays a
+          list of available screenshot formats.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
   <sect1 id="vboxmanage-showvminfo">
+
     <title>VBoxManage showvminfo</title>
 
-    <para>The <computeroutput>showvminfo</computeroutput> command shows
-    information about a particular virtual machine. This is the same
-    information as <computeroutput>VBoxManage list vms --long</computeroutput>
-    would show for all virtual machines.</para>
-
-    <para>You will get information that resembles the following example.</para>
-
-    <para><screen>$ VBoxManage showvminfo "Windows XP"
-VirtualBox Command Line Management Interface Version @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@
-(C) 2005-@VBOX_C_YEAR@ @VBOX_VENDOR@
+    <para>
+      The <computeroutput>showvminfo</computeroutput> command shows
+      information about a particular virtual machine. This is the same
+      information as <computeroutput>VBoxManage list vms
+      --long</computeroutput> would show for all virtual machines.
+    </para>
+
+    <para>
+      You will get information that resembles the following example.
+    </para>
+
+    <para>
+<screen>$ VBoxManage showvminfo "Windows XP"
+VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
+(C) 2005-2018 Oracle Corporation
 All rights reserved.
 
@@ -366,9 +524,15 @@
 IOAPIC:          on
 ...
-    </screen></para>
-    <para>Use the <computeroutput>--machinereadable</computeroutput> option
-      to produce the same output, but in machine readable format: property="value" on a
-      line by line basis, e.g.:</para>
-    <para><screen>
+    </screen>
+    </para>
+
+    <para>
+      Use the <computeroutput>--machinereadable</computeroutput> option
+      to produce the same output, but in machine readable format:
+      property="value" on a line by line basis, e.g.:
+    </para>
+
+    <para>
+<screen>
 name="VBoxSDL --startvm OL7.2"
 groups="/"
@@ -376,1554 +540,2246 @@
 UUID="457af700-bc0a-4258-aa3c-13b03da171f2"
 ...
-    </screen></para>
+    </screen>
+    </para>
+
   </sect1>
 
   <sect1 id="vboxmanage-registervm">
-    <title>VBoxManage registervm / unregistervm</title>
-
-    <para>The <computeroutput>registervm</computeroutput> command allows you
-    to import a virtual machine definition in an XML file into VirtualBox. The
-    machine must not conflict with one already registered in VirtualBox and it
-    may not have any hard or removable disks attached. It is advisable to
-    place the definition file in the machines folder before registering
-    it.<note>
-        <para>When creating a new virtual machine with
-        <computeroutput>VBoxManage createvm</computeroutput> (see below), you
-        can directly specify the <computeroutput>--register</computeroutput>
-        option to avoid having to register it separately.</para>
-      </note></para>
-
-    <para>The <computeroutput>unregistervm</computeroutput> command
-    unregisters a virtual machine. If
-    <computeroutput>--delete</computeroutput> is also specified, the following
-    files will automatically be deleted as well:<orderedlist>
-        <listitem>
-          <para>all hard disk image files, including differencing files, which
-          are used by the machine and not shared with other machines;</para>
-        </listitem>
-
-        <listitem>
-          <para>saved state files that the machine created, if any (one if the
-          machine was in "saved" state and one for each online
-          snapshot);</para>
-        </listitem>
-
-        <listitem>
-          <para>the machine XML file and its backups;</para>
-        </listitem>
-
-        <listitem>
-          <para>the machine log files, if any;</para>
-        </listitem>
-
-        <listitem>
-          <para>the machine directory, if it is empty after having deleted all
-          the above.</para>
-        </listitem>
-      </orderedlist></para>
+
+    <title>VBoxManage registervm/unregistervm</title>
+
+    <para>
+      The <computeroutput>registervm</computeroutput> command allows you
+      to import a virtual machine definition in an XML file into
+      VirtualBox. The machine must not conflict with one already
+      registered in VirtualBox and it may not have any hard or removable
+      disks attached. It is advisable to place the definition file in
+      the machines folder before registering it.
+
+      <note>
+        <para>
+          When creating a new virtual machine with
+          <computeroutput>VBoxManage createvm</computeroutput> (see
+          below), you can directly specify the
+          <computeroutput>--register</computeroutput> option to avoid
+          having to register it separately.
+        </para>
+      </note>
+    </para>
+
+    <para>
+      The <computeroutput>unregistervm</computeroutput> command
+      unregisters a virtual machine. If
+      <computeroutput>--delete</computeroutput> is also specified, the
+      following files will automatically be deleted as well:
+    </para>
+
+    <orderedlist>
+
+      <listitem>
+        <para>
+          All hard disk image files, including differencing files, which
+          are used by the machine and not shared with other machines.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Saved state files that the machine created. One if the machine
+          was in "saved" state and one for each online snapshot.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The machine XML file and its backups,
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The machine log files.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The machine directory, if it is empty after having deleted all
+          of the above files.
+        </para>
+      </listitem>
+
+    </orderedlist>
+
   </sect1>
 
   <sect1 id="vboxmanage-createvm">
+
     <title>VBoxManage createvm</title>
 
-    <para>This command creates a new XML virtual machine definition
-    file.</para>
-
-    <para>The <computeroutput>--name &lt;name&gt;</computeroutput> parameter
-    is required and must specify the name of the machine. Since this name is
-    used by default as the file name of the settings file (with the extension
-    <computeroutput>.xml</computeroutput>) and the machine folder (a subfolder
-    of the <computeroutput>.config/VirtualBox/Machines</computeroutput> folder
-    - this folder name may vary depending on the operating system and the
-    version of VirtualBox which you are using), it must conform to your host
-    operating system's requirements for file name specifications. If the VM
-    is later renamed, the file and folder names will change automatically.</para>
-
-    <para>However, if the <computeroutput>--basefolder
-    &lt;path&gt;</computeroutput> option is used, the machine folder will be
-    named <computeroutput>&lt;path&gt;</computeroutput>. In this case, the
-    names of the file and the folder will not change if the virtual machine is
-    renamed.</para>
-
-    <para>If the <computeroutput>--group &lt;group&gt;, ...</computeroutput>
-    option is used, the machine will be assigned membership of the specified
-    VM groups in the list. Note that group ids always start with a
-    <computeroutput>/</computeroutput> and can be nested. By default,
-    VMs are always assigned membership of the group
-    <computeroutput>/</computeroutput>.</para>
-
-    <para>If the <computeroutput>--ostype &lt;ostype&gt;</computeroutput>:
-    option is used, &lt;ostype&gt; specifies the guest operating system
-    to run in the VM. To learn about the available OS options,
-    run <computeroutput>VBoxManage list ostypes</computeroutput> .</para>
-
-    <para>If the <computeroutput>--uuid &lt;uuid&gt;</computeroutput>:
-    option is used, &lt;uuid&gt; specifies the VM uuid. This must be
-    unique within the namespace of the host, or that of the VM Group if
-    it is assigned to a VM group membership. By default, a unique uuid
-    within the appropriate namespace is automatically generated.
-    </para>
-
-    <para>By default, this command only creates the XML file without
-    automatically registering the VM with your VirtualBox installation. To
-    register the VM instantly, use the optional
-    <computeroutput>--register</computeroutput> option, or run
-    <computeroutput>VBoxManage registervm</computeroutput> separately
-    afterwards.</para>
+    <para>
+      This command creates a new XML virtual machine definition file.
+    </para>
+
+    <para>
+      The <computeroutput>--name &lt;name&gt;</computeroutput> parameter
+      is required and must specify the name of the machine. Since this
+      name is used by default as the file name of the settings file
+      (with the extension <computeroutput>.xml</computeroutput>) and the
+      machine folder (a subfolder of the
+      <computeroutput>.config/VirtualBox/Machines</computeroutput>
+      folder - this folder name may vary depending on the operating
+      system and the version of VirtualBox which you are using), it must
+      conform to your host operating system's requirements for file name
+      specifications. If the VM is later renamed, the file and folder
+      names will change automatically.
+    </para>
+
+    <para>
+      However, if the <computeroutput>--basefolder
+      &lt;path&gt;</computeroutput> option is used, the machine folder
+      will be named <computeroutput>&lt;path&gt;</computeroutput>. In
+      this case, the names of the file and the folder will not change if
+      the virtual machine is renamed.
+    </para>
+
+    <para>
+      If the <computeroutput>--group &lt;group&gt;, ...</computeroutput>
+      option is used, the machine will be assigned membership of the
+      specified VM groups in the list. Note that group ids always start
+      with a <computeroutput>/</computeroutput> and can be nested. By
+      default, VMs are always assigned membership of the group
+      <computeroutput>/</computeroutput>.
+    </para>
+
+    <para>
+      If the <computeroutput>--ostype &lt;ostype&gt;</computeroutput>:
+      option is used, &lt;ostype&gt; specifies the guest operating
+      system to run in the VM. To learn about the available OS options,
+      run <computeroutput>VBoxManage list ostypes</computeroutput> .
+    </para>
+
+    <para>
+      If the <computeroutput>--uuid &lt;uuid&gt;</computeroutput>:
+      option is used, &lt;uuid&gt; specifies the VM uuid. This must be
+      unique within the namespace of the host, or that of the VM Group
+      if it is assigned to a VM group membership. By default, a unique
+      uuid within the appropriate namespace is automatically generated.
+    </para>
+
+    <para>
+      By default, this command only creates the XML file without
+      automatically registering the VM with your VirtualBox
+      installation. To register the VM instantly, use the optional
+      <computeroutput>--register</computeroutput> option, or run
+      <computeroutput>VBoxManage registervm</computeroutput> separately
+      afterwards.
+    </para>
 
   </sect1>
 
   <sect1 id="vboxmanage-modifyvm">
+
     <title>VBoxManage modifyvm</title>
 
-    <para>This command changes the properties of a registered virtual machine
-    which is not running. Most of the properties that this command makes
-    available correspond to the VM settings that VirtualBox graphical user
-    interface displays in each VM's "Settings" dialog; these were described in
-    <xref linkend="BasicConcepts" />. Some of the more advanced settings,
-    however, are only available through the
-    <computeroutput>VBoxManage</computeroutput> interface.</para>
-
-    <para>These commands require that the machine is powered off (neither
-    running nor in "saved" state). Some machine settings can also be changed
-    while a machine is running; those settings will then have a corresponding
-    subcommand with the <computeroutput>VBoxManage controlvm</computeroutput>
-    subcommand (see <xref linkend="vboxmanage-controlvm" />).</para>
-
-    <sect2>
-      <title>General settings</title>
-
-      <para>The following general settings are available through
-      <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
+    <para>
+      This command changes the properties of a registered virtual
+      machine which is not running. Most of the properties that this
+      command makes available correspond to the VM settings that
+      VirtualBox graphical user interface displays in each VM's
+      "Settings" dialog. These were described in
+      <xref linkend="BasicConcepts" />. Some of the more advanced
+      settings, however, are only available through the
+      <computeroutput>VBoxManage</computeroutput> interface.
+    </para>
+
+    <para>
+      These commands require that the machine is powered off (neither
+      running nor in "saved" state). Some machine settings can also be
+      changed while a machine is running; those settings will then have
+      a corresponding subcommand with the <computeroutput>VBoxManage
+      controlvm</computeroutput> subcommand. See
+      <xref linkend="vboxmanage-controlvm" />.
+    </para>
+
+    <sect2 id="vboxmanage-modifyvm-general">
+
+      <title>General Settings</title>
+
+      <para>
+        The following general settings are available through
+        <computeroutput>VBoxManage modifyvm</computeroutput>:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <computeroutput>--name &lt;name&gt;</computeroutput>: This
+            changes the VM's name and can be used to rename the internal
+            virtual machine files, as described in
+            <xref linkend="vboxmanage-createvm"/>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--groups &lt;group&gt;,
+            ...</computeroutput>: This changes the group membership of a
+            VM. Groups always start with a
+            <computeroutput>/</computeroutput> and can be nested. By
+            default VMs are in group <computeroutput>/</computeroutput>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--description &lt;desc&gt;</computeroutput>:
+            This changes the VM's description, which is a way to record
+            details about the VM in a way which is meaningful for the
+            user. The GUI interprets HTML formatting, the command line
+            allows arbitrary strings potentially containing multiple
+            lines.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--ostype &lt;ostype&gt;</computeroutput>:
+            This specifies what guest operating system is supposed to
+            run in the VM. To learn about the various identifiers that
+            can be used here, use <computeroutput>VBoxManage list
+            ostypes</computeroutput>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--iconfile
+            &lt;filename&gt;</computeroutput>: This specifies the
+            absolute path on the host file system for the VirtualBox
+            icon to be displayed in the VM.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--memory
+            &lt;memorysize&gt;</computeroutput>: This sets the amount of
+            RAM, in MB, that the virtual machine should allocate for
+            itself from the host. See <xref linkend="gui-createvm" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--pagefusion on|off</computeroutput>:
+            Enables/disables (default) the Page Fusion feature. The Page
+            Fusion feature minimises memory duplication between VMs with
+            similar configurations running on the same host. See
+            <xref linkend="guestadd-pagefusion" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vram &lt;vramsize&gt;</computeroutput>:
+            This sets the amount of RAM that the virtual graphics card
+            should have. See <xref linkend="settings-display" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--acpi on|off</computeroutput> and
+            <computeroutput>--ioapic on|off</computeroutput>: These
+            settings determine whether the VM should have ACPI and I/O
+            APIC support, respectively. See
+            <xref linkend="settings-motherboard" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--pciattach &lt;host PCI address [@ guest
+            PCI bus address]&gt;</computeroutput>: Attaches a specified
+            PCI network controller on the host to a specified PCI bus on
+            the guest. See <xref linkend="pcipassthrough" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--pcidetach &lt;host PCI
+            address&gt;</computeroutput>: Detaches a specified PCI
+            network controller on the host from the attached PCI bus on
+            the guest. See <xref linkend="pcipassthrough" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--hardwareuuid
+            &lt;uuid&gt;</computeroutput>: The UUID presented to the
+            guest via memory tables (DMI/SMBIOS), hardware and guest
+            properties. By default this is the same as the VM uuid.
+            Useful when cloning a VM. Teleporting takes care of this
+            automatically.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--cpus &lt;cpucount&gt;</computeroutput>:
+            This sets the number of virtual CPUs for the virtual
+            machine, see <xref linkend="settings-processor" />. If CPU
+            hot-plugging is enabled, this then sets the
+            <emphasis>maximum</emphasis> number of virtual CPUs that can
+            be plugged into the virtual machines.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--cpuhotplug on|off</computeroutput>: This
+            enables CPU hot-plugging. When enabled, virtual CPUs can be
+            added to and removed from a virtual machine while it is
+            running. See <xref linkend="cpuhotplug" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--plugcpu|unplugcpu
+            &lt;id&gt;</computeroutput>: If CPU hot-plugging is enabled,
+            this adds or removes a virtual CPU on the virtual machine.
+            <computeroutput>&lt;id&gt;</computeroutput> specifies the
+            index of the virtual CPU to be added or removed and must be
+            a number from 0 to the maximum no. of CPUs configured with
+            the <computeroutput>--cpus</computeroutput> option. CPU 0
+            can never be removed.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--cpuexecutioncap
+            &lt;1-100&gt;</computeroutput>: This setting controls how
+            much CPUtime a virtual CPU can use. A value of 50 implies a
+            single virtual CPU can use up to 50% of a single host CPU.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--pae on|off</computeroutput>: This
+            enables/disables PAE. See
+            <xref linkend="settings-processor" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--longmode on|off</computeroutput>: This
+            enables/disables long mode. See
+            <xref linkend="settings-processor" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--spec-ctrl on|off</computeroutput>: This
+            setting enables/disables exposing speculation control
+            interfaces to the guest, provided they are available on the
+            host. Depending on the host CPU and workload, enabling
+            speculation control may significantly reduce performance.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--cpu-profile &lt;host|intel
+            80[86|286|386]&gt;</computeroutput>: This enables
+            specification of a profile for guest CPU emulation. Specify
+            either one based on the host system CPU (host), or one from
+            a number of older Intel Micro-architectures - 8086, 80286,
+            80386.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--hpet on|off</computeroutput>: This
+            enables/disables a High Precision Event Timer (HPET) which
+            can replace the legacy system timers. This is turned off by
+            default. Note that Windows supports a HPET only from Vista
+            onwards.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--hwvirtex on|off</computeroutput>: This
+            enables or disables the use of hardware virtualization
+            extensions (Intel VT-x or AMD-V) in the processor of your
+            host system. See <xref linkend="hwvirt" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--triplefaultreset on|off</computeroutput>:
+            This setting enables resetting of the guest instead of
+            triggering a Guru Meditation. Some guests raise a triple
+            fault to reset the CPU so sometimes this is desired
+            behavior. Works only for non-SMP guests.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--apic on|off</computeroutput>: This setting
+            enables(default)/disables IO APIC. With I/O APIC, operating
+            systems can use more than 16 interrupt requests (IRQs) thus
+            avoiding IRQ sharing for improved reliability. See
+            <xref linkend="settings-motherboard" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--x2apic on|off</computeroutput>: This
+            setting enables(default)/disables CPU x2APIC support. CPU
+            x2APIC support helps operating systems run more efficiently
+            on high core count configurations, and optimizes interrupt
+            distribution in virtualized environments. Disable when using
+            host/guest operating systems incompatible with x2APIC
+            support.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--paravirtprovider
+            none|default|legacy|minimal|hyperv|kvm</computeroutput>:
+            This setting specifies which paravirtualization interface to
+            provide to the guest operating system. Specifying
+            <computeroutput>none</computeroutput> explicitly turns off
+            exposing any paravirtualization interface. The option
+            <computeroutput>default</computeroutput>, will pick an
+            appropriate interface depending on the guest OS type while
+            starting the VM. This is the default option chosen while
+            creating new VMs. The
+            <computeroutput>legacy</computeroutput> option is chosen for
+            VMs which were created with older VirtualBox versions and
+            will pick a paravirtualization interface while starting the
+            VM with VirtualBox 5.0 and newer. The
+            <computeroutput>minimal</computeroutput> provider is
+            mandatory for Mac OS X guests, while
+            <computeroutput>kvm</computeroutput> and
+            <computeroutput>hyperv</computeroutput> are recommended for
+            Linux and Windows guests respectively. These options are
+            explained in <xref linkend="gimproviders" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--paravirtdebug &lt;key=value&gt;
+            [,&lt;key=value&gt; ...]</computeroutput>: This setting
+            specifies debugging options specific to the
+            paravirtualization provider configured for this VM. See the
+            provider specific options in <xref linkend="gimdebug" /> for
+            a list of supported key-value pairs for each provider.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--nestedpaging on|off</computeroutput>: If
+            hardware virtualization is enabled, this additional setting
+            enables or disables the use of the nested paging feature in
+            the processor of your host system. See
+            <xref
+            linkend="hwvirt" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--largepages on|off</computeroutput>: If
+            hardware virtualization <emphasis>and</emphasis> nested
+            paging are enabled, for Intel VT-x only, an additional
+            performance improvement of up to 5% can be obtained by
+            enabling this setting. This causes the hypervisor to use
+            large pages to reduce TLB use and overhead.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vtxvpid on|off</computeroutput>: If
+            hardware virtualization is enabled, for Intel VT-x only,
+            this additional setting enables or disables the use of the
+            tagged TLB (VPID) feature in the processor of your host
+            system. See <xref
+            linkend="hwvirt" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vtxux on|off</computeroutput>: If hardware
+            virtualization is enabled, for Intel VT-x only, this setting
+            enables or disables the use of the unrestricted guest mode
+            feature for executing your guest.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--accelerate3d on|off</computeroutput>: If
+            the Guest Additions are installed, this setting enables or
+            disables hardware 3D acceleration. See
+            <xref
+            linkend="guestadd-3d" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--accelerate2dvideo on|off</computeroutput>:
+            If the Guest Additions are installed, this setting enables
+            or disables 2D video acceleration. See
+            <xref
+            linkend="guestadd-2d" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--chipset piix3|ich9</computeroutput>: By
+            default VirtualBox emulates an Intel PIIX3 chipset. Usually
+            there is no reason to change the default setting unless this
+            is required to relax some of its constraints. See
+            <xref
+            linkend="settings-motherboard" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            You can influence the BIOS logo that is displayed when a
+            virtual machine starts up with a number of settings. By
+            default, a VirtualBox logo is displayed.
+          </para>
+
+          <para>
+            With <computeroutput>--bioslogofadein
+            on|off</computeroutput> and
+            <computeroutput>--bioslogofadeout on|off</computeroutput>,
+            you can determine whether the logo should fade in and out,
+            respectively.
+          </para>
+
+          <para>
+            With <computeroutput>--bioslogodisplaytime
+            &lt;msec&gt;</computeroutput> you can set how long the logo
+            should be visible, in milliseconds.
+          </para>
+
+          <para>
+            With <computeroutput>--bioslogoimagepath
+            &lt;imagepath&gt;</computeroutput> you can, if you are so
+            inclined, replace the image that is shown, with your own
+            logo. The image must be an uncompressed 256 color BMP file
+            without color space information (Windows 3.0 format). The
+            image must not be bigger than 640 x 480.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--biosbootmenu
+            disabled|menuonly|messageandmenu</computeroutput>: This
+            specifies whether the BIOS allows the user to select a
+            temporary boot device.
+            <computeroutput>menuonly</computeroutput> suppresses the
+            message, but the user can still press F12 to select a
+            temporary boot device.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--biosapic
+            x2apic|apic|disabled</computeroutput>: This specifies the
+            firmware APIC level to be used. Options are: x2apic, apic or
+            disabled (no apic or x2apic) respectively.
+          </para>
+
+          <para>
+            Note that if x2apic is specified and x2apic is unsupported
+            by the VCPU, biosapic downgrades to apic, if supported -
+            otherwise down to 'disabled'. Similarly, if apic is
+            specified, and apic is unsupported a downgrade to 'disabled'
+            results.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--biossystemtimeoffset
+            &lt;ms&gt;</computeroutput>: This specifies a fixed time
+            offset (milliseconds) of the guest relative to the host
+            time. If the offset is positive, the guest time runs ahead
+            of the host time.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--biospxedebug on|off</computeroutput>: This
+            option enables additional debugging output when using the
+            Intel PXE boot ROM. The output will be written to the
+            release log file (<xref linkend="collect-debug-info" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--boot&lt;1-4&gt;
+            none|floppy|dvd|disk|net</computeroutput>: This specifies
+            the boot order for the virtual machine. There are four
+            "slots", which the VM will try to access from 1 to 4, and
+            for each of which you can set a device that the VM should
+            attempt to boot from.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--rtcuseutc on|off</computeroutput>: This
+            option lets the real-time clock (RTC) operate in UTC time.
+            See <xref linkend="settings-motherboard" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--graphicscontroller
+            none|vboxvga|vmsvga</computeroutput>: This option specifies
+            use of a graphics controller, and type chosen from vboxvga
+            or vmsvga. <xref linkend="settings-motherboard" />).
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--snapshotfolder
+            default|&lt;path&gt;</computeroutput>: This option specifies
+            the folder in which snapshots will be kept for a virtual
+            machine.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--firmware
+            bios|efi|efi32|efi64</computeroutput>: This option specifies
+            which firmware to be used to boot the VM: Available options
+            are: BIOS, or one of the EFI options: efi, efi32 or efi64.
+            Use EFI options with care.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--guestmemoryballoon
+            &lt;size&gt;</computeroutput> This option sets the default
+            size of the guest memory balloon, that is, memory allocated
+            by the VirtualBox Guest Additions from the guest operating
+            system and returned to the hypervisor for re-use by other
+            virtual machines.
+            <computeroutput>&lt;size&gt;</computeroutput> must be
+            specified in megabytes. The default size is 0 megabytes. See
+            <xref linkend="guestadd-balloon" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--defaultfrontend
+            default|&lt;name&gt;</computeroutput>: This option specifies
+            the default frontend to be used when starting this VM. See
+            <xref linkend="vboxmanage-startvm" />.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </sect2>
+
+    <sect2 id="vboxmanage-modifyvm-networking">
+
+      <title>Networking Settings</title>
+
+      <para>
+        The following networking settings are available through
+        <computeroutput>VBoxManage modifyvm</computeroutput>. With all
+        these settings, the decimal number directly following the option
+        name ("1-N" in the list below) specifies the virtual network
+        adapter whose settings should be changed.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <computeroutput>--nic&lt;1-N&gt;
+            none|null|nat|natnetwork|bridged|intnet|hostonly|generic</computeroutput>:
+            You can configure for each of the VM's virtual network
+            cards, what type of networking should be available. Options
+            are: not present (<computeroutput>none</computeroutput>),
+            not connected to the host
+            (<computeroutput>null</computeroutput>), use network address
+            translation (<computeroutput>nat</computeroutput>), use the
+            new network address translation engine
+            (<computeroutput>natnetwork</computeroutput>), bridged
+            networking (<computeroutput>bridged</computeroutput>), or
+            use internal networking
+            (<computeroutput>intnet</computeroutput>), host-only
+            networking (<computeroutput>hostonly</computeroutput>), or
+            access rarely used sub-modes
+            (<computeroutput>generic</computeroutput>). These options
+            correspond to the modes described in
+            <xref
+            linkend="networkingmodes" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--nictype&lt;1-N&gt;
+            Am79C970A|Am79C973|82540EM|82543GC|82545EM|virtio</computeroutput>:
+            This enables you to specify which networking hardware
+            VirtualBox presents to the guest for a specified VM virtual
+            network card. See <xref linkend="nichardware" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--cableconnected&lt;1-N&gt;
+            on|off</computeroutput>: This enables you to temporarily
+            disconnect a virtual network interface, as if a network
+            cable had been pulled from a real network card. This might
+            be useful e.g. for resetting certain software components in
+            the VM.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            With the "nictrace" options, you can optionally trace
+            network traffic by dumping it to a file, for debugging
+            purposes.
+          </para>
+
+          <para>
+            With <computeroutput>--nictrace&lt;1-N&gt;
+            on|off</computeroutput>, you can enable network tracing for
+            a particular virtual network card.
+          </para>
+
+          <para>
+            If enabled, you must specify with
+            <computeroutput>--nictracefile&lt;1-N&gt;
+            &lt;filename&gt;</computeroutput> the absolute path of the
+            file the trace should be logged to.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--nicproperty&lt;1-N&gt;
+            &lt;paramname&gt;="paramvalue"</computeroutput>: This
+            option, in combination with "nicgenericdrv" allows you to
+            pass parameters to rarely-used network backends.
+          </para>
+
+          <para>
+            These parameters are backend engine-specific, and are
+            different between UDP Tunnel and the VDE backend drivers.
+            For examples, please see
+            <xref linkend="network_udp_tunnel" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--nicspeed&lt;1-N&gt;
+            &lt;kbps&gt;</computeroutput>: If generic networking has
+            been enabled for a particular virtual network card (see the
+            <computeroutput>--nic</computeroutput> option above -
+            otherwise this setting has no effect), this mode enables
+            access to rarely used networking sub-modes, such as VDE
+            network or UDP Tunnel. This option specifies the throughput
+            rate in KBytes/sec.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--nicbootprio&lt;1-N&gt;
+            &lt;priority&gt;</computeroutput>: This specifies the order
+            in which NICs are tried for booting over the network (using
+            PXE). The priority is an integer in the 0 to 4 range.
+            Priority 1 is the highest, priority 4 is low. Priority 0,
+            which is the default unless otherwise specified, is the
+            lowest.
+          </para>
+
+          <para>
+            Note that this option only has effect when the Intel PXE
+            boot ROM is used.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--nicpromisc&lt;1-N&gt;
+            deny|allow-vms|allow-all</computeroutput>: This ernables you
+            to specify how the promiscuous mode is handled for the
+            specified VM virtual network card. This setting is only
+            relevant for bridged networking.
+            <computeroutput>deny</computeroutput> (default setting)
+            hides any traffic not intended for this VM.
+            <computeroutput>allow-vms</computeroutput> hides all host
+            traffic from this VM but allows the VM to see traffic
+            from/to other VMs.
+            <computeroutput>allow-all</computeroutput> removes this
+            restriction completely.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--nicbandwidthgroup&lt;1-N&gt;
+            none|&lt;name&gt;</computeroutput>: This removes/adds an
+            assignment of a bandwidth group from/to the specified
+            virtual network interface. Specifying
+            <computeroutput>none</computeroutput> removes any current
+            bandwidth group assignment from the specified virtual
+            network interface. Specifying
+            <computeroutput>&lt;name&gt;</computeroutput> adds an
+            assignment of a bandwidth group to the specified virtual
+            network interface.
+          </para>
+
+          <para>
+            For details, please see
+            <xref linkend="network_bandwidth_limit" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--bridgeadapter&lt;1-N&gt;
+            none|&lt;devicename&gt;</computeroutput>: If bridged
+            networking has been enabled for a virtual network card (see
+            the <computeroutput>--nic</computeroutput> option above),
+            otherwise this setting has no effect. Use this option to
+            specify which host interface the given virtual network
+            interface will use. For details, please see
+            <xref linkend="network_bridged" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--hostonlyadapter&lt;1-N&gt;
+            none|&lt;devicename&gt;</computeroutput>: If host-only
+            networking has been enabled for a virtual network card (see
+            the <computeroutput>--nic</computeroutput> option above),
+            otherwise this setting has no effect. Use this option to
+            specify which host-only networking interface the given
+            virtual network interface will use. For details, please see
+            <xref
+            linkend="network_hostonly" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--intnet&lt;1-N&gt;
+            network</computeroutput>: If internal networking has been
+            enabled for a virtual network card (see the
+            <computeroutput>--nic</computeroutput> option above),
+            otherwise this setting has no effect. Ue this option to
+            specify the name of the internal network (see
+            <xref
+            linkend="network_internal" />).
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--nat-network&lt;1-N&gt; &lt;network
+            name&gt;</computeroutput>: If the networking type is set to
+            <computeroutput>natnetwork</computeroutput> (not
+            <computeroutput>nat</computeroutput>) then this setting
+            specifies the name of the NAT network this adapter is
+            connected to. Optional.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--nicgenericdrv&lt;1-N&gt; &lt;backend
+            driver&gt;</computeroutput>: If generic networking has been
+            enabled for a virtual network card (see the
+            <computeroutput>--nic</computeroutput> option above),
+            otherwise this setting has no effect. This mode allows you
+            to access rarely used networking sub-modes, such as VDE
+            network or UDP Tunnel.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--macaddress&lt;1-N&gt;
+            auto|&lt;mac&gt;</computeroutput>: With this option you can
+            set the MAC address of a particular network adapter on the
+            VM. Normally, each network adapter is assigned a random
+            address by VirtualBox at VM creation.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <sect3 id="vboxmanage-modifyvm-networking-nat">
+
+        <title>NAT Networking Settings</title>
+
+        <para>
+          The following NAT networking settings are available through
+          <computeroutput>VBoxManage modifyvm</computeroutput>. With all
+          these settings, the decimal number directly following the
+          option name ("1-N" in the list below) specifies the virtual
+          network adapter whose settings should be changed.
+        </para>
+
+        <itemizedlist>
+
           <listitem>
-            <para><computeroutput>--name &lt;name&gt;</computeroutput>: This
-            changes the VM's name and possibly renames the internal virtual
-            machine files, as described with <computeroutput>VBoxManage
-            createvm</computeroutput> above.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--groups &lt;group&gt;, ...</computeroutput>:
-            This changes the group membership of a VM. Groups always start with
-            a <computeroutput>/</computeroutput> and can be nested. By default
-            VMs are in group <computeroutput>/</computeroutput>.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--description &lt;desc&gt;</computeroutput>:
-            This changes the VM's description, which is a way to record details
-            about the VM in a way which is meaningful for the user. The GUI
-            interprets HTML formatting, the command line allows arbitrary
-            strings potentially containing multiple lines.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--ostype &lt;ostype&gt;</computeroutput>:
-            This specifies what guest operating system is supposed to run in
-            the VM. To learn about the various identifiers that can be used
-            here, use <computeroutput>VBoxManage list
-            ostypes</computeroutput>.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--iconfile &lt;filename&gt;</computeroutput>:
-            This specifies the absolute path on the host file system for the VirtualBox
-            icon to be displayed in the VM.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--memory &lt;memorysize&gt;</computeroutput>: This sets the amount of RAM,
-            in MB, that the virtual machine should allocate for itself from
-            the host. See the remarks in <xref linkend="gui-createvm" /> for
-            more information.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--pagefusion on|off</computeroutput>:
-            Enables/disables (default) the Page Fusion feature.
-            The Page Fusion feature minimises memory duplication between VMs with similar
-            configurations running on the same host.
-            See <xref linkend="guestadd-pagefusion" /> for details.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vram &lt;vramsize&gt;</computeroutput>:
-            This sets the amount of RAM that the virtual graphics card should
-            have. See <xref linkend="settings-display" /> for details.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--acpi on|off</computeroutput>;
-            <computeroutput>--ioapic on|off</computeroutput>: These two
-            determine whether the VM should have ACPI and I/O APIC support,
-            respectively; see <xref linkend="settings-motherboard" /> for
-            details.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--pciattach &lt;host PCI address [@ guest
-            PCI bus address]&gt;</computeroutput>: Attaches a specified PCI network
-            controller on the host to a PCI bus (can specify) on the guest.
-            See <xref linkend="pcipassthrough" /> for details. </para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--pcidetach &lt;host PCI address&gt;</computeroutput>:
-            Detaches a specified PCI network controller on the host from the attached
-            PCI bus on the guest. See <xref linkend="pcipassthrough" />
-            for details. </para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--hardwareuuid
-            &lt;uuid&gt;</computeroutput>: The UUID presented to the guest via
-            memory tables (DMI/SMBIOS), hardware and guest properties. By
-            default this is the same as the VM uuid. Useful when cloning a VM.
-            Teleporting takes care of this automatically.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--cpus &lt;cpucount&gt;</computeroutput>:
-            This sets the number of virtual CPUs for the virtual machine (see
-            <xref linkend="settings-processor" />). If CPU hot-plugging is
-            enabled (see below), this then sets the
-            <emphasis>maximum</emphasis> number of virtual CPUs that can be
-            plugged into the virtual machines.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--cpuhotplug on|off</computeroutput>: This
-            enables CPU hot-plugging. When enabled, virtual CPUs can be added
-            to and removed from a virtual machine while it is running. See
-            <xref linkend="cpuhotplug" /> for more information.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--plugcpu|unplugcpu
-            &lt;id&gt;</computeroutput>: If CPU hot-plugging is enabled (see
-            above), this adds a virtual CPU to the virtual machines (or
-            removes one). <computeroutput>&lt;id&gt;</computeroutput>
-            specifies the index of the virtual CPU to be added or removed and
-            must be a number from 0 to the maximum no. of CPUs configured with
-            the <computeroutput>--cpus</computeroutput> option. CPU 0 can
-            never be removed.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--cpuexecutioncap
-            &lt;1-100&gt;</computeroutput>: This setting controls how much cpu
-            time a virtual CPU can use. A value of 50 implies a single virtual
-            CPU can use up to 50% of a single host CPU.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--pae on|off</computeroutput>: This
-            enables/disables PAE. See <xref linkend="settings-processor" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--longmode on|off</computeroutput>: This
-            enables/disables long mode. See <xref linkend="settings-processor" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--spec-ctrl on|off</computeroutput>: This setting
-            enables/disables exposing speculation control interfaces to the guest, provided
-            they are available on the host. Depending on the host CPU and workload, enabling
-            speculation control may significantly reduce performance.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--cpu-profile &lt;host|intel 80[86|286|386]&gt;</computeroutput>:
-            This enables specification of a profile for guest cpu emulation.
-            Specify either one based on the host system CPU (host), or one from
-            a number of older Intel Micro-architectures - 8086, 80286, 80386.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--hpet on|off</computeroutput>: This
-            enables/disables a High Precision Event Timer (HPET) which can
-            replace the legacy system timers. This is turned off by default.
-            Note that Windows supports a HPET only from Vista onwards.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--hwvirtex on|off</computeroutput>: This
-            enables or disables the use of hardware virtualization extensions
-            (Intel VT-x or AMD-V) in the processor of your host system;
-            see <xref linkend="hwvirt" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--triplefaultreset on|off</computeroutput>:
-            This setting enables resetting of the guest instead of triggering a
-            Guru Meditation. Some guests raise a triple fault to reset the
-            CPU so sometimes this is desired behavior. Works only for non-SMP
-            guests.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--apic on|off</computeroutput>:
-            This setting enables(default)/disables IO APIC. With
-            I/O APIC, operating systems can use more than 16 interrupt
-            requests (IRQs) thus avoiding IRQ sharing for improved
-            reliability. See <xref linkend="settings-motherboard" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--x2apic on|off</computeroutput>:
-            This setting enables(default)/disables CPU x2APIC support.
-            CPU x2APIC support helps operating systems run more efficiently on high
-            core count configurations, and optimizes interrupt
-            distribution in virtualized environments. Disable when using host/guest
-            operating systems incompatible with x2APIC support.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--paravirtprovider
-            none|default|legacy|minimal|hyperv|kvm</computeroutput>: This
-            setting specifies which paravirtualization interface to provide to
-            the guest operating system. Specifying
-            <computeroutput>none</computeroutput> explicitly turns off exposing
-            any paravirtualization interface. The option
-            <computeroutput>default</computeroutput>, will pick an appropriate
-            interface depending on the guest OS type while starting the VM.
-            This is the default option chosen while creating new VMs. The
-            <computeroutput>legacy</computeroutput> option is chosen for VMs
-            which were created with older VirtualBox versions and will pick a
-            paravirtualization interface while starting the VM with VirtualBox
-            5.0 and newer. The <computeroutput>minimal</computeroutput> provider
-            is mandatory for Mac OS X guests, while
-            <computeroutput>kvm</computeroutput> and
-            <computeroutput>hyperv</computeroutput> are recommended for Linux
-            and Windows guests respectively. These options are explained in
-            detail under <xref linkend="gimproviders" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--paravirtdebug &lt;key=value&gt;
-            [,&lt;key=value&gt; ...]</computeroutput>: This setting specifies debugging
-            options specific to the paravirtualization provider
-            configured for this VM. Please refer to the provider specific
-            options under <xref linkend="gimdebug" /> for a list of supported
-            key-value pairs for each provider.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--nestedpaging on|off</computeroutput>: If
-            hardware virtualization is enabled, this additional setting
-            enables or disables the use of the nested paging feature in the
-            processor of your host system; see <xref
-            linkend="hwvirt" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--largepages on|off</computeroutput>: If
-            hardware virtualization <emphasis>and</emphasis> nested paging are
-            enabled, for Intel VT-x only, an additional performance
-            improvement of up to 5% can be obtained by enabling this setting.
-            This causes the hypervisor to use large pages to reduce TLB use
-            and overhead.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vtxvpid on|off</computeroutput>: If
-            hardware virtualization is enabled, for Intel VT-x only, this
-            additional setting enables or disables the use of the tagged TLB
-            (VPID) feature in the processor of your host system; see <xref
-            linkend="hwvirt" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vtxux on|off</computeroutput>: If
-            hardware virtualization is enabled, for Intel VT-x only, this
-            setting enables or disables the use of the unrestricted guest mode
-            feature for executing your guest.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--accelerate3d on|off</computeroutput>:
-            If the Guest Additions are installed, this setting enables or
-            disables hardware 3D acceleration; see <xref
-            linkend="guestadd-3d" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--accelerate2dvideo on|off</computeroutput>:
-            If the Guest Additions are installed, this setting enables or
-            disables 2D video acceleration; see <xref
-            linkend="guestadd-2d" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--chipset piix3|ich9</computeroutput>:
-            By default VirtualBox emulates an Intel PIIX3 chipset. Usually there
-            is no reason to change the default setting unless this is required to
-            relax some of its constraints; see <xref
-            linkend="settings-motherboard" />.</para>
-          </listitem>
-
-          <listitem>
-            <para>You can influence the BIOS logo that is displayed when a
-            virtual machine starts up with a number of settings. By default,
-            a VirtualBox logo is displayed.</para>
-
-            <para>With <computeroutput>--bioslogofadein
-            on|off</computeroutput> and <computeroutput>--bioslogofadeout
-            on|off</computeroutput>, you can determine whether the logo should
-            fade in and out, respectively.</para>
-
-            <para>With <computeroutput>--bioslogodisplaytime
-            &lt;msec&gt;</computeroutput> you can set how long the logo should
-            be visible, in milliseconds.</para>
-
-            <para>With <computeroutput>--bioslogoimagepath
-            &lt;imagepath&gt;</computeroutput> you can, if you are so
-            inclined, replace the image that is shown, with your own logo. The
-            image must be an uncompressed 256 color BMP file without color
-            space information (Windows 3.0 format). The image must not be
-            bigger than 640 x 480.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--biosbootmenu
-            disabled|menuonly|messageandmenu</computeroutput>: This specifies
-            whether the BIOS allows the user to select a temporary boot
-            device. <computeroutput>menuonly</computeroutput> suppresses the
-            message, but the user can still press F12 to select a temporary
-            boot device.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--biosapic
-            x2apic|apic|disabled</computeroutput>: This specifies
-            the firmware APIC level to be used. Options are: x2apic, apic or
-            disabled (no apic or x2apic) respectively.</para>
-
-            <para>Note that if x2apic is specified and x2apic is unsupported by the
-            VCPU, biosapic downgrades to apic, if supported - otherwise down to 'disabled'.
-            Similarly, if apic is specified, and apic is unsupported a
-            downgrade to 'disabled' results.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--biossystemtimeoffset &lt;ms&gt;</computeroutput>:
-            This specifies a fixed time offset (milliseconds) of the guest relative to
-            the host time. If the offset is positive, the guest time runs ahead of the
-            host time.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--biospxedebug on|off</computeroutput>:
-            This option enables additional debugging output when using the
-            Intel PXE boot ROM. The output will be written to the release log
-            file (<xref linkend="collect-debug-info" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--boot&lt;1-4&gt;
-            none|floppy|dvd|disk|net</computeroutput>: This specifies the boot
-            order for the virtual machine. There are four "slots", which the
-            VM will try to access from 1 to 4, and for each of which you can
-            set a device that the VM should attempt to boot from.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--rtcuseutc on|off</computeroutput>: This
-            option lets the real-time clock (RTC) operate in UTC time. See
-            <xref linkend="settings-motherboard" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--graphicscontroller none|vboxvga|vmsvga</computeroutput>: This
-            option specifies use of a graphics controller, and type chosen from vboxvga or vmsvga.
-            <xref linkend="settings-motherboard" />).</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--snapshotfolder
-            default|&lt;path&gt;</computeroutput>: This option specifies the folder in which
-            snapshots will be kept for a virtual machine.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--firmware bios|efi|efi32|efi64</computeroutput>:
-            This option specifies which firmware to be used to boot the VM:
-            Available options are: BIOS, or one of the EFI options: efi, efi32 or efi64.
-            Use EFI options with care.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--guestmemoryballoon
-            &lt;size&gt;</computeroutput> This option sets the default size of the guest
-            memory balloon, that is, memory allocated by the VirtualBox Guest
-            Additions from the guest operating system and returned to the
-            hypervisor for re-use by other virtual machines.
-            <computeroutput>&lt;size&gt;</computeroutput> must be specified in
-            megabytes. The default size is 0 megabytes. For details,
-            see <xref linkend="guestadd-balloon" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--defaultfrontend
-            default|&lt;name&gt;</computeroutput>: This option specifies
-            the default frontend to be used when starting this VM;
-            see <xref linkend="vboxmanage-startvm" /> for details.</para>
-          </listitem>
-        </itemizedlist></para>
-    </sect2>
-
-    <sect2>
-      <title>Networking settings</title>
-
-      <para>The following networking settings are available through
-      <computeroutput>VBoxManage modifyvm</computeroutput>. With all these
-      settings, the decimal number directly following the option name ("1-N"
-      in the list below) specifies the virtual network adapter whose settings
-      should be changed.<itemizedlist>
-          <listitem>
-            <para><computeroutput>--nic&lt;1-N&gt;
-            none|null|nat|natnetwork|bridged|intnet|hostonly|generic</computeroutput>:
-            With this, you can set, for each of the VM's virtual network cards,
-            what type of networking should be available. They can be not
-            present (<computeroutput>none</computeroutput>), not connected to
-            the host (<computeroutput>null</computeroutput>), use network
-            address translation (<computeroutput>nat</computeroutput>),
-            use the new network address translation engine
-            (<computeroutput>natnetwork</computeroutput>),
-            bridged networking (<computeroutput>bridged</computeroutput>) or
-            communicate with other virtual machines using internal networking
-            (<computeroutput>intnet</computeroutput>), host-only networking
-            (<computeroutput>hostonly</computeroutput>), or access rarely used
-            sub-modes (<computeroutput>generic</computeroutput>).
-            These options correspond
-            to the modes which are described in detail in <xref
-            linkend="networkingmodes" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--nictype&lt;1-N&gt;
-            Am79C970A|Am79C973|82540EM|82543GC|82545EM|virtio</computeroutput>:
-            This enables you to specify which networking hardware VirtualBox presents
-            to the guest for a specified VM virtual network card;
-            see <xref linkend="nichardware" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--cableconnected&lt;1-N&gt;
-            on|off</computeroutput>: This enables you to temporarily disconnect
-            a virtual network interface, as if a network cable had been pulled
-            from a real network card. This might be useful e.g. for resetting
-            certain software components in the VM.</para>
-          </listitem>
-
-          <listitem>
-            <para>With the "nictrace" options, you can optionally trace
-            network traffic by dumping it to a file, for debugging
-            purposes.</para>
-
-            <para>With <computeroutput>--nictrace&lt;1-N&gt;
-            on|off</computeroutput>, you can enable network tracing for a
-            particular virtual network card.</para>
-
-            <para>If enabled, you must specify with
-            <computeroutput>--nictracefile&lt;1-N&gt;
-            &lt;filename&gt;</computeroutput> the absolute path of the file the trace should be
-            logged to.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--nicproperty&lt;1-N&gt;
-            &lt;paramname&gt;="paramvalue"</computeroutput>:
-            This option, in combination with "nicgenericdrv" allows you to
-            pass parameters to rarely-used network backends.</para>
-
-            <para>These parameters are backend engine-specific, and are different
-            between UDP Tunnel and the VDE backend drivers. For examples,
-            please see <xref linkend="network_udp_tunnel" />.
+            <para>
+              <computeroutput>--natnet&lt;1-N&gt;
+              &lt;network&gt;|default</computeroutput>: If the
+              networking type is set to
+              <computeroutput>nat</computeroutput> (not
+              <computeroutput>natnetwork</computeroutput>) then this
+              setting specifies the IP address range to be used for this
+              network. See <xref linkend="changenat" /> for an example.
             </para>
           </listitem>
 
           <listitem>
-            <para><computeroutput>--nicspeed&lt;1-N&gt; &lt;kbps&gt;</computeroutput>:
-            If generic networking has been enabled for a particular virtual network
-            card (see the <computeroutput>--nic</computeroutput> option above - otherwise
-            this setting has no effect), this mode enables access to rarely used networking
-            sub-modes, such as VDE network or UDP Tunnel. This option specifies the
-            throughput rate in KBytes/sec.
+            <para>
+              <computeroutput>--natpf&lt;1-N&gt;
+              [&lt;name&gt;],tcp|udp,[&lt;hostip&gt;],&lt;hostport&gt;,[&lt;guestip&gt;],
+              &lt;guestport&gt;</computeroutput>: This setting defines a
+              NAT port-forwarding rule. See
+              <xref linkend="natforward" />.
             </para>
           </listitem>
 
           <listitem>
-            <para><computeroutput>--nicbootprio&lt;1-N&gt;
-            &lt;priority&gt;</computeroutput>: This specifies the order in which
-            NICs are tried for booting over the network (using PXE). The
-            priority is an integer in the 0 to 4 range. Priority 1 is the
-            highest, priority 4 is low. Priority 0, which is the default unless
-            otherwise specified, is the lowest.</para>
-
-            <para>Note that this option only has effect when the Intel PXE boot
-            ROM is used.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--nicpromisc&lt;1-N&gt;
-            deny|allow-vms|allow-all</computeroutput>:
-            This ernables you to specify how the promiscuous mode is handled for
-            the specified VM virtual network card.
-            This setting is only relevant for bridged networking.
-            <computeroutput>deny</computeroutput> (default setting) hides
-            any traffic not intended for this VM.
-            <computeroutput>allow-vms</computeroutput> hides all host
-            traffic from this VM but allows the VM to see traffic from/to other
-            VMs.
-            <computeroutput>allow-all</computeroutput> removes this
-            restriction completely.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--nicbandwidthgroup&lt;1-N&gt;
-            none|&lt;name&gt;</computeroutput>: This removes/adds an assignment
-            of a bandwidth group from/to the specified virtual network interface.
-            Specifying <computeroutput>none</computeroutput> removes any current
-            bandwidth group assignment from the specified virtual network interface.
-            Specifying <computeroutput>&lt;name&gt;</computeroutput> adds an
-            assignment of a bandwidth group to the specified virtual network
-            interface.</para>
-            <para>For details, please see <xref linkend="network_bandwidth_limit" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--bridgeadapter&lt;1-N&gt;
-            none|&lt;devicename&gt;</computeroutput>: If bridged networking
-            has been enabled for a virtual network card (see the
-            <computeroutput>--nic</computeroutput> option above; otherwise
-            this setting has no effect), use this option to specify which host
-            interface the given virtual network interface will use. For
-            details, please see <xref linkend="network_bridged" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--hostonlyadapter&lt;1-N&gt;
-            none|&lt;devicename&gt;</computeroutput>: If host-only networking
-            has been enabled for a virtual network card (see the
-            <computeroutput>--nic</computeroutput> option
-            above; otherwise this setting has no effect), use this option to
-            specify which host-only networking interface the given virtual
-            network interface will use. For details, please see <xref
-            linkend="network_hostonly" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--intnet&lt;1-N&gt;
-            network</computeroutput>: If internal networking has been enabled
-            for a virtual network card (see the
-            <computeroutput>--nic</computeroutput> option above; otherwise
-            this setting has no effect), use this option to specify the name
-            of the internal network (see <xref
-            linkend="network_internal" />).</para>
-          </listitem>
-
-
-          <listitem>
-            <para><computeroutput>--nat-network&lt;1-N&gt; &lt;network
-            name&gt;</computeroutput>: If the networking type is set to
-            <computeroutput>natnetwork</computeroutput> (not
-            <computeroutput>nat</computeroutput>) then this setting specifies
-            the name of the NAT network this adapter is connected to. Optional.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--nicgenericdrv&lt;1-N&gt;
-            &lt;backend driver&gt;</computeroutput>: If generic networking has been
-            enabled for a virtual network card (see the
-            <computeroutput>--nic</computeroutput> option above; otherwise
-            this setting has no effect), this mode allows you to access
-            rarely used networking sub-modes, such as VDE network or UDP Tunnel.
+            <para>
+              <computeroutput>--natpf&lt;1-N&gt; delete
+              &lt;name&gt;</computeroutput>: This setting deletes a NAT
+              port-forwarding rule. See <xref linkend="natforward" />.
             </para>
           </listitem>
 
           <listitem>
-            <para><computeroutput>--macaddress&lt;1-N&gt;
-            auto|&lt;mac&gt;</computeroutput>: With this option you can set
-            the MAC address of a particular network adapter on the VM. Normally, each
-            network adapter is assigned a random address by VirtualBox at
-            VM creation.</para>
+            <para>
+              <computeroutput>--nattftpprefix&lt;1-N&gt;
+              &lt;prefix&gt;</computeroutput>: This setting defines a
+              prefix for the built-in TFTP server, i.e. where the boot
+              file is located. See <xref linkend="nat-tftp" /> and
+              <xref
+              linkend="nat-adv-tftp" />.
+            </para>
           </listitem>
-        </itemizedlist></para>
-
-      <sect3>
-        <title>NAT Networking settings.</title>
-
-        <para>The following NAT networking settings are available through
-        <computeroutput>VBoxManage modifyvm</computeroutput>. With all these
-        settings, the decimal number directly following the option name ("1-N"
-        in the list below) specifies the virtual network adapter whose
-        settings should be changed.<itemizedlist>
-
-            <listitem>
-              <para><computeroutput>--natnet&lt;1-N&gt;
-              &lt;network&gt;|default</computeroutput>:
-              If the networking type is set to <computeroutput>nat</computeroutput>
-              (not <computeroutput>natnetwork</computeroutput>) then this
-              setting specifies the IP address range to be used for
-              this network. See <xref linkend="changenat" /> for an
-              example.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--natpf&lt;1-N&gt;
-              [&lt;name&gt;],tcp|udp,[&lt;hostip&gt;],&lt;hostport&gt;,[&lt;guestip&gt;],
-              &lt;guestport&gt;</computeroutput>: This setting defines a NAT
-              port-forwarding rule. See <xref linkend="natforward" />
-              for details.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--natpf&lt;1-N&gt; delete
-              &lt;name&gt;</computeroutput>: This setting deletes a NAT
-              port-forwarding rule. See <xref linkend="natforward" />
-              for details.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--nattftpprefix&lt;1-N&gt;
-              &lt;prefix&gt;</computeroutput>: This setting defines a prefix
-              for the built-in TFTP server, i.e. where the boot file is
-              located. See <xref linkend="nat-tftp" /> and <xref
-              linkend="nat-adv-tftp" /> for details.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--nattftpfile&lt;1-N&gt;
-              &lt;bootfile&gt;</computeroutput>: This setting defines the TFT
-              boot file. See <xref linkend="nat-adv-tftp" /> for
-              details.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--nattftpserver&lt;1-N&gt;
-              &lt;tftpserver&gt;</computeroutput>: This setting defines the
-              TFTP server address to boot from. Please see <xref
-              linkend="nat-adv-tftp" /> for details.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--nattbindip&lt;1-N&gt;
-              &lt;ip;&gt;</computeroutput>: VirtualBox's NAT engine normally routes
-              TCP/IP packets through the default interface assigned by the host's
-              TCP/IP stack. Use this setting to instruct the NAT engine to bind
-              to a specified IP address instead. Please see <xref
-              linkend="nat-adv-settings" /> for details.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--natdnspassdomain&lt;1-N&gt;
-              on|off</computeroutput>: This setting specifies whether the
-              built-in DHCP server passes the domain name for network name
-              resolution.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--natdnsproxy&lt;1-N&gt;
-              on|off</computeroutput>: This setting makes the NAT engine proxy
-              all guest DNS requests to the host's DNS servers. Please see
-              <xref linkend="nat-adv-dns" /> for details.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--natdnshostresolver&lt;1-N&gt;
-              on|off</computeroutput>: This setting makes the NAT engine use
-              the host's resolver mechanisms to handle DNS requests. Please
-              see <xref linkend="nat-adv-dns" /> for detailsx).</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--natsettings&lt;1-N&gt;
+
+          <listitem>
+            <para>
+              <computeroutput>--nattftpfile&lt;1-N&gt;
+              &lt;bootfile&gt;</computeroutput>: This setting defines
+              the TFT boot file. See <xref linkend="nat-adv-tftp" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>--nattftpserver&lt;1-N&gt;
+              &lt;tftpserver&gt;</computeroutput>: This setting defines
+              the TFTP server address to boot from. See
+              <xref
+              linkend="nat-adv-tftp" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>--nattbindip&lt;1-N&gt;
+              &lt;ip;&gt;</computeroutput>: VirtualBox's NAT engine
+              normally routes TCP/IP packets through the default
+              interface assigned by the host's TCP/IP stack. Use this
+              setting to instruct the NAT engine to bind to a specified
+              IP address instead. See
+              <xref
+              linkend="nat-adv-settings" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>--natdnspassdomain&lt;1-N&gt;
+              on|off</computeroutput>: This setting specifies whether
+              the built-in DHCP server passes the domain name for
+              network name resolution.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>--natdnsproxy&lt;1-N&gt;
+              on|off</computeroutput>: This setting makes the NAT engine
+              proxy all guest DNS requests to the host's DNS servers.
+              See <xref linkend="nat-adv-dns" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>--natdnshostresolver&lt;1-N&gt;
+              on|off</computeroutput>: This setting makes the NAT engine
+              use the host's resolver mechanisms to handle DNS requests.
+              See <xref linkend="nat-adv-dns" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>--natsettings&lt;1-N&gt;
               [&lt;mtu&gt;],[&lt;socksnd&gt;],[&lt;sockrcv&gt;],[&lt;tcpsnd&gt;],
-              [&lt;tcprcv&gt;]</computeroutput>: This setting controls several
-              NAT settings. Please see <xref linkend="nat-adv-settings" /> for
-              details.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>--nataliasmode&lt;1-N&gt;
-              default|[log],[proxyonly],[sameports]</computeroutput>: This
-              setting defines behaviour of NAT engine core: log - enables
-              logging, proxyonly - switches of aliasing mode makes NAT
-              transparent, sameports enforces NAT engine to send packets via
-              the same port as they originated on, default - disable all
-              mentioned modes above. Please see <xref
-              linkend="nat-adv-alias" /> for details.</para>
-            </listitem>
-          </itemizedlist></para>
+              [&lt;tcprcv&gt;]</computeroutput>: This setting controls
+              several NAT settings. See
+              <xref linkend="nat-adv-settings" />.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>--nataliasmode&lt;1-N&gt;
+              default|[log],[proxyonly],[sameports]</computeroutput>:
+              This setting defines behaviour of NAT engine core: log -
+              enables logging, proxyonly - switches of aliasing mode
+              makes NAT transparent, sameports enforces NAT engine to
+              send packets via the same port as they originated on,
+              default - disable all mentioned modes above. See
+              <xref
+              linkend="nat-adv-alias" />.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
       </sect3>
+
     </sect2>
 
     <sect2 id="vboxmanage-modifyvm-other">
-      <title>Miscellaneous settings</title>
-
-      <para>The following other hardware settings, such as serial port, audio,
-      clipboard, drag and drop, monitor and USB settings are available through
-      <computeroutput>VBoxManage modifyvm</computeroutput>:<itemizedlist>
-        <listitem>
-          <para><computeroutput>--mouse &lt;ps2|usb|usbtablet|usbmultitouch&gt;</computeroutput>:
-          Specifies the mode of the mouse to be used in the VM. Available options are: ps2, usb,
-          usbtablet, usbmultitouch.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--keyboard &lt;ps2|usb&gt;</computeroutput>:
-          Specifies the mode of the keyboard to be used in the VM. Available options are: ps2, usb.
-          </para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--uart&lt;1-N&gt; off|&lt;I/O base&gt;
-          &lt;IRQ&gt;</computeroutput>: With this setting you can configure
-          virtual serial ports for the VM. See <xref
-          linkend="serialports" /> for an introduction.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--uartmode&lt;1-N&gt;
-          &lt;arg&gt;</computeroutput>: This setting controls how VirtualBox
-          connects a given virtual serial port (previously configured with
-          the <computeroutput>--uartX</computeroutput> setting, see above)
-          to the host on which the virtual machine is running. As
-          described in detail in <xref linkend="serialports" />, for each
-          such port, you can specify <computeroutput>&lt;arg&gt;</computeroutput>
-          as one of the following options:<itemizedlist>
-            <listitem>
-              <para><computeroutput>disconnected</computeroutput>: Even
-              though the serial port is shown to the guest, it has no
-              "other end" -- like a real COM port without a cable.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>server
-              &lt;pipename&gt;</computeroutput>: On a Windows host, this
-              tells VirtualBox to create a named pipe on the host named
-              <computeroutput>&lt;pipename&gt;</computeroutput> and
-              connect the virtual serial device to it. Note that Windows
-              requires that the name of a named pipe begin with
-              <computeroutput>\\.\pipe\</computeroutput>.</para>
-
-              <para>On a Linux host, instead of a named pipe, a local
-              domain socket is used.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>client
-              &lt;pipename&gt;</computeroutput>: This operates just like
-              <computeroutput>server ...</computeroutput>, except that the
-              pipe (or local domain socket) is not created by VirtualBox,
-              but assumed to exist already.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>tcpserver
-              &lt;port&gt;</computeroutput>: This
-              tells VirtualBox to create a TCP socket on the host with TCP
-              <computeroutput>&lt;port&gt;</computeroutput> and
-              connect the virtual serial device to it. Note that UNIX-like
-              systems require ports over 1024 for normal users.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>tcpclient
-              &lt;hostname:port&gt;</computeroutput>: This operates just like
-              <computeroutput>tcpserver ...</computeroutput>, except that the
-              TCP socket is not created by VirtualBox,
-              but assumed to exist already.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>file &lt;file&gt;</computeroutput>:
-              This redirects the serial port output to a raw file &lt;file&gt;
-              specified by its absolute path on the host file system.</para>
-            </listitem>
-
-            <listitem>
-              <para><computeroutput>&lt;devicename&gt;</computeroutput>:
-              If, instead of the above, the device name of a physical
-              hardware serial port of the host is specified, the virtual
-              serial port is connected to that hardware port. On a Windows
-              host, the device name will be a COM port such as
-              <computeroutput>COM1</computeroutput>; on a Linux host, the
-              device name will look like
-              <computeroutput>/dev/ttyS0</computeroutput>. This allows you
-              to "wire" a real serial port to a virtual machine.</para>
-            </listitem>
-          </itemizedlist></para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--lptmode&lt;1-N&gt;
-          &lt;Device&gt;</computeroutput>:
-          Specifies the Device Name of the parallel port that
-          the Parallel Port feature will be using. Use this
-          <emphasis>before</emphasis> <computeroutput>--lpt</computeroutput>.
-          This feature is host operating system specific. For Windows hosts, use
-          a device name like <emphasis>lpt1</emphasis> while on Linux
-          hosts you have to use a device name like <emphasis>/dev/lp0</emphasis></para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--lpt&lt;1-N&gt;
-          &lt;I/O base&gt; &lt;IRQ&gt;</computeroutput>:
-          Specifies the I/O address of the parallel port and the IRQ
-          number that the Parallel Port feature will be using.  Optional. Use this
-          <emphasis>after</emphasis> <computeroutput>--lptmod</computeroutput>.
-          I/O base address and IRQ are the values that guest sees i.e. the values
-          avalable under guest Device Manager.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--audio none|null|dsound|oss|alsa|pulse|coreaudio</computeroutput>:
-          With this setting, you can specify whether the VM should have audio support, and
-          &ndash; if so &ndash; which type. The list of supported audio types depends on the
-          host and can be determined with <computeroutput>VBoxManage modifyvm</computeroutput>.
-        </para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--audiocontroller ac97|hda|sb16</computeroutput>: With
-          this setting, you can specify the audio controller to be used with this
-          VM.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--audiocodec stac9700|ad1980|stac9221|sb16</computeroutput>: With
-          this setting, you can specify the audio codec to be used with this VM.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--audioin on</computeroutput>: With
-          this setting, you can specify whether capturing audio from the
-          host is enabled or disabled.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--audioout on</computeroutput>: With
-          this setting, you can specify whether audio playback from the guest
-          is enabled or disabled.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--clipboard
-          disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
-          With this setting, you can select if and how the guest or host
-          operating system's clipboard should be shared with the host or guest.
-          See <xref linkend="generalsettings" />. This requires that the Guest
-          Additions be installed in the virtual machine.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--draganddrop
-          disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
-          With this setting, you can specify the current drag and drop mode
-          being used between the host and the virtual machine.
-          See <xref linkend="guestadd-dnd" />. This requires that the Guest
-          Additions be installed in the virtual machine.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--monitorcount
-          &lt;count&gt;</computeroutput>: This enables multi-monitor
-          support. See <xref linkend="settings-display" />.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--usb on|off</computeroutput>: This setting
-          enables or disables the VM's virtual USB controller. See <xref
-          linkend="settings-usb" /> for details.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--usbehci on|off</computeroutput>: This
-          setting enables or disables the VM's virtual USB 2.0 controller.
-          See <xref linkend="settings-usb" /> for details.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--usbxhci on|off</computeroutput>: This
-          setting enables or disables the VM's virtual USB 3.0 controller.
-          See <xref linkend="settings-usb" /> for details.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--usbrename
-          &lt;oldname&gt; &lt;newname&gt;</computeroutput>: This
-          setting enables renaming of the VM's virtual USB controller from &lt;oldname&gt;
-          to &lt;newname&gt;.</para>
-        </listitem>
-      </itemizedlist></para>
+
+      <title>Miscellaneous Settings</title>
+
+      <para>
+        The following hardware settings, such as serial port, audio,
+        clipboard, drag and drop, monitor and USB settings are available
+        through <computeroutput>VBoxManage modifyvm</computeroutput>:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <computeroutput>--mouse
+            &lt;ps2|usb|usbtablet|usbmultitouch&gt;</computeroutput>:
+            Specifies the mode of the mouse to be used in the VM.
+            Available options are: ps2, usb, usbtablet, usbmultitouch.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--keyboard &lt;ps2|usb&gt;</computeroutput>:
+            Specifies the mode of the keyboard to be used in the VM.
+            Available options are: ps2, usb.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--uart&lt;1-N&gt; off|&lt;I/O base&gt;
+            &lt;IRQ&gt;</computeroutput>: With this setting you can
+            configure virtual serial ports for the VM. See
+            <xref
+          linkend="serialports" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--uartmode&lt;1-N&gt;
+            &lt;arg&gt;</computeroutput>: This setting controls how
+            VirtualBox connects a given virtual serial port (previously
+            configured with the <computeroutput>--uartX</computeroutput>
+            setting, see above) to the host on which the virtual machine
+            is running. As described in <xref linkend="serialports" />,
+            for each such port, you can specify
+            <computeroutput>&lt;arg&gt;</computeroutput> as one of the
+            following options:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <computeroutput>disconnected</computeroutput>: Even
+                though the serial port is shown to the guest, it has no
+                "other end". This is like a real COM port without a
+                cable.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>server
+                &lt;pipename&gt;</computeroutput>: On a Windows host,
+                this tells VirtualBox to create a named pipe on the host
+                named <computeroutput>&lt;pipename&gt;</computeroutput>
+                and connect the virtual serial device to it. Note that
+                Windows requires that the name of a named pipe begin
+                with <computeroutput>\\.\pipe\</computeroutput>.
+              </para>
+
+              <para>
+                On a Linux host, instead of a named pipe, a local domain
+                socket is used.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>client
+                &lt;pipename&gt;</computeroutput>: This operates just
+                like <computeroutput>server ...</computeroutput>, except
+                that the pipe, or local domain socket, is not created by
+                VirtualBox, but assumed to exist already.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>tcpserver &lt;port&gt;</computeroutput>:
+                This tells VirtualBox to create a TCP socket on the host
+                with TCP <computeroutput>&lt;port&gt;</computeroutput>
+                and connect the virtual serial device to it. Note that
+                UNIX-like systems require ports over 1024 for normal
+                users.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>tcpclient
+                &lt;hostname:port&gt;</computeroutput>: This operates
+                just like <computeroutput>tcpserver
+                ...</computeroutput>, except that the TCP socket is not
+                created by VirtualBox, but assumed to exist already.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>file &lt;file&gt;</computeroutput>: This
+                redirects the serial port output to a raw file
+                &lt;file&gt; specified by its absolute path on the host
+                file system.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>&lt;devicename&gt;</computeroutput>: If,
+                instead of the above, the device name of a physical
+                hardware serial port of the host is specified, the
+                virtual serial port is connected to that hardware port.
+                On a Windows host, the device name will be a COM port
+                such as <computeroutput>COM1</computeroutput>; on a
+                Linux host, the device name will look like
+                <computeroutput>/dev/ttyS0</computeroutput>. This allows
+                you to "wire" a real serial port to a virtual machine.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--lptmode&lt;1-N&gt;
+            &lt;Device&gt;</computeroutput>: Specifies the Device Name
+            of the parallel port that the Parallel Port feature will be
+            using. Use this <emphasis>before</emphasis>
+            <computeroutput>--lpt</computeroutput>. This feature is host
+            operating system specific. For Windows hosts, use a device
+            name like <emphasis>lpt1</emphasis> while on Linux hosts you
+            have to use a device name like <emphasis>/dev/lp0</emphasis>
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--lpt&lt;1-N&gt; &lt;I/O base&gt;
+            &lt;IRQ&gt;</computeroutput>: Specifies the I/O address of
+            the parallel port and the IRQ number that the Parallel Port
+            feature will be using. Optional. Use this
+            <emphasis>after</emphasis>
+            <computeroutput>--lptmod</computeroutput>. I/O base address
+            and IRQ are the values that guest sees. For example, the
+            values avalable under guest Device Manager.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--audio
+            none|null|dsound|oss|alsa|pulse|coreaudio</computeroutput>:
+            With this setting, you can specify whether the VM should
+            have audio support, and &ndash; if so &ndash; which type.
+            The list of supported audio types depends on the host and
+            can be determined with <computeroutput>VBoxManage
+            modifyvm</computeroutput>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--audiocontroller
+            ac97|hda|sb16</computeroutput>: With this setting, you can
+            specify the audio controller to be used with this VM.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--audiocodec
+            stac9700|ad1980|stac9221|sb16</computeroutput>: With this
+            setting, you can specify the audio codec to be used with
+            this VM.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--audioin on</computeroutput>: With this
+            setting, you can specify whether capturing audio from the
+            host is enabled or disabled.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--audioout on</computeroutput>: With this
+            setting, you can specify whether audio playback from the
+            guest is enabled or disabled.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--clipboard
+            disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
+            With this setting, you can select if and how the guest or
+            host operating system's clipboard should be shared with the
+            host or guest. See <xref linkend="generalsettings" />. This
+            requires that the Guest Additions be installed in the
+            virtual machine.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--draganddrop
+            disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
+            With this setting, you can specify the current drag and drop
+            mode being used between the host and the virtual machine.
+            See <xref linkend="guestadd-dnd" />. This requires that the
+            Guest Additions be installed in the virtual machine.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--monitorcount
+            &lt;count&gt;</computeroutput>: This enables multi-monitor
+            support. See <xref linkend="settings-display" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--usb on|off</computeroutput>: This setting
+            enables or disables the VM's virtual USB controller. See
+            <xref
+          linkend="settings-usb" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--usbehci on|off</computeroutput>: This
+            setting enables or disables the VM's virtual USB 2.0
+            controller. See <xref linkend="settings-usb" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--usbxhci on|off</computeroutput>: This
+            setting enables or disables the VM's virtual USB 3.0
+            controller. See <xref linkend="settings-usb" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--usbrename &lt;oldname&gt;
+            &lt;newname&gt;</computeroutput>: This setting enables
+            renaming of the VM's virtual USB controller from
+            &lt;oldname&gt; to &lt;newname&gt;.
+          </para>
+        </listitem>
+
+      </itemizedlist>
 
     </sect2>
 
     <sect2 id="vboxmanage-modifyvm-videocap">
-      <title>Video Capture settings</title>
-
-      <para>The following settings for changing video recording parameters are
-      available through <computeroutput>VBoxManage modifyvm</computeroutput>.
+
+      <title>Video Capture Settings</title>
+
+      <para>
+        The following settings for changing video recording parameters
+        are available through <computeroutput>VBoxManage
+        modifyvm</computeroutput>.
+      </para>
+
       <itemizedlist>
-        <listitem>
-          <para><computeroutput>--videocap on|off</computeroutput>:
-          This option enables or disables recording a VM session into a WebM/VP8
-          file. If this option is enabled, recording will start when the VM
-          session is started.</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--videocapscreens all|&lt;screen ID&gt;
-          [&lt;screen ID&gt; ...]</computeroutput>: This option allows to specify which screens of
-          the VM are being recorded. Each screen is recorded into a separate file.</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--videocapfile &lt;filename&gt;</computeroutput>:
-            This option sets the filename VirtualBox uses to save the recorded content.
-          </para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--videocapres &lt;width&gt;x&lt;height&gt;</computeroutput>:
-            This option sets the resolution (in pixels) of the recorded video.</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--videocaprate &lt;rate&gt;</computeroutput>:
-            This option sets the bitrate in kilobits (kb) per second. Increasing this
-            value makes the video look better for the cost of an increased file size.</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--videocapfps &lt;fps&gt;</computeroutput>:
-            This option sets the maximum number of frames per second (FPS) to be
-            recorded. Frames with a higher frequency will be skipped. Reducing this
-            value increases the number of skipped frames and reduces the file size.</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--videocapmaxtime &lt;ms&gt;</computeroutput>:
-            This option sets the maximum time in milliseconds the video capturing
-            will be enabled since activation. The capturing stops when the defined
-            time interval has elapsed. If this value is zero the capturing is not
-            limited by time.</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--videocapmaxsize &lt;MB&gt;</computeroutput>:
-            This option limits the maximum size of the captured video file (in MB).
-            The capturing stops when the file size has reached the specified size. If
-            this value is zero the capturing will not be limited by file size.</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--videocapopts &lt;key=value&gt;
-            [,&lt;key=value&gt; ...]</computeroutput>:
-            This format can be used to specify additional video capturing options.
-            These options only are for advanced users and must be specified in a
-            comma-separated key=value format, e.g.
+
+        <listitem>
+          <para>
+            <computeroutput>--videocap on|off</computeroutput>: This
+            option enables or disables recording a VM session into a
+            WebM/VP8 file. If this option is enabled, recording will
+            start when the VM session is started.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--videocapscreens all|&lt;screen ID&gt;
+            [&lt;screen ID&gt; ...]</computeroutput>: This option allows
+            to specify which screens of the VM are being recorded. Each
+            screen is recorded into a separate file.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--videocapfile
+            &lt;filename&gt;</computeroutput>: This option sets the
+            filename VirtualBox uses to save the recorded content.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--videocapres
+            &lt;width&gt;x&lt;height&gt;</computeroutput>: This option
+            sets the resolution (in pixels) of the recorded video.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--videocaprate
+            &lt;rate&gt;</computeroutput>: This option sets the bitrate
+            in kilobits (kb) per second. Increasing this value makes the
+            video look better for the cost of an increased file size.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--videocapfps &lt;fps&gt;</computeroutput>:
+            This option sets the maximum number of frames per second
+            (FPS) to be recorded. Frames with a higher frequency will be
+            skipped. Reducing this value increases the number of skipped
+            frames and reduces the file size.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--videocapmaxtime
+            &lt;ms&gt;</computeroutput>: This option sets the maximum
+            time in milliseconds the video capturing will be enabled
+            since activation. The capturing stops when the defined time
+            interval has elapsed. If this value is zero the capturing is
+            not limited by time.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--videocapmaxsize
+            &lt;MB&gt;</computeroutput>: This option limits the maximum
+            size of the captured video file (in MB). The capturing stops
+            when the file size has reached the specified size. If this
+            value is zero the capturing will not be limited by file
+            size.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--videocapopts &lt;key=value&gt;
+            [,&lt;key=value&gt; ...]</computeroutput>: This format can
+            be used to specify additional video capturing options. These
+            options only are for advanced users and must be specified in
+            a comma-separated key=value format. For example:
             <computeroutput>foo=bar,a=b</computeroutput>.
           </para>
 
-          <para>The following keys and their corresponding values are available:
-            <itemizedlist>
-              <listitem>
-                <para><computeroutput>ac_enabled</computeroutput>:
-                  Enables audio recording when set to <computeroutput>true</computeroutput>,
-                  otherwise set to <computeroutput>false</computeroutput> to disable.
-                  This feature is considered being experimental.</para>
-              </listitem>
-            </itemizedlist>
-          </para>
-
-        </listitem>
-      </itemizedlist></para>
+          <para>
+            The following keys and their corresponding values are
+            available:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <computeroutput>ac_enabled</computeroutput>: Enables
+                audio recording when set to
+                <computeroutput>true</computeroutput>, otherwise set to
+                <computeroutput>false</computeroutput> to disable. This
+                feature is considered being experimental.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </listitem>
+
+      </itemizedlist>
 
     </sect2>
 
     <sect2 id="vboxmanage-modifyvm-vrde">
-      <title>Remote machine settings</title>
-
-      <para>The following settings that affect remote machine behavior are
-      available through <computeroutput>VBoxManage
-      modifyvm</computeroutput>:<itemizedlist>
-          <listitem>
-            <para><computeroutput>--vrde on|off</computeroutput>:
-            This enables or disables the VirtualBox remote desktop extension
-            (VRDE) server.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeproperty "TCP/Ports|Address=&lt;value&gt;"</computeroutput>
-            sets the port number(s) and IP address on the VM that the VRDE server can bind to.</para>
-
-            <itemizedlist>
-              <listitem>
-                <para>For TCP/Ports, &lt;value&gt; should be a port or a range of ports that the VRDE
-                server can bind to; "default" or "0" means port 3389, the standard port for RDP.
-                For details, see the description for the
-                <computeroutput>--vrdeport</computeroutput> option in <xref
-                linkend="vboxmanage-modifyvm-vrde" />.</para>
-              </listitem>
-
-              <listitem>
-                <para>For TCP/Address, &lt;value&gt; should be the IP address of the host network
-                interface that the VRDE server will bind to. If specified, the server
-                will accept connections only on the specified host network interface.
-                For details, see the description for the
-                <computeroutput>--vrdeaddress</computeroutput> option in <xref
-                linkend="vboxmanage-modifyvm-vrde" />.</para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeproperty "VideoChannel/Enabled|Quality|DownscaleProtection=&lt;value&gt;"</computeroutput>
-            sets the VRDP video redirection properties.</para>
-            <itemizedlist>
-              <listitem>
-                <para>For VideoChannel/Enabled, &lt;value&gt; can be set to "1" switching the VRDP video channel on.
-                For details, see <xref linkend="vrde-videochannel" />.</para>
-              </listitem>
-
-              <listitem>
-                <para>For VideoChannel/Quality, &lt;value&gt; should be set between 10 and 100% inclusive,
-                representing a JPEG compression level on the VRDE server video channel. Lower values mean lower
-                quality but higher compression. For details, see <xref linkend="vrde-videochannel" />.</para>
-              </listitem>
-
-              <listitem>
-                <para>For VideoChannel/DownscaleProtection, &lt;value&gt; can be set to "1" to
-                enable the videochannel downscale protection feature. When enabled, if a video's size equals the shadow buffer
-                size, then it is regarded as a full screen video, and is displayed; but if its size is between fullscreen and the downscale
-                threshold - it is NOT displayed, as it could be an application window, which would be unreadable when downscaled.
-                When the downscale protection feature is disabled, an attempt is always made to display videos.</para>
-              </listitem>
-            </itemizedlist>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeproperty "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1"</computeroutput></para>
-            <para>disables one of the VRDE server features: Display, Input, Audio or USB respectively.
-            To re-enable a feature, use e.g. "Client/DisableDisplay=".
-            For details, see <xref linkend="vrde-customization" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeproperty "Client/DisableClipboard|DisableUpstreamAudio=1"</computeroutput></para>
-            <para>disables one of the VRDE server features: Clipboard or UpstreamAudio respectively.
-            To re-enable a feature, use e.g. "Client/DisableClipboard=".
-            For details, see <xref linkend="vrde-customization" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeproperty "Client/DisableRDPDR=1"</computeroutput></para>
-            <para>disables the VRDE server feature: RDP device redirection for smart cards.
-            To re-enable this feature, use "Client/DisableRDPR=".</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeproperty "H3DRedirect/Enabled=1"</computeroutput></para>
-            <para>enables the VRDE server feature: 3D redirection.
-            To re-disable this feature, use "H3DRedirect/Enabled=".</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeproperty "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=&lt;value&gt;"</computeroutput>
-            sets the desired security method/Path of server certificate, path of server private key, path of CA certificate, used for a connection.
-
-            <itemizedlist>
-              <listitem>
-                <para><computeroutput>--vrdeproperty "Security/Method=&lt;value&gt;"</computeroutput>
-                sets the desired security method, which is used for a connection. Valid values are:
-                <itemizedlist>
-                  <listitem>
-                    <para> <computeroutput>Negotiate</computeroutput> - both Enhanced (TLS)
-                    and Standard RDP Security connections are allowed. The security
-                    method is negotiated with the client. This is the default setting.</para>
-                  </listitem>
-                  <listitem>
-                    <para> <computeroutput>RDP</computeroutput> - only Standard RDP Security is accepted.</para>
-                  </listitem>
-                  <listitem>
-                    <para> <computeroutput>TLS</computeroutput> - only Enhanced RDP Security is accepted.
-                    The client must support TLS.</para>
-                  </listitem>
-                </itemizedlist>
-                    For details, see <xref linkend="vrde-crypt" />.</para>
-              </listitem>
-
-              <listitem>
-                <para><computeroutput>--vrdeproperty "Security/ServerCertificate=&lt;value&gt;"</computeroutput>
-                where &lt;value&gt; is the absolute path of the server certificate.
-                For details, see <xref linkend="vrde-crypt" />.</para>
-              </listitem>
-
-              <listitem>
-                <para><computeroutput>--vrdeproperty "Security/ServerPrivateKey=&lt;value&gt;"</computeroutput>
-                where &lt;value&gt; is the absolute path of the server private key.
-                For details, see <xref linkend="vrde-crypt" />.</para>
-              </listitem>
-
-              <listitem>
-                <para><computeroutput>--vrdeproperty "Security/CACertificate=&lt;value&gt;"</computeroutput>
-                where &lt;value&gt; is the absolute path of the CA self signed certificate.
-                For details, see <xref linkend="vrde-crypt" />.</para>
-              </listitem>
-            </itemizedlist></para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeproperty "Audio/RateCorrectionMode|LogPath=&lt;value&gt;"</computeroutput>
-            sets the Audio connection mode, or Path of the audio logfile.
-
-            <itemizedlist>
-              <listitem>
-                <para><computeroutput>--vrdeproperty "Audio/RateCorrectionMode=&lt;value&gt;"</computeroutput>
-                where &lt;value&gt; is the desired rate correction mode, allowed values are:
-                <itemizedlist>
-                  <listitem>
-                    <para> <computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput> - no mode specified, use to unset any Audio mode already set.</para>
-                  </listitem>
-                  <listitem>
-                    <para> <computeroutput>VRDP_AUDIO_MODE_RC</computeroutput> - rate correction mode.</para>
-                  </listitem>
-                  <listitem>
-                    <para> <computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput> - low pass filter mode.</para>
-                  </listitem>
-                  <listitem>
-                    <para> <computeroutput>VRDP_AUDIO_MODE_CS</computeroutput> - client sync mode to prevent under/overflow of the client queue.</para>
-                  </listitem>
-                </itemizedlist></para>
-              </listitem>
-              <listitem>
-                <para><computeroutput>--vrdeproperty "Audio/LogPath=&lt;value&gt;"</computeroutput>
-                where &lt;value&gt; is the absolute path of the Audio log file.</para>
-              </listitem>
-            </itemizedlist></para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeextpack default|&lt;name&gt;</computeroutput>:
-            Enables specification of the library for accessing the VM
-            remotely. The default is to use the RDP code which is part of the
-            Oracle VM VirtualBox Extension Pack.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeport
-            default|&lt;ports&gt;</computeroutput>: A port or a range of ports
-            the VRDE server can bind to; "default" or "0" means port 3389, the
-            standard port for RDP. You can specify a comma-separated list of
-            ports or ranges of ports. Use a dash between two port numbers to
-            specify a range. The VRDE server will bind to <emphasis
-            role="bold">one</emphasis> of the available ports from the specified
-            list. Only one machine can use a given port at a time. For
-            example, the option <computeroutput> --vrdeport
-            5000,5010-5012</computeroutput> will tell the server to bind to
-            one of following ports: 5000, 5010, 5011 or 5012.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeaddress &lt;IP
-            address&gt;</computeroutput>: The IP address of the host network
-            interface the VRDE server will bind to. If specified, the server
-            will accept connections only on the specified host network
-            interface.</para>
-            <para>The setting can be used to specify whether the VRDP server
+
+      <title>Remote Machine Settings</title>
+
+      <para>
+        The following settings that affect remote machine behavior are
+        available through <computeroutput>VBoxManage
+        modifyvm</computeroutput>:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrde on|off</computeroutput>: This enables
+            or disables the VirtualBox remote desktop extension (VRDE)
+            server.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeproperty
+            "TCP/Ports|Address=&lt;value&gt;"</computeroutput> sets the
+            port number(s) and IP address on the VM that the VRDE server
+            can bind to.
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                For TCP/Ports, &lt;value&gt; should be a port or a range
+                of ports that the VRDE server can bind to; "default" or
+                "0" means port 3389, the standard port for RDP. See the
+                description for the
+                <computeroutput>--vrdeport</computeroutput> option in
+                <xref
+                linkend="vboxmanage-modifyvm-vrde" />.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                For TCP/Address, &lt;value&gt; should be the IP address
+                of the host network interface that the VRDE server will
+                bind to. If specified, the server will accept
+                connections only on the specified host network
+                interface. See the description for the
+                <computeroutput>--vrdeaddress</computeroutput> option in
+                <xref
+                linkend="vboxmanage-modifyvm-vrde" />.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeproperty
+            "VideoChannel/Enabled|Quality|DownscaleProtection=&lt;value&gt;"</computeroutput>
+            sets the VRDP video redirection properties.
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                For VideoChannel/Enabled, &lt;value&gt; can be set to
+                "1" switching the VRDP video channel on. For details,
+                see <xref linkend="vrde-videochannel" />.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                For VideoChannel/Quality, &lt;value&gt; should be set
+                between 10 and 100% inclusive, representing a JPEG
+                compression level on the VRDE server video channel.
+                Lower values mean lower quality but higher compression.
+                See <xref linkend="vrde-videochannel" />.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                For VideoChannel/DownscaleProtection, &lt;value&gt; can
+                be set to "1" to enable the videochannel downscale
+                protection feature. When enabled, if a video's size
+                equals the shadow buffer size, then it is regarded as a
+                full screen video, and is displayed. But if its size is
+                between fullscreen and the downscale threshold then it
+                is <emphasis>not</emphasis> displayed, as it could be an
+                application window, which would be unreadable when
+                downscaled. When the downscale protection feature is
+                disabled, an attempt is always made to display videos.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeproperty
+            "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1"</computeroutput>
+          </para>
+
+          <para>
+            Disables one of the VRDE server features: Display, Input,
+            Audio or USB respectively. To reenable a feature, use
+            "Client/DisableDisplay=" for example. See
+            <xref linkend="vrde-customization" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeproperty
+            "Client/DisableClipboard|DisableUpstreamAudio=1"</computeroutput>
+          </para>
+
+          <para>
+            Disables one of the VRDE server features: Clipboard or
+            UpstreamAudio respectively. To reenable a feature, use
+            "Client/DisableClipboard=" for example. See
+            <xref linkend="vrde-customization" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeproperty
+            "Client/DisableRDPDR=1"</computeroutput>
+          </para>
+
+          <para>
+            Disables the VRDE server feature: RDP device redirection for
+            smart cards. To reenable this feature, use
+            "Client/DisableRDPR=".
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeproperty
+            "H3DRedirect/Enabled=1"</computeroutput>
+          </para>
+
+          <para>
+            Enables the VRDE server feature: 3D redirection. To disable
+            this feature, use "H3DRedirect/Enabled=".
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeproperty
+            "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=&lt;value&gt;"</computeroutput>
+            sets the desired security method/Path of server certificate,
+            path of server private key, path of CA certificate, used for
+            a connection.
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <computeroutput>--vrdeproperty
+                "Security/Method=&lt;value&gt;"</computeroutput> sets
+                the desired security method, which is used for a
+                connection. Valid values are:
+              </para>
+
+              <itemizedlist>
+
+                <listitem>
+                  <para>
+                    <computeroutput>Negotiate</computeroutput> - both
+                    Enhanced (TLS) and Standard RDP Security connections
+                    are allowed. The security method is negotiated with
+                    the client. This is the default setting.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    <computeroutput>RDP</computeroutput> - only Standard
+                    RDP Security is accepted.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    <computeroutput>TLS</computeroutput> - only Enhanced
+                    RDP Security is accepted. The client must support
+                    TLS.
+                  </para>
+                </listitem>
+
+              </itemizedlist>
+
+              <para>
+                See <xref linkend="vrde-crypt" />.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>--vrdeproperty
+                "Security/ServerCertificate=&lt;value&gt;"</computeroutput>
+                where &lt;value&gt; is the absolute path of the server
+                certificate. Ssee <xref linkend="vrde-crypt" />.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>--vrdeproperty
+                "Security/ServerPrivateKey=&lt;value&gt;"</computeroutput>
+                where &lt;value&gt; is the absolute path of the server
+                private key. See <xref linkend="vrde-crypt" />.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>--vrdeproperty
+                "Security/CACertificate=&lt;value&gt;"</computeroutput>
+                where &lt;value&gt; is the absolute path of the CA self
+                signed certificate. See <xref linkend="vrde-crypt" />.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeproperty
+            "Audio/RateCorrectionMode|LogPath=&lt;value&gt;"</computeroutput>
+            sets the Audio connection mode, or Path of the audio
+            logfile.
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <computeroutput>--vrdeproperty
+                "Audio/RateCorrectionMode=&lt;value&gt;"</computeroutput>
+                where &lt;value&gt; is the desired rate correction mode,
+                allowed values are:
+              </para>
+
+              <itemizedlist>
+
+                <listitem>
+                  <para>
+                    <computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput>
+                    - no mode specified, use to unset any Audio mode
+                    already set.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    <computeroutput>VRDP_AUDIO_MODE_RC</computeroutput>
+                    - rate correction mode.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    <computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput>
+                    - low pass filter mode.
+                  </para>
+                </listitem>
+
+                <listitem>
+                  <para>
+                    <computeroutput>VRDP_AUDIO_MODE_CS</computeroutput>
+                    - client sync mode to prevent under/overflow of the
+                    client queue.
+                  </para>
+                </listitem>
+
+              </itemizedlist>
+            </listitem>
+
+            <listitem>
+              <para>
+                <computeroutput>--vrdeproperty
+                "Audio/LogPath=&lt;value&gt;"</computeroutput> where
+                &lt;value&gt; is the absolute path of the Audio log
+                file.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeextpack
+            default|&lt;name&gt;</computeroutput>: Enables specification
+            of the library for accessing the VM remotely. The default is
+            to use the RDP code which is part of the Oracle VM
+            VirtualBox Extension Pack.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeport
+            default|&lt;ports&gt;</computeroutput>: A port or a range of
+            ports the VRDE server can bind to; "default" or "0" means
+            port 3389, the standard port for RDP. You can specify a
+            comma-separated list of ports or ranges of ports. Use a dash
+            between two port numbers to specify a range. The VRDE server
+            will bind to
+            <emphasis
+            role="bold">one</emphasis> of the
+            available ports from the specified list. Only one machine
+            can use a given port at a time. For example, the option
+            <computeroutput> --vrdeport 5000,5010-5012</computeroutput>
+            will tell the server to bind to one of following ports:
+            5000, 5010, 5011 or 5012.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeaddress &lt;IP
+            address&gt;</computeroutput>: The IP address of the host
+            network interface the VRDE server will bind to. If
+            specified, the server will accept connections only on the
+            specified host network interface.
+          </para>
+
+          <para>
+            The setting can be used to specify whether the VRDP server
             should accept either IPv4, IPv6 or both connections:
-            <itemizedlist>
-              <listitem>
-                <para>only IPv4: <computeroutput>--vrdeaddress "0.0.0.0"
-                </computeroutput></para>
-              </listitem>
-              <listitem>
-                <para>only IPv6: <computeroutput>--vrdeaddress "::"
-                </computeroutput></para>
-              </listitem>
-              <listitem>
-                <para>both IPv6 and IPv4 (default): <computeroutput>--vrdeaddress ""
-                </computeroutput></para>
-              </listitem>
-            </itemizedlist></para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeauthtype
-            null|external|guest</computeroutput>: This enables you to indicate
-            use of authorization, and specify how authorization will be performed;
-            see <xref linkend="vbox-auth" /> for details.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdeauthlibrary
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                Only IPv4: <computeroutput>--vrdeaddress "0.0.0.0"
+                </computeroutput>
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Only IPv6: <computeroutput>--vrdeaddress "::"
+                </computeroutput>
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Both IPv6 and IPv4 (default):
+                <computeroutput>--vrdeaddress "" </computeroutput>
+              </para>
+            </listitem>
+
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeauthtype
+            null|external|guest</computeroutput>: This enables you to
+            indicate use of authorization, and specify how authorization
+            will be performed. See <xref linkend="vbox-auth" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdeauthlibrary
             default|&lt;name&gt;</computeroutput>: This specifies the
-            library used for RDP authentication, see <xref lang=""
-            linkend="vbox-auth" /> for details.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdemulticon on|off</computeroutput>: This
-            enables multiple connections to be made to the same VRDE server, if the
-            server supports this feature; see <xref lang=""
-            linkend="vrde-multiconnection" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdereusecon on|off</computeroutput>: This
-            specifies the VRDE server behavior when multiple connections are
-            disabled. When this option is enabled, the server will allow a new
-            client to connect and will drop the existing connection. When this
-            option is disabled (this is the default setting), a new connection
-            will not be accepted if there is already a client connected to the
-            server.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdevideochannel on|off</computeroutput>:
-            This enables video redirection, if it is supported by the VRDE
-            server; see <xref lang="" linkend="vrde-videochannel" />.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--vrdevideochannelquality
-            &lt;percent&gt;</computeroutput>: Specifies the image quality for video
-            redirection; see <xref lang=""
-            linkend="vrde-videochannel" />.</para>
-          </listitem>
-        </itemizedlist></para>
+            library used for RDP authentication. See
+            <xref 
+            linkend="vbox-auth" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdemulticon on|off</computeroutput>: This
+            enables multiple connections to be made to the same VRDE
+            server, if the server supports this feature. See
+            <xref 
+            linkend="vrde-multiconnection" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdereusecon on|off</computeroutput>: This
+            specifies the VRDE server behavior when multiple connections
+            are disabled. When this option is enabled, the server will
+            allow a new client to connect and will drop the existing
+            connection. When this option is disabled, the default
+            setting, a new connection will not be accepted if there is
+            already a client connected to the server.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdevideochannel on|off</computeroutput>:
+            This enables video redirection, if it is supported by the
+            VRDE server. See <xref linkend="vrde-videochannel" />.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--vrdevideochannelquality
+            &lt;percent&gt;</computeroutput>: Specifies the image
+            quality for video redirection. See
+            <xref 
+            linkend="vrde-videochannel" />.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </sect2>
 
     <sect2 id="vboxmanage-modifyvm-teleport">
-      <title>Teleporting settings</title>
-
-      <para>With the following commands for <computeroutput>VBoxManage
-      modifyvm</computeroutput> you can configure a machine to be a target for
-      teleporting. See <xref linkend="teleporting" /> for an
-      introduction.<itemizedlist>
-          <listitem>
-            <para><computeroutput>--teleporter on|off</computeroutput>:
-            This setting enables/disables the teleporter feature whereby when the
-            machine is started, it waits to receieve a teleporting request from the
-            network instead of booting normally; teleporting requests are received on the
-            port and address specified using the following two parameters.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--teleporterport
-            &lt;port&gt;</computeroutput>, <computeroutput>--teleporteraddress
-            &lt;address&gt;</computeroutput>: these settings must be used with
-            --teleporter and they specify the port and address the virtual machine should
-            listen to to receive a teleporting request sent from another virtual machine.
-            <computeroutput>&lt;port&gt;</computeroutput> can
-            be any free TCP/IP port number (e.g. 6000);
-            <computeroutput>&lt;address&gt;</computeroutput> can be any IP
-            address or hostname and specifies the TCP/IP socket to bind to.
-            The default is "0.0.0.0", which means any address.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--teleporterpassword
-            &lt;password&gt;</computeroutput>: if this optional setting is
-            given, then the teleporting request will only succeed if the
-            source machine specifies the same password as the one given with
-            this command.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--teleporterpasswordfile
-            &lt;password&gt;</computeroutput>: if this optional setting is
-            given, then the teleporting request will only succeed if the
-            source machine specifies the same password as the one specified
-            in the file give with this command. Use <computeroutput>stdin</computeroutput>
-            to read the password from stdin.</para>
-          </listitem>
-
-          <listitem>
-            <para><computeroutput>--cpuid &lt;leaf&gt; &lt;eax&gt; &lt;ebx&gt;
-            &lt;ecx&gt; &lt;edx&gt;</computeroutput>: Advanced users can use
-            this setting  before a teleporting operation to restrict the
-            virtual CPU capabilities that VirtualBox presents to the guest
-            operating system. This must be run on both the source and the
-            target machines involved in the teleporting and will then modify
-            what the guest sees when it executes the
-            <computeroutput>CPUID</computeroutput> machine instruction. This
-            might help with misbehaving applications that wrongly assume that
-            certain CPU capabilities are present. The meaning of the
-            parameters is hardware dependent; please refer to the AMD or Intel
-            processor manuals.</para>
-          </listitem>
-        </itemizedlist></para>
+
+      <title>Teleporting Settings</title>
+
+      <para>
+        With the following commands for <computeroutput>VBoxManage
+        modifyvm</computeroutput> you can configure a machine to be a
+        target for teleporting. See <xref linkend="teleporting" />.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <computeroutput>--teleporter on|off</computeroutput>: This
+            setting enables/disables the teleporter feature whereby when
+            the machine is started, it waits to receieve a teleporting
+            request from the network instead of booting normally.
+            Teleporting requests are received on the port and address
+            specified using the following parameters.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--teleporterport
+            &lt;port&gt;</computeroutput>,
+            <computeroutput>--teleporteraddress
+            &lt;address&gt;</computeroutput>: These settings must be
+            used with --teleporter and they specify the port and address
+            the virtual machine should listen to to receive a
+            teleporting request sent from another virtual machine.
+            <computeroutput>&lt;port&gt;</computeroutput> can be any
+            free TCP/IP port number, such as 6000.
+            <computeroutput>&lt;address&gt;</computeroutput> can be any
+            IP address or hostname and specifies the TCP/IP socket to
+            bind to. The default is "0.0.0.0", which means any address.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--teleporterpassword
+            &lt;password&gt;</computeroutput>: If this optional setting
+            is given, then the teleporting request will only succeed if
+            the source machine specifies the same password as the one
+            given with this command.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--teleporterpasswordfile
+            &lt;password&gt;</computeroutput>: If this optional setting
+            is given, then the teleporting request will only succeed if
+            the source machine specifies the same password as the one
+            specified in the file give with this command. Use
+            <computeroutput>stdin</computeroutput> to read the password
+            from stdin.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--cpuid &lt;leaf&gt; &lt;eax&gt; &lt;ebx&gt;
+            &lt;ecx&gt; &lt;edx&gt;</computeroutput>: Advanced users can
+            use this setting before a teleporting operation to restrict
+            the virtual CPU capabilities that VirtualBox presents to the
+            guest operating system. This must be run on both the source
+            and the target machines involved in the teleporting and will
+            then modify what the guest sees when it executes the
+            <computeroutput>CPUID</computeroutput> machine instruction.
+            This might help with misbehaving applications that wrongly
+            assume that certain CPU capabilities are present. The
+            meaning of the parameters is hardware dependent, refer to
+            the AMD or Intel processor documentation.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </sect2>
 
     <sect2 id="vboxmanage-modifyvm-debugging">
-      <title>Debugging settings</title>
-
-      <para>The following settings are only relevant for low-level VM
-      debugging. Regular users will never need these settings.<itemizedlist>
-          <listitem>
-            <para><computeroutput>--tracing-enabled on|off</computeroutput>:
-            Enable the tracebuffer. This consumes some memory for the tracebuffer
-            and adds extra overhead.</para>
-          </listitem>
-          <listitem>
-            <para><computeroutput>--tracing-config &lt;config-string&gt;</computeroutput>:
-            Enables tracing configuration. In particular, this defines which group of
-            tracepoints are enabled.</para>
-          </listitem>
-          <listitem>
-            <para><computeroutput>--tracing-allow-vm-access on|off</computeroutput>:
-            Enables/disables(default) VM access to the tracebuffer.</para>
-          </listitem>
-        </itemizedlist>
+
+      <title>Debugging Settings</title>
+
+      <para>
+        The following settings are only relevant for low-level VM
+        debugging. Regular users will never need these settings.
       </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <computeroutput>--tracing-enabled on|off</computeroutput>:
+            Enable the tracebuffer. This consumes some memory for the
+            tracebuffer and adds extra overhead.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--tracing-config
+            &lt;config-string&gt;</computeroutput>: Enables tracing
+            configuration. In particular, this defines which group of
+            tracepoints are enabled.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--tracing-allow-vm-access
+            on|off</computeroutput>: Enables/disables (default) VM
+            access to the tracebuffer.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
     </sect2>
 
     <sect2 id="vboxmanage-usbcardreader">
-      <title>USB card reader settings</title>
-
-      <para>The following setting defines access to a USB Card Reader by the guest environment.
-      USB card readers are typically used for accessing data on memory cards such as
-      CompactFlash (CF), Secure Digital (SD) or MultiMediaCard (MMC).</para>
+
+      <title>USB Card Reader Settings</title>
+
+      <para>
+        The following setting defines access to a USB Card Reader by the
+        guest environment. USB card readers are typically used for
+        accessing data on memory cards such as CompactFlash (CF), Secure
+        Digital (SD), or MultiMediaCard (MMC).
+      </para>
+
       <itemizedlist>
-          <listitem>
-            <para><computeroutput>--usbcardreader on|off</computeroutput>:
-            Enables/disables the USB card reader interface.</para>
-          </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--usbcardreader on|off</computeroutput>:
+            Enables/disables the USB card reader interface.
+          </para>
+        </listitem>
+
       </itemizedlist>
+
     </sect2>
 
     <sect2 id="vboxmanage-autostart">
-      <title>Auto starting VMs during host system boot</title>
-
-      <para>These settings configure the VM autostart feature,
-      which automatically starts the VM at host system boot-up.
-      Note that there are pre-requisites that need to be addressed before using this feature.
-      See <xref lang="" linkend="autostart" /> for more details.</para>
+
+      <title>Autostarting VMs During Host System Boot</title>
+
+      <para>
+        These settings configure the VM autostart feature, which
+        automatically starts the VM at host system boot-up. Note that
+        there are prerequisites that need to be addressed before using
+        this feature. See <xref linkend="autostart" />.
+      </para>
+
       <itemizedlist>
-        <listitem>
-          <para><computeroutput>--autostart-enabled on|off</computeroutput>:
-          Enables/disables VM autostart at host system boot-up, using specified user name.</para>
-        </listitem>
-        <listitem>
-          <para><computeroutput>--autostart-delay &lt;seconds&gt;</computeroutput>:
-          Specifies a delay (seconds) following host system boot-up, before VM autostarts.</para>
-        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--autostart on|off</computeroutput>:
+            Enables/disables VM autostart at host system boot-up, using
+            specified user name.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <computeroutput>--autostart-delay
+            &lt;seconds&gt;</computeroutput>: Specifies a delay
+            (seconds) following host system boot-up, before VM
+            autostarts.
+          </para>
+        </listitem>
+
       </itemizedlist>
+
     </sect2>
+
   </sect1>
 
   <sect1 id="vboxmanage-clonevm">
+
     <title>VBoxManage clonevm</title>
 
-    <para>This command creates a full or linked copy of an existing virtual
-    machine.</para>
-
-    <para>The <computeroutput>clonevm</computeroutput> subcommand takes at
-    least the name of the virtual machine which should be cloned. The following
-    additional settings can be used to further configure the clone VM
-    operation:</para>
+    <para>
+      This command creates a full or linked copy of an existing virtual
+      machine.
+    </para>
+
+    <para>
+      The <computeroutput>clonevm</computeroutput> subcommand takes at
+      least the name of the virtual machine which should be cloned. The
+      following additional settings can be used to further configure the
+      clone VM operation:
+    </para>
 
     <itemizedlist>
-       <listitem>
-           <para><computeroutput>--snapshot &lt;uuid&gt;|&lt;name&gt;</computeroutput>:
-            Select a specific snapshot where the clone operation should refer
-            to. Default is referring to the current state.</para>
-       </listitem>
-       <listitem>
-           <para><computeroutput>--mode machine|machineandchildren|all</computeroutput>:
-           Selects the cloning mode of the operation. If
-           <computeroutput>machine</computeroutput> is selected (the default),
-           the current state of the VM without any snapshots is cloned. In the
-           <computeroutput>machineandchildren</computeroutput> mode the snapshot
-           provided by <computeroutput>--snapshot</computeroutput> and all
-           child snapshots are cloned. If <computeroutput>all</computeroutput>
-           is the selected mode all snapshots and the current state are cloned.
-           </para>
-       </listitem>
-       <listitem>
-           <para><computeroutput>--options link|keepallmacs|keepnatmacs|keepdisknames</computeroutput>:
-           Allows additional fine tuning of the clone operation. The first
-           option defines that a linked clone should be created, which is
-           only possible for a machine cloned from a snapshot. The next two
-           options enable specification of the handling of MAC addresses of
-           every virtual network card. They can either be reinitialized
-           (the default), left unchanged
-           (<computeroutput>keepallmacs</computeroutput>) or left unchanged
-           when the network type is NAT
-           (<computeroutput>keepnatmacs</computeroutput>). If you add
-           <computeroutput>keepdisknames</computeroutput> all new disk images
-           are called like the original ones, otherwise they are
-           renamed.</para>
-       </listitem>
-       <listitem>
-           <para><computeroutput>--name &lt;name&gt;</computeroutput>: Select a
-           new name for the new virtual machine. Default is "Original Name
-           Clone".</para>
-       </listitem>
-       <listitem>
-           <para><computeroutput>--groups &lt;group&gt;, ...</computeroutput>
-           Enables the clone to be assigned membership of the specified
-           VM groups in the list. Note that group ids always start with a
-           <computeroutput>/</computeroutput> and can be nested. By default,
-           clones are always assigned membership of the group
-           <computeroutput>/</computeroutput>.</para>
-       </listitem>
-       <listitem>
-           <para><computeroutput>--basefolder &lt;basefolder&gt;</computeroutput>:
-           Select the folder where the new virtual machine configuration should
-           be saved in.</para>
-       </listitem>
-       <listitem>
-           <para><computeroutput>--uuid &lt;uuid&gt;</computeroutput>:
-           Select the UUID the new VM should have. This id has to be unique in
-           the VirtualBox instance this clone should be registered. Default is
-           creating a new UUID.</para>
-       </listitem>
-       <listitem>
-           <para><computeroutput>--register</computeroutput>:
-           Automatically register the new clone in this VirtualBox
-           installation. If you manually want to register the new VM later, see
-           <xref linkend="vboxmanage-registervm" /> for instructions how to do
-           so.</para>
-       </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--snapshot
+          &lt;uuid&gt;|&lt;name&gt;</computeroutput>: Select a specific
+          snapshot where the clone operation should refer to. Default is
+          referring to the current state.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--mode
+          machine|machineandchildren|all</computeroutput>: Selects the
+          cloning mode of the operation. If
+          <computeroutput>machine</computeroutput> is selected (the
+          default), the current state of the VM without any snapshots is
+          cloned. In the
+          <computeroutput>machineandchildren</computeroutput> mode the
+          snapshot provided by
+          <computeroutput>--snapshot</computeroutput> and all child
+          snapshots are cloned. If <computeroutput>all</computeroutput>
+          is the selected mode all snapshots and the current state are
+          cloned.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--options
+          link|keepallmacs|keepnatmacs|keepdisknames</computeroutput>:
+          Allows additional fine tuning of the clone operation. The
+          first option defines that a linked clone should be created,
+          which is only possible for a machine cloned from a snapshot.
+          The next two options enable specification of the handling of
+          MAC addresses of every virtual network card. They can either
+          be reinitialized (the default), left unchanged
+          (<computeroutput>keepallmacs</computeroutput>) or left
+          unchanged when the network type is NAT
+          (<computeroutput>keepnatmacs</computeroutput>). If you add
+          <computeroutput>keepdisknames</computeroutput> all new disk
+          images are called like the original ones, otherwise they are
+          renamed.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--name &lt;name&gt;</computeroutput>: Select a
+          new name for the new virtual machine. Default is "Original
+          Name Clone".
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--groups &lt;group&gt;, ...</computeroutput>
+          Enables the clone to be assigned membership of the specified
+          VM groups in the list. Note that group ids always start with a
+          <computeroutput>/</computeroutput> and can be nested. By
+          default, clones are always assigned membership of the group
+          <computeroutput>/</computeroutput>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--basefolder
+          &lt;basefolder&gt;</computeroutput>: Select the folder where
+          the new virtual machine configuration should be saved in.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--uuid &lt;uuid&gt;</computeroutput>: Select
+          the UUID the new VM should have. This ID has to be unique in
+          the VirtualBox instance this clone should be registered.
+          Default is creating a new UUID.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--register</computeroutput>: Automatically
+          register the new clone in this VirtualBox installation. If you
+          manually want to register the new VM later, see
+          <xref linkend="vboxmanage-registervm" />.
+        </para>
+      </listitem>
+
     </itemizedlist>
+
   </sect1>
 
   <sect1 id="vboxmanage-import">
+
     <title>VBoxManage import</title>
 
-    <para>This command imports a virtual appliance in OVF format by copying
-    the virtual disk images and creating virtual machines in VirtualBox. See
-    <xref linkend="ovf" /> for an introduction to appliances.</para>
-
-    <para>The <computeroutput>import</computeroutput> subcommand takes at
-    least the path name of an OVF file as input and expects the disk images,
-    if needed, in the same directory as the OVF file. A lot of additional
-    command-line options are supported to control in detail what is being
-    imported and modify the import parameters, but the details depend on the
-    content of the OVF file.</para>
-
-    <para>It is therefore recommended to first run the import subcommand with
-    the <computeroutput>--dry-run</computeroutput> or
-    <computeroutput>-n</computeroutput> option. This will then print a
-    description of the appliance's contents to the screen how it would be
-    imported into VirtualBox, together with the optional command-line options
-    to influence the import behavior.</para>
-
-    <para>Use of the <computeroutput>--options link|keepallmacs|keepnatmacs|keepdisknames</computeroutput>:
-    option enables additional fine tuning of the clone operation. The first
-    option defines that a linked clone should be created, which is
-    only possible for a machine clone from a snapshot. The next two
-    options enable specification of how the MAC addresses of every virtual
-    network card should be handled. They can either be reinitialized
-    (the default), left unchanged
-    (<computeroutput>keepallmacs</computeroutput>) or left unchanged
-    when the network type is NAT
-    (<computeroutput>keepnatmacs</computeroutput>). If you add
-    <computeroutput>keepdisknames</computeroutput> all new disk images
-    are assigned the same names as the originals, otherwise they are
-    renamed.</para>
-
-    <para>As an example, here is the screen output with a sample appliance
-    containing a Windows XP guest:<screen>VBoxManage import WindowsXp.ovf --dry-run
+    <para>
+      This command imports a virtual appliance in OVF format by copying
+      the virtual disk images and creating virtual machines in
+      VirtualBox. See <xref linkend="ovf" /> for an introduction to
+      appliances.
+    </para>
+
+    <para>
+      The <computeroutput>import</computeroutput> subcommand takes at
+      least the path name of an OVF file as input and expects the disk
+      images, if needed, in the same directory as the OVF file. A lot of
+      additional command-line options are supported to control in detail
+      what is being imported and modify the import parameters, but the
+      details depend on the content of the OVF file.
+    </para>
+
+    <para>
+      It is therefore recommended to first run the import subcommand
+      with the <computeroutput>--dry-run</computeroutput> or
+      <computeroutput>-n</computeroutput> option. This will then print a
+      description of the appliance's contents to the screen how it would
+      be imported into VirtualBox, together with the optional
+      command-line options to influence the import behavior.
+    </para>
+
+    <para>
+      Use of the <computeroutput>--options
+      link|keepallmacs|keepnatmacs|keepdisknames</computeroutput>:
+      option enables additional fine tuning of the clone operation. The
+      first option defines that a linked clone should be created, which
+      is only possible for a machine clone from a snapshot. The next two
+      options enable specification of how the MAC addresses of every
+      virtual network card should be handled. They can either be
+      reinitialized (the default), left unchanged
+      (<computeroutput>keepallmacs</computeroutput>) or left unchanged
+      when the network type is NAT
+      (<computeroutput>keepnatmacs</computeroutput>). If you add
+      <computeroutput>keepdisknames</computeroutput> all new disk images
+      are assigned the same names as the originals, otherwise they are
+      renamed.
+    </para>
+
+    <para>
+      As an example, here is the screen output with a sample appliance
+      containing a Windows XP guest:
+    </para>
+
+<screen>VBoxManage import WindowsXp.ovf --dry-run
 Interpreting WindowsXp.ovf...
 OK.
@@ -1951,818 +2807,1229 @@
       target path=/home/user/disks/WindowsXp.vmdk, controller=9;channel=0
     (change controller with "--vsys 0 --unit 11 --controller &lt;id&gt;";
-    disable with "--vsys 0 --unit 11 --ignore")</screen></para>
-
-    <para>As you can see, the individual configuration items are numbered, and
-    depending on their type support different command-line options. The import
-    subcommand can be directed to ignore many such items with a
-    <computeroutput>--vsys X --unit Y --ignore</computeroutput> option, where
-    X is the number of the virtual system (zero unless there are several
-    virtual system descriptions in the appliance) and Y the item number, as
-    printed on the screen.</para>
-
-    <para>In the above example, Item #1 specifies the name of the target
-    machine in VirtualBox. Items #9 and #10 specify hard disk controllers,
-    respectively. Item #11 describes a hard disk image; in this case, the
-    additional <computeroutput>--controller</computeroutput> option indicates
-    which item the disk image should be connected to, with the default coming
-    from the OVF file.</para>
-
-    <para>You can combine several items for the same virtual system behind the
-    same <computeroutput>--vsys</computeroutput> option. For example, to
-    import a machine as described in the OVF, but without the sound card and
-    without the USB controller, and with the disk image connected to the IDE
-    controller instead of the SCSI controller, use this:<screen>VBoxManage import WindowsXp.ovf
-      --vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen></para>
+    disable with "--vsys 0 --unit 11 --ignore")</screen>
+
+    <para>
+      The individual configuration items are numbered, and depending on
+      their type support different command-line options. The import
+      subcommand can be directed to ignore many such items with a
+      <computeroutput>--vsys X --unit Y --ignore</computeroutput>
+      option, where X is the number of the virtual system (zero unless
+      there are several virtual system descriptions in the appliance)
+      and Y the item number, as printed on the screen.
+    </para>
+
+    <para>
+      In the above example, Item #1 specifies the name of the target
+      machine in VirtualBox. Items #9 and #10 specify hard disk
+      controllers, respectively. Item #11 describes a hard disk image;
+      in this case, the additional
+      <computeroutput>--controller</computeroutput> option indicates
+      which item the disk image should be connected to, with the default
+      coming from the OVF file.
+    </para>
+
+    <para>
+      You can combine several items for the same virtual system behind
+      the same <computeroutput>--vsys</computeroutput> option. For
+      example, to import a machine as described in the OVF, but without
+      the sound card and without the USB controller, and with the disk
+      image connected to the IDE controller instead of the SCSI
+      controller, use this command:
+    </para>
+
+<screen>VBoxManage import WindowsXp.ovf
+      --vsys 0 --unit 5 --ignore --unit 6 --ignore --unit 11 --controller 10</screen>
+
   </sect1>
 
   <sect1 id="vboxmanage-export">
+
     <title>VBoxManage export</title>
 
-    <para>This command exports one or more virtual machines from VirtualBox
-    into a virtual appliance in OVF format, including copying their virtual
-    disk images to compressed VMDK. See <xref linkend="ovf" /> for an
-    introduction to appliances.</para>
-
-    <para>The <computeroutput>export</computeroutput> command is simple to
-    use: list the machine (or the machines) that you would like to export to
-    the same OVF file and specify the target OVF file after an additional
-    <computeroutput>--output</computeroutput> or
-    <computeroutput>-o</computeroutput> option. Note that the directory of the
-    target OVF file will also receive the exported disk images in the
-    compressed VMDK format (regardless of the original format) and should have
-    enough disk space left for them.</para>
-
-    <para>Beside a simple export of a given virtual machine, you can append
-    several product information to the appliance file. Use
-    <computeroutput>--product</computeroutput>,
-    <computeroutput>--producturl</computeroutput>,
-    <computeroutput>--vendor</computeroutput>,
-    <computeroutput>--vendorurl</computeroutput>,
-    <computeroutput>--version</computeroutput> and
-    <computeroutput>--description</computeroutput> to specify this additional
-    information. For legal reasons you may add a license text or the content
-    of a license file by using the <computeroutput>--eula</computeroutput> and
-    <computeroutput>--eulafile</computeroutput> option respectively. As with
-    OVF import, you must use the <computeroutput>--vsys X</computeroutput>
-    option to direct the previously mentioned options to the correct virtual
-    machine.</para>
-
-    <para>For virtualization products which aren't fully compatible with the
-    OVF standard 1.0 you can enable a OVF 0.9 legacy mode with the
-    <computeroutput>--legacy09</computeroutput> option. Other options are
-    <computeroutput>--ovf09</computeroutput>,
-    <computeroutput>--ovf10</computeroutput>,
-    <computeroutput>--ovf20</computeroutput>.</para>
-
-    <para>To specify options controlling the exact content of the appliance
-    file, you can use <computeroutput>--options</computeroutput> to request the
-    creation of a manifest file (encouraged, allows detection of corrupted
-    appliances on import), the additional export of DVD images, and the
-    exclusion of MAC addresses. You can specify a list of options, e.g.
-    <computeroutput>--options manifest,nomacs</computeroutput>. For details,
-    check the help output of <computeroutput>VBoxManage export</computeroutput>.</para>
+    <para>
+      This command exports one or more virtual machines from VirtualBox
+      into a virtual appliance in OVF format, including copying their
+      virtual disk images to compressed VMDK. See <xref linkend="ovf" />
+      for an introduction to appliances.
+    </para>
+
+    <para>
+      The <computeroutput>export</computeroutput> command is simple to
+      use: list the machine (or the machines) that you would like to
+      export to the same OVF file and specify the target OVF file after
+      an additional <computeroutput>--output</computeroutput> or
+      <computeroutput>-o</computeroutput> option. Note that the
+      directory of the target OVF file will also receive the exported
+      disk images in the compressed VMDK format (regardless of the
+      original format) and should have enough disk space left for them.
+    </para>
+
+    <para>
+      Beside a simple export of a given virtual machine, you can append
+      several product information to the appliance file. Use
+      <computeroutput>--product</computeroutput>,
+      <computeroutput>--producturl</computeroutput>,
+      <computeroutput>--vendor</computeroutput>,
+      <computeroutput>--vendorurl</computeroutput>,
+      <computeroutput>--version</computeroutput> and
+      <computeroutput>--description</computeroutput> to specify this
+      additional information. For legal reasons you may add a license
+      text or the content of a license file by using the
+      <computeroutput>--eula</computeroutput> and
+      <computeroutput>--eulafile</computeroutput> option respectively.
+      As with OVF import, you must use the <computeroutput>--vsys
+      X</computeroutput> option to direct the previously mentioned
+      options to the correct virtual machine.
+    </para>
+
+    <para>
+      For virtualization products which are not fully compatible with
+      the OVF standard 1.0 you can enable an OVF 0.9 legacy mode with
+      the <computeroutput>--legacy09</computeroutput> option. Other
+      options are <computeroutput>--ovf09</computeroutput>,
+      <computeroutput>--ovf10</computeroutput>,
+      <computeroutput>--ovf20</computeroutput>.
+    </para>
+
+    <para>
+      To specify options controlling the exact content of the appliance
+      file, you can use <computeroutput>--options</computeroutput> to
+      request the creation of a manifest file, which allows detection of
+      corrupted appliances on import, the additional export of DVD
+      images, and the exclusion of MAC addresses. You can specify a list
+      of options, such as <computeroutput>--options
+      manifest,nomacs</computeroutput>. For details, check the help
+      output of <computeroutput>VBoxManage export</computeroutput>.
+    </para>
+
   </sect1>
 
   <sect1 id="vboxmanage-startvm">
+
     <title>VBoxManage startvm</title>
 
-    <para>This command starts a virtual machine that is currently in the
-    "Powered off" or "Saved" states.</para>
-
-    <para>The optional <computeroutput>--type</computeroutput> specifier
-    determines whether the machine will be started in a window or whether the
-    output should go through <computeroutput>VBoxHeadless</computeroutput>,
-    with VRDE enabled or not; see <xref linkend="vboxheadless" /> for more
-    information. The list of types is subject to change, and it's not
-    guaranteed that all types are accepted by any product variant.</para>
-
-    <para>The global or per-VM default value for the VM frontend type will be
-    taken if the type is not explicitly specified. If none of these are set,
-    the GUI variant will be started.</para>
-
-    <para>The following values are allowed:</para>
-
-    <glosslist>
-      <glossentry>
-        <glossterm><computeroutput>gui</computeroutput></glossterm>
-
-        <glossdef>
-          <para>Starts a VM showing a GUI window. This is the default.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm><computeroutput>headless</computeroutput></glossterm>
-
-        <glossdef>
-          <para>Starts a VM without a window for remote display only.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm><computeroutput>sdl</computeroutput></glossterm>
-
-        <glossdef>
-          <para>Starts a VM with a minimal GUI and limited features.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm><computeroutput>separate</computeroutput></glossterm>
-
-        <glossdef>
-          <para>Starts a VM with detachable UI (technically it is a headless VM
-            with user interface in a separate process). This is an experimental
-            feature as it lacks certain functionality at the moment (e.g. 3D
-            acceleration will not work).</para>
-        </glossdef>
-      </glossentry>
-    </glosslist>
+    <para>
+      This command starts a virtual machine that is currently in the
+      "Powered off" or "Saved" states.
+    </para>
+
+    <para>
+      The optional <computeroutput>--type</computeroutput> specifier
+      determines whether the machine will be started in a window or
+      whether the output should go through
+      <computeroutput>VBoxHeadless</computeroutput>, with VRDE enabled
+      or not. See <xref linkend="vboxheadless" />. The list of types is
+      subject to change, and it is not guaranteed that all types are
+      accepted by any product variant.
+    </para>
+
+    <para>
+      The global or per-VM default value for the VM frontend type will
+      be taken if the type is not explicitly specified. If none of these
+      are set, the GUI variant will be started.
+    </para>
+
+    <para>
+      The following values are allowed:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>gui</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Starts a VM showing a GUI window. This is the default.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>headless</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Starts a VM without a window for remote display only.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>sdl</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Starts a VM with a minimal GUI and limited features.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>separate</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Starts a VM with detachable UI. Technically, it is a
+            headless VM with user interface in a separate process. This
+            is an experimental feature as it lacks certain
+            functionality, such as 3D acceleration, at the moment.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
 
     <note>
-      <para>If you experience problems with starting virtual machines with
-      particular frontends and there is no conclusive error information,
-      consider starting virtual machines directly by running the respective
-      front-end, as this can give additional error information.</para>
+      <para>
+        If you experience problems with starting virtual machines with
+        particular frontends and there is no conclusive error
+        information, consider starting virtual machines directly by
+        running the respective front-end, as this can give additional
+        error information.
+      </para>
     </note>
+
   </sect1>
 
   <sect1 id="vboxmanage-controlvm">
+
     <title>VBoxManage controlvm</title>
 
-    <para>The <computeroutput>controlvm</computeroutput> subcommand allows you
-    to change the state of a virtual machine that is currently running. The
-    following can be specified:</para>
-
-    <para><itemizedlist>
-        <listitem>
-          <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
-          pause</computeroutput> temporarily puts a virtual machine on hold,
-          without changing its state for good. The VM window will be painted
-          in gray to indicate that the VM is currently paused. (This is
-          equivalent to selecting the "Pause" item in the "Machine" menu of
-          the GUI).</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>VBoxManage controlvm &lt;vm&gt;
+    <para>
+      The <computeroutput>controlvm</computeroutput> subcommand allows
+      you to change the state of a virtual machine that is currently
+      running. The following can be specified:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxManage controlvm &lt;vm&gt;
+          pause</computeroutput> temporarily puts a virtual machine on
+          hold, without changing its state for good. The VM window will
+          be painted in gray to indicate that the VM is currently
+          paused. This is equivalent to selecting the "Pause" item in
+          the "Machine" menu of the GUI.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>VBoxManage controlvm &lt;vm&gt;
           resume</computeroutput> to undo a previous
-          <computeroutput>pause</computeroutput> command. (This is equivalent
-          to selecting the "Resume" item in the "Machine" menu of the
-          GUI.)</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
-          reset</computeroutput> has the same effect on a virtual machine as
-          pressing the "Reset" button on a real computer: a cold reboot of the
-          virtual machine, which will restart and boot the guest operating
-          system again immediately. The state of the VM is not saved
-          beforehand, and data may be lost. (This is equivalent to selecting
-          the "Reset" item in the "Machine" menu of the GUI).</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
-          poweroff</computeroutput> has the same effect on a virtual machine
-          as pulling the power cable on a real computer. Again, the state of
-          the VM is not saved beforehand, and data may be lost. (This is
-          equivalent to selecting the "Close" item in the "Machine" menu of
-          the GUI or pressing the window's close button, and then selecting
-          "Power off the machine" in the dialog).</para>
-
-          <para>After this, the VM's state will be "Powered off". From there,
-          it can be started again; see <xref
-          linkend="vboxmanage-startvm" />.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
-          savestate</computeroutput> will save the current state of the VM to
-          disk and then stop the VM. (This is equivalent to selecting the
-          "Close" item in the "Machine" menu of the GUI or pressing the
-          window's close button, and then selecting "Save the machine state"
-          in the dialog.)</para>
-
-          <para>After this, the VM's state will be "Saved". From there, it can
-          be started again; see <xref linkend="vboxmanage-startvm" />.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
-          acpipowerbutton</computeroutput> will send an ACPI shutdown signal to
-          the VM, as if the power button on a real computer had been pressed.
-          So long as the VM is running a fairly modern guest operating system
-          providing ACPI support, this should trigger a proper shutdown mechanism
-          from within the VM.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxManage controlvm &lt;vm&gt;
-          keyboardputscancode &lt;hex&gt; [&lt;hex&gt;...]</computeroutput>
-          Sends commands using keycodes to the VM. Keycodes are documented in the
-          public domain, e.g. http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>VBoxManage controlvm "VM name" teleport
+          <computeroutput>pause</computeroutput> command. This is
+          equivalent to selecting the "Resume" item in the "Machine"
+          menu of the GUI.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxManage controlvm &lt;vm&gt;
+          reset</computeroutput> has the same effect on a virtual
+          machine as pressing the "Reset" button on a real computer: a
+          cold reboot of the virtual machine, which will restart and
+          boot the guest operating system again immediately. The state
+          of the VM is not saved beforehand, and data may be lost. This
+          is equivalent to selecting the "Reset" item in the "Machine"
+          menu of the GUI.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxManage controlvm &lt;vm&gt;
+          poweroff</computeroutput> has the same effect on a virtual
+          machine as pulling the power cable on a real computer. Again,
+          the state of the VM is not saved beforehand, and data may be
+          lost. This is equivalent to selecting the "Close" item in the
+          "Machine" menu of the GUI or pressing the window's close
+          button, and then selecting "Power off the machine" in the
+          dialog.
+        </para>
+
+        <para>
+          After this, the VM's state will be "Powered off". From there,
+          it can be started again. See
+          <xref
+          linkend="vboxmanage-startvm" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxManage controlvm &lt;vm&gt;
+          savestate</computeroutput> will save the current state of the
+          VM to disk and then stop the VM. This is equivalent to
+          selecting the "Close" item in the "Machine" menu of the GUI or
+          pressing the window's close button, and then selecting "Save
+          the machine state" in the dialog.
+        </para>
+
+        <para>
+          After this, the VM's state will be "Saved". From there, it can
+          be started again. See <xref linkend="vboxmanage-startvm" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxManage controlvm &lt;vm&gt;
+          acpipowerbutton</computeroutput> will send an ACPI shutdown
+          signal to the VM, as if the power button on a real computer
+          had been pressed. So long as the VM is running a fairly modern
+          guest operating system providing ACPI support, this should
+          trigger a proper shutdown mechanism from within the VM.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxManage controlvm &lt;vm&gt;
+          keyboardputscancode &lt;hex&gt;
+          [&lt;hex&gt;...]</computeroutput> Sends commands using
+          keycodes to the VM. Keycodes are documented in the public
+          domain, e.g.
+          http://www.win.tue.nl/~aeb/linux/kbd/scancodes-1.html.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>VBoxManage controlvm "VM name" teleport
           --hostname &lt;name&gt; --port &lt;port&gt; [--passwordfile
-          &lt;file&gt; | --password &lt;password&gt;]</computeroutput> makes
-          the machine the source of a teleporting operation and initiates a
-          teleport to the given target. See <xref linkend="teleporting" /> for
-          an introduction. If the optional password is specified, it must match
-          the password that was given to the
-          <computeroutput>modifyvm</computeroutput> command for the target
-          machine; see <xref linkend="vboxmanage-modifyvm-teleport" /> for
-          details.</para>
-        </listitem>
-    </itemizedlist></para>
-
-    <para>A few extra options are available with
-    <computeroutput>controlvm</computeroutput> that do not directly affect the
-    VM's running state:</para>
+          &lt;file&gt; | --password &lt;password&gt;]</computeroutput>
+          makes the machine the source of a teleporting operation and
+          initiates a teleport to the given target. See
+          <xref linkend="teleporting" /> for an introduction. If the
+          optional password is specified, it must match the password
+          that was given to the
+          <computeroutput>modifyvm</computeroutput> command for the
+          target machine. See
+          <xref linkend="vboxmanage-modifyvm-teleport" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      A few extra options are available with
+      <computeroutput>controlvm</computeroutput> that do not directly
+      affect the VM's running state:
+    </para>
 
     <itemizedlist>
-      <listitem>
-        <para>The <computeroutput>setlinkstate&lt;1-N&gt;</computeroutput>
-        operation connects or disconnects virtual network cables from their
-        network interfaces.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>nic&lt;1-N&gt;
-        null|nat|bridged|intnet|hostonly|generic|natnetwork[&lt;devicename&gt;]</computeroutput>:
-        specifies the type of networking that should be made available on the specified VM
-        virtual network card.
-        They can be: not connected to the host
-        (<computeroutput>null</computeroutput>), use network address
-        translation (<computeroutput>nat</computeroutput>), bridged networking
-        (<computeroutput>bridged</computeroutput>) or communicate with other
-        virtual machines using internal networking
-        (<computeroutput>intnet</computeroutput>) or host-only networking
-        (<computeroutput>hostonly</computeroutput>) or natnetwork networking
-        (<computeroutput>natnetwork</computeroutput>) or access to rarely used
-        sub-modes
-        (<computeroutput>generic</computeroutput>).
-        These options correspond to the modes which are described in detail in <xref
-        linkend="networkingmodes" />.</para>
-      </listitem>
-
-      <listitem>
-        <para>With the "nictrace" options, you can optionally trace network traffic by dumping
-        it to a file, for debugging purposes.</para>
-
-        <para>With <computeroutput>nictrace&lt;1-N&gt;
-        on|off</computeroutput>, you can enable network tracing for a particular virtual
-        network card.</para>
-
-        <para>If enabled, you must specify with
-        <computeroutput>--nictracefile&lt;1-N&gt;
-        &lt;filename&gt;</computeroutput> the pathname of the file to which the trace should be
-        logged.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>nicpromisc&lt;1-N&gt;
-        deny|allow-vms|allow-all</computeroutput>:
-        This specifies how the promiscious mode is handled for the specified VM
-        virtual network card. This setting is only relevant for bridged networking.
-        <computeroutput>deny</computeroutput> (default setting) hides
-        any traffic not intended for this VM.
-        <computeroutput>allow-vms</computeroutput> hides all host
-        traffic from this VM but allows the VM to see traffic from/to other
-        VMs.
-        <computeroutput>allow-all</computeroutput> removes this
-        restriction completely.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>nicproperty&lt;1-N&gt;
-        &lt;paramname&gt;="paramvalue"</computeroutput>:
-        This option, in combination with "nicgenericdrv" enables you to
-        pass parameters to rarely-used network backends.</para><para>
-        Those parameters are backend engine-specific, and are different
-        between UDP Tunnel and the VDE backend drivers. For example,
-        please see <xref linkend="network_udp_tunnel" />.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>natpf&lt;1-N&gt;
-        [&lt;name&gt;],tcp|udp,[&lt;hostip&gt;],&lt;hostport&gt;,[&lt;guestip&gt;],
-        &lt;guestport&gt;</computeroutput>: This option specifies a NAT
-        port-forwarding rule (please see <xref linkend="natforward"/>
-        for details).
-        </para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>natpf&lt;1-N&gt; delete
-        &lt;name&gt;</computeroutput>: This option deletes a NAT
-        port-forwarding rule (please see <xref linkend="natforward"/>
-        for details).</para>
-      </listitem>
-
-      <listitem>
-        <para>The <computeroutput>guestmemoryballoon&lt;balloon size in MB&gt;</computeroutput>
-        operation changes the size of the guest memory balloon, that is,
-        memory allocated by the VirtualBox Guest Additions from the guest
-        operating system and returned to the hypervisor for re-use by other
-        virtual machines. This must be specified in megabytes. For details,
-        see <xref linkend="guestadd-balloon" />.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>usbattach&lt;uuid|address&gt; [--capturefile &lt;filename&gt;]</computeroutput></para>
-        <para>and <computeroutput>usbdetach &lt;uuid|address&gt; [--capturefile &lt;filename&gt;]</computeroutput>
-        make host USB devices visible/invisible to the virtual machine on the fly, without the need for
-        creating filters first. The USB devices can be specified by UUID
-        (unique identifier) or by address on the host system. Use the --capturefile
-        option to specify the absolute path of a file for writing activity logging data.</para>
-
-        <para>You can use <computeroutput>VBoxManage list
-        usbhost</computeroutput> to locate this information.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>audioin on</computeroutput>: With
-        this setting, you can select whether capturing audio from the
-        host is enabled or disabled.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>audioout on</computeroutput>: With
-        this setting, you can select whether audio playback from the guest
-        is enabled or disabled.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>clipboard
-        disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
-        With this setting, you can select if and how the guest or host
-        operating system's clipboard should be shared with the host or guest;
-        see <xref linkend="generalsettings" />. This requires that the Guest
-        Additions be installed in the virtual machine.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>draganddrop
-        disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
-        With this setting, you can select the current drag and drop mode
-        being used between the host and the virtual machine;
-        see <xref linkend="guestadd-dnd" />. This requires that the Guest
-        Additions be installed in the virtual machine.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>vrde on|off</computeroutput> lets you enable or
-        disable the VRDE server, if it is installed.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>vrdeport default|&lt;ports&gt;</computeroutput>
-        changes the port or a range of ports that the VRDE server can bind to;
-        "default" or "0" means port 3389, the standard port for RDP. For
-        details, see the description for the
-        <computeroutput>--vrdeport</computeroutput> option in <xref
-        linkend="vboxmanage-modifyvm-vrde" />.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>vrdeproperty "TCP/Ports|Address=&lt;value&gt;"</computeroutput>
-        sets the port number(s) and IP address on the VM to which the VRDE server can bind.</para>
+
+      <listitem>
+        <para>
+          The <computeroutput>setlinkstate&lt;1-N&gt;</computeroutput>
+          operation connects or disconnects virtual network cables from
+          their network interfaces.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>nic&lt;1-N&gt;
+          null|nat|bridged|intnet|hostonly|generic|natnetwork[&lt;devicename&gt;]</computeroutput>:
+          specifies the type of networking that should be made available
+          on the specified VM virtual network card. They can be: not
+          connected to the host (<computeroutput>null</computeroutput>),
+          use network address translation
+          (<computeroutput>nat</computeroutput>), bridged networking
+          (<computeroutput>bridged</computeroutput>) or communicate with
+          other virtual machines using internal networking
+          (<computeroutput>intnet</computeroutput>) or host-only
+          networking (<computeroutput>hostonly</computeroutput>) or
+          natnetwork networking
+          (<computeroutput>natnetwork</computeroutput>) or access to
+          rarely used sub-modes
+          (<computeroutput>generic</computeroutput>). These options
+          correspond to the modes which are described in detail in
+          <xref
+        linkend="networkingmodes" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          With the "nictrace" options, you can optionally trace network
+          traffic by dumping it to a file, for debugging purposes.
+        </para>
+
+        <para>
+          With <computeroutput>nictrace&lt;1-N&gt;
+          on|off</computeroutput>, you can enable network tracing for a
+          particular virtual network card.
+        </para>
+
+        <para>
+          If enabled, you must specify with
+          <computeroutput>--nictracefile&lt;1-N&gt;
+          &lt;filename&gt;</computeroutput> the pathname of the file to
+          which the trace should be logged.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>nicpromisc&lt;1-N&gt;
+          deny|allow-vms|allow-all</computeroutput>: This specifies how
+          the promiscious mode is handled for the specified VM virtual
+          network card. This setting is only relevant for bridged
+          networking. <computeroutput>deny</computeroutput> (default
+          setting) hides any traffic not intended for this VM.
+          <computeroutput>allow-vms</computeroutput> hides all host
+          traffic from this VM but allows the VM to see traffic from/to
+          other VMs. <computeroutput>allow-all</computeroutput> removes
+          this restriction completely.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>nicproperty&lt;1-N&gt;
+          &lt;paramname&gt;="paramvalue"</computeroutput>: This option,
+          in combination with "nicgenericdrv" enables you to pass
+          parameters to rarely-used network backends.
+        </para>
+
+        <para>
+          Those parameters are backend engine-specific, and are
+          different between UDP Tunnel and the VDE backend drivers. For
+          example, please see <xref linkend="network_udp_tunnel" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>natpf&lt;1-N&gt;
+          [&lt;name&gt;],tcp|udp,[&lt;hostip&gt;],&lt;hostport&gt;,[&lt;guestip&gt;],
+          &lt;guestport&gt;</computeroutput>: This option specifies a
+          NAT port-forwarding rule. See <xref linkend="natforward"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>natpf&lt;1-N&gt; delete
+          &lt;name&gt;</computeroutput>: This option deletes a NAT
+          port-forwarding rule. See <xref linkend="natforward"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The <computeroutput>guestmemoryballoon&lt;balloon size in
+          MB&gt;</computeroutput> operation changes the size of the
+          guest memory balloon, that is, memory allocated by the
+          VirtualBox Guest Additions from the guest operating system and
+          returned to the hypervisor for re-use by other virtual
+          machines. This must be specified in megabytes. See
+          <xref linkend="guestadd-balloon" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>usbattach&lt;uuid|address&gt; [--capturefile
+          &lt;filename&gt;]</computeroutput>
+        </para>
+
+        <para>
+          and <computeroutput>usbdetach &lt;uuid|address&gt;
+          [--capturefile &lt;filename&gt;]</computeroutput> make host
+          USB devices visible/invisible to the virtual machine on the
+          fly, without the need for creating filters first. The USB
+          devices can be specified by UUID (unique identifier) or by
+          address on the host system. Use the --capturefile option to
+          specify the absolute path of a file for writing activity
+          logging data.
+        </para>
+
+        <para>
+          You can use <computeroutput>VBoxManage list
+          usbhost</computeroutput> to locate this information.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>audioin on</computeroutput>: With this
+          setting, you can select whether capturing audio from the host
+          is enabled or disabled.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>audioout on</computeroutput>: With this
+          setting, you can select whether audio playback from the guest
+          is enabled or disabled.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>clipboard
+          disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
+          With this setting, you can select if and how the guest or host
+          operating system's clipboard should be shared with the host or
+          guest. See <xref linkend="generalsettings" />. This requires
+          that the Guest Additions be installed in the virtual machine.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>draganddrop
+          disabled|hosttoguest|guesttohost|bidirectional</computeroutput>:
+          With this setting, you can select the current drag and drop
+          mode being used between the host and the virtual machine. See
+          <xref linkend="guestadd-dnd" />. This requires that the Guest
+          Additions be installed in the virtual machine.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>vrde on|off</computeroutput> lets you enable
+          or disable the VRDE server, if it is installed.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>vrdeport
+          default|&lt;ports&gt;</computeroutput> changes the port or a
+          range of ports that the VRDE server can bind to; "default" or
+          "0" means port 3389, the standard port for RDP. See the
+          description for the
+          <computeroutput>--vrdeport</computeroutput> option in
+          <xref
+        linkend="vboxmanage-modifyvm-vrde" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>vrdeproperty
+          "TCP/Ports|Address=&lt;value&gt;"</computeroutput> sets the
+          port number(s) and IP address on the VM to which the VRDE
+          server can bind.
+        </para>
 
         <itemizedlist>
+
           <listitem>
-            <para>For TCP/Ports, &lt;value&gt; should be a port or a range of ports to which
-            the VRDE server can bind; "default" or "0" means port 3389, the standard port for RDP.
-            For details, see the description for the
-            <computeroutput>--vrdeport</computeroutput> option in <xref
-            linkend="vboxmanage-modifyvm-vrde" />.</para>
+            <para>
+              For TCP/Ports, &lt;value&gt; should be a port or a range
+              of ports to which the VRDE server can bind; "default" or
+              "0" means port 3389, the standard port for RDP. See the
+              description for the
+              <computeroutput>--vrdeport</computeroutput> option in
+              <xref
+            linkend="vboxmanage-modifyvm-vrde" />.
+            </para>
           </listitem>
 
           <listitem>
-            <para>For TCP/Address, &lt;value&gt; should be the IP address of the host network
-            interface that the VRDE server will bind to. If specified, the server
-            will accept connections only on the specified host network interface.
-            For details, see the description for the
-            <computeroutput>--vrdeaddress</computeroutput> option in <xref
-            linkend="vboxmanage-modifyvm-vrde" />.</para>
+            <para>
+              For TCP/Address, &lt;value&gt; should be the IP address of
+              the host network interface that the VRDE server will bind
+              to. If specified, the server will accept connections only
+              on the specified host network interface. See the
+              description for the
+              <computeroutput>--vrdeaddress</computeroutput> option in
+              <xref
+            linkend="vboxmanage-modifyvm-vrde" />.
+            </para>
           </listitem>
+
         </itemizedlist>
       </listitem>
 
       <listitem>
-        <para><computeroutput>vrdeproperty "VideoChannel/Enabled|Quality|DownscaleProtection=&lt;value&gt;"</computeroutput>
-        sets the VRDP video redirection properties.</para>
+        <para>
+          <computeroutput>vrdeproperty
+          "VideoChannel/Enabled|Quality|DownscaleProtection=&lt;value&gt;"</computeroutput>
+          sets the VRDP video redirection properties.
+        </para>
+
         <itemizedlist>
+
           <listitem>
-            <para>For VideoChannel/Enabled, &lt;value&gt; can be set to "1" switching the VRDP video channel on.
-            For details, see <xref linkend="vrde-videochannel" />.</para>
+            <para>
+              For VideoChannel/Enabled, &lt;value&gt; can be set to "1"
+              switching the VRDP video channel on. See
+              <xref linkend="vrde-videochannel" />.
+            </para>
           </listitem>
 
           <listitem>
-            <para>For VideoChannel/Quality, &lt;value&gt; should be set between 10 and 100% inclusive,
-            representing a JPEG compression level on the VRDE server video channel. Lower values mean lower
-            quality but higher compression. For details, see <xref linkend="vrde-videochannel" />.</para>
+            <para>
+              For VideoChannel/Quality, &lt;value&gt; should be set
+              between 10 and 100% inclusive, representing a JPEG
+              compression level on the VRDE server video channel. Lower
+              values mean lower quality but higher compression. For
+              details, see <xref linkend="vrde-videochannel" />.
+            </para>
           </listitem>
 
           <listitem>
-            <para>For VideoChannel/DownscaleProtection, &lt;value&gt; can be set to "1" to enable the
-            videochannel downscale protection feature. When enabled, if a video's size equals the shadow
-            buffer size, then it is regarded as a full screen video, and is displayed; but if its size
-            is between fullscreen and the downscale threshold - it is NOT displayed, as it could be an
-            application window, which would be unreadable when downscaled.
-            When the downscale protection feature is disabled, an attempt is always made to display videos.</para>
+            <para>
+              For VideoChannel/DownscaleProtection, &lt;value&gt; can be
+              set to "1" to enable the videochannel downscale protection
+              feature. When enabled, if a video's size equals the shadow
+              buffer size, then it is regarded as a full screen video,
+              and is displayed; but if its size is between fullscreen
+              and the downscale threshold - it is NOT displayed, as it
+              could be an application window, which would be unreadable
+              when downscaled. When the downscale protection feature is
+              disabled, an attempt is always made to display videos.
+            </para>
           </listitem>
+
         </itemizedlist>
       </listitem>
 
       <listitem>
-        <para><computeroutput>vrdeproperty "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1"</computeroutput></para>
-        <para>disables one of the VRDE server features: Display, Input, Audio or USB respectively.
-        To re-enable a feature, use e.g. "Client/DisableDisplay=".
-        For details, see <xref linkend="vrde-customization" />.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>vrdeproperty "Client/DisableClipboard|DisableUpstreamAudio=1"</computeroutput></para>
-        <para>disables one of the VRDE server features: Clipboard or UpstreamAudio respectively.
-        To re-enable a feature, use e.g. "Client/DisableClipboard=".
-        For details, see <xref linkend="vrde-customization" />.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>vrdeproperty "Client/DisableRDPDR=1"</computeroutput></para>
-        <para>disables the VRDE server feature: RDP device redirection for smart cards.
-        To re-enable this feature, use "Client/DisableRDPR=".</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>vrdeproperty "H3DRedirect/Enabled=1"</computeroutput></para>
-        <para>enables the VRDE server feature: 3D redirection.
-        To re-disable this feature, use "H3DRedirect/Enabled=".</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>vrdeproperty "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=&lt;value&gt;"</computeroutput>
-        sets the desired security method/Path of server certificate, path of server private key, path of CA certificate, used for a connection.
+        <para>
+          <computeroutput>vrdeproperty
+          "Client/DisableDisplay|DisableInput|DisableAudio|DisableUSB=1"</computeroutput>
+        </para>
+
+        <para>
+          disables one of the VRDE server features: Display, Input,
+          Audio or USB respectively. To reenable a feature, use
+          "Client/DisableDisplay=" for example. See
+          <xref linkend="vrde-customization" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>vrdeproperty
+          "Client/DisableClipboard|DisableUpstreamAudio=1"</computeroutput>
+        </para>
+
+        <para>
+          disables one of the VRDE server features: Clipboard or
+          UpstreamAudio respectively. To reenable a feature, use
+          "Client/DisableClipboard=" for example. See
+          <xref linkend="vrde-customization" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>vrdeproperty
+          "Client/DisableRDPDR=1"</computeroutput>
+        </para>
+
+        <para>
+          disables the VRDE server feature: RDP device redirection for
+          smart cards. To reenable this feature, use
+          "Client/DisableRDPR=".
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>vrdeproperty
+          "H3DRedirect/Enabled=1"</computeroutput>
+        </para>
+
+        <para>
+          enables the VRDE server feature: 3D redirection. To disable
+          this feature, use "H3DRedirect/Enabled=".
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>vrdeproperty
+          "Security/Method|ServerCertificate|ServerPrivateKey|CACertificate=&lt;value&gt;"</computeroutput>
+          sets the desired security method/Path of server certificate,
+          path of server private key, path of CA certificate, used for a
+          connection.
+        </para>
 
         <itemizedlist>
+
           <listitem>
-            <para><computeroutput>vrdeproperty "Security/Method=&lt;value&gt;"</computeroutput>
-            sets the desired security method, which is used for a connection. Valid values are:
+            <para>
+              <computeroutput>vrdeproperty
+              "Security/Method=&lt;value&gt;"</computeroutput> sets the
+              desired security method, which is used for a connection.
+              Valid values are:
+            </para>
+
             <itemizedlist>
+
               <listitem>
-                <para> <computeroutput>Negotiate</computeroutput> - both Enhanced (TLS)
-                and Standard RDP Security connections are allowed. The security
-                method is negotiated with the client. This is the default setting.</para>
+                <para>
+                  <computeroutput>Negotiate</computeroutput> - both
+                  Enhanced (TLS) and Standard RDP Security connections
+                  are allowed. The security method is negotiated with
+                  the client. This is the default setting.
+                </para>
               </listitem>
+
               <listitem>
-                <para> <computeroutput>RDP</computeroutput> - only Standard RDP Security is accepted.</para>
+                <para>
+                  <computeroutput>RDP</computeroutput> - only Standard
+                  RDP Security is accepted.
+                </para>
               </listitem>
+
               <listitem>
-                <para> <computeroutput>TLS</computeroutput> - only Enhanced RDP Security is accepted.
-                The client must support TLS.</para>
+                <para>
+                  <computeroutput>TLS</computeroutput> - only Enhanced
+                  RDP Security is accepted. The client must support TLS.
+                </para>
               </listitem>
+
             </itemizedlist>
-            For details, see <xref linkend="vrde-crypt" />.</para>
+
+            <para>
+              See <xref linkend="vrde-crypt" />.
+            </para>
           </listitem>
 
           <listitem>
-            <para><computeroutput>vrdeproperty "Security/ServerCertificate=&lt;value&gt;"</computeroutput>
-            where &lt;value&gt; is the absolute path of the server certificate.
-            For details, see <xref linkend="vrde-crypt" />.</para>
+            <para>
+              <computeroutput>vrdeproperty
+              "Security/ServerCertificate=&lt;value&gt;"</computeroutput>
+              where &lt;value&gt; is the absolute path of the server
+              certificate. See <xref linkend="vrde-crypt" />.
+            </para>
           </listitem>
 
           <listitem>
-            <para><computeroutput>vrdeproperty "Security/ServerPrivateKey=&lt;value&gt;"</computeroutput>
-            where &lt;value&gt; is the absolute path of the server private key.
-            For details, see <xref linkend="vrde-crypt" />.</para>
+            <para>
+              <computeroutput>vrdeproperty
+              "Security/ServerPrivateKey=&lt;value&gt;"</computeroutput>
+              where &lt;value&gt; is the absolute path of the server
+              private key. See <xref linkend="vrde-crypt" />.
+            </para>
           </listitem>
 
           <listitem>
-            <para><computeroutput>vrdeproperty "Security/CACertificate=&lt;value&gt;"</computeroutput>
-            where &lt;value&gt; is the absolute path of the CA self signed certificate.
-            For details, see <xref linkend="vrde-crypt" />.</para>
+            <para>
+              <computeroutput>vrdeproperty
+              "Security/CACertificate=&lt;value&gt;"</computeroutput>
+              where &lt;value&gt; is the absolute path of the CA self
+              signed certificate. See <xref linkend="vrde-crypt" />.
+            </para>
           </listitem>
-        </itemizedlist></para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>vrdeproperty "Audio/RateCorrectionMode|LogPath=&lt;value&gt;"</computeroutput>
-        sets the Audio connection mode, or Path of the audio logfile.
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>vrdeproperty
+          "Audio/RateCorrectionMode|LogPath=&lt;value&gt;"</computeroutput>
+          sets the Audio connection mode, or Path of the audio logfile.
+        </para>
 
         <itemizedlist>
+
           <listitem>
-            <para><computeroutput>vrdeproperty "Audio/RateCorrectionMode=&lt;value&gt;"</computeroutput>
-            where &lt;value&gt; is the desired rate correction mode, allowed values are:
+            <para>
+              <computeroutput>vrdeproperty
+              "Audio/RateCorrectionMode=&lt;value&gt;"</computeroutput>
+              where &lt;value&gt; is the desired rate correction mode,
+              allowed values are:
+            </para>
+
             <itemizedlist>
+
               <listitem>
-                <para> <computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput> - no mode specified, use to
-                unset any Audio mode already set.</para>
+                <para>
+                  <computeroutput>VRDP_AUDIO_MODE_VOID</computeroutput>
+                  - no mode specified, use to unset any Audio mode
+                  already set.
+                </para>
               </listitem>
+
               <listitem>
-                <para> <computeroutput>VRDP_AUDIO_MODE_RC</computeroutput> - rate correction mode.</para>
+                <para>
+                  <computeroutput>VRDP_AUDIO_MODE_RC</computeroutput> -
+                  rate correction mode.
+                </para>
               </listitem>
+
               <listitem>
-                <para> <computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput> - low pass filter mode.</para>
+                <para>
+                  <computeroutput>VRDP_AUDIO_MODE_LPF</computeroutput> -
+                  low pass filter mode.
+                </para>
               </listitem>
+
               <listitem>
-                <para> <computeroutput>VRDP_AUDIO_MODE_CS</computeroutput> - client sync mode to prevent
-                under/overflow of the client queue.</para>
+                <para>
+                  <computeroutput>VRDP_AUDIO_MODE_CS</computeroutput> -
+                  client sync mode to prevent under/overflow of the
+                  client queue.
+                </para>
               </listitem>
-            </itemizedlist></para>
+
+            </itemizedlist>
           </listitem>
+
           <listitem>
-            <para><computeroutput>vrdeproperty "Audio/LogPath=&lt;value&gt;"</computeroutput>
-            where &lt;value&gt; is the absolute path of the Audio log file.</para>
+            <para>
+              <computeroutput>vrdeproperty
+              "Audio/LogPath=&lt;value&gt;"</computeroutput> where
+              &lt;value&gt; is the absolute path of the Audio log file.
+            </para>
           </listitem>
-        </itemizedlist></para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>vrdevideochannelquality
-        &lt;percent&gt;</computeroutput>: Sets the image quality for video
-        redirection; see <xref lang=""
-        linkend="vrde-videochannel" />.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>setvideomodehint</computeroutput> requests that
-        the guest system change to a particular video mode. This requires that
-        the Guest Additions be installed, and will not work for all guest
-        systems.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>screenshotpng</computeroutput> takes a screenshot
-        of the guest display and saves it in PNG format.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>videocap on|off</computeroutput> enables or disables
-        recording a VM session into a WebM/VP8 file.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>videocapscreens all|&lt;screen ID&gt;
-        [&lt;screen ID&gt; ...]]</computeroutput> allows to specify which screens of
-        the VM are being recorded. This setting
-        cannot be changed while video capturing is enabled. Each screen is recorded
-        into a separate file.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>videocapfile &lt;file&gt;</computeroutput> sets the filename
-        VirtualBox uses to save the recorded content. This setting cannot be changed
-        while video capturing is enabled.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>videocapres &lt;width&gt; &lt;height&gt;</computeroutput>
-        sets the resolution (in pixels) of the recorded video. This setting cannot be
-        changed while video capturing is enabled.</para>
-      </listitem>
-
-      <listitem> <!-- @todo r=andy Clarify rate. -->
-        <para><computeroutput>videocaprate &lt;rate&gt;</computeroutput> sets the
-        bitrate in kilobits (kb) per second. Increasing this value makes the video
-        look better for the cost of an increased file size. This setting cannot be
-        changed while video capturing is enabled.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>videocapfps &lt;fps&gt;</computeroutput> sets the
-        maximum number of frames per second (FPS) to be recorded. Frames with a
-        higher frequency will be skipped. Reducing this value increases the number
-        of skipped frames and reduces the file size. This setting cannot be changed
-        while video capturing is enabled.</para>
-      </listitem>
-
-      <listitem> <!-- @todo r=andy Clarify time format. -->
-        <para><computeroutput>videocapmaxtime &lt;ms&gt;</computeroutput> sets
-        the maximum time in milliseconds the video capturing will be enabled
-        since activation.
-        The capturing stops when the defined time interval has elapsed. If this
-        value is zero the capturing is not limited by time. This setting cannot
-        be changed while video capturing is enabled.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>videocapmaxsize &lt;MB&gt;</computeroutput> limits
-        the maximum size of the captured video file (in MB). The capturing stops
-        when the file size has reached the specified size. If this value is zero
-        the capturing will not be limited by file size. This setting cannot be
-        changed while video capturing is enabled.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>videocapopts &lt;key=value&gt;[,&lt;key=value&gt; ...]</computeroutput>
-        can be used to specify additional video capturing options. These options
-        only are for advanced users and must be specified in a comma-separated
-        key=value format, e.g. <computeroutput>foo=bar,a=b</computeroutput>.
-        This setting cannot be changed while video capturing is enabled.</para>
-      </listitem>
-
-      <listitem>
-        <para>The <computeroutput>setcredentials</computeroutput> operation is
-        used for remote logons in Windows guests. For details, please refer to
-        <xref linkend="autologon" />.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>teleport --host &lt;name&gt; --port &lt;port&gt;</computeroutput>
-        can be used to configure a VM as a target for teleporting.
-        &lt;name&gt; specifies the virtual machine name. &lt;port&gt; specifies the port on the
-        virtual machine which should listen for teleporting requests from other
-        virtual machines. It can be any free TCP/IP port number (e.g. 6000);
-        See <xref linkend="teleporting" /> for an introduction.</para>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>vrdevideochannelquality
+          &lt;percent&gt;</computeroutput>: Sets the image quality for
+          video redirection. See
+          <xref 
+        linkend="vrde-videochannel" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>setvideomodehint</computeroutput> requests
+          that the guest system change to a particular video mode. This
+          requires that the Guest Additions be installed, and will not
+          work for all guest systems.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>screenshotpng</computeroutput> takes a
+          screenshot of the guest display and saves it in PNG format.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>videocap on|off</computeroutput> enables or
+          disables recording a VM session into a WebM/VP8 file.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>videocapscreens all|&lt;screen ID&gt;
+          [&lt;screen ID&gt; ...]]</computeroutput> allows to specify
+          which screens of the VM are being recorded. This setting
+          cannot be changed while video capturing is enabled. Each
+          screen is recorded into a separate file.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>videocapfile &lt;file&gt;</computeroutput>
+          sets the filename VirtualBox uses to save the recorded
+          content. This setting cannot be changed while video capturing
+          is enabled.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>videocapres &lt;width&gt;
+          &lt;height&gt;</computeroutput> sets the resolution (in
+          pixels) of the recorded video. This setting cannot be changed
+          while video capturing is enabled.
+        </para>
+      </listitem>
+
+      <listitem>
+<!-- @todo r=andy Clarify rate. -->
+
+        <para>
+          <computeroutput>videocaprate &lt;rate&gt;</computeroutput>
+          sets the bitrate in kilobits (kb) per second. Increasing this
+          value makes the video look better for the cost of an increased
+          file size. This setting cannot be changed while video
+          capturing is enabled.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>videocapfps &lt;fps&gt;</computeroutput> sets
+          the maximum number of frames per second (FPS) to be recorded.
+          Frames with a higher frequency will be skipped. Reducing this
+          value increases the number of skipped frames and reduces the
+          file size. This setting cannot be changed while video
+          capturing is enabled.
+        </para>
+      </listitem>
+
+      <listitem>
+<!-- @todo r=andy Clarify time format. -->
+
+        <para>
+          <computeroutput>videocapmaxtime &lt;ms&gt;</computeroutput>
+          sets the maximum time in milliseconds the video capturing will
+          be enabled since activation. The capturing stops when the
+          defined time interval has elapsed. If this value is zero the
+          capturing is not limited by time. This setting cannot be
+          changed while video capturing is enabled.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>videocapmaxsize &lt;MB&gt;</computeroutput>
+          limits the maximum size of the captured video file, in MB. The
+          capturing stops when the file size has reached the specified
+          size. If this value is zero the capturing will not be limited
+          by file size. This setting cannot be changed while video
+          capturing is enabled.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>videocapopts
+          &lt;key=value&gt;[,&lt;key=value&gt; ...]</computeroutput> can
+          be used to specify additional video capturing options. These
+          options only are for advanced users and must be specified in a
+          comma-separated key=value format, e.g.
+          <computeroutput>foo=bar,a=b</computeroutput>. This setting
+          cannot be changed while video capturing is enabled.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The <computeroutput>setcredentials</computeroutput> operation
+          is used for remote logons in Windows guests. See
+          <xref linkend="autologon" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>teleport --host &lt;name&gt; --port
+          &lt;port&gt;</computeroutput> can be used to configure a VM as
+          a target for teleporting. &lt;name&gt; specifies the virtual
+          machine name. &lt;port&gt; specifies the port on the virtual
+          machine which should listen for teleporting requests from
+          other virtual machines. It can be any free TCP/IP port number,
+          such as 6000. See <xref linkend="teleporting" />.
+        </para>
+
         <itemizedlist>
+
           <listitem>
-            <para><computeroutput>--maxdowntime &lt;msec&gt;</computeroutput>:
-            specifies the maximum downtime (milliseconds) for the
-            teleporting target VM. Optional.</para>
+            <para>
+              <computeroutput>--maxdowntime
+              &lt;msec&gt;</computeroutput>: specifies the maximum
+              downtime (milliseconds) for the teleporting target VM.
+              Optional.
+            </para>
           </listitem>
 
           <listitem>
-            <para><computeroutput>--password
-            &lt;password&gt;</computeroutput>:
-            indicates that the teleporting request will only succeed if the
-            source machine specifies the same password as the one given with
-            this command. Optional.</para>
+            <para>
+              <computeroutput>--password
+              &lt;password&gt;</computeroutput>: indicates that the
+              teleporting request will only succeed if the source
+              machine specifies the same password as the one given with
+              this command. Optional.
+            </para>
           </listitem>
 
           <listitem>
-            <para><computeroutput>--passwordfile
-            &lt;password file&gt;</computeroutput>:
-            indicates that the teleporting request will only succeed if the
-            source machine specifies the same password as the one specified
-            in the password file with the path specified with this command.
-            Use <computeroutput>stdin</computeroutput> to read the password
-            from stdin. Optional.</para>
+            <para>
+              <computeroutput>--passwordfile &lt;password
+              file&gt;</computeroutput>: indicates that the teleporting
+              request will only succeed if the source machine specifies
+              the same password as the one specified in the password
+              file with the path specified with this command. Use
+              <computeroutput>stdin</computeroutput> to read the
+              password from stdin. Optional.
+            </para>
           </listitem>
+
         </itemizedlist>
       </listitem>
 
       <listitem>
-        <para><computeroutput>plugcpu|unplugcpu
-        &lt;id&gt;</computeroutput>: If CPU hot-plugging is enabled, this adds
-        a virtual CPU to the virtual machines (or removes one).
-        <computeroutput>&lt;id&gt;</computeroutput> specifies the index of
-        the virtual CPU to be added or removed and must be a number from 0
-        to the maximum no. of CPUs configured. CPU 0 can never be removed.</para>
-      </listitem>
-
-      <listitem>
-        <para>The <computeroutput>cpuexecutioncap
-        &lt;1-100&gt;</computeroutput>: This operation controls how much cpu
-        time a virtual CPU can use. A value of 50 implies a single virtual CPU
-        can use up to 50% of a single host CPU.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>webcam
-        attach &lt;path|alias&gt; [&lt;key=value&gt;[;&lt;key=value&gt;...]]</computeroutput>: This operation
-        attaches a webcam to a running VM. Specify the absolute path of the
-        webcam on the host operating system, or use its alias (obtained by using the command: VBoxManage
-        list webcams).</para>
-
-        <para>Note that alias '.0' means default video input device on the host operating system, '.1', '.2',
-        etc. mean first, second, etc. video input device. The device order is host-specific.</para>
-
-        <para>The optional settings parameter is a ';' delimited list of name/value pairs, enabling configuration
-        of the emulated webcam device.</para>
-
-        <para>The following settings are supported:</para>
-
-        <para>MaxFramerate (default no maximum limit) - this specifies the highest rate (frames/sec) at which
-        video frames are sent to the guest. Higher frame rates increase CPU load, so this setting can be useful
-        when there is a need to reduce CPU load. Its default 'value' is 'no maximum limit', thus enabling the
-        guest to use all frame rates supported by the host webcam.</para>
-
-        <para>MaxPayloadTransferSize (default 3060 bytes) - this specifies the maximum number of bytes the emulated
-        webcam can send to the guest in one buffer. The default is used by some webcams. Higher values can
-        slightly reduce CPU load, if the guest is able to use larger buffers.
-        Note that higher MaxPayloadTransferSize values may be not supported by some guest operating systems.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>webcam
-        detach &lt;path|alias&gt;</computeroutput>: This operation
-        detaches a webcam from a running VM. Specify the absolute path of the
-        webcam on the host, or use its alias (obtained from webcam list below).</para>
-        <para>Note the points below relating to specific Host Operating Systems:</para>
-
-        <para>Windows hosts</para>
-
-        <para>When the webcam device is detached from the host, the emulated webcam device
-        is automatically detached from the guest.</para>
-
-        <para>Mac OS X hosts</para>
-
-        <para>OS X version 10.7 or newer is required.</para>
-
-        <para>When the webcam device is detached from the host, the emulated webcam device remains
-        attached to the guest and must be manually detached using the
-        VBoxManage controlvm "VM name" webcam detach command.</para>
-
-        <para>Linux hosts</para>
-
-        <para>When the webcam is detached from the host, the emulated webcam device is automatically detached
-        from the guest only if the webcam is streaming video. If the emulated webcam is inactive, it
-        should be manually detached using the VBoxManage controlvm "VM name" webcam detach command.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>webcam list</computeroutput>: This operation
-        lists webcams attached to the running VM.
-        The output is a list of absolute paths or aliases that were used for attaching the webcams
-        to the VM using the 'webcam attach' command above.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>addencpassword
-        &lt;id&gt; &lt;password file&gt;|- [--removeonsuspend &lt;yes|no&gt;]</computeroutput>: This operation
-        supplies an encrypted VM specified by &lt;id&gt; with the encryption password to enable a headless start.
-        Either specify the absolute path of a password file on the host file system: &lt;password file&gt;, or
-        use a '-' to instruct VBoxManage to prompt the user for the encryption password. </para>
-
-        <para><computeroutput>--removeonsuspend &lt;yes|no&gt;</computeroutput> specifies whether to remove/keep
-        the password from/in VM memory when the VM is suspended. If the VM has been suspended and the password has
-        been removed, the user needs to resupply the password before the VM can be resumed. This feature is useful
-        in cases where the user doesn't want the password to be stored in VM memory, and the VM is suspended by a
-        host suspend event.</para>
-
-        <para>Note: On VirtualBox versions 5.0 and later, data stored on hard disk images can be transparently
-        encrypted for the guest. VirtualBox uses the AES algorithm in XTS mode and supports 128 or 256
-        bit data encryption keys (DEK). The DEK is stored encrypted in the medium properties, and is
-        decrypted during VM startup by supplying the encryption password.</para>
-
-        <para>The "VBoxManage encryptmedium" operation is used to create a DEK encrypted medium.
-        See <xref linkend="diskencryption-encryption" />" for details.
-        When starting an encrypted VM from a VirtualBox GUI app, the user will be prompted for the
-        encryption password.</para>
-
-        <para>For a headless encrypted VM start, use:</para>
-
-        <para>VBoxManage startvm "vmname" --type headless</para>
-
-        <para>followed by:</para>
-
-        <para>VBoxManage "vmname" controlvm "vmname" addencpassword ...</para>
-
-        <para>to supply the encryption password required.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>removeencpassword &lt;id&gt;</computeroutput>: This operation
-        removes encryption password authorization for password &lt;id&gt; for all encrypted media
-        attached to the VM.</para>
-      </listitem>
-
-      <listitem>
-        <para><computeroutput>removeallencpasswords</computeroutput>: This operation
-        removes encryption password authorization for all passwords for all
-        encrypted media attached to the VM.</para>
+        <para>
+          <computeroutput>plugcpu|unplugcpu &lt;id&gt;</computeroutput>:
+          If CPU hot-plugging is enabled, this adds a virtual CPU to the
+          virtual machines (or removes one).
+          <computeroutput>&lt;id&gt;</computeroutput> specifies the
+          index of the virtual CPU to be added or removed and must be a
+          number from 0 to the maximum no. of CPUs configured. CPU 0 can
+          never be removed.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The <computeroutput>cpuexecutioncap
+          &lt;1-100&gt;</computeroutput>: This operation controls how
+          much cpu time a virtual CPU can use. A value of 50 implies a
+          single virtual CPU can use up to 50% of a single host CPU.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>webcam attach &lt;path|alias&gt;
+          [&lt;key=value&gt;[;&lt;key=value&gt;...]]</computeroutput>:
+          This operation attaches a webcam to a running VM. Specify the
+          absolute path of the webcam on the host operating system, or
+          use its alias, obtained by using the command: VBoxManage list
+          webcams.
+        </para>
+
+        <para>
+          Note that alias '.0' means default video input device on the
+          host operating system, '.1', '.2', etc. mean first, second,
+          etc. video input device. The device order is host-specific.
+        </para>
+
+        <para>
+          The optional settings parameter is a ';' delimited list of
+          name/value pairs, enabling configuration of the emulated
+          webcam device.
+        </para>
+
+        <para>
+          The following settings are supported:
+        </para>
+
+        <para>
+          MaxFramerate (default no maximum limit) - this specifies the
+          highest rate (frames/sec) at which video frames are sent to
+          the guest. Higher frame rates increase CPU load, so this
+          setting can be useful when there is a need to reduce CPU load.
+          Its default 'value' is 'no maximum limit', thus enabling the
+          guest to use all frame rates supported by the host webcam.
+        </para>
+
+        <para>
+          MaxPayloadTransferSize (default 3060 bytes) - this specifies
+          the maximum number of bytes the emulated webcam can send to
+          the guest in one buffer. The default is used by some webcams.
+          Higher values can slightly reduce CPU load, if the guest is
+          able to use larger buffers. Note that higher
+          MaxPayloadTransferSize values may be not supported by some
+          guest operating systems.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>webcam detach
+          &lt;path|alias&gt;</computeroutput>: This operation detaches a
+          webcam from a running VM. Specify the absolute path of the
+          webcam on the host, or use its alias (obtained from webcam
+          list below).
+        </para>
+
+        <para>
+          Note the points below relating to specific Host Operating
+          Systems:
+        </para>
+
+        <para>
+          Windows hosts
+        </para>
+
+        <para>
+          When the webcam device is detached from the host, the emulated
+          webcam device is automatically detached from the guest.
+        </para>
+
+        <para>
+          Mac OS X hosts
+        </para>
+
+        <para>
+          OS X version 10.7 or newer is required.
+        </para>
+
+        <para>
+          When the webcam device is detached from the host, the emulated
+          webcam device remains attached to the guest and must be
+          manually detached using the VBoxManage controlvm "VM name"
+          webcam detach command.
+        </para>
+
+        <para>
+          Linux hosts
+        </para>
+
+        <para>
+          When the webcam is detached from the host, the emulated webcam
+          device is automatically detached from the guest only if the
+          webcam is streaming video. If the emulated webcam is inactive,
+          it should be manually detached using the VBoxManage controlvm
+          "VM name" webcam detach command.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>webcam list</computeroutput>: This operation
+          lists webcams attached to the running VM. The output is a list
+          of absolute paths or aliases that were used for attaching the
+          webcams to the VM using the 'webcam attach' command above.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>addencpassword &lt;id&gt; &lt;password
+          file&gt;|- [--removeonsuspend
+          &lt;yes|no&gt;]</computeroutput>: This operation supplies an
+          encrypted VM specified by &lt;id&gt; with the encryption
+          password to enable a headless start. Either specify the
+          absolute path of a password file on the host file system:
+          &lt;password file&gt;, or use a '-' to instruct VBoxManage to
+          prompt the user for the encryption password.
+        </para>
+
+        <para>
+          <computeroutput>--removeonsuspend
+          &lt;yes|no&gt;</computeroutput> specifies whether to
+          remove/keep the password from/in VM memory when the VM is
+          suspended. If the VM has been suspended and the password has
+          been removed, the user needs to resupply the password before
+          the VM can be resumed. This feature is useful in cases where
+          the user does not want the password to be stored in VM memory,
+          and the VM is suspended by a host suspend event.
+        </para>
+
+        <para>
+          Note: On VirtualBox versions 5.0 and later, data stored on
+          hard disk images can be transparently encrypted for the guest.
+          VirtualBox uses the AES algorithm in XTS mode and supports 128
+          or 256 bit data encryption keys (DEK). The DEK is stored
+          encrypted in the medium properties, and is decrypted during VM
+          startup by supplying the encryption password.
+        </para>
+
+        <para>
+          The "VBoxManage encryptmedium" operation is used to create a
+          DEK encrypted medium. See
+          <xref linkend="diskencryption-encryption" />. When starting an
+          encrypted VM from a VirtualBox GUI app, the user will be
+          prompted for the encryption password.
+        </para>
+
+        <para>
+          For a headless encrypted VM start, use:
+        </para>
+
+<screen>
+          VBoxManage startvm "vmname" --type headless
+        </screen>
+
+        <para>
+          followed by:
+        </para>
+
+<screen>
+          VBoxManage "vmname" controlvm "vmname" addencpassword ...
+        </screen>
+
+        <para>
+          to supply the encryption password required.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>removeencpassword &lt;id&gt;</computeroutput>:
+          This operation removes encryption password authorization for
+          password &lt;id&gt; for all encrypted media attached to the
+          VM.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>removeallencpasswords</computeroutput>: This
+          operation removes encryption password authorization for all
+          passwords for all encrypted media attached to the VM.
+        </para>
       </listitem>
 
     </itemizedlist>
+
   </sect1>
 
-  <sect1>
+  <sect1 id="vboxmanage-discardstate">
+
     <title>VBoxManage discardstate</title>
 
-    <para>This command discards the saved state of a virtual machine which is
-    not currently running, which will cause its operating system to restart
-    next time you start it. This is the equivalent of pulling out the power
-    cable on a physical machine, and should be avoided if possible.</para>
+    <para>
+      This command discards the saved state of a virtual machine which
+      is not currently running, which will cause its operating system to
+      restart next time you start it. This is the equivalent of pulling
+      out the power cable on a physical machine, and should be avoided
+      if possible.
+    </para>
+
   </sect1>
 
-  <sect1>
+  <sect1 id="vboxmanage-adoptstate">
+
     <title>VBoxManage adoptstate</title>
 
-    <para>If you have a saved state file (<computeroutput>.sav</computeroutput>)
-    that is separate from the VM configuration, you can use this command to
-    "adopt" the file. This will change the VM to saved state and when you
-    start it, VirtualBox will attempt to restore it from the saved state file
-    you indicated. This command should only be used in special setups.</para>
+    <para>
+      If you have a saved state file
+      (<computeroutput>.sav</computeroutput>) that is separate from the
+      VM configuration, you can use this command to "adopt" the file.
+      This will change the VM to saved state and when you start it,
+      VirtualBox will attempt to restore it from the saved state file
+      you indicated. This command should only be used in special setups.
+    </para>
+
   </sect1>
 
-  <sect1>
+  <sect1 id="vboxmanage-snapshot">
+
     <title>VBoxManage snapshot</title>
 
-    <para>This command is used to control snapshots from the command line. A
-    snapshot consists of a complete copy of the virtual machine settings,
-    copied at the time when the snapshot was taken, and optionally a virtual
-    machine saved state file if the snapshot was taken while the machine was
-    running. After a snapshot has been taken, VirtualBox creates differencing
-    hard disk for each normal hard disk associated with the machine so that
-    when a snapshot is restored, the contents of the virtual machine's virtual
-    hard disks can be quickly reset by simply dropping the pre-existing
-    differencing files.</para>
-
-   <screen>VBoxManage snapshot         &lt;uuid|vmname&gt;
+    <para>
+      This command is used to control snapshots from the command line. A
+      snapshot consists of a complete copy of the virtual machine
+      settings, copied at the time when the snapshot was taken, and
+      optionally a virtual machine saved state file if the snapshot was
+      taken while the machine was running. After a snapshot has been
+      taken, VirtualBox creates differencing hard disk for each normal
+      hard disk associated with the machine so that when a snapshot is
+      restored, the contents of the virtual machine's virtual hard disks
+      can be quickly reset by simply dropping the pre-existing
+      differencing files.
+    </para>
+
+<screen>VBoxManage snapshot         &lt;uuid|vmname&gt;
                             take &lt;name&gt; [--description &lt;desc&gt;] [--live]
                                  [--uniquename Number,Timestamp,Space,Force] |
@@ -2776,74 +4043,108 @@
                             showvminfo &lt;uuid|snapname&gt;</screen>
 
-    <para>The <computeroutput>take</computeroutput> operation takes a snapshot
-    of the current state of the virtual machine. You must supply a name for
-    the snapshot and can optionally supply a description. The new snapshot is
-    inserted into the snapshots tree as a child of the current snapshot and
-    then becomes the new current snapshot. The
-    <computeroutput>--description</computeroutput> parameter allows to
-    describe the snapshot. If <computeroutput>--live</computeroutput>
-    is specified, the VM will not be stopped during the snapshot creation
-    (live snapshotting).</para>
-
-    <para>The <computeroutput>delete</computeroutput> operation deletes a
-    snapshot (specified by name or by UUID). This can take a while to finish
-    since the differencing images associated with the snapshot might need to
-    be merged with their child differencing images.</para>
-
-    <para>The <computeroutput>restore</computeroutput> operation will restore
-    the given snapshot (specified by name or by UUID) by resetting the virtual
-    machine's settings and current state to that of the snapshot. The previous
-    current state of the machine will be lost. After this, the given snapshot
-    becomes the new "current" snapshot so that subsequent snapshots are
-    inserted under the snapshot from which was restored.</para>
-
-    <para>The <computeroutput>restorecurrent</computeroutput> operation is a
-    shortcut to restore the current snapshot (i.e. the snapshot from which the
-    current state is derived). This subcommand is equivalent to using the
-    "restore" subcommand with the name or UUID of the current snapshot, except
-    that it avoids the extra step of determining that name or UUID.</para>
-
-    <para>With the <computeroutput>edit</computeroutput> operation, you can
-    change the name or description of an existing snapshot.</para>
-
-    <para>The <computeroutput>list</computeroutput> operation shows all
-    snapshots of a virtual machine.</para>
-
-    <para>With the <computeroutput>showvminfo</computeroutput> operation, you
-    can view the virtual machine settings that were stored with an existing
-    snapshot.</para>
+    <para>
+      The <computeroutput>take</computeroutput> operation takes a
+      snapshot of the current state of the virtual machine. You must
+      supply a name for the snapshot and can optionally supply a
+      description. The new snapshot is inserted into the snapshots tree
+      as a child of the current snapshot and then becomes the new
+      current snapshot. The
+      <computeroutput>--description</computeroutput> parameter allows to
+      describe the snapshot. If <computeroutput>--live</computeroutput>
+      is specified, the VM will not be stopped during the snapshot
+      creation (live snapshotting).
+    </para>
+
+    <para>
+      The <computeroutput>delete</computeroutput> operation deletes a
+      snapshot (specified by name or by UUID). This can take a while to
+      finish since the differencing images associated with the snapshot
+      might need to be merged with their child differencing images.
+    </para>
+
+    <para>
+      The <computeroutput>restore</computeroutput> operation will
+      restore the given snapshot (specified by name or by UUID) by
+      resetting the virtual machine's settings and current state to that
+      of the snapshot. The previous current state of the machine will be
+      lost. After this, the given snapshot becomes the new "current"
+      snapshot so that subsequent snapshots are inserted under the
+      snapshot from which was restored.
+    </para>
+
+    <para>
+      The <computeroutput>restorecurrent</computeroutput> operation is a
+      shortcut to restore the current snapshot (i.e. the snapshot from
+      which the current state is derived). This subcommand is equivalent
+      to using the "restore" subcommand with the name or UUID of the
+      current snapshot, except that it avoids the extra step of
+      determining that name or UUID.
+    </para>
+
+    <para>
+      With the <computeroutput>edit</computeroutput> operation, you can
+      change the name or description of an existing snapshot.
+    </para>
+
+    <para>
+      The <computeroutput>list</computeroutput> operation shows all
+      snapshots of a virtual machine.
+    </para>
+
+    <para>
+      With the <computeroutput>showvminfo</computeroutput> operation,
+      you can view the virtual machine settings that were stored with an
+      existing snapshot.
+    </para>
+
   </sect1>
 
   <sect1 id="vboxmanage-closemedium">
+
     <title>VBoxManage closemedium</title>
 
-    <para>This commands removes a hard disk, DVD or floppy image from a
-    VirtualBox media registry.<footnote>
-        <para>Before VirtualBox 4.0, it was necessary to call VBoxManage
-        openmedium before a medium could be attached to a virtual machine;
-        that call "registered" the medium with the global VirtualBox media
-        registry. With VirtualBox 4.0 this is no longer necessary; media are
-        added to media registries automatically. The "closemedium" call has
-        been retained, however, to allow for explicitly removing a medium from
-        a registry.</para>
-      </footnote></para>
-
-    <screen>VBoxManage closemedium      [disk|dvd|floppy] &lt;uuid|filename&gt;
+    <para>
+      This command removes a hard disk, DVD, or floppy image from a
+      VirtualBox media registry.
+
+      <footnote>
+
+        <para>
+          Before VirtualBox 4.0, it was necessary to call VBoxManage
+          openmedium before a medium could be attached to a virtual
+          machine; that call "registered" the medium with the global
+          VirtualBox media registry. With VirtualBox 4.0 this is no
+          longer necessary; media are added to media registries
+          automatically. The "closemedium" call has been retained,
+          however, to allow for explicitly removing a medium from a
+          registry.
+        </para>
+
+      </footnote>
+    </para>
+
+<screen>VBoxManage closemedium      [disk|dvd|floppy] &lt;uuid|filename&gt;
                             [--delete]</screen>
 
-    <para>Optionally, you can request that the image be deleted. You will get
-    appropriate diagnostics that the deletion failed, however the image will
-    become unregistered in any case.</para>
+    <para>
+      Optionally, you can request that the image be deleted. You will
+      get appropriate diagnostics that the deletion failed, however the
+      image will become unregistered in any case.
+    </para>
+
   </sect1>
 
   <sect1 id="vboxmanage-storageattach">
+
     <title>VBoxManage storageattach</title>
 
-    <para>This command attaches/modifies/removes a storage medium connected to
-    a storage controller that was previously added with the
-    <computeroutput>storagectl</computeroutput> command (see the previous
-    section). The syntax is as follows:</para>
-
-    <screen>VBoxManage storageattach    &lt;uuid|vmname&gt;
+    <para>
+      This command attaches/modifies/removes a storage medium connected
+      to a storage controller that was previously added with the
+      <computeroutput>storagectl</computeroutput> command. The syntax is
+      as follows:
+    </para>
+
+<screen>VBoxManage storageattach    &lt;uuid|vmname&gt;
                             --storagectl &lt;name&gt;
                             [--port &lt;number&gt;]
@@ -2875,355 +4176,540 @@
                             [--intnet]</screen>
 
-    <para>A number of parameters are commonly required; the ones at the end of
-    the list are required only for iSCSI targets (see below).</para>
-
-    <para>The common parameters are:<glosslist>
-        <glossentry>
-          <glossterm><computeroutput>uuid|vmname</computeroutput></glossterm>
-
-          <glossdef>
-            <para>The VM UUID or VM Name. Mandatory.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--storagectl</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Name of the storage controller. Mandatory. The list of the
-            storage controllers currently attached to a VM can be obtained
-            with <computeroutput>VBoxManage showvminfo</computeroutput>; see
-            <xref linkend="vboxmanage-showvminfo" />.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--port</computeroutput></glossterm>
-
-          <glossdef>
-            <para>The number of the storage controller's port which is to be
-            modified. Mandatory, unless the storage controller has only a
-            single port.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--device</computeroutput></glossterm>
-
-          <glossdef>
-            <para>The number of the port's device which is to be modified.
-            Mandatory, unless the storage controller has only a single device
-            per port.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--type</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Define the type of the drive to which the medium is being
-            attached/detached/modified. This argument can only be omitted if
-            the type of medium can be determined from either the medium given
-            with the <computeroutput>--medium</computeroutput> argument or
-            from a previous medium attachment.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--medium</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Specifies what is to be attached. The following values are
-            supported:<itemizedlist>
-                <listitem>
-                  <para>"none": Any existing device should be removed from the
-                  given slot.</para>
-                </listitem>
-
-                <listitem>
-                  <para>"emptydrive": For a virtual DVD or floppy drive only,
-                  this makes the device slot behaves like a removeable drive
-                  into which no media has been inserted.</para>
-                </listitem>
-
-                <listitem>
-                  <para>"additions": For a virtual DVD drive only, this
-                    attaches the <emphasis>VirtualBox Guest Additions</emphasis>
-                    image to the given device slot.</para>
-                </listitem>
-
-                <listitem>
-                  <para>If a UUID is specified, it must be the UUID of a
-                  storage medium that is already known to VirtualBox (e.g.
-                  because it has been attached to another virtual machine).
-                  See <xref linkend="vboxmanage-list" /> for how to list known
-                  media. This medium is then attached to the given device
-                  slot.</para>
-                </listitem>
-
-                <listitem>
-                  <para>If a filename is specified, it must be the full path
-                  of an existing disk image (ISO, RAW, VDI, VMDK or other),
-                  which is then attached to the given device slot.</para>
-                </listitem>
-
-                <listitem>
-                  <para>"host:&lt;drive&gt;": For a virtual DVD or floppy
-                  drive only, this connects the given device slot to the
-                  specified DVD or floppy drive on the host computer.</para>
-                </listitem>
-
-                <listitem>
-                  <para>"iscsi": For virtual hard disks only, this allows for
-                  specifying an iSCSI target. In this case, more parameters
-                  must be given; see below.</para>
-                </listitem>
-              </itemizedlist></para>
-
-            <para>Some of the above changes, in particular for removeable
+    <para>
+      A number of parameters are commonly required. The ones at the end
+      of the list are required only for iSCSI targets, as described
+      below.
+    </para>
+
+    <para>
+      The common parameters are:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>uuid|vmname</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            The VM UUID or VM Name. Mandatory.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--storagectl</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Name of the storage controller. Mandatory. The list of the
+            storage controllers currently attached to a VM can be
+            obtained with <computeroutput>VBoxManage
+            showvminfo</computeroutput>. See
+            <xref linkend="vboxmanage-showvminfo" />.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--port</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            The number of the storage controller's port which is to be
+            modified. Mandatory, unless the storage controller has only
+            a single port.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--device</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            The number of the port's device which is to be modified.
+            Mandatory, unless the storage controller has only a single
+            device per port.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--type</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Define the type of the drive to which the medium is being
+            attached/detached/modified. This argument can only be
+            omitted if the type of medium can be determined from either
+            the medium given with the
+            <computeroutput>--medium</computeroutput> argument or from a
+            previous medium attachment.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--medium</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies what is to be attached. The following values are
+            supported:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                "none": Any existing device should be removed from the
+                given slot.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                "emptydrive": For a virtual DVD or floppy drive only,
+                this makes the device slot behaves like a removeable
+                drive into which no media has been inserted.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                "additions": For a virtual DVD drive only, this attaches
+                the <emphasis>VirtualBox Guest Additions</emphasis>
+                image to the given device slot.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If a UUID is specified, it must be the UUID of a storage
+                medium that is already known to VirtualBox (e.g. because
+                it has been attached to another virtual machine). See
+                <xref linkend="vboxmanage-list" /> for how to list known
+                media. This medium is then attached to the given device
+                slot.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If a filename is specified, it must be the full path of
+                an existing disk image (ISO, RAW, VDI, VMDK or other),
+                which is then attached to the given device slot.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                "host:&lt;drive&gt;": For a virtual DVD or floppy drive
+                only, this connects the given device slot to the
+                specified DVD or floppy drive on the host computer.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                "iscsi": For virtual hard disks only, this allows for
+                specifying an iSCSI target. In this case, more
+                parameters must be given. See the description below.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
+          <para>
+            Some of the above changes, in particular for removeable
             media (floppies and CDs/DVDs), can be effected while a VM is
-            running. Others (device changes or changes in hard disk device
-            slots) require the VM to be powered off.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--mtype</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Defines how this medium behaves with respect to snapshots
-            and write operations. See <xref linkend="hdimagewrites" /> for
-            details.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--comment</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Any description that you want to have stored with this
-            medium (optional; for example, for an iSCSI target, "Big storage
-            server downstairs"). This is purely descriptive and not needed for
-            the medium to function correctly.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--setuuid, --setparentuuid</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Modifies the UUID or parent UUID of a medium before
-            attaching it to a VM. This is an expert option. Inappropriate use
-            can make the medium unusable or lead to broken VM configurations
-            if any other VM is referring to the same media already. The most
-            frequently used variant is <code>--setuuid ""</code>, which assigns
-            a new (random) UUID to an image. This is useful to resolve the
-            duplicate UUID errors if one duplicated an image using file copy
-            utilities.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--passthrough</computeroutput></glossterm>
-
-          <glossdef>
-            <para>For a virtual DVD drive only, you can enable DVD writing
-            support (currently experimental; see <xref
-            linkend="storage-cds" />).</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--tempeject</computeroutput></glossterm>
-
-          <glossdef>
-            <para>For a virtual DVD drive only, you can configure the behavior
-            for guest-triggered medium eject. If this is set to "on", the eject
-            has only temporary effects. If the VM is powered off and restarted
-            the originally configured medium will be still in the drive.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--nonrotational</computeroutput></glossterm>
-
-          <glossdef>
-            <para>This switch allows to enable the non-rotational flag for virtual
-              hard disks. Some guests (i.e. Windows 7+) treat such disks like SSDs
-              and don't perform disk fragmentation on such media.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--discard</computeroutput></glossterm>
-          <glossdef>
-            <para>This switch enables the auto-discard feature for the virtual
-            hard disks. This specifies that a VDI image will be shrunk in response
-            to the trim command from the guest OS. The following requirements
-            must be met:
-
-            <itemizedlist>
-              <listitem>
-                <para>The disk format must be VDI.</para>
-              </listitem>
-              <listitem>
-                <para>The size of the cleared area must be at least 1MB.</para>
-              </listitem>
-              <listitem>
-                <para>VirtualBox will only trim whole 1MB blocks. The VDIs themselves are organized
-                into 1MB blocks, so this will only work if the space being TRIM-ed is at least
-                a 1MB contiguous block at a 1MB boundary. On Windows, occasional defrag (with "defrag.exe /D"),
-                or under Linux running "btrfs filesystem defrag" as a background cron job may be
-                beneficial.</para>
-              </listitem>
-            </itemizedlist></para>
-
-            <para>Notes: the Guest OS must be configured to issue trim command, and typically this
-            means that the guest OS is made to 'see' the disk as an SSD. Ext4 supports -o discard mount flag;
-            OSX probably requires additional settings. Windows ought to automatically detect and
-            support SSDs - at least in versions 7, 8 and 10. Linux exFAT driver (courtesy of Samsung)
-            supports the trim command.</para>
-            <para>It is unclear whether Microsoft's implementation of exFAT supports this feature, even
-            though that file system was originally designed for flash.</para>
-            <para>Alternatively, there are ad hoc methods to issue trim, e.g. Linux fstrim command,
-            part of util-linux package. Earlier solutions required a user to zero out unused areas,
-            e.g. using zerofree, and explicitly compact the disk - only possible when the VM is
-            offline.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--bandwidthgroup</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Sets the bandwidth group to use for the given device; see
-            <xref linkend="storage-bandwidth-limit" />.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--forceunmount</computeroutput></glossterm>
-
-          <glossdef>
-            <para>For a virtual DVD or floppy drive only, this forcibly
-            unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy even if
-            the previous one is locked down by the guest for reading. Again,
-            see <xref linkend="storage-cds" /> for details.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist></para>
-
-    <para>When "iscsi" is used with the
-    <computeroutput>--medium</computeroutput> parameter for iSCSI support --
-    see <xref linkend="storage-iscsi" /> --, additional parameters must or can
-    be used:<glosslist>
-        <glossentry>
-          <glossterm><computeroutput>--server</computeroutput></glossterm>
-
-          <glossdef>
-            <para>The host name or IP address of the iSCSI target;
-            required.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--target</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Target name string. This is determined by the iSCSI target
-            and used to identify the storage resource; required.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--tport</computeroutput></glossterm>
-
-          <glossdef>
-            <para>TCP/IP port number of the iSCSI service on the target.
-            Optional.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--lun</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Logical Unit Number of the target resource. Optional.
-            Often, this value is zero.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--encodedlun</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Hex encoded Logical Unit Number of the target resource. Optional.
-            Often, this value is zero.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--username, --password, --passwordfile</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Username and password (initiator secret) for target
-                authentication, if required. Optional.<note>
-                <para>Username and password are stored without
-                encryption (i.e. in clear text) in the XML machine
-                configuration file if no settings password is provided.
-                When a settings password was specified the first time,
-                the password is stored encrypted. Alternatively to providing the password
-                on the command line, a reference to a file containing the text
-                can be provided instead via the passwordfile option.</para>
-              </note></para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--initiator</computeroutput></glossterm>
-
-          <glossdef>
-            <para>iSCSI Initiator (optional). Note:</para>
-
-            <para>Microsoft iSCSI Initiator is a system, such as a server that attaches to an IP network and initiates requests and receives responses
-            from an iSCSI target. The SAN components in Microsoft iSCSI Initiator are largely analogous to Fibre Channel SAN components, and
-            they include the following:/</para>
-
-            <para>To transport blocks of iSCSI commands over the IP network, an iSCSI driver must be installed on the iSCSI host.
-            An iSCSI driver is included with Microsoft iSCSI Initiator.</para>
-
-            <para>A gigabit Ethernet adapter that transmits 1000 megabits per second (Mbps) is recommended for the connection to an iSCSI target. Like
-            standard 10/100 adapters, most gigabit adapters use a pre-existing Category 5 or Category 6E cable. Each port on the adapter is
-            identified by a unique IP address.</para>
-
-           <para>An iSCSI target is any device that receives iSCSI commands. The device can be an end node, such as a storage device, or it can be an
-           intermediate device, such as a network bridge between IP and Fibre Channel devices. Each port on the storage array controller or network
-           bridge is identified by one or more IP addresses</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--intnet</computeroutput></glossterm>
-
-          <glossdef>
-            <para>If specified, connect to the iSCSI target via Internal
-            Networking. This needs further configuration which is described in
-            <xref linkend="iscsi-intnet" />.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist></para>
+            running. Others, such as device changes or changes in hard
+            disk device slots, require the VM to be powered off.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--mtype</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Defines how this medium behaves with respect to snapshots
+            and write operations. See <xref linkend="hdimagewrites" />
+            for details.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--comment</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            An optional description that you want to have stored with
+            this medium. For example, for an iSCSI target, "Big storage
+            server downstairs". This is purely descriptive and not
+            needed for the medium to function correctly.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--setuuid, --setparentuuid</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Modifies the UUID or parent UUID of a medium before
+            attaching it to a VM. This is an expert option.
+            Inappropriate use can make the medium unusable or lead to
+            broken VM configurations if any other VM is referring to the
+            same media already. The most frequently used variant is
+            <code>--setuuid ""</code>, which assigns a new (random) UUID
+            to an image. This is useful to resolve the duplicate UUID
+            errors if one duplicated an image using file copy utilities.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--passthrough</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            For a virtual DVD drive only, you can enable DVD writing
+            support. This feature is currently experimental, see
+            <xref
+            linkend="storage-cds" />.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--tempeject</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            For a virtual DVD drive only, you can configure the behavior
+            for guest-triggered medium eject. If this is set to "on",
+            the eject has only temporary effects. If the VM is powered
+            off and restarted the originally configured medium will be
+            still in the drive.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--nonrotational</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This switch allows to enable the non-rotational flag for
+            virtual hard disks. Some guests (i.e. Windows 7+) treat such
+            disks like SSDs and do not perform disk fragmentation on
+            such media.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--discard</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This switch enables the auto-discard feature for the virtual
+            hard disks. This specifies that a VDI image will be shrunk
+            in response to the trim command from the guest OS. The
+            following requirements must be met:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                The disk format must be VDI.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                The size of the cleared area must be at least 1MB.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                VirtualBox will only trim whole 1 MB blocks. The VDIs
+                themselves are organized into 1 MB blocks, so this will
+                only work if the space being TRIM-ed is at least a 1 MB
+                contiguous block at a 1 MB boundary. On Windows,
+                occasional defrag (with "defrag.exe /D"), or under Linux
+                running "btrfs filesystem defrag" as a background cron
+                job may be beneficial.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
+          <para>
+            Notes: the Guest OS must be configured to issue trim
+            command, and typically this means that the guest OS is made
+            to 'see' the disk as an SSD. Ext4 supports -o discard mount
+            flag; OSX probably requires additional settings. Windows
+            ought to automatically detect and support SSDs - at least in
+            versions 7, 8 and 10. Linux exFAT driver (courtesy of
+            Samsung) supports the trim command.
+          </para>
+
+          <para>
+            It is unclear whether Microsoft's implementation of exFAT
+            supports this feature, even though that file system was
+            originally designed for flash.
+          </para>
+
+          <para>
+            Alternatively, there are ad hoc methods to issue trim, e.g.
+            Linux fstrim command, part of util-linux package. Earlier
+            solutions required a user to zero out unused areas, e.g.
+            using zerofree, and explicitly compact the disk - only
+            possible when the VM is offline.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--bandwidthgroup</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Sets the bandwidth group to use for the given device. See
+            <xref linkend="storage-bandwidth-limit" />.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--forceunmount</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            For a virtual DVD or floppy drive only, this forcibly
+            unmounts the DVD/CD/Floppy or mounts a new DVD/CD/Floppy
+            even if the previous one is locked down by the guest for
+            reading. Again, see <xref linkend="storage-cds" /> for
+            details.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+      When "iscsi" is used with the
+      <computeroutput>--medium</computeroutput> parameter for iSCSI
+      support, additional parameters must or can be used. See also
+      <xref linkend="storage-iscsi" />.
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--server</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            The host name or IP address of the iSCSI target; required.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--target</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Target name string. This is determined by the iSCSI target
+            and used to identify the storage resource; required.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--tport</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            TCP/IP port number of the iSCSI service on the target.
+            Optional.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--lun</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Logical Unit Number of the target resource. Optional. Often,
+            this value is zero.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--encodedlun</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Hex encoded Logical Unit Number of the target resource.
+            Optional. Often, this value is zero.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--username, --password,
+          --passwordfile</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Username and password (initiator secret) for target
+            authentication, if required. Optional.
+
+            <note>
+              <para>
+                Username and password are stored without encryption, in
+                clear text, in the XML machine configuration file if no
+                settings password is provided. When a settings password
+                was specified the first time, the password is stored
+                encrypted. Alternatively to providing the password on
+                the command line, a reference to a file containing the
+                text can be provided instead via the passwordfile
+                option.
+              </para>
+            </note>
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--initiator</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            iSCSI Initiator (optional).
+          </para>
+
+          <para>
+            Note: Microsoft iSCSI Initiator is a system, such as a
+            server that attaches to an IP network and initiates requests
+            and receives responses from an iSCSI target. The SAN
+            components in Microsoft iSCSI Initiator are largely
+            analogous to Fibre Channel SAN components, and they include
+            the following:
+          </para>
+
+          <para>
+            To transport blocks of iSCSI commands over the IP network,
+            an iSCSI driver must be installed on the iSCSI host. An
+            iSCSI driver is included with Microsoft iSCSI Initiator.
+          </para>
+
+          <para>
+            A gigabit Ethernet adapter that transmits 1000 megabits per
+            second (Mbps) is recommended for the connection to an iSCSI
+            target. Like standard 10/100 adapters, most gigabit adapters
+            use a pre-existing Category 5 or Category 6E cable. Each
+            port on the adapter is identified by a unique IP address.
+          </para>
+
+          <para>
+            An iSCSI target is any device that receives iSCSI commands.
+            The device can be an end node, such as a storage device, or
+            it can be an intermediate device, such as a network bridge
+            between IP and Fibre Channel devices. Each port on the
+            storage array controller or network bridge is identified by
+            one or more IP addresses
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--intnet</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            If specified, connect to the iSCSI target via Internal
+            Networking. This needs further configuration, see
+            <xref linkend="iscsi-intnet" />.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
   </sect1>
 
   <sect1 id="vboxmanage-storagectl">
+
     <title>VBoxManage storagectl</title>
 
-    <para>This command attaches/modifies/removes a storage controller. After
-    this, virtual media can be attached to the controller with the
-    <computeroutput>storageattach</computeroutput> command (see the next
-    section).</para>
-
-    <para>The syntax is as follows:</para>
-
-    <screen>VBoxManage storagectl       &lt;uuid|vmname&gt;
+    <para>
+      This command attaches/modifies/removes a storage controller. After
+      this, virtual media can be attached to the controller with the
+      <computeroutput>storageattach</computeroutput> command .
+    </para>
+
+    <para>
+      The syntax is as follows:
+    </para>
+
+<screen>VBoxManage storagectl       &lt;uuid|vmname&gt;
                             --name &lt;name&gt;
                             [--add ide|sata|scsi|floppy|sas|usb|pcie]
@@ -3237,201 +4723,308 @@
                             [--remove]</screen>
 
-    <para>where the parameters mean: <glosslist>
-        <glossentry>
-          <glossterm><computeroutput>uuid|vmname</computeroutput></glossterm>
-
-          <glossdef>
-            <para>The VM UUID or VM Name. Mandatory.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--name</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Specifies the name of the storage controller. Mandatory.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--add</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Specifies the type of the system bus to which the storage
-            controller must be connected.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--controller</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Enables a choice of chipset type being emulated for the
-            given storage controller.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--portcount</computeroutput></glossterm>
-
-          <glossdef>
-            <para>This specifies the number of ports the storage controller should
-            support.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--hostiocache</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Configures the use of the host I/O cache for all disk images
-            attached to this storage controller. For details, please see <xref
-            linkend="iocaching" />.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--bootable</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Specifies whether this controller is bootable.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--rename</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Specifies a new name for the storage controller.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--remove</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Removes the storage controller from the VM config.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist></para>
+    <para>
+      where the parameters mean:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>uuid|vmname</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            The VM UUID or VM Name. Mandatory.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--name</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies the name of the storage controller. Mandatory.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--add</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies the type of the system bus to which the storage
+            controller must be connected.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--controller</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables a choice of chipset type being emulated for the
+            given storage controller.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--portcount</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This specifies the number of ports the storage controller
+            should support.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--hostiocache</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Configures the use of the host I/O cache for all disk images
+            attached to this storage controller. See
+            <xref
+            linkend="iocaching" />.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--bootable</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies whether this controller is bootable.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--rename</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies a new name for the storage controller.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--remove</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Removes the storage controller from the VM config.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
   </sect1>
 
-  <sect1>
+  <sect1 id="vboxmanage-bandwidthctl">
+
     <title>VBoxManage bandwidthctl</title>
 
-    <para>This command creates/deletes/modifies/shows bandwidth groups of the given
-    virtual machine:
-    <screen>VBoxManage bandwidthctl    &lt;uuid|vmname&gt;
-                           add &lt;name&gt; --type disk|network --limit &lt;megabytes per second&gt;[k|m|g|K|M|G] |
-                           set &lt;name&gt; --limit &lt;megabytes per second&gt;[k|m|g|K|M|G] |
+    <para>
+      This command creates/deletes/modifies/shows bandwidth groups of
+      the given virtual machine:
+
+<screen>VBoxManage bandwidthctl    &lt;uuid|vmname&gt;
+                           add &lt;name&gt; --type disk|network --limit &lt;MBps&gt;[k|m|g|K|M|G] |
+                           set &lt;name&gt; --limit &lt;MBps&gt;[k|m|g|K|M|G] |
                            remove &lt;name&gt; |
-                           list [--machinereadable]</screen></para>
-
-    <para>The following subcommands are available:<itemizedlist>
-      <listitem>
-        <para><computeroutput>add</computeroutput>, creates a new bandwidth
-        group of a given type.</para>
-      </listitem>
-      <listitem>
-        <para><computeroutput>set</computeroutput>, modifies the limit for an
-        existing bandwidth group.</para>
-      </listitem>
-      <listitem>
-        <para><computeroutput>remove</computeroutput>, destroys a bandwidth
-        group.</para>
-      </listitem>
-      <listitem>
-        <para><computeroutput>list</computeroutput>, shows all bandwidth groups
-        defined for the given VM. Use the <computeroutput>--machinereadable</computeroutput>
-        option to produce the same output, but in machine readable format. This is of the
-        form: name="value" on a line by line basis.</para>
-      </listitem>
+                           list [--machinereadable]</screen>
+    </para>
+
+    <para>
+      The following subcommands are available:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <computeroutput>add</computeroutput>, creates a new bandwidth
+          group of a given type.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>set</computeroutput>, modifies the limit for
+          an existing bandwidth group.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>remove</computeroutput>, destroys a bandwidth
+          group.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>list</computeroutput>, shows all bandwidth
+          groups defined for the given VM. Use the
+          <computeroutput>--machinereadable</computeroutput> option to
+          produce the same output, but in machine readable format. This
+          is of the form: name="value" on a line by line basis.
+        </para>
+      </listitem>
+
     </itemizedlist>
-    </para>
-    <para>The parameters mean:<glosslist>
-        <glossentry>
-          <glossterm><computeroutput>uuid|vmname</computeroutput></glossterm>
-
-          <glossdef>
-            <para>The VM UUID or VM Name. Mandatory.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--name</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Name of the bandwidth group. Mandatory.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--type</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Type of the bandwidth group. Mandatory. Two types are
+
+    <para>
+      The parameters mean the following:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>uuid|vmname</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            The VM UUID or VM Name. Mandatory.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--name</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Name of the bandwidth group. Mandatory.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--type</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Type of the bandwidth group. Mandatory. Two types are
             supported: <computeroutput>disk</computeroutput> and
             <computeroutput>network</computeroutput>. See
             <xref linkend="storage-bandwidth-limit" /> or
-            <xref linkend="network_bandwidth_limit" /> for the description of a
-            particular type.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--limit</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Specifies the limit for the given bandwidth group. This can be changed
-            while the VM is running. The default unit is megabytes per
-            second. The unit can be changed by specifying one of the
-            following suffixes: <computeroutput>k</computeroutput> for kilobits/s,
+            <xref linkend="network_bandwidth_limit" /> for the
+            description of a particular type.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--limit</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies the limit for the given bandwidth group. This can
+            be changed while the VM is running. The default unit is
+            megabytes per second. The unit can be changed by specifying
+            one of the following suffixes:
+            <computeroutput>k</computeroutput> for kilobits/s,
             <computeroutput>m</computeroutput> for megabits/s,
             <computeroutput>g</computeroutput> for gigabits/s,
             <computeroutput>K</computeroutput> for kilobytes/s,
             <computeroutput>M</computeroutput> for megabytes/s,
-            <computeroutput>G</computeroutput> for gigabytes/s.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
+            <computeroutput>G</computeroutput> for gigabytes/s.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <note>
+      <para>
+        The network bandwidth limits apply only to the traffic being
+        sent by virtual machines. The traffic being received by VMs is
+        unlimited.
+      </para>
+    </note>
+
+    <note>
+      <para>
+        To remove a bandwidth group it must not be referenced by any
+        disks or adapters in the running VM.
+      </para>
+    </note>
+
+  </sect1>
+
+  <sect1 id="vboxmanage-showmediuminfo">
+
+    <title>VBoxManage showmediuminfo</title>
+
+    <para>
+      This command shows information about a medium, notably its size,
+      its size on disk, its type and the virtual machines which use it.
+
       <note>
-        <para>The network bandwidth limits apply only to the traffic being sent by
-        virtual machines. The traffic being received by VMs is unlimited.</para>
+        <para>
+          For compatibility with earlier versions of VirtualBox, the
+          "showvdiinfo" command is also supported and mapped internally
+          to the "showmediuminfo" command.
+        </para>
       </note>
-      <note>
-        <para>To remove a bandwidth group it must not be referenced by any disks
-        or adapters in the running VM.</para>
-      </note>
-    </para>
+    </para>
+
+<screen>VBoxManage showmediuminfo     [disk|dvd|floppy] &lt;uuid|filename&gt;</screen>
+
+    <para>
+      The medium must be specified either by its UUID (if the medium is
+      registered) or by its filename. Registered images can be listed by
+      <computeroutput>VBoxManage list hdds</computeroutput>,
+      <computeroutput>VBoxManage list dvds</computeroutput>, or
+      <computeroutput>VBoxManage list floppies</computeroutput>, as
+      appropriate. See <xref linkend="vboxmanage-list" />.
+    </para>
+
   </sect1>
 
-  <sect1>
-    <title>VBoxManage showmediuminfo</title>
-
-    <para>This command shows information about a medium,
-    notably its size, its size on disk, its type and the virtual machines
-    which use it.<note>
-        <para>For compatibility with earlier versions of VirtualBox, the
-        "showvdiinfo" command is also supported and mapped internally to the
-        "showmediuminfo" command.</para>
-      </note></para>
-
-    <screen>VBoxManage showmediuminfo     [disk|dvd|floppy] &lt;uuid|filename&gt;</screen>
-
-    <para>The medium must be specified either by its UUID (if the medium
-      is registered) or by its filename. Registered images can be listed by
-      <computeroutput>VBoxManage list hdds</computeroutput>,
-      <computeroutput>VBoxManage list dvds</computeroutput>,
-      or <computeroutput>VBoxManage list floppies</computeroutput>, as appropriate.
-      (see <xref linkend="vboxmanage-list" />
-      for more information).</para>
-  </sect1>
-
   <sect1 id="vboxmanage-createmedium">
+
     <title>VBoxManage createmedium</title>
 
-    <para>This command creates a new medium. The syntax is as follows:</para>
-
-    <screen>VBoxManage createmedium     [disk|dvd|floppy]    --filename &lt;filename&gt;
+    <para>
+      This command creates a new medium. The syntax is as follows:
+    </para>
+
+<screen>VBoxManage createmedium     [disk|dvd|floppy]    --filename &lt;filename&gt;
                             [--size &lt;megabytes&gt;|--sizebyte &lt;bytes&gt;]
                             [--diffparent &lt;uuid&gt;|&lt;filename&gt;
@@ -3439,63 +5032,103 @@
                             [--variant Standard,Fixed,Split2G,Stream,ESX]</screen>
 
-    <para>where the parameters mean:<glosslist>
-        <glossentry>
-          <glossterm><computeroutput>--filename &lt;filename&gt;</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Specifies a file name &lt;filename&gt; as an absolute path on the host file
-            system. Mandatory.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--size &lt;megabytes&gt;</computeroutput></glossterm>
-
-          <glossdef>
-            <para>&lt;megabytes&gt; Specifies the image capacity, in 1 MB units.
-            Optional.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--diffparent &lt;uuid&gt;|&lt;filename&gt;</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Specifies the differencing image parent, either as a UUID or
-            by the absolute pathname of the file on the host file system.
-            Useful for sharing a base box disk image among several VMs.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--format VDI|VMDK|VHD</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Specifies the file format for the output file. Available
-            options are VDI, VMDK, VHD. Default is VDI. Optional. </para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--variant Standard,Fixed,Split2G,Stream,ESX</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Specifies any required file format variant(s) for the output file.  It is a
-            comma-separated list of variant flags. Not all combinations are supported, and specifying
-            mutually incompatible flags results in an error message. Optional.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist> <note>
-        <para>For compatibility with earlier versions of VirtualBox, the "createvdi"  and "createhd" commands
-        are also supported and mapped internally to the "createmedium" command.</para>
-      </note></para>
+    <para>
+      where the parameters mean:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--filename &lt;filename&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies a file name &lt;filename&gt; as an absolute path
+            on the host file system. Mandatory.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--size &lt;megabytes&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            &lt;megabytes&gt; Specifies the image capacity, in 1 MB
+            units. Optional.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--diffparent
+          &lt;uuid&gt;|&lt;filename&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies the differencing image parent, either as a UUID or
+            by the absolute pathname of the file on the host file
+            system. Useful for sharing a base box disk image among
+            several VMs.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--format VDI|VMDK|VHD</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies the file format for the output file. Available
+            options are VDI, VMDK, VHD. Default is VDI. Optional.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--variant
+          Standard,Fixed,Split2G,Stream,ESX</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies any required file format variant(s) for the output
+            file. It is a comma-separated list of variant flags. Not all
+            combinations are supported, and specifying mutually
+            incompatible flags results in an error message. Optional.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <note>
+      <para>
+        For compatibility with earlier versions of VirtualBox, the
+        "createvdi" and "createhd" commands are also supported and
+        mapped internally to the "createmedium" command.
+      </para>
+    </note>
+
   </sect1>
 
   <sect1 id="vboxmanage-modifyvdi">
+
     <title>VBoxManage modifymedium</title>
 
-    <para>With the <computeroutput>modifymedium</computeroutput> command, you can
-    change the characteristics of a disk image after it has been
-    created:<screen>VBoxManage modifymedium  [disk|dvd|floppy]    &lt;uuid|filename&gt;
+    <para>
+      With the <computeroutput>modifymedium</computeroutput> command,
+      you can change the characteristics of a disk image after it has
+      been created:
+
+<screen>VBoxManage modifymedium  [disk|dvd|floppy]    &lt;uuid|filename&gt;
                          [--type normal|writethrough|immutable|shareable|
                                  readonly|multiattach]
@@ -3504,98 +5137,148 @@
                          [--compact]
                          [--resize &lt;megabytes&gt;|--resizebyte &lt;bytes&gt;]
-                         [--move &lt;path&gt;</screen><note>
-        <para>For compatibility with earlier versions of VirtualBox, the "modifyvdi" and "modifyhd"
-        commands are also supported and mapped internally to the "modifymedium" command.</para>
-      </note></para>
-
-      <para>The disk image to modify must be specified either by its UUID
-        (if the medium is registered) or by its filename. Registered images
-        can be listed by <computeroutput>VBoxManage list hdds</computeroutput>
-        (see <xref linkend="vboxmanage-list" /> for more information).
-        A filename must be specified as valid path, either as an absolute path
-        or as a relative path starting from the current directory.</para>
-    <para>The following options are available:<itemizedlist>
-        <listitem>
-          <para>With the <computeroutput>--type</computeroutput> argument, you
+                         [--move &lt;path&gt;</screen>
+
+      <note>
+        <para>
+          For compatibility with earlier versions of VirtualBox, the
+          "modifyvdi" and "modifyhd" commands are also supported and
+          mapped internally to the "modifymedium" command.
+        </para>
+      </note>
+    </para>
+
+    <para>
+      The disk image to modify must be specified either by its UUID (if
+      the medium is registered) or by its filename. Registered images
+      can be listed by <computeroutput>VBoxManage list
+      hdds</computeroutput>, see <xref linkend="vboxmanage-list" />. A
+      filename must be specified as a valid path, either as an absolute
+      path or as a relative path starting from the current directory.
+    </para>
+
+    <para>
+      The following options are available:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          With the <computeroutput>--type</computeroutput> argument, you
           can change the type of an existing image between the normal,
-          immutable, write-through and other modes; see <xref
-          linkend="hdimagewrites" /> for details.</para>
-        </listitem>
-
-        <listitem>
-          <para>For immutable (differencing) hard disks only, the
+          immutable, write-through and other modes. See
+          <xref
+          linkend="hdimagewrites" />.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          For immutable (differencing) hard disks only, the
           <computeroutput>--autoreset on|off</computeroutput> option
           determines whether the disk is automatically reset on every VM
-          startup (again, see <xref linkend="hdimagewrites" />). The default
-          is "on".</para>
-        </listitem>
-
-        <listitem>
-          <para>The <computeroutput>--compact</computeroutput> option
-          can be used to compact disk images, i.e. remove blocks that only
-          contains zeroes. This will shrink a dynamically allocated image
-          again; it will reduce the <emphasis>physical</emphasis> size of the
-          image without affecting the logical size of the virtual disk.
-          Compaction works both for base images and for diff images created as
-          part of a snapshot.</para>
-
-          <para>For this operation to be effective, it is required that free
+          startup, see <xref linkend="hdimagewrites" />. The default is
+          "on".
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The <computeroutput>--compact</computeroutput> option can be
+          used to compact disk images, i.e. remove blocks that only
+          contains zeroes. This will shrink a dynamically allocated
+          image again; it will reduce the <emphasis>physical</emphasis>
+          size of the image without affecting the logical size of the
+          virtual disk. Compaction works both for base images and for
+          diff images created as part of a snapshot.
+        </para>
+
+        <para>
+          For this operation to be effective, it is required that free
           space in the guest system first be zeroed out using a suitable
           software tool. For Windows guests, you can use the
-          <computeroutput>sdelete</computeroutput> tool provided by Microsoft.
-          Execute <computeroutput>sdelete -z</computeroutput> in the guest to
-          zero the free disk space before compressing the virtual disk
-          image. For Linux, use the <code>zerofree</code> utility which
-          supports ext2/ext3 filesystems. For Mac OS X guests, use the
-          <code>diskutil secureErase freespace 0 /</code> command line
-          from an elevated Terminal.</para>
-
-          <para>Please note that compacting is currently only available for
-          VDI images. A similar effect can be achieved by zeroing out free
-          blocks and then cloning the disk to any other dynamically allocated
-          format. You can use this workaround until compacting is also
-          supported for disk formats other than VDI.</para>
-        </listitem>
-
-        <listitem>
-          <para>The <computeroutput>--resize x</computeroutput> option (where x
-          is the desired new total space in <emphasis role="bold">megabytes</emphasis>)
-          allows you to change the capacity of an existing image; this adjusts the
-          <emphasis>logical</emphasis> size of a virtual disk without affecting
-          the physical size much.<footnote>
-              <para>Image resizing was added with VirtualBox 4.0.</para>
-            </footnote> This currently works only for VDI and VHD formats, and only
-          for the dynamically allocated variants, and can only be used to expand
-          (not shrink) the capacity.
-          For example, if you originally created a 10G disk which is now full,
-          you can use the <computeroutput>--resize 15360</computeroutput>
-          command to change the capacity to 15G (15,360MB) without having to create a new
-          image and copy all data from within a virtual machine. Note however that
-          this only changes the drive capacity; you will typically next need to use
-          a partition management tool inside the guest to adjust the main partition
-          to fill the drive.</para><para>The <computeroutput>--resizebyte x</computeroutput>
-          option does almost the same thing, except that x is expressed in bytes
-          instead of megabytes.</para>
-        </listitem>
-
-        <listitem>
-          <para>The <computeroutput>--move &lt;path&gt;</computeroutput> option
-          can be used to relocate a medium to a different location &lt;path&gt; on the
-          host file system. The path can be either relative to the current directory or
-          absolute.</para>
-        </listitem>
-      </itemizedlist></para>
+          <computeroutput>sdelete</computeroutput> tool provided by
+          Microsoft. Execute <computeroutput>sdelete -z</computeroutput>
+          in the guest to zero the free disk space before compressing
+          the virtual disk image. For Linux, use the
+          <code>zerofree</code> utility which supports ext2/ext3
+          filesystems. For Mac OS X guests, use the <code>diskutil
+          secureErase freespace 0 /</code> command line from an elevated
+          Terminal.
+        </para>
+
+        <para>
+          Please note that compacting is currently only available for
+          VDI images. A similar effect can be achieved by zeroing out
+          free blocks and then cloning the disk to any other dynamically
+          allocated format. You can use this workaround until compacting
+          is also supported for disk formats other than VDI.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The <computeroutput>--resize x</computeroutput> option, where
+          x is the desired new total space in
+          <emphasis role="bold">megabytes</emphasis> enables you to
+          change the capacity of an existing image. This adjusts the
+          <emphasis>logical</emphasis> size of a virtual disk without
+          affecting the physical size much.
+
+          <footnote>
+
+            <para>
+              Image resizing was added with VirtualBox 4.0.
+            </para>
+
+          </footnote>
+
+          This currently works only for VDI and VHD formats, and only
+          for the dynamically allocated variants, and can only be used
+          to expand (not shrink) the capacity. For example, if you
+          originally created a 10 GB disk which is now full, you can use
+          the <computeroutput>--resize 15360</computeroutput> command to
+          change the capacity to 15 GB (15,360 MB) without having to
+          create a new image and copy all data from within a virtual
+          machine. Note however that this only changes the drive
+          capacity. You will typically next need to use a partition
+          management tool inside the guest to adjust the main partition
+          to fill the drive.
+        </para>
+
+        <para>
+          The <computeroutput>--resizebyte x</computeroutput> option
+          does almost the same thing, except that x is expressed in
+          bytes instead of megabytes.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          The <computeroutput>--move &lt;path&gt;</computeroutput>
+          option can be used to relocate a medium to a different
+          location &lt;path&gt; on the host file system. The path can be
+          either relative to the current directory or absolute.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
   <sect1 id="vboxmanage-clonevdi">
+
     <title>VBoxManage clonemedium</title>
 
-    <para>This command duplicates a virtual disk/DVD/floppy medium to a
-    new medium (usually an image file) with a new unique identifier (UUID).
-    The new image can be transferred to another host system or imported into
-    VirtualBox again using the Virtual Media Manager; see <xref linkend="vdis" />
-    and <xref linkend="cloningvdis" />. The syntax is as follows:</para>
-
-    <screen>VBoxManage clonemedium      [disk|dvd|floppy] &lt;uuid|inputfile&gt; &lt;uuid|outputfile&gt;
+    <para>
+      This command duplicates a virtual disk/DVD/floppy medium to a new
+      medium, usually an image file, with a new unique identifier
+      (UUID). The new image can be transferred to another host system or
+      reimported into VirtualBox using the Virtual Media Manager. See
+      <xref linkend="vdis" /> and <xref linkend="cloningvdis" />. The
+      syntax is as follows:
+    </para>
+
+<screen>VBoxManage clonemedium      [disk|dvd|floppy] &lt;uuid|inputfile&gt; &lt;uuid|outputfile&gt;
 
                             [--format VDI|VMDK|VHD|RAW|&lt;other&gt;]
@@ -3603,132 +5286,199 @@
                             [--existing]</screen>
 
-
-    <para>The medium to clone as well as the target image must be described
-       either by its UUIDs (if the mediums are registered) or by its filename.
-       Registered images can be listed by <computeroutput>VBoxManage list hdds</computeroutput>
-       (see <xref linkend="vboxmanage-list" /> for more information).
-       A filename must be specified as valid path, either as an absolute path or
-       as a relative path starting from the current directory.</para>
-    <para>The following options are available:<glosslist>
-        <glossentry>
-          <glossterm><computeroutput>--format</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Allow to choose a file format for the output file different
-            from the file format of the input file.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--variant</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Allow to choose a file format variant for the output file.
+    <para>
+      The medium to clone as well as the target image must be described
+      either by its UUIDs, if the mediums are registered, or by its
+      filename. Registered images can be listed by
+      <computeroutput>VBoxManage list hdds</computeroutput>. See
+      <xref linkend="vboxmanage-list" />. A filename must be specified
+      as valid path, either as an absolute path or as a relative path
+      starting from the current directory.
+    </para>
+
+    <para>
+      The following options are available:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--format</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Allow to choose a file format for the output file different
+            from the file format of the input file.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--variant</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Allow to choose a file format variant for the output file.
             It is a comma-separated list of variant flags. Not all
-            combinations are supported, and specifying inconsistent flags will
-            result in an error message.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--existing</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Perform the clone operation to an already existing
-            destination medium. Only the portion of the source medium which
-            fits into the destination medium is copied. This means if the
-            destination medium is smaller than the source only a part of it is
-            copied, and if the destination medium is larger than the source
-            the remaining part of the destination medium is unchanged.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist> <note>
-        <para>For compatibility with earlier versions of VirtualBox, the
+            combinations are supported, and specifying inconsistent
+            flags will result in an error message.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--existing</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Perform the clone operation to an already existing
+            destination medium. Only the portion of the source medium
+            which fits into the destination medium is copied. This means
+            if the destination medium is smaller than the source only a
+            part of it is copied, and if the destination medium is
+            larger than the source the remaining part of the destination
+            medium is unchanged.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <note>
+      <para>
+        For compatibility with earlier versions of VirtualBox, the
         "clonevdi" and "clonehd" commands are still supported and mapped
-        internally to the "clonehd disk" command.</para>
-      </note></para>
+        internally to the "clonehd disk" command.
+      </para>
+    </note>
+
   </sect1>
 
   <sect1 id="vboxmanage-mediumproperty">
+
     <title>VBoxManage mediumproperty</title>
 
-    <para>This command sets up, gets or deletes a medium property.
-    The syntax is as follows:</para>
-
-    <screen>VBoxManage mediumproperty [disk|dvd|floppy] set &lt;uuid|filename&gt;
+    <para>
+      This command sets up, gets or deletes a medium property. The
+      syntax is as follows:
+    </para>
+
+<screen>VBoxManage mediumproperty [disk|dvd|floppy] set &lt;uuid|filename&gt;
                                                 &lt;property&gt; &lt;value&gt;</screen>
 
-
-    <para><itemizedlist>
-        <listitem>
-          <para>Use <computeroutput>&lt;disk|dvd|floppy&gt;</computeroutput> to optionally specify
-           the type of medium: disk (hard drive), dvd or floppy.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to supply either the uuid
-          or absolute path of the medium/image to be encrypted.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>&lt;property&gt;</computeroutput> to supply the name of the
-          property.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>&lt;value&gt;</computeroutput> to supply the property value.</para>
-        </listitem>
-    </itemizedlist></para>
-
-    <screen>VBoxManage mediumproperty [disk|dvd|floppy] get &lt;uuid|filename&gt;
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;disk|dvd|floppy&gt;</computeroutput>
+          to optionally specify the type of medium: disk (hard drive),
+          dvd or floppy.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to
+          supply either the uuid or absolute path of the medium/image to
+          be encrypted.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;property&gt;</computeroutput> to
+          supply the name of the property.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;value&gt;</computeroutput> to supply
+          the property value.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+<screen>VBoxManage mediumproperty [disk|dvd|floppy] get &lt;uuid|filename&gt;
                                                 &lt;property&gt;</screen>
-    <para><itemizedlist>
-        <listitem>
-          <para>Use <computeroutput>&lt;disk|dvd|floppy&gt;</computeroutput> to optionally specify
-           the type of medium: disk (hard drive), dvd or floppy.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to supply either the uuid
-          or absolute path of the medium/image to be encrypted.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>&lt;property&gt;</computeroutput> to supply the name of the
-          property.</para>
-        </listitem>
-    </itemizedlist></para>
-
-    <screen>VBoxManage mediumproperty [disk|dvd|floppy] delete &lt;uuid|filename&gt;
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;disk|dvd|floppy&gt;</computeroutput>
+          to optionally specify the type of medium: disk (hard drive),
+          dvd or floppy.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to
+          supply either the uuid or absolute path of the medium/image to
+          be encrypted.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;property&gt;</computeroutput> to
+          supply the name of the property.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+<screen>VBoxManage mediumproperty [disk|dvd|floppy] delete &lt;uuid|filename&gt;
                                                    &lt;property&gt;</screen>
 
-
-    <para><itemizedlist>
-        <listitem>
-          <para>Use <computeroutput>&lt;disk|dvd|floppy&gt;</computeroutput> to optionally specify
-           the type of medium: disk (hard drive), dvd or floppy.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to supply either the uuid
-          or absolute path of the medium/image.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>&lt;property&gt;</computeroutput> to supply the name of the
-          property.</para>
-        </listitem>
-    </itemizedlist></para>
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;disk|dvd|floppy&gt;</computeroutput>
+          to optionally specify the type of medium: disk (hard drive),
+          dvd or floppy.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to
+          supply either the uuid or absolute path of the medium/image.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;property&gt;</computeroutput> to
+          supply the name of the property.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
   <sect1 id="vboxmanage-encryptmedium">
+
     <title>VBoxManage encryptmedium</title>
 
-    <para>This command is used to create a DEK encrypted medium/image.
-    See <xref linkend="diskencryption-encryption" />" for details.</para>
-
-    <para>The syntax is as follows:</para>
-
-    <screen>VBoxManage encryptmedium &lt;uuid|filename&gt;
+    <para>
+      This command is used to create a DEK encrypted medium/image. See
+      <xref linkend="diskencryption-encryption" />.
+    </para>
+
+    <para>
+      The syntax is as follows:
+    </para>
+
+<screen>VBoxManage encryptmedium &lt;uuid|filename&gt;
                          [--newpassword &lt;file|-&gt;]
                          [--oldpassword &lt;file|-&gt;]
@@ -3736,45 +5486,77 @@
                          [--newpasswordid &lt;password id&gt;]</screen>
 
-    <para><itemizedlist>
-        <listitem>
-          <para>use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to supply the
-           uuid or absolute path of the medium/image to be encrypted.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>--newpassword &lt;file|-&gt;</computeroutput> to supply a new
-          encryption password; either specify the absolute pathname of a password file on the host operating system,
-          or <computeroutput>-</computeroutput> to prompt you for the password on the command line.
-          Always use the <computeroutput>--newpasswordid</computeroutput> option with this option.</para>
-        </listitem>
-
-        <listitem>
-          <para>use <computeroutput>--oldpassword &lt;file|-&gt;</computeroutput> to supply any old
-          encryption password; either specify the absolute pathname of a password file on the host operating system,
-          or <computeroutput>-</computeroutput> to prompt you for the old password on the command line.</para>
-
-          <para>Use this option to gain access to an encrypted medium/image to change its password using
-          <computeroutput>--newpassword</computeroutput> and/or change its encryption using
-          <computeroutput>--cipher</computeroutput>.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>--cipher &lt;cipher&gt;</computeroutput> to specify the cipher to use for
-          encryption; this can be either <computeroutput>AES-XTS128-PLAIN64</computeroutput> or
-          <computeroutput>AES-AXTS256-PLAIN64</computeroutput>.</para>
-
-          <para>Use this option to change any existing encryption on the medium/image, or setup new encryption on
-          it for the 1st time.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>--newpasswordid &lt;password id&gt;</computeroutput> to supply the new password identifier.
-          This can be freely chosen by the user, and is used for correct identification when supplying multiple
-          passwords during VM startup.</para>
-
-          <para>If the user uses the same password when encrypting multiple images and also the same password identifier, the
-          user needs to supply the password only once during VM startup.</para>
-        </listitem>
-    </itemizedlist></para>
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to
+          supply the uuid or absolute path of the medium/image to be
+          encrypted.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>--newpassword
+          &lt;file|-&gt;</computeroutput> to supply a new encryption
+          password; either specify the absolute pathname of a password
+          file on the host operating system, or
+          <computeroutput>-</computeroutput> to prompt you for the
+          password on the command line. Always use the
+          <computeroutput>--newpasswordid</computeroutput> option with
+          this option.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          use <computeroutput>--oldpassword
+          &lt;file|-&gt;</computeroutput> to supply any old encryption
+          password; either specify the absolute pathname of a password
+          file on the host operating system, or
+          <computeroutput>-</computeroutput> to prompt you for the old
+          password on the command line.
+        </para>
+
+        <para>
+          Use this option to gain access to an encrypted medium/image to
+          change its password using
+          <computeroutput>--newpassword</computeroutput> and/or change
+          its encryption using
+          <computeroutput>--cipher</computeroutput>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>--cipher &lt;cipher&gt;</computeroutput>
+          to specify the cipher to use for encryption; this can be
+          either <computeroutput>AES-XTS128-PLAIN64</computeroutput> or
+          <computeroutput>AES-AXTS256-PLAIN64</computeroutput>.
+        </para>
+
+        <para>
+          Use this option to change any existing encryption on the
+          medium/image, or setup new encryption on it for the 1st time.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>--newpasswordid &lt;password
+          id&gt;</computeroutput> to supply the new password identifier.
+          This can be freely chosen by the user, and is used for correct
+          identification when supplying multiple passwords during VM
+          startup.
+        </para>
+
+        <para>
+          If the user uses the same password when encrypting multiple
+          images and also the same password identifier, the user needs
+          to supply the password only once during VM startup.
+        </para>
+      </listitem>
+
+    </itemizedlist>
 
   </sect1>
@@ -3784,33 +5566,51 @@
     <title>VBoxManage checkmediumpwd</title>
 
-    <para>This command is used to check the current encryption password on a DEK encrypted medium/image.
-    See <xref linkend="diskencryption-encryption" />" for details.</para>
-
-    <para>The syntax is as follows:</para>
-
-    <screen>VBoxManage checkmediumpwd &lt;uuid|filename&gt;
+    <para>
+      This command is used to check the current encryption password on a
+      DEK encrypted medium/image. See
+      <xref linkend="diskencryption-encryption" />.
+    </para>
+
+    <para>
+      The syntax is as follows:
+    </para>
+
+<screen>VBoxManage checkmediumpwd &lt;uuid|filename&gt;
                                       &lt;pwd file|-&gt;</screen>
-    <para><itemizedlist>
-        <listitem>
-          <para>Use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to supply the uuid or absolute path of the
-           medium/image to be checked.</para>
-        </listitem>
-
-        <listitem>
-          <para>Use <computeroutput>&lt;pwd file|-&gt;</computeroutput> to supply the password identifier to be checked. Either
-          specify the absolute pathname of a password file on the host operating system, or <computeroutput>-</computeroutput> to
-          prompt you for the password on the command line.</para>
-        </listitem>
-    </itemizedlist></para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;uuid|filename&gt;</computeroutput> to
+          supply the uuid or absolute path of the medium/image to be
+          checked.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Use <computeroutput>&lt;pwd file|-&gt;</computeroutput> to
+          supply the password identifier to be checked. Either specify
+          the absolute pathname of a password file on the host operating
+          system, or <computeroutput>-</computeroutput> to prompt you
+          for the password on the command line.
+        </para>
+      </listitem>
+
+    </itemizedlist>
 
   </sect1>
 
-  <sect1>
+  <sect1 id="vboxmanage-convertfromraw">
+
     <title>VBoxManage convertfromraw</title>
 
-    <para>This command converts a raw disk image to a VirtualBox Disk Image
-    (VDI) file. The syntax is as follows:</para>
-
-    <screen>VBoxManage convertfromraw   &lt;filename&gt; &lt;outputfile&gt;
+    <para>
+      This command converts a raw disk image to a VirtualBox Disk Image
+      (VDI) file. The syntax is as follows:
+    </para>
+
+<screen>VBoxManage convertfromraw   &lt;filename&gt; &lt;outputfile&gt;
                             [--format VDI|VMDK|VHD]
                             [--variant Standard,Fixed,Split2G,Stream,ESX]
@@ -3821,189 +5621,287 @@
                             [--uuid &lt;uuid&gt;]</screen>
 
-    <para>where the parameters mean:<glosslist>
-        <glossentry>
-          <glossterm><computeroutput>--bytes</computeroutput></glossterm>
-
-          <glossdef>
-            <para>The size of the image file, in bytes, provided through
-            stdin.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--format</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Select the disk image format to create. Default is
-            VDI. Other options are VMDK and VHD.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--variant</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Allow to choose a file format variant for the output file.
+    <para>
+      where the parameters mean:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--bytes</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            The size of the image file, in bytes, provided through
+            stdin.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--format</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Select the disk image format to create. Default is VDI.
+            Other options are VMDK and VHD.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--variant</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Allow to choose a file format variant for the output file.
             It is a comma-separated list of variant flags. Not all
-            combinations are supported, and specifying inconsistent flags will
-            result in an error message.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--uuid</computeroutput></glossterm>
-
-          <glossdef>
-            <para>Allow to specifiy the UUID of the output file.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist> The second form forces VBoxManage to read the content for
-    the disk image from standard input (useful for using that command in a
-    pipe).</para>
-
-    <para><note>
-        <para>For compatibility with earlier versions of VirtualBox, the
-        "convertdd" command is also supported and mapped internally to the
-        "convertfromraw" command.</para>
-      </note></para>
+            combinations are supported, and specifying inconsistent
+            flags will result in an error message.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--uuid</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Allow to specifiy the UUID of the output file.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+      The second form forces VBoxManage to read the content for the disk
+      image from standard input (useful for using that command in a
+      pipe).
+    </para>
+
+    <para>
+      <note>
+        <para>
+          For compatibility with earlier versions of VirtualBox, the
+          "convertdd" command is also supported and mapped internally to
+          the "convertfromraw" command.
+        </para>
+      </note>
+    </para>
+
   </sect1>
 
-  <sect1>
+  <sect1 id="vboxmanage-extradata">
+
     <title>VBoxManage getextradata/setextradata</title>
 
-    <para>These commands let you attach and retrieve string data to a virtual
-    machine or to a VirtualBox configuration (by specifying
-    <computeroutput>global</computeroutput> instead of a virtual machine
-    name). You must specify a key (as a text string) to associate the data
-    with, which you can later use to retrieve it. For example:</para>
-
-    <screen>VBoxManage setextradata Fedora5 installdate 2006.01.01
+    <para>
+      These commands let you attach and retrieve string data to a
+      virtual machine or to a VirtualBox configuration, by specifying
+      <computeroutput>global</computeroutput> instead of a virtual
+      machine name. You must specify a key as a text string to associate
+      the data with, which you can later use to retrieve it. For
+      example:
+    </para>
+
+<screen>VBoxManage setextradata Fedora5 installdate 2006.01.01
 VBoxManage setextradata SUSE10 installdate 2006.02.02</screen>
 
-    <para>would associate the string "2006.01.01" with the key installdate for
-    the virtual machine Fedora5, and "2006.02.02" on the machine SUSE10. You
-    could retrieve the information as follows:</para>
-
-    <screen>VBoxManage getextradata Fedora5 installdate</screen>
-
-    <para>which would return</para>
-
-    <screen>VirtualBox Command Line Management Interface Version @VBOX_VERSION_MAJOR@.@VBOX_VERSION_MINOR@.@VBOX_VERSION_BUILD@
-(C) 2005-@VBOX_C_YEAR@ @VBOX_VENDOR@
+    <para>
+      would associate the string "2006.01.01" with the key installdate
+      for the virtual machine Fedora5, and "2006.02.02" on the machine
+      SUSE10. You could retrieve the information as follows:
+    </para>
+
+<screen>VBoxManage getextradata Fedora5 installdate</screen>
+
+    <para>
+      which would return
+    </para>
+
+<screen>VirtualBox Command Line Management Interface Version <replaceable>version-number</replaceable>
+(C) 2005-2018 Oracle Corporation
 All rights reserved.
 
 Value: 2006.01.01</screen>
 
-    <para>You could retrieve the information for all keys as follows:</para>
-
-    <screen>VBoxManage getextradata Fedora5 enumerate</screen>
-
-    <para>To remove a key, the <computeroutput>setextradata</computeroutput>
-    command must be run without specifying data (only the key), for example:
-    </para>
-
-    <screen>VBoxManage setextradata Fedora5 installdate</screen>
+    <para>
+      You could retrieve the information for all keys as follows:
+    </para>
+
+<screen>VBoxManage getextradata Fedora5 enumerate</screen>
+
+    <para>
+      To remove a key, the <computeroutput>setextradata</computeroutput>
+      command must be run without specifying data, only the key. For
+      example:
+    </para>
+
+<screen>VBoxManage setextradata Fedora5 installdate</screen>
 
   </sect1>
 
   <sect1 id="vboxmanage-setproperty">
+
     <title>VBoxManage setproperty</title>
 
-    <para>This command is used to change global settings which affect the
-    entire VirtualBox installation. Some of these correspond to the settings
-    in the "Global settings" dialog in the graphical user interface. The
-    following properties are available:<glosslist>
-        <glossentry>
-          <glossterm><computeroutput>machinefolder</computeroutput></glossterm>
-          <glossdef>
-            <para>This specifies the default folder in which virtual machine
-            definitions are kept; see <xref linkend="vboxconfigdata" /> for
-            details.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>hwvirtexclusive</computeroutput></glossterm>
-          <glossdef><para>This specifies whether VirtualBox will make exclusive use of
-          the hardware virtualization extensions (Intel VT-x or AMD-V) of the
-          host system's processor; see <xref linkend="hwvirt" />. If you wish to
-          share these extensions with other hypervisors running at the same time,
-          you must disable this setting. Doing so has negative performance implications.
-          </para></glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>vrdeauthlibrary</computeroutput></glossterm>
-
-          <glossdef>
-            <para>This specifies which library to use when "external"
-            authentication has been selected for a particular virtual machine;
-            see <xref linkend="vbox-auth" /> for details.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>websrvauthlibrary</computeroutput></glossterm>
-
-          <glossdef>
-            <para>This specifies which library the web service uses to
-            authenticate users. For details about the VirtualBox web service,
-            please refer to the separate VirtualBox SDK reference (see <xref
-            linkend="VirtualBoxAPI" />).</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>vrdeextpack</computeroutput></glossterm>
-
-          <glossdef>
-            <para>This specifies which library implements the VirtualBox
-            Remote Desktop Extension.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>loghistorycount</computeroutput></glossterm>
-
-          <glossdef>
-            <para>This selects how many rotated (old) VM logs are kept.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>autostartdbpath</computeroutput></glossterm>
-
-          <glossdef>
-            <para>This selects the path to the autostart database. See
-            <xref linkend="autostart" />.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>defaultfrontend</computeroutput></glossterm>
-
-          <glossdef>
-            <para>This selects the global default VM frontend setting. See
-            <xref linkend="vboxmanage-startvm" />.</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>logginglevel</computeroutput></glossterm>
-
-          <glossdef>
-            <para>This configures the VBoxSVC release logging details.<footnote>
-              <para><ulink url="http://www.virtualbox.org/wiki/VBoxLogging">http://www.virtualbox.org/wiki/VBoxLogging</ulink>.</para>
-              </footnote>
-            </para>
-          </glossdef>
-        </glossentry>
-      </glosslist></para>
+    <para>
+      This command is used to change global settings which affect the
+      entire VirtualBox installation. Some of these correspond to the
+      settings in the "Global settings" dialog in the graphical user
+      interface. The following properties are available:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>machinefolder</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This specifies the default folder in which virtual machine
+            definitions are kept. See <xref linkend="vboxconfigdata" />.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>hwvirtexclusive</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This specifies whether VirtualBox will make exclusive use of
+            the hardware virtualization extensions (Intel VT-x or AMD-V)
+            of the host system's processor. See
+            <xref linkend="hwvirt" />. If you wish to share these
+            extensions with other hypervisors running at the same time,
+            you must disable this setting. Doing so has negative
+            performance implications.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>vrdeauthlibrary</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This specifies which library to use when "external"
+            authentication has been selected for a particular virtual
+            machine. See <xref linkend="vbox-auth" />.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>websrvauthlibrary</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This specifies which library the web service uses to
+            authenticate users. For details about the VirtualBox web
+            service, please refer to the separate VirtualBox SDK
+            reference. See <xref
+            linkend="VirtualBoxAPI" />.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>vrdeextpack</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This specifies which library implements the VirtualBox
+            Remote Desktop Extension.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>loghistorycount</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This selects how many rotated (old) VM logs are kept.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>autostartdbpath</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This selects the path to the autostart database. See
+            <xref linkend="autostart" />.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>defaultfrontend</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This selects the global default VM frontend setting. See
+            <xref linkend="vboxmanage-startvm" />.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>logginglevel</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This configures the VBoxSVC release logging details.
+
+            <footnote>
+
+              <para>
+                <ulink url="http://www.virtualbox.org/wiki/VBoxLogging">http://www.virtualbox.org/wiki/VBoxLogging</ulink>.
+              </para>
+
+            </footnote>
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
   </sect1>
 
-  <sect1>
+  <sect1 id="vboxmanage-usbfilter">
+
     <title>VBoxManage usbfilter add/modify/remove</title>
 
-    <screen>VBoxManage usbfilter        add &lt;index,0-N&gt;
+<screen>VBoxManage usbfilter        add &lt;index,0-N&gt;
                           --target &lt;uuid|vmname&gt;global
                           --name &lt;string&gt;
@@ -4020,5 +5918,5 @@
     </screen>
 
-    <screen>VBoxManage usbfilter        modify &lt;index,0-N&gt;
+<screen>VBoxManage usbfilter        modify &lt;index,0-N&gt;
                           --target &lt;uuid|vmname&gt;global
                          [--name &lt;string&gt;]
@@ -4035,122 +5933,169 @@
     </screen>
 
-    <screen>VBoxManage usbfilter        remove &lt;index,0-N&gt;
+<screen>VBoxManage usbfilter        remove &lt;index,0-N&gt;
                           --target &lt;uuid|vmname&gt;global
     </screen>
 
-    <para>The <computeroutput>usbfilter</computeroutput> commands are used for
-    working with USB filters in virtual machines, or global filters which
-    affect the whole VirtualBox setup. Global filters are applied before
-    machine-specific filters, and may be used to prevent devices from being
-    captured by any virtual machine. Global filters are always applied in a
-    particular order, and only the first filter which fits a device is
-    applied. So for example, if the first global filter says to hold (make
-    available) a particular Kingston memory stick device and the second to
-    ignore all Kingston devices, that memory stick will be available to any
-    machine with an appropriate filter, but no other Kingston device
-    will.</para>
-
-    <para>When creating a USB filter using <computeroutput>usbfilter
-    add</computeroutput>, you must supply three or four mandatory parameters.
-    The index specifies the position in the list at which the filter should be
-    placed. If there is already a filter at that position, then it and the
-    following ones will be shifted back one place. Otherwise the new filter
-    will be added onto the end of the list. The
-    <computeroutput>target</computeroutput> parameter selects the virtual
-    machine that the filter should be attached to or use "global" to apply it
-    to all virtual machines. <computeroutput>name</computeroutput> is a name
-    for the new filter and for global filters,
-    <computeroutput>action</computeroutput> says whether to allow VMs
-    access to devices that fit the filter description ("hold") or not to give
-    them access ("ignore"). In addition, you should specify parameters to
-    filter by. You can find the parameters for devices attached to your system
-    using <computeroutput>VBoxManage list usbhost</computeroutput>. Finally,
-    you can specify whether the filter should be active, and for local
-    filters, whether they are for local devices, remote (over an RDP
-    connection) or either.</para>
-
-    <para>When you modify a USB filter using <computeroutput>usbfilter
-    modify</computeroutput>, you must specify the filter by index (see the
-    output of <computeroutput>VBoxManage list usbfilters</computeroutput> to
-    find global filter indexes and that of <computeroutput>VBoxManage
-    showvminfo</computeroutput> to find indexes for individual machines) and
-    by target, which is either a virtual machine or "global". The properties
-    which can be changed are the same as for <computeroutput>usbfilter
-    add</computeroutput>. To remove a filter, use <computeroutput>usbfilter
-    remove</computeroutput> and specify the index and the target.</para>
-
-    <para>The following is a list of the additional
-    <computeroutput>usbfilter add</computeroutput> and
-    <computeroutput>usbfilter modify</computeroutput> options, with detailed
-    explanations on how to use them.</para>
-
-    <para><itemizedlist>
-        <listitem>
-          <para><computeroutput>--action ignore|hold</computeroutput>Specifies
-          whether devices that fit the filter description are allowed access by
-          machines ("hold"), or have access denied ("ignore"). Applies to
-          global filters only.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--active yes|no</computeroutput>Specifies whether
-          the USB Filter is active or temporarily disabled. For
-          <computeroutput>usbfilter create</computeroutput> the default is
-          active.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--vendorid &lt;XXXX&gt;|""</computeroutput>Specifies
-           a vendor ID filter - the string representation for the exact matching
-           has the form XXXX, where X is the hex digit (including leading zeroes).</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--productid &lt;XXXX&gt;|""</computeroutput>Specifies
-           a product ID filter - The string representation for the exact matching has
-           the form XXXX, where X is the hex digit (including leading zeroes).</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--revision &lt;IIFF&gt;|""</computeroutput>Specifies
-           a revision ID filter - the string representation for the exact matching has
-           the form IIFF, where I is the decimal digit of the integer part of the revision,
-           and F is the decimal digit of its fractional part (including leading and trailing zeros).
-           Note that for interval filters, it's best to use the hex form, because the revision is
-           stored as a 16 bit packed BCD value; so the expression int:0x0100-0x0199 will match
-           any revision from 1.0 to 1.99 inclusive.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--manufacturer &lt;string&gt;|""</computeroutput>Specifies
-           a manufacturer ID filter, as a string.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--product &lt;string&gt;|""</computeroutput>Specifies
-           a product ID filter, as a string.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--remote yes|no""</computeroutput>Specifies
-           a remote filter - indicating whether the device is physically connected to a
-           remote VRDE client or to a local host machine. Applies to VM filters only.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--serialnumber &lt;string&gt;|""</computeroutput>Specifies
-           a serial number filter, as a string.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>--maskedinterfaces &lt;XXXXXXXX&gt;</computeroutput>Specifies
-           a masked interface filter, for hiding one or more USB interfaces from the guest.
-           The value is a bit mask where the set bits correspond to the USB interfaces that
-           should be hidden, or masked off. This feature only works on Linux hosts.</para>
-        </listitem>
-    </itemizedlist></para>
+    <para>
+      The <computeroutput>usbfilter</computeroutput> commands are used
+      for working with USB filters in virtual machines, or global
+      filters which affect the whole VirtualBox setup. Global filters
+      are applied before machine-specific filters, and may be used to
+      prevent devices from being captured by any virtual machine. Global
+      filters are always applied in a particular order, and only the
+      first filter which fits a device is applied. So for example, if
+      the first global filter says to hold (make available) a particular
+      Kingston memory stick device and the second to ignore all Kingston
+      devices, that memory stick will be available to any machine with
+      an appropriate filter, but no other Kingston device will.
+    </para>
+
+    <para>
+      When creating a USB filter using <computeroutput>usbfilter
+      add</computeroutput>, you must supply three or four mandatory
+      parameters. The index specifies the position in the list at which
+      the filter should be placed. If there is already a filter at that
+      position, then it and the following ones will be shifted back one
+      place. Otherwise the new filter will be added onto the end of the
+      list. The <computeroutput>target</computeroutput> parameter
+      selects the virtual machine that the filter should be attached to
+      or use "global" to apply it to all virtual machines.
+      <computeroutput>name</computeroutput> is a name for the new filter
+      and for global filters, <computeroutput>action</computeroutput>
+      says whether to allow VMs access to devices that fit the filter
+      description ("hold") or not to give them access ("ignore"). In
+      addition, you should specify parameters to filter by. You can find
+      the parameters for devices attached to your system using
+      <computeroutput>VBoxManage list usbhost</computeroutput>. Finally,
+      you can specify whether the filter should be active, and for local
+      filters, whether they are for local devices, remote (over an RDP
+      connection) or either.
+    </para>
+
+    <para>
+      When you modify a USB filter using <computeroutput>usbfilter
+      modify</computeroutput>, you must specify the filter by index and
+      by target, which is either a virtual machine or "global". See the
+      output of <computeroutput>VBoxManage list
+      usbfilters</computeroutput> to find global filter indexes and
+      <computeroutput>VBoxManage showvminfo</computeroutput> to find
+      indexes for individual machines. The properties which can be
+      changed are the same as for <computeroutput>usbfilter
+      add</computeroutput>. To remove a filter, use
+      <computeroutput>usbfilter remove</computeroutput> and specify the
+      index and the target.
+    </para>
+
+    <para>
+      The following is a list of the additional
+      <computeroutput>usbfilter add</computeroutput> and
+      <computeroutput>usbfilter modify</computeroutput> options, with
+      detailed explanations on how to use them.
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <computeroutput>--action ignore|hold</computeroutput>Specifies
+          whether devices that fit the filter description are allowed
+          access by machines ("hold"), or have access denied ("ignore").
+          Applies to global filters only.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--active yes|no</computeroutput>Specifies
+          whether the USB Filter is active or temporarily disabled. For
+          <computeroutput>usbfilter create</computeroutput> the default
+          is active.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--vendorid
+          &lt;XXXX&gt;|""</computeroutput>Specifies a vendor ID filter -
+          the string representation for the exact matching has the form
+          XXXX, where X is the hex digit (including leading zeroes).
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--productid
+          &lt;XXXX&gt;|""</computeroutput>Specifies a product ID filter
+          - The string representation for the exact matching has the
+          form XXXX, where X is the hex digit (including leading
+          zeroes).
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--revision
+          &lt;IIFF&gt;|""</computeroutput>Specifies a revision ID filter
+          - the string representation for the exact matching has the
+          form IIFF, where I is the decimal digit of the integer part of
+          the revision, and F is the decimal digit of its fractional
+          part (including leading and trailing zeros). Note that for
+          interval filters, it's best to use the hex form, because the
+          revision is stored as a 16 bit packed BCD value; so the
+          expression int:0x0100-0x0199 will match any revision from 1.0
+          to 1.99 inclusive.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--manufacturer
+          &lt;string&gt;|""</computeroutput>Specifies a manufacturer ID
+          filter, as a string.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--product
+          &lt;string&gt;|""</computeroutput>Specifies a product ID
+          filter, as a string.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--remote yes|no""</computeroutput>Specifies a
+          remote filter - indicating whether the device is physically
+          connected to a remote VRDE client or to a local host machine.
+          Applies to VM filters only.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--serialnumber
+          &lt;string&gt;|""</computeroutput>Specifies a serial number
+          filter, as a string.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--maskedinterfaces
+          &lt;XXXXXXXX&gt;</computeroutput>Specifies a masked interface
+          filter, for hiding one or more USB interfaces from the guest.
+          The value is a bit mask where the set bits correspond to the
+          USB interfaces that should be hidden, or masked off. This
+          feature only works on Linux hosts.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
   <sect1 id="vboxmanage-sharedfolder">
+
     <title>VBoxManage sharedfolder add/remove</title>
 
@@ -4161,55 +6106,77 @@
 </screen>
 
-    <para>This command allows you to share folders on the host computer with
-    guest operating systems. For this, the guest systems must have a version
-    of the VirtualBox Guest Additions installed which supports this
-    functionality.</para>
-
-    <para>Parameters are:</para>
-
-    <para><itemizedlist>
-       <listitem>
-         <para><computeroutput>&lt;uuid|vmname&gt;</computeroutput>
-         Specifies the UUID or name of the VM whose guest operating system will be
-         sharing folders with the host computer. Mandatory.</para>
-       </listitem>
-
-       <listitem>
-         <para><computeroutput>--name &lt;name&gt;</computeroutput>
-         Specifies the name of the share. Each share has a unique name within the
-         namespace of the host operating system. Mandatory.</para>
-       </listitem>
-
-       <listitem>
-         <para><computeroutput>-hostpath &lt;hostpath&gt;</computeroutput>
-         Specifies the absolute path on the host operating system of the
-         folder/directory to be shared with the guest operating system.
-         Mandatory.</para>
-       </listitem>
-
-       <listitem>
-         <para><computeroutput>-transient</computeroutput>
-         Specifies that the share is 'transient', meaning that it can be added
-         and removed at runtime and does not persist after the VM has stopped.
-         Optional.</para>
-       </listitem>
-
-       <listitem>
-         <para><computeroutput>-readonly</computeroutput>
-         Specifies that the share has only read-only access to files at the host path.</para>
-
-         <para>By default, shared folders have read/write access to the files at the host
-         path. More specifically, on Linux distros - shared folders are mounted with
-         770 io permissions with root user and vboxsf as the group, and using this option
-         the io permissions change to 700. Optional.</para>
-       </listitem>
-
-       <listitem>
-         <para><computeroutput>-automount</computeroutput>
-         Specifies that the share will be automatically mounted. On Linux distros, this will
-         be to either /media/USER/sf_&lt;name&gt; or /media/sf_&lt;name&gt; - depending on
-         your guest OS. Where &lt;name&gt; is the share name. Optional.</para>
-       </listitem>
-    </itemizedlist></para>
+    <para>
+      This command allows you to share folders on the host computer with
+      guest operating systems. For this, the guest systems must have a
+      version of the VirtualBox Guest Additions installed which supports
+      this functionality.
+    </para>
+
+    <para>
+      Parameters are as follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <computeroutput>&lt;uuid|vmname&gt;</computeroutput> Specifies
+          the UUID or name of the VM whose guest operating system will
+          be sharing folders with the host computer. Mandatory.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--name &lt;name&gt;</computeroutput> Specifies
+          the name of the share. Each share has a unique name within the
+          namespace of the host operating system. Mandatory.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>-hostpath &lt;hostpath&gt;</computeroutput>
+          Specifies the absolute path on the host operating system of
+          the folder/directory to be shared with the guest operating
+          system. Mandatory.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>-transient</computeroutput> Specifies that the
+          share is 'transient', meaning that it can be added and removed
+          at runtime and does not persist after the VM has stopped.
+          Optional.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>-readonly</computeroutput> Specifies that the
+          share has only read-only access to files at the host path.
+        </para>
+
+        <para>
+          By default, shared folders have read/write access to the files
+          at the host path. More specifically, on Linux distros - shared
+          folders are mounted with 770 io permissions with root user and
+          vboxsf as the group, and using this option the io permissions
+          change to 700. Optional.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>-automount</computeroutput> Specifies that the
+          share will be automatically mounted. On Linux distros, this
+          will be to either /media/USER/sf_&lt;name&gt; or
+          /media/sf_&lt;name&gt; - depending on your guest OS. Where
+          &lt;name&gt; is the share name. Optional.
+        </para>
+      </listitem>
+
+    </itemizedlist>
 
 <screen>
@@ -4219,159 +6186,233 @@
 </screen>
 
-    <para>This command allows you to delete shared folders on the host computer shares with
-    the guest operating systems. For this, the guest systems must have a version
-    of the VirtualBox Guest Additions installed which supports this
-    functionality.</para>
-
-    <para>Parameters are:</para>
-
-    <para><itemizedlist>
-       <listitem>
-         <para><computeroutput>&lt;uuid|vmname&gt;</computeroutput>
-         Specifies the UUID or name of the VM whose guest operating system is
-         sharing folders with the host computer. Mandatory.</para>
-       </listitem>
-
-       <listitem>
-         <para><computeroutput>--name &lt;name&gt;</computeroutput>
-         Specifies the name of the share to be removed. Each share has a unique name within the
-         namespace of the host operating system. Mandatory.</para>
-       </listitem>
-
-       <listitem>
-         <para><computeroutput>-transient</computeroutput>
-         Specifies that the share is 'transient', meaning that it can be added
-         and removed at runtime and does not persist after the VM has stopped.
-         Optional.</para>
-       </listitem>
-    </itemizedlist></para>
-
-
-    <para>Shared folders are described in detail in <xref linkend="sharedfolders" />.</para>
+    <para>
+      This command allows you to delete shared folders on the host
+      computer shares with the guest operating systems. For this, the
+      guest systems must have a version of the VirtualBox Guest
+      Additions installed which supports this functionality.
+    </para>
+
+    <para>
+      Parameters are as follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <computeroutput>&lt;uuid|vmname&gt;</computeroutput> Specifies
+          the UUID or name of the VM whose guest operating system is
+          sharing folders with the host computer. Mandatory.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>--name &lt;name&gt;</computeroutput> Specifies
+          the name of the share to be removed. Each share has a unique
+          name within the namespace of the host operating system.
+          Mandatory.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>-transient</computeroutput> Specifies that the
+          share is 'transient', meaning that it can be added and removed
+          at runtime and does not persist after the VM has stopped.
+          Optional.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Shared folders are described in <xref linkend="sharedfolders" />.
+    </para>
+
   </sect1>
 
   <sect1 id="vboxmanage-guestproperty">
+
     <title>VBoxManage guestproperty</title>
 
-    <para>The "guestproperty" commands allow you to get or set properties of a
-    running virtual machine. Please see <xref linkend="guestadd-guestprops" />
-    for an introduction. As explained there, guest properties are arbitrary
-    key/value string pairs which can be written to and read from by either the
-    guest or the host, so they can be used as a low-volume communication
-    channel for strings, provided that a guest is running and has the Guest
-    Additions installed. In addition, a number of values whose keys begin with
-    "/VirtualBox/" are automatically set and maintained by the Guest
-    Additions.</para>
-
-    <para>The following subcommands are available (where
-    <computeroutput>&lt;vm&gt;</computeroutput>, in each case, can either be a
-    VM name or a VM UUID, as with the other VBoxManage commands):<itemizedlist>
-        <listitem>
-          <para><computeroutput>enumerate &lt;vm&gt; [--patterns
+    <para>
+      The "guestproperty" commands allow you to get or set properties of
+      a running virtual machine. See
+      <xref linkend="guestadd-guestprops" /> for an introduction. As
+      explained there, guest properties are arbitrary key/value string
+      pairs which can be written to and read from by either the guest or
+      the host, so they can be used as a low-volume communication
+      channel for strings, provided that a guest is running and has the
+      Guest Additions installed. In addition, a number of values whose
+      keys begin with "/VirtualBox/" are automatically set and
+      maintained by the Guest Additions.
+    </para>
+
+    <para>
+      The following subcommands are available, where
+      <computeroutput>&lt;vm&gt;</computeroutput> can either be a VM
+      name or a VM UUID, as with the other VBoxManage commands:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <computeroutput>enumerate &lt;vm&gt; [--patterns
           &lt;pattern&gt;]</computeroutput>: This lists all the guest
-          properties that are available for the given VM, including the value.
-          This list will be very limited if the guest's service process cannot
-          be contacted, e.g. because the VM is not running or the Guest
-          Additions are not installed.</para>
-
-          <para>If <computeroutput>--patterns &lt;pattern&gt;</computeroutput>
-          is specified, it acts as a filter to only list properties that match
-          the given pattern. The pattern can contain the following wildcard
-          characters:<itemizedlist>
-              <listitem>
-                <para><computeroutput>*</computeroutput> (asterisk):
-                represents any number of characters; for example,
-                "<computeroutput>/VirtualBox*</computeroutput>" would match
-                all properties beginning with "/VirtualBox".</para>
-              </listitem>
-
-              <listitem>
-                <para><computeroutput>?</computeroutput> (question mark):
-                represents a single arbitrary character; for example,
-                "<computeroutput>fo?</computeroutput>" would match both "foo"
-                and "for".</para>
-              </listitem>
-
-              <listitem>
-                <para><computeroutput>|</computeroutput> (pipe symbol): can be
-                used to specify multiple alternative patterns; for example,
-                "<computeroutput>s*|t*</computeroutput>" would match anything
-                starting with either "s" or "t".</para>
-              </listitem>
-            </itemizedlist></para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>get &lt;vm&gt; &lt;property&gt;
-          </computeroutput>: This
-          retrieves the value of a single property only. If the property
-          cannot be found (e.g. because the guest is not running), this will
-          print <screen>No value set!</screen></para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>set &lt;vm&gt; &lt;property&gt; [&lt;value&gt;
-          [--flags &lt;flags&gt;]]</computeroutput>: This allows you to set a
-          guest property by specifying the key and value. If
+          properties that are available for the given VM, including the
+          value. This list will be very limited if the guest's service
+          process cannot be contacted, e.g. because the VM is not
+          running or the Guest Additions are not installed.
+        </para>
+
+        <para>
+          If <computeroutput>--patterns &lt;pattern&gt;</computeroutput>
+          is specified, it acts as a filter to only list properties that
+          match the given pattern. The pattern can contain the following
+          wildcard characters:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <computeroutput>*</computeroutput> (asterisk): represents
+              any number of characters; for example,
+              "<computeroutput>/VirtualBox*</computeroutput>" would
+              match all properties beginning with "/VirtualBox".
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>?</computeroutput> (question mark):
+              represents a single arbitrary character; for example,
+              "<computeroutput>fo?</computeroutput>" would match both
+              "foo" and "for".
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>|</computeroutput> (pipe symbol): can be
+              used to specify multiple alternative patterns; for
+              example, "<computeroutput>s*|t*</computeroutput>" would
+              match anything starting with either "s" or "t".
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>get &lt;vm&gt; &lt;property&gt;
+          </computeroutput>: This retrieves the value of a single
+          property only. If the property cannot be found (e.g. because
+          the guest is not running), this will print
+
+<screen>No value set!</screen>
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>set &lt;vm&gt; &lt;property&gt; [&lt;value&gt;
+          [--flags &lt;flags&gt;]]</computeroutput>: This allows you to
+          set a guest property by specifying the key and value. If
           <computeroutput>&lt;value&gt;</computeroutput> is omitted, the
-          property is deleted. With <computeroutput>--flags</computeroutput>
-          you can optionally specify additional behavior (you can combine
-          several by separating them with commas):<itemizedlist>
-              <listitem>
-                <para><computeroutput>TRANSIENT</computeroutput>: the value
-                will not be stored with the VM data when the VM exits;</para>
-              </listitem>
-
-              <listitem>
-                <para><computeroutput>TRANSRESET</computeroutput>: the value
-                will be deleted as soon as the VM restarts and/or exits;</para>
-              </listitem>
-
-              <listitem>
-                <para><computeroutput>RDONLYGUEST</computeroutput>: the value
-                can only be changed by the host, but the guest can only read
-                it;</para>
-              </listitem>
-
-              <listitem>
-                <para><computeroutput>RDONLYHOST</computeroutput>: reversely,
-                the value can only be changed by the guest, but the host can
-                only read it;</para>
-              </listitem>
-
-              <listitem>
-                <para><computeroutput>READONLY</computeroutput>: a combination
-                of the two, the value cannot be changed at all.</para>
-              </listitem>
-            </itemizedlist></para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>wait &lt;vm&gt; &lt;pattern&gt; --timeout
-          &lt;timeout&gt;</computeroutput>: This waits for a particular value
-          described by "pattern" to change or to be deleted or created. The
-          pattern rules are the same as for the "enumerate" subcommand
-          above.</para>
-        </listitem>
-
-        <listitem>
-          <para><computeroutput>delete &lt;vm&gt; &lt;property&gt;
-          </computeroutput>: Deletes a formerly set guest property.
-          </para></listitem>
-      </itemizedlist></para>
+          property is deleted. With
+          <computeroutput>--flags</computeroutput>, you can specify
+          additional behavior. You can combine several flags by
+          separating them with commas.
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <computeroutput>TRANSIENT</computeroutput>: The value will
+              not be stored with the VM data when the VM exits.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>TRANSRESET</computeroutput>: The value
+              will be deleted as soon as the VM restarts and/or exits.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>RDONLYGUEST</computeroutput>: The value
+              can only be changed by the host, but the guest can only
+              read it.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>RDONLYHOST</computeroutput>: The value can
+              only be changed by the guest, but the host can only read
+              it.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <computeroutput>READONLY</computeroutput>: The value
+              cannot be changed at all.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>wait &lt;vm&gt; &lt;pattern&gt; --timeout
+          &lt;timeout&gt;</computeroutput>: This waits for a particular
+          value described by "pattern" to change or to be deleted or
+          created. The pattern rules are the same as for the "enumerate"
+          subcommand above.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <computeroutput>delete &lt;vm&gt;
+          &lt;property&gt;</computeroutput>: Deletes a formerly set
+          guest property.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
   <sect1 id="vboxmanage-guestcontrol">
+
     <title>VBoxManage guestcontrol</title>
 
-    <para>The <computeroutput>guestcontrol</computeroutput> commands enable
-    control of the guest from the host. Please see <xref
-    linkend="guestadd-guestcontrol" /> for an introduction.</para>
-
-    <para>guestcontrol has two sets of subcommands. The first set requires guest
-      credentials to be specified, the second does not.</para>
-
-    <para>The first set of subcommands is of the form:</para>
-    <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; &lt;sub-command&gt;
+    <para>
+      The <computeroutput>guestcontrol</computeroutput> commands enable
+      control of the guest from the host. See
+      <xref
+    linkend="guestadd-guestcontrol" /> for an introduction.
+    </para>
+
+    <para>
+      guestcontrol has two sets of subcommands. The first set requires
+      guest credentials to be specified, the second does not.
+    </para>
+
+    <para>
+      The first set of subcommands is of the form:
+    </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; &lt;sub-command&gt;
             [--username &lt;name&gt; ]
             [--passwordfile &lt;file&gt; | --password &lt;password&gt;]
@@ -4380,6 +6421,9 @@
     </screen>
 
-    <para>The "common-options" are:</para>
-    <screen>
+    <para>
+      The "common-options" are:
+    </para>
+
+<screen>
            [--username &lt;name&gt; ]
            [--passwordfile &lt;file&gt; | --password &lt;password&gt;]
@@ -4388,51 +6432,105 @@
     </screen>
 
-    <para>Where details of the common options for the first set of subcommands are:
-      <glosslist>
-
-        <glossentry>
-          <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-            <glossdef>
-              <para>Specifies the VM UUID or VM name. Mandatory.</para>
-            </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--username &lt;name&gt;</computeroutput></glossterm>
-          <glossdef><para>Specifies the user name on guest OS under which the process should run. This
-            user name must already exist on the guest OS. If unspecified, the host user name is used. Optional</para>
-          </glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--passwordfile &lt;file&gt;|--password</computeroutput></glossterm>
-          <glossdef><para>Specifies the absolute path on guest file system of password file containing the
-            password for the specified user account or password for the specified user account. Optional.
-            If both are omitted, empty password is assumed.</para></glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>--domain &lt;domain&gt;</computeroutput></glossterm>
-          <glossdef><para>User domain for Windows guests. Optional.</para></glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>-v|--verbose</computeroutput></glossterm>
-          <glossdef><para>Makes the subcommand execution more verbose. Optional</para></glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>-q|--quiet</computeroutput></glossterm>
-          <glossdef><para>Makes the subcommand execution quieter. Optional.</para></glossdef>
-        </glossentry>
-      </glosslist>
-    </para>
-
-    <para>The first set of subcommands: <itemizedlist>
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>run</computeroutput></emphasis>
-          Executes a guest program - forwarding stdout, stderr and stdin to/from the host
-          until it completes.</para>
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; run [common-options]
+    <para>
+      Where details of the common options for the first set of
+      subcommands are:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies the VM UUID or VM name. Mandatory.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--username &lt;name&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies the user name on guest OS under which the process
+            should run. This user name must already exist on the guest
+            OS. If unspecified, the host user name is used. Optional
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--passwordfile
+          &lt;file&gt;|--password</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Specifies the absolute path on guest file system of password
+            file containing the password for the specified user account
+            or password for the specified user account. Optional. If
+            both are omitted, empty password is assumed.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--domain &lt;domain&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            User domain for Windows guests. Optional.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>-v|--verbose</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Makes the subcommand execution more verbose. Optional
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>-q|--quiet</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Makes the subcommand execution quieter. Optional.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+      The first set of subcommands:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>run</computeroutput></emphasis>
+          Executes a guest program - forwarding stdout, stderr and stdin
+          to/from the host until it completes.
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; run [common-options]
             --exe &lt;path to executable&gt; [--timeout &lt;msec&gt;]
            [-E|--putenv &lt;NAME&gt;[=&lt;VALUE&gt;]] [--unquoted-args]
@@ -4443,145 +6541,270 @@
             -- &lt;program/arg0&gt; [argument1] ... [argumentN]]
           </screen>
-            <glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--exe &lt;path to executable&gt;</computeroutput></glossterm>
-                <glossdef><para>Specifies the absolute path of the executable on the guest OS file system. Mandatory. e.g.:
-                  <computeroutput>C:\Windows\System32\calc.exe</computeroutput>.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--timeout &lt;msec&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the maximum time (microseconds) that the executable can run,
-                  during which VBoxManage receives its output. Optional.
-                  If unspecified, VBoxManage waits indefinitely for the process to end, or an error occurs.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>-E|--putenv &lt;NAME&gt;=&lt;VALUE&gt;
-                </computeroutput></glossterm>
-                <glossdef>
-                  <para>Sets/modifies/unsets environment variable(s) in the environment in which the program will run. Optional.</para>
-                  <para>The guest process is created with the standard default guest OS environment.
-                  Use this option to modify that default environment. To set/modify a variable use:
-                  <computeroutput>&lt;NAME&gt;=&lt;VALUE&gt;</computeroutput>.
-                  To unset a variable use:
-                  <computeroutput>&lt;NAME&gt;=</computeroutput></para>
-                  <para>Any spaces in names/values should be enclosed by quotes. </para>
-                  <para>To set/modify/unset multiple variables, use multiple instances of the
-                  <computeroutput>--E|--putenv</computeroutput> option. </para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--unquoted-args</computeroutput></glossterm>
-                <glossdef>
-                  <para>Disables escaped double quoting (e.g. \"fred\") on arguments passed to the executed program. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--ignore-operhaned-processes</computeroutput></glossterm>
-                <glossdef>
-                  <para>Ignore orphaned processes. Not yet implemented. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--profile</computeroutput></glossterm>
-                <glossdef>
-                  <para>Use Profile. Not yet implemented. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--no-wait-stdout|--wait-stdout</computeroutput></glossterm>
-                <glossdef>
-                  <para>Does not wait/waits until the guest process ends and receives its exit code and reason/flags.
-                  In the case of --wait-stdout -  while the process runs, VBoxManage receives its stdout. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--no-wait-stderr|--wait-stderr</computeroutput></glossterm>
-                <glossdef>
-                  <para>Does not wait/waits until the guest process ends and receives its exit code and reason/flags.
-                  In case of --wait-stderr - while the process runs, VBoxManage receives its stderr. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--dos2unix</computeroutput></glossterm>
-                <glossdef><para>
-                  Converts output from DOS/Windows guests to UNIX/Linux-compatible line endings
-                  (CR + LF &rarr; LF). Not yet implemented. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--unix2dos</computeroutput></glossterm>
-                <glossdef><para>
-                  Converts output from a UNIX/Linux guests to DOS/Windows-compatible
-                  line endings (LF &rarr; CR + LF). Not yet implemented. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>[-- &lt;program/arg0&gt; [&lt;argument1&gt;] ... [&lt;argumentN&gt;]]</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies program name, followed by one or more arguments to pass to the program. Optional.</para>
-                  <para>Note: Any spaces in arguments should be enclosed by quotes.</para>
-                </glossdef>
-              </glossentry>
-            </glosslist>
-
-          <para><note>
-              <para>On Windows there are certain limitations for graphical
-              applications; please see <xref linkend="KnownIssues" /> for more
-              information.</para>
-            </note> Examples: <screen>VBoxManage --nologo guestcontrol "My VM" run --exe "/bin/ls"
-          --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen> <screen>VBoxManage --nologo guestcontrol "My VM" run --exe "c:\\windows\\system32\\ipconfig.exe"
-          --username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen> Note that
-          the double backslashes in the second example are only required on
-          Unix hosts.</para>
-
-          <para><note>
-            <para>For certain commands a user name of an existing user account on the guest
-            must be specified; anonymous executions are not supported for security reasons. A
-            user account password, however, is optional and depends on the guest's OS security
-            policy or rules. If no password is specified for a given user name, an empty password
-            will be used. On certain OSes like Windows the security policy may needs to be adjusted
-            in order to allow user accounts with an empty password set. Also, global domain rules might
-            apply and therefore cannot be changed.</para>
-          </note></para>
-
-          <para>Starting at VirtualBox 4.1.2 guest process execution by default is limited
-          to serve up to 5 guest processes at a time. If a new guest process gets started
-          which would exceed this limit, the oldest not running guest process will be discarded
-          in order to be able to run that new process. Also, retrieving output from this
-          old guest process will not be possible anymore then. If all 5 guest processes
-          are still active and running, starting a new guest process will result in an
-          appropriate error message.</para>
-
-          <para>To raise or lower the guest process execution limit, either the guest
-          property <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
-          or VBoxService' command line by specifying <computeroutput>--control-procs-max-kept</computeroutput>
-          needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited
-          guest processes, a value of <computeroutput>0</computeroutput> needs to be set (not recommended).</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>start</computeroutput></emphasis>
-          Executes a guest program until it completes.</para>
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; start [common-options]
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--exe &lt;path to
+              executable&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the absolute path of the executable on the
+                guest OS file system. Mandatory. e.g.:
+                <computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--timeout &lt;msec&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the maximum time (microseconds) that the
+                executable can run, during which VBoxManage receives its
+                output. Optional. If unspecified, VBoxManage waits
+                indefinitely for the process to end, or an error occurs.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>-E|--putenv &lt;NAME&gt;=&lt;VALUE&gt;
+              </computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Sets/modifies/unsets environment variable(s) in the
+                environment in which the program will run. Optional.
+              </para>
+
+              <para>
+                The guest process is created with the standard default
+                guest OS environment. Use this option to modify that
+                default environment. To set/modify a variable use:
+                <computeroutput>&lt;NAME&gt;=&lt;VALUE&gt;</computeroutput>.
+                To unset a variable use:
+                <computeroutput>&lt;NAME&gt;=</computeroutput>
+              </para>
+
+              <para>
+                Any spaces in names/values should be enclosed by quotes.
+              </para>
+
+              <para>
+                To set/modify/unset multiple variables, use multiple
+                instances of the
+                <computeroutput>--E|--putenv</computeroutput> option.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--unquoted-args</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Disables escaped double quoting (e.g. \"fred\") on
+                arguments passed to the executed program. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--ignore-operhaned-processes</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Ignore orphaned processes. Not yet implemented.
+                Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--profile</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Use Profile. Not yet implemented. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--no-wait-stdout|--wait-stdout</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Does not wait/waits until the guest process ends and
+                receives its exit code and reason/flags. In the case of
+                --wait-stdout - while the process runs, VBoxManage
+                receives its stdout. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--no-wait-stderr|--wait-stderr</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Does not wait/waits until the guest process ends and
+                receives its exit code and reason/flags. In case of
+                --wait-stderr - while the process runs, VBoxManage
+                receives its stderr. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--dos2unix</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Converts output from DOS/Windows guests to
+                UNIX/Linux-compatible line endings, CR + LF to LF. Not
+                yet implemented. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--unix2dos</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Converts output from a UNIX/Linux guests to
+                DOS/Windows-compatible line endings, LF to CR + LF. Not
+                yet implemented. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>[-- &lt;program/arg0&gt;
+              [&lt;argument1&gt;] ...
+              [&lt;argumentN&gt;]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies program name, followed by one or more
+                arguments to pass to the program. Optional.
+              </para>
+
+              <para>
+                Note: Any spaces in arguments should be enclosed by
+                quotes.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+
+        <para>
+          <note>
+            <para>
+              On Windows there are certain limitations for graphical
+              applications; please see <xref linkend="KnownIssues" />
+              for more information.
+            </para>
+          </note>
+
+          Examples:
+
+<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "/bin/ls"
+          --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen>
+
+<screen>VBoxManage --nologo guestcontrol "My VM" run --exe "c:\\windows\\system32\\ipconfig.exe"
+          --username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen>
+
+          Note that the double backslashes in the second example are
+          only required on Unix hosts.
+        </para>
+
+        <para>
+          <note>
+            <para>
+              For certain commands a user name of an existing user
+              account on the guest must be specified; anonymous
+              executions are not supported for security reasons. A user
+              account password, however, is optional and depends on the
+              guest's OS security policy or rules. If no password is
+              specified for a given user name, an empty password will be
+              used. On certain OSes like Windows the security policy may
+              needs to be adjusted in order to allow user accounts with
+              an empty password set. Also, global domain rules might
+              apply and therefore cannot be changed.
+            </para>
+          </note>
+        </para>
+
+        <para>
+          Starting at VirtualBox 4.1.2 guest process execution by
+          default is limited to serve up to 5 guest processes at a time.
+          If a new guest process gets started which would exceed this
+          limit, the oldest not running guest process will be discarded
+          in order to be able to run that new process. Also, retrieving
+          output from this old guest process will not be possible
+          anymore then. If all 5 guest processes are still active and
+          running, starting a new guest process will result in an
+          appropriate error message.
+        </para>
+
+        <para>
+          To raise or lower the guest process execution limit, either
+          the guest property
+          <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
+          or VBoxService' command line by specifying
+          <computeroutput>--control-procs-max-kept</computeroutput>
+          needs to be modified. A restart of the guest OS is required
+          afterwards. To serve unlimited guest processes, a value of
+          <computeroutput>0</computeroutput> needs to be set (not
+          recommended).
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>start</computeroutput></emphasis>
+          Executes a guest program until it completes.
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; start [common-options]
            [--exe &lt;path to executable&gt;] [--timeout &lt;msec&gt;]
            [-E|--putenv &lt;NAME&gt;[=&lt;VALUE&gt;]] [--unquoted-args]
@@ -4590,859 +6813,1461 @@
           </screen>
 
-          <para>Where the options are: <glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--exe &lt;path to executable&gt;</computeroutput></glossterm>
-                <glossdef><para>Specifies the absolute path of the executable on the guest OS file system. Mandatory. e.g.:
-                  <computeroutput>C:\Windows\System32\calc.exe</computeroutput></para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--timeout &lt;msec&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the maximum time (microseconds) that the executable can run. Optional.
-                  If unspecified, VBoxManage waits indefinitely for the process to end, or an error occurs.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>-E|--putenv &lt;NAME&gt;=&lt;VALUE&gt;
-                </computeroutput></glossterm>
-                <glossdef>
-                  <para>Sets/modifies/unsets environment variable(s) in the environment in which the program will run. Optional.</para>
-                  <para>The guest process is created with the standard default guest OS environment.
-                  Use this option to modify that default environment. To set/modify a variable use:
-                  <computeroutput>&lt;NAME&gt;=&lt;VALUE&gt;</computeroutput>.
-                  To unset a variable use:
-                  <computeroutput>&lt;NAME&gt;=</computeroutput></para>
-                  <para>Any spaces in names/values should be enclosed by quotes. </para>
-                  <para>To set/modify/unset multiple variables, use multiple instances of the
-                  <computeroutput>--E|--putenv</computeroutput> option. </para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--unquoted-args</computeroutput></glossterm>
-                <glossdef>
-                  <para>Disables escaped double quoting (e.g. \"fred\") on arguments passed to the executed program. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--ignore-operhaned-processes</computeroutput></glossterm>
-                <glossdef>
-                  <para>Ignores orphaned processes. Not yet implemented. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--profile</computeroutput></glossterm>
-                <glossdef>
-                  <para>Use a profile. Not yet implemented. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>[-- &lt;program/arg0&gt; [&lt;argument1&gt;] ... [&lt;argumentN&gt;]]</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies program name, followed by one or more arguments to pass to the program. Optional.</para>
-                  <para>Note: Any spaces in arguments should be enclosed by quotes.</para>
-                </glossdef>
-              </glossentry>
-            </glosslist></para>
-
-          <para><note>
-              <para>On Windows there are certain limitations for graphical
-              applications; please see <xref linkend="KnownIssues" /> for more
-              information.</para>
-            </note> Examples: <screen>VBoxManage --nologo guestcontrol "My VM" start --exe "/bin/ls"
-          --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen> <screen>VBoxManage --nologo guestcontrol "My VM" start --exe "c:\\windows\\system32\\ipconfig.exe"
-          --username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen> Note that
-          the double backslashes in the second example are only required on
-          Unix hosts.</para>
-
-          <para><note>
-            <para>For certain commands a user name of an existing user account on the guest
-            must be specified; anonymous executions are not supported for security reasons. A
-            user account password, however, is optional and depends on the guest's OS security
-            policy or rules. If no password is specified for a given user name, an empty password
-            will be used. On certain OSes like Windows the security policy may needs to be adjusted
-            in order to allow user accounts with an empty password set. Also, global domain rules might
-            apply and therefore cannot be changed.</para>
-          </note></para>
-
-          <para>Starting at VirtualBox 4.1.2 guest process execution by default is limited
-          to serve up to 5 guest processes at a time. If a new guest process gets started
-          which would exceed this limit, the oldest not running guest process will be discarded
-          in order to be able to run that new process. Also, retrieving output from this
-          old guest process will not be possible anymore then. If all 5 guest processes
-          are still active and running, starting a new guest process will result in an
-          appropriate error message.</para>
-
-          <para>To raise or lower the guest process execution limit, either the guest
-          property <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
-          or VBoxService' command line by specifying <computeroutput>--control-procs-max-kept</computeroutput>
-          needs to be modified. A restart of the guest OS is required afterwards. To serve unlimited
-          guest processes, a value of <computeroutput>0</computeroutput> needs to be set (not recommended).</para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>copyfrom</computeroutput></emphasis>
-          Copies files from the guest to the host file system.
-          (Note - only with Guest Additions 4.0 or later installed).</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; copyfrom [common-options]
+        <para>
+          Where the options are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--exe &lt;path to
+              executable&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the absolute path of the executable on the
+                guest OS file system. Mandatory. e.g.:
+                <computeroutput>C:\Windows\System32\calc.exe</computeroutput>
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--timeout &lt;msec&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the maximum time (microseconds) that the
+                executable can run. Optional. If unspecified, VBoxManage
+                waits indefinitely for the process to end, or an error
+                occurs.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>-E|--putenv &lt;NAME&gt;=&lt;VALUE&gt;
+              </computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Sets/modifies/unsets environment variable(s) in the
+                environment in which the program will run. Optional.
+              </para>
+
+              <para>
+                The guest process is created with the standard default
+                guest OS environment. Use this option to modify that
+                default environment. To set/modify a variable use:
+                <computeroutput>&lt;NAME&gt;=&lt;VALUE&gt;</computeroutput>.
+                To unset a variable use:
+                <computeroutput>&lt;NAME&gt;=</computeroutput>
+              </para>
+
+              <para>
+                Any spaces in names/values should be enclosed by quotes.
+              </para>
+
+              <para>
+                To set/modify/unset multiple variables, use multiple
+                instances of the
+                <computeroutput>--E|--putenv</computeroutput> option.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--unquoted-args</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Disables escaped double quoting (e.g. \"fred\") on
+                arguments passed to the executed program. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--ignore-operhaned-processes</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Ignores orphaned processes. Not yet implemented.
+                Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--profile</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Use a profile. Not yet implemented. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>[-- &lt;program/arg0&gt;
+              [&lt;argument1&gt;] ...
+              [&lt;argumentN&gt;]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies program name, followed by one or more
+                arguments to pass to the program. Optional.
+              </para>
+
+              <para>
+                Note: Any spaces in arguments should be enclosed by
+                quotes.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+
+        <note>
+          <para>
+            On Windows there are certain limitations for graphical
+            applications; please see <xref linkend="KnownIssues" /> for
+            more information.
+          </para>
+        </note>
+
+        <para>
+          Examples:
+
+<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "/bin/ls"
+          --username foo --passwordfile bar.txt --wait-exit --wait-stdout -- -l /usr</screen>
+
+<screen>VBoxManage --nologo guestcontrol "My VM" start --exe "c:\\windows\\system32\\ipconfig.exe"
+          --username foo --passwordfile bar.txt --wait-exit --wait-stdout</screen>
+
+          Note that the double backslashes in the second example are
+          only required on Unix hosts.
+        </para>
+
+        <note>
+          <para>
+            For certain commands a user name of an existing user account
+            on the guest must be specified; anonymous executions are not
+            supported for security reasons. A user account password,
+            however, is optional and depends on the guest's OS security
+            policy or rules. If no password is specified for a given
+            user name, an empty password will be used. On certain OSes
+            like Windows the security policy may needs to be adjusted in
+            order to allow user accounts with an empty password set.
+            Also, global domain rules might apply and therefore cannot
+            be changed.
+          </para>
+        </note>
+
+        <para>
+          Starting at VirtualBox 4.1.2 guest process execution by
+          default is limited to serve up to 5 guest processes at a time.
+          If a new guest process gets started which would exceed this
+          limit, the oldest not running guest process will be discarded
+          in order to be able to run that new process. Also, retrieving
+          output from this old guest process will not be possible
+          anymore then. If all 5 guest processes are still active and
+          running, starting a new guest process will result in an
+          appropriate error message.
+        </para>
+
+        <para>
+          To raise or lower the guest process execution limit, either
+          the guest property
+          <computeroutput>/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept</computeroutput>
+          or VBoxService' command line by specifying
+          <computeroutput>--control-procs-max-kept</computeroutput>
+          needs to be modified. A restart of the guest OS is required
+          afterwards. To serve unlimited guest processes, a value of
+          <computeroutput>0</computeroutput> needs to be set (not
+          recommended).
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>copyfrom</computeroutput></emphasis>
+          Copies files from the guest to the host file system. (Note -
+          only with Guest Additions 4.0 or later installed).
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; copyfrom [common-options]
            [--follow] [--R|recursive]
             --target-directory &lt;host-dst-dir&gt;
             &lt;guest-src0&gt; [&lt;guest-src1&gt; [...]] </screen>
 
-          <para>Where the parameters are:<glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--follow</computeroutput></glossterm>
-                <glossdef>
-                  <para>Enables symlink following on the guest file system. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>-R|--recursive</computeroutput></glossterm>
-                <glossdef>
-                  <para>Enables recursive copying of files/directories from the specified guest file system
-                  directory. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--target-directory &lt;host-dst-dir&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the absolute path of the host file system destination directory. Mandatory. e.g.
-                  <computeroutput>C:\Temp</computeroutput>.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>&lt;guest-src0&gt; [&lt;guest-src1&gt; [...]]</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the absolute path(s) of guest file system file(s) to be copied. Mandatory. e.g.
-                  <computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
-                  Wildcards can be used in the expression(s), e.g.
-                  <computeroutput>C:\Windows\System*\*.dll</computeroutput>.</para>
-                </glossdef>
-              </glossentry>
-            </glosslist>
-          </para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>copyto</computeroutput></emphasis>
-          Copies files from the host to the guest file system.
-          (Note - only with Guest Additions 4.0 or later installed).</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; copyto [common-options]
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--follow</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Enables symlink following on the guest file system.
+                Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>-R|--recursive</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Enables recursive copying of files/directories from the
+                specified guest file system directory. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--target-directory
+              &lt;host-dst-dir&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the absolute path of the host file system
+                destination directory. Mandatory. e.g.
+                <computeroutput>C:\Temp</computeroutput>.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;guest-src0&gt; [&lt;guest-src1&gt;
+              [...]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the absolute path(s) of guest file system
+                file(s) to be copied. Mandatory. e.g.
+                <computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
+                Wildcards can be used in the expression(s), e.g.
+                <computeroutput>C:\Windows\System*\*.dll</computeroutput>.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>copyto</computeroutput></emphasis>
+          Copies files from the host to the guest file system. (Note -
+          only with Guest Additions 4.0 or later installed).
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; copyto [common-options]
            [--follow] [--R|recursive]
             --target-directory &lt;guest-dst&gt;
             &lt;host-src0&gt; [&lt;host-src1&gt; [...]] </screen>
 
-          <para>Where the parameters are:<glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--follow</computeroutput></glossterm>
-                <glossdef>
-                  <para>Enables symlink following on the host file system. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>-R|--recursive</computeroutput></glossterm>
-                <glossdef>
-                  <para>Enables recursive copying of files/directories from the specified host file system
-                  directory(ies). Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--target-directory &lt;guest-dst&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the absolute path of the guest file system destination directory. Mandatory. e.g.
-                  <computeroutput>C:\Temp</computeroutput>.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>&lt;host-src0&gt; [&lt;host-src1&gt; [...]]</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the absolute path(s) of host file system file(s) to be copied. Mandatory. e.g.
-                  <computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
-                  Wildcards can be used in the expression(s), e.g.
-                  <computeroutput>C:\Windows\System*\*.dll</computeroutput>.</para>
-                </glossdef>
-              </glossentry>
-            </glosslist>
-          </para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>md|mkdir|createdir|createdirectory</computeroutput></emphasis>
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--follow</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Enables symlink following on the host file system.
+                Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>-R|--recursive</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Enables recursive copying of files/directories from the
+                specified host file system directory(ies). Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--target-directory
+              &lt;guest-dst&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the absolute path of the guest file system
+                destination directory. Mandatory. e.g.
+                <computeroutput>C:\Temp</computeroutput>.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;host-src0&gt; [&lt;host-src1&gt;
+              [...]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the absolute path(s) of host file system
+                file(s) to be copied. Mandatory. e.g.
+                <computeroutput>C:\Windows\System32\calc.exe</computeroutput>.
+                Wildcards can be used in the expression(s), e.g.
+                <computeroutput>C:\Windows\System*\*.dll</computeroutput>.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>md|mkdir|createdir|createdirectory</computeroutput></emphasis>
           Creates one or more directory(ies) on the guest file system.
-          (Note - only with Guest Additions 4.0 or later installed).</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt;  md|mkdir|createdir|createdirectory [common-options]
+          (Note - only with Guest Additions 4.0 or later installed).
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt;  md|mkdir|createdir|createdirectory [common-options]
             [--parents] [--mode &lt;mode&gt;]
             &lt;guest-dir0&gt; [&lt;guest-dir1&gt; [...]] </screen>
 
-          <para>Where the parameters are: <glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-              <glossentry>
-                <glossterm><computeroutput>--parents</computeroutput></glossterm>
-                <glossdef>
-                  <para>Creates any absent parent directory(ies) of the specified directory. Optional.</para>
-                  <para>e.g. If specified directory is <computeroutput>D:\Foo\Bar</computeroutput>
-                  and <computeroutput>D:\Foo</computeroutput> is absent, it will
-                  be created. In such a case, had the <computeroutput>--parents</computeroutput>
-                  option not been used, this command would have failed.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--mode &lt;mode&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the permission mode on the specified directory(ies) (and any parents,
-                  where <computeroutput>--parents</computeroutput> option used).
-                  Currently octal modes (e.g. <computeroutput>0755</computeroutput>) only are
-                  supported.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>&lt;guest-dir0&gt; [&lt;guest-dir1&gt; [...]]</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies list of absolute path(s) of directory(ies) to be created on
-                  guest file system. Mandatory.
-                  e.g. <computeroutput>D:\Foo\Bar</computeroutput>.</para>
-                  <para>All parent directories must already exist
-                  unless switch <computeroutput>--parents</computeroutput> used.
-                  (e.g. in the above example <computeroutput>D:\Foo</computeroutput>).
-                  The specified user must have sufficient rights to create the
-                  specified directory(ies), and any parents that need
-                  to be created.</para>
-                </glossdef>
-              </glossentry>
-            </glosslist>
-          </para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>rmdir|removedir|removedirectory</computeroutput></emphasis>
-          Deletes specified guest file system directories. (Only with installed Guest Additions 4.3.2 and later).</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; rmdir|removedir|removedirectory [common-options]
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--parents</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Creates any absent parent directory(ies) of the
+                specified directory. Optional.
+              </para>
+
+              <para>
+                e.g. If specified directory is
+                <computeroutput>D:\Foo\Bar</computeroutput> and
+                <computeroutput>D:\Foo</computeroutput> is absent, it
+                will be created. In such a case, had the
+                <computeroutput>--parents</computeroutput> option not
+                been used, this command would have failed.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--mode &lt;mode&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the permission mode on the specified
+                directory(ies) (and any parents, where
+                <computeroutput>--parents</computeroutput> option used).
+                Currently octal modes (e.g.
+                <computeroutput>0755</computeroutput>) only are
+                supported.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;guest-dir0&gt; [&lt;guest-dir1&gt;
+              [...]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies list of absolute path(s) of directory(ies) to
+                be created on guest file system. Mandatory. e.g.
+                <computeroutput>D:\Foo\Bar</computeroutput>.
+              </para>
+
+              <para>
+                All parent directories must already exist unless switch
+                <computeroutput>--parents</computeroutput> used. (e.g.
+                in the above example
+                <computeroutput>D:\Foo</computeroutput>). The specified
+                user must have sufficient rights to create the specified
+                directory(ies), and any parents that need to be created.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>rmdir|removedir|removedirectory</computeroutput></emphasis>
+          Deletes specified guest file system directories. (Only with
+          installed Guest Additions 4.3.2 and later).
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; rmdir|removedir|removedirectory [common-options]
            [--recursive|-R]
             &lt;guest-dir0&gt; [&lt;guest-dir1&gt; [...]]
           </screen>
 
-          <para>Where the parameters are: <glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--recursive</computeroutput></glossterm>
-                <glossdef>
-                  <para>Recursively removes directories and contents. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>&lt;guest-dir0&gt; [&lt;guest-dir1&gt; [...]]</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies list of the absolute path(s) of directory(ies) to be deleted on
-                  guest file system. Mandatory. Wildcards are allowed. e.g. <computeroutput>D:\Foo\*Bar</computeroutput>.
-                  The specified user must have sufficient rights to delete the
-                  specified directory(ies).</para>
-                </glossdef>
-              </glossentry>
-            </glosslist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>rm|removefile</computeroutput></emphasis>
-          Deletes specified files on the guest file system. (Only with installed Guest
-          Additions 4.3.2 and later).</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; rm|removefile [common-options]
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--recursive</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Recursively removes directories and contents. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;guest-dir0&gt; [&lt;guest-dir1&gt;
+              [...]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies list of the absolute path(s) of directory(ies)
+                to be deleted on guest file system. Mandatory. Wildcards
+                are allowed. e.g.
+                <computeroutput>D:\Foo\*Bar</computeroutput>. The
+                specified user must have sufficient rights to delete the
+                specified directory(ies).
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>rm|removefile</computeroutput></emphasis>
+          Deletes specified files on the guest file system. (Only with
+          installed Guest Additions 4.3.2 and later).
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; rm|removefile [common-options]
            [-f|--force]
             &lt;guest-file0&gt; [&lt;guest-file1&gt; [...]] </screen>
 
-          <para>Where the parameters are: <glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>-f|--force</computeroutput></glossterm>
-                <glossdef>
-                  <para>Enforce operation (override any requests for confirmations). Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>&lt;guest-file0&gt; [&lt;guest-file1&gt; [...]]</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies list of absolute path(s) of file(s) to be deleted on guest file system. Mandatory.
-                   Wildcards are allowed. e.g. <computeroutput>D:\Foo\Bar\text*.txt</computeroutput>.
-                   The specified user should have sufficient rights to delete the specified file(s).</para>
-                </glossdef>
-              </glossentry>
-            </glosslist>
-          </para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>mv|move|ren|rename</computeroutput></emphasis>
-          This subcommand renames file(s) and/or directory(ies) on the guest file system. (Only with installed Guest
-          Additions 4.3.2 and later).</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; mv|move|ren|rename [common-options]
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>-f|--force</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Enforce operation (override any requests for
+                confirmations). Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;guest-file0&gt; [&lt;guest-file1&gt;
+              [...]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies list of absolute path(s) of file(s) to be
+                deleted on guest file system. Mandatory. Wildcards are
+                allowed. e.g.
+                <computeroutput>D:\Foo\Bar\text*.txt</computeroutput>.
+                The specified user should have sufficient rights to
+                delete the specified file(s).
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>mv|move|ren|rename</computeroutput></emphasis>
+          This subcommand renames file(s) and/or directory(ies) on the
+          guest file system. (Only with installed Guest Additions 4.3.2
+          and later).
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; mv|move|ren|rename [common-options]
            &lt;guest-source0&gt; [&lt;guest-source1&gt; [...]] &lt;guest-dest&gt;</screen>
 
-          <para>Where the parameters are: <glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>&lt;guest-source0&gt; [&lt;guest-source1&gt; [...]]</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies absolute path(s) of file(s) and/or single directory to be moved/renamed on guest
-                  file system. Mandatory.
-                  Wildcards are allowed in file names(s). The specified user should have sufficient rights to
-                  access the specified file(s).</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>&lt;dest&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the absolute path of the destination file/directory to which the file(s)
-                  are to be moved. Mandatory. If only one file to be moved, &lt;dest&gt; can be file or directory,
-                  else it must be a directory.
-                  The specified user must have sufficient rights to access the destination file/directory.</para>
-                </glossdef>
-              </glossentry>
-            </glosslist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>mktemp|createtemp|createtemporary</computeroutput></emphasis>
-          Creates a temporary file/directory on the guest file system, to assist subsequent
-          copying of files from the host to the guest file systems. By default, the file/directory
-          is created in the guest's platform specific temp directory. Not currently supported.
-          (Only with installed Guest Additions 4.2 and later).</para>
-
-            <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; mktemp|createtemp|createtemporary [common-options]
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;guest-source0&gt;
+              [&lt;guest-source1&gt; [...]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies absolute path(s) of file(s) and/or single
+                directory to be moved/renamed on guest file system.
+                Mandatory. Wildcards are allowed in file names(s). The
+                specified user should have sufficient rights to access
+                the specified file(s).
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;dest&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the absolute path of the destination
+                file/directory to which the file(s) are to be moved.
+                Mandatory. If only one file to be moved, &lt;dest&gt;
+                can be file or directory, else it must be a directory.
+                The specified user must have sufficient rights to access
+                the destination file/directory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>mktemp|createtemp|createtemporary</computeroutput></emphasis>
+          Creates a temporary file/directory on the guest file system,
+          to assist subsequent copying of files from the host to the
+          guest file systems. By default, the file/directory is created
+          in the guest's platform specific temp directory. Not currently
+          supported. (Only with installed Guest Additions 4.2 and
+          later).
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; mktemp|createtemp|createtemporary [common-options]
            [--directory] [--secure] [--mode &lt;mode&gt;] [--tmpdir &lt;directory&gt;]
             &lt;template&gt;
             </screen>
 
-          <para>The parameters are: <glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--directory</computeroutput></glossterm>
-                <glossdef>
-                  <para>Creates a temporary directory instead of a file, specified by the &lt;template&gt; parameter. Optional.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--secure</computeroutput></glossterm>
-                <glossdef>
-                  <para>
-                  Enforces secure file/directory creation. Optional. The permission mode is set to
-                  <computeroutput>0755</computeroutput>. Operation fails if it cannot be performed securely.
-                  </para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--mode &lt;mode&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the permission mode of the specified directory. Optional.
-                  Currently only octal modes (e.g. <computeroutput>0755</computeroutput>)
-                  are supported.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--tmpdir &lt;directory&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>
-                  Specifies the absolute path of the directory on the guest file system into which the
-                  file/directory specified in will be created. Optional.
-                  If unspecified, the platform-specific temp directory is used.
-                  </para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>&lt;template&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies a file name without a directory path, containing at least one sequence comprising
-                   three consecutive 'X' characters, or ending in 'X'. Mandatory.
-                  </para>
-                </glossdef>
-              </glossentry>
-            </glosslist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>stat</computeroutput></emphasis>
-          Displays file or file system status(es) on the guest.</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; stat [common-options]
+        <para>
+          The parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--directory</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Creates a temporary directory instead of a file,
+                specified by the &lt;template&gt; parameter. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--secure</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Enforces secure file/directory creation. Optional. The
+                permission mode is set to
+                <computeroutput>0755</computeroutput>. Operation fails
+                if it cannot be performed securely.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--mode &lt;mode&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the permission mode of the specified
+                directory. Optional. Currently only octal modes (e.g.
+                <computeroutput>0755</computeroutput>) are supported.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--tmpdir
+              &lt;directory&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the absolute path of the directory on the
+                guest file system into which the file/directory
+                specified in will be created. Optional. If unspecified,
+                the platform-specific temp directory is used.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;template&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies a file name without a directory path,
+                containing at least one sequence comprising three
+                consecutive 'X' characters, or ending in 'X'. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>stat</computeroutput></emphasis>
+          Displays file or file system status(es) on the guest.
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; stat [common-options]
            &lt;file0&gt; [&lt;file1&gt; [...]]</screen>
 
-          <para>Where the parameters are: <glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>&lt;file0&gt; [&lt;file1&gt; [...]]</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies absolute path(s) of file(s) and/or file system(s) on guest file system. Mandatory.
-                  e.g. <computeroutput>/home/foo/a.out</computeroutput>.
-                  The specified user should have sufficient rights to access
-                  the specified file(s)/file system(s).</para>
-                </glossdef>
-              </glossentry>
-            </glosslist></para>
-        </listitem>
-      </itemizedlist>
-    </para>
-
-    <para>The second set of subcommands is of the form:</para>
-    <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; &lt;sub-command&gt;
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;file0&gt; [&lt;file1&gt;
+              [...]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies absolute path(s) of file(s) and/or file
+                system(s) on guest file system. Mandatory. e.g.
+                <computeroutput>/home/foo/a.out</computeroutput>. The
+                specified user should have sufficient rights to access
+                the specified file(s)/file system(s).
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      The second set of subcommands is of the form:
+    </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; &lt;sub-command&gt;
            [-v|--verbose] [-q|quiet] ...
     </screen>
 
-    <para>The "common-options" are:</para>
-    <screen>
+    <para>
+      The "common-options" are:
+    </para>
+
+<screen>
             [-v|--verbose] [-q|--quiet]
     </screen>
 
-    <para>Where details of the common options for the second set of subcommands are:
-      <glosslist>
-
-        <glossentry>
-          <glossterm><computeroutput>-v|--verbose</computeroutput></glossterm>
-          <glossdef><para>Makes the sub-command execution more verbose. Optional.</para></glossdef>
-        </glossentry>
-
-        <glossentry>
-          <glossterm><computeroutput>-q|--quiet</computeroutput></glossterm>
-          <glossdef><para>Makes the sub-command execution quieter. Optional.</para></glossdef>
-        </glossentry>
-      </glosslist>
-    </para>
-
-    <para>The second set of subcommands: <itemizedlist>
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>list</computeroutput></emphasis>
-          Lists guest control configuration and status data, e.g. open guest sessions,
-          guest processes and files.</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; list [common-opts]
+    <para>
+      Where details of the common options for the second set of
+      subcommands are:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>-v|--verbose</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Makes the sub-command execution more verbose. Optional.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>-q|--quiet</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Makes the sub-command execution quieter. Optional.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+    <para>
+      The second set of subcommands:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>list</computeroutput></emphasis>
+          Lists guest control configuration and status data, e.g. open
+          guest sessions, guest processes and files.
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; list [common-opts]
            &lt;all|sessions|processes|files&gt; </screen>
 
-          <para>Where the parameters are: <glosslist>
-            <glossentry>
-              <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-              <glossdef>
-                <para>Specifies the VM UUID or VM name. Mandatory.</para>
-              </glossdef>
-            </glossentry>
-
-            <glossentry>
-              <glossterm><computeroutput>all|sessions|processes|files</computeroutput></glossterm>
-              <glossdef>
-                <para>Indicates whether to list all available data or guest sessions, processes or files.
-                Mandatory.</para>
-              </glossdef>
-            </glossentry>
-
-          </glosslist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>closeprocess</computeroutput></emphasis>
-          Terminates guest processes specified by PID(s))running in guest session(s),
-          specified by the session ID or name(s).</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; closeprocess [common-options]
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>all|sessions|processes|files</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Indicates whether to list all available data or guest
+                sessions, processes or files. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>closeprocess</computeroutput></emphasis>
+          Terminates guest processes specified by PID(s))running in
+          guest session(s), specified by the session ID or name(s).
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; closeprocess [common-options]
            --session-id &lt;ID&gt; | --session-name &lt;name or pattern&gt;
            &lt;PID0&gt; [&lt;PID1&gt; [...]] </screen>
 
-          <para>Where the parameters are: <glosslist>
-            <glossentry>
-              <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-              <glossdef>
-                <para>Specifies the VM UUID or VM name. Mandatory.</para>
-              </glossdef>
-            </glossentry>
-
-            <glossentry>
-              <glossterm><computeroutput>--session-id &lt;ID&gt;</computeroutput></glossterm>
-              <glossdef>
-                <para>Specifies the guest session by its ID. Optional.</para>
-              </glossdef>
-            </glossentry>
-
-            <glossentry>
-              <glossterm><computeroutput>--session-name &lt;name or pattern&gt;</computeroutput></glossterm>
-              <glossdef>
-                <para>Specifies the guest session by its name, or multiple sessions
-                using a pattern containing wildcards. Optional.</para>
-              </glossdef>
-            </glossentry>
-
-            <glossentry>
-              <glossterm><computeroutput>&lt;PID0&gt; [&lt;PID1&gt; [...]]</computeroutput></glossterm>
-              <glossdef>
-                <para>Specifies a list of process identifiers (PIDs) of guest processes to be terminated. Mandatory.</para>
-              </glossdef>
-            </glossentry>
-          </glosslist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>closesession</computeroutput></emphasis>
-          Closes specified guest sessions, specified either by session ID or name.</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; closesession [common-options]
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--session-id &lt;ID&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the guest session by its ID. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--session-name &lt;name or
+              pattern&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the guest session by its name, or multiple
+                sessions using a pattern containing wildcards. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;PID0&gt; [&lt;PID1&gt;
+              [...]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies a list of process identifiers (PIDs) of guest
+                processes to be terminated. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>closesession</computeroutput></emphasis>
+          Closes specified guest sessions, specified either by session
+          ID or name.
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; closesession [common-options]
            --session-id &lt;ID&gt; | --session-name &lt;name or pattern&gt; | --all </screen>
 
-          <para>Where the parameters are: <glosslist>
-            <glossentry>
-              <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-              <glossdef>
-                <para>Specifies the VM UUID or VM name. Mandatory.</para>
-              </glossdef>
-            </glossentry>
-
-            <glossentry>
-              <glossterm><computeroutput>--session-id &lt;ID&gt;</computeroutput></glossterm>
-              <glossdef>
-                <para>Specifies the guest session to be closed by ID. Optional.</para>
-              </glossdef>
-            </glossentry>
-
-             <glossentry>
-              <glossterm><computeroutput>--session-name &lt;name or pattern&gt;</computeroutput></glossterm>
-              <glossdef>
-                <para>Specifies the guest session to be closed by name. Optional.
-                Multiple sessions can be specified by using a pattern
-                containing wildcards. </para>
-              </glossdef>
-            </glossentry>
-
-             <glossentry>
-              <glossterm><computeroutput>--all</computeroutput></glossterm>
-              <glossdef>
-                <para>Close all guest sessions. Optional.</para>
-              </glossdef>
-            </glossentry>
-          </glosslist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>updatega|updateadditions|updateguestadditions</computeroutput></emphasis>
-          Ugrades Guest Additions already installed on the guest.
-          (Only already installed Guest Additions 4.0 and later).</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; updatega|updateadditions|updateguestadditions [common-options]
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--session-id &lt;ID&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the guest session to be closed by ID.
+                Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--session-name &lt;name or
+              pattern&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the guest session to be closed by name.
+                Optional. Multiple sessions can be specified by using a
+                pattern containing wildcards.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--all</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Close all guest sessions. Optional.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>updatega|updateadditions|updateguestadditions</computeroutput></emphasis>
+          Ugrades Guest Additions already installed on the guest. (Only
+          already installed Guest Additions 4.0 and later).
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; updatega|updateadditions|updateguestadditions 
+           [common-options]
            [--source &lt;New .ISO path&gt;]
            [--wait-start]
            [-- &lt;argument0&gt; [&lt;argument1&gt; [...]]]</screen>
 
-          <para>Where the parameters are: <glosslist>
-              <glossentry>
-                <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies the VM UUID or VM name. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--source</computeroutput> &lt;New .ISO path&gt;</glossterm>
-                <glossdef>
-                  <para>Specifies the absolute path on guest file system of the .ISO file for Guest Additions update. Mandatory.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>--wait-start</computeroutput></glossterm>
-                <glossdef>
-                  <para>Indicates that VBoxManage starts the usual updating process on the guest and then waits
-                   until the actual Guest Additions updating begins, at which point VBoxManage self-terminates. Optional.</para>
-                  <para>Default behavior is that VBoxManage waits for completion of the Guest Additions update before
-                   terminating. Use of this option is sometimes necessary, as a running VBoxManage
-                   can affect the interaction between the installer and the guest OS.</para>
-                </glossdef>
-              </glossentry>
-
-              <glossentry>
-                <glossterm><computeroutput>[-- &lt;argument0&gt; [&lt;argument1&gt; [...]]]</computeroutput></glossterm>
-                <glossdef>
-                  <para>Specifies optional command line arguments to be supplied to the Guest Additions
-                   updater. Useful for retrofitting features which are not currently installed.</para>
-                  <para>Arguments containing spaces should be enclosed by quotes.</para>
-                </glossdef>
-              </glossentry>
-            </glosslist></para>
-        </listitem>
-
-        <listitem>
-          <para><emphasis role="bold"><computeroutput>watch</computeroutput></emphasis>
-          This subcommand prints current guest control activity.</para>
-
-          <screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; watch [common-options]
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--source</computeroutput> &lt;New .ISO
+              path&gt;
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the absolute path on guest file system of the
+                .ISO file for Guest Additions update. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>--wait-start</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Indicates that VBoxManage starts the usual updating
+                process on the guest and then waits until the actual
+                Guest Additions updating begins, at which point
+                VBoxManage self-terminates. Optional.
+              </para>
+
+              <para>
+                Default behavior is that VBoxManage waits for completion
+                of the Guest Additions update before terminating. Use of
+                this option is sometimes necessary, as a running
+                VBoxManage can affect the interaction between the
+                installer and the guest OS.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              <computeroutput>[-- &lt;argument0&gt; [&lt;argument1&gt;
+              [...]]]</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies optional command line arguments to be supplied
+                to the Guest Additions updater. Useful for retrofitting
+                features which are not currently installed.
+              </para>
+
+              <para>
+                Arguments containing spaces should be enclosed by
+                quotes.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+      <listitem>
+        <para>
+          <emphasis role="bold"><computeroutput>watch</computeroutput></emphasis>
+          This subcommand prints current guest control activity.
+        </para>
+
+<screen>VBoxManage guestcontrol &lt;uuid|vmname&gt; watch [common-options]
           </screen>
-          <para>Where the parameters are: <glosslist>
-            <glossentry>
-              <glossterm><computeroutput>&lt;uuid|vmname&gt;</computeroutput></glossterm>
-              <glossdef>
-                <para>Specifies the VM UUID or VM name. Mandatory.</para>
-              </glossdef>
-            </glossentry>
-          </glosslist></para>
-        </listitem>
-      </itemizedlist></para>
+
+        <para>
+          Where the parameters are:
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              <computeroutput>&lt;uuid|vmname&gt;</computeroutput>
+            </term>
+
+            <listitem>
+              <para>
+                Specifies the VM UUID or VM name. Mandatory.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
-  <sect1 id="metrics">
+  <sect1 id="vboxmanage-metrics">
+
     <title>VBoxManage metrics</title>
 
-    <para>This command supports monitoring the usage of system resources.
-    Resources are represented by various metrics associated with the host
-    system or a particular VM. For example, the host system has a
-    <computeroutput>CPU/Load/User</computeroutput> metric that shows the
-    percentage of time CPUs spend executing in user mode over a specific
-    sampling period.</para>
-
-    <para>Metric data is collected and retained internally; it may be
-    retrieved at any time with the <computeroutput>VBoxManage metrics
-    query</computeroutput> subcommand. The data is available as long as the
-    background <computeroutput>VBoxSVC</computeroutput> process is alive. That
-    process terminates shortly after all VMs and frontends have been
-    closed.</para>
-
-    <para>By default no metrics are collected at all. Metrics collection does
-    not start until <computeroutput>VBoxManage metrics setup</computeroutput>
-    is invoked with a proper sampling interval and the number of metrics to be
-    retained. The interval is measured in seconds. For example, to enable
-    collecting the host processor and memory usage metrics every second and
-    keeping the 5 most current samples, the following command can be
-    used:</para>
-
-    <screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
-
-    <para>Metric collection can only be enabled for started VMs. Collected
-    data and collection settings for a particular VM will disappear as soon as
-    it shuts down. Use <computeroutput>VBoxManage metrics list
-    </computeroutput> subcommand to see which metrics are currently available.
-    You can also use <computeroutput>--list</computeroutput> option with any
-    subcommand that modifies metric settings to find out which metrics were
-    affected.</para>
-
-    <para>Note that the <computeroutput>VBoxManage metrics
-    setup</computeroutput> subcommand discards all samples that may have been
-    previously collected for the specified set of objects and metrics.</para>
-
-    <para>To enable or disable metrics collection without discarding the data
-    <computeroutput>VBoxManage metrics enable</computeroutput> and
-    <computeroutput>VBoxManage metrics disable</computeroutput> subcommands
-    can be used. Note that these subcommands expect metrics, not submetrics,
-    like <code>CPU/Load</code> or <code>RAM/Usage</code> as parameters. In
-    other words enabling <code>CPU/Load/User</code> while disabling
-    <code>CPU/Load/Kernel</code> is not supported.</para>
-
-    <para>The host and VMs have different sets of associated metrics.
-    Available metrics can be listed with <computeroutput>VBoxManage metrics
-    list</computeroutput> subcommand.</para>
-
-    <para>A complete metric name may include an aggregate function. The name
-    has the following form:
-    <computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
-    For example, <computeroutput>RAM/Usage/Free:min</computeroutput> stands
-    for the minimum amount of available memory over all retained data if
-    applied to the host object.</para>
-
-    <para>Subcommands may apply to all objects and metrics or can be limited
-    to one object or/and a list of metrics. If no objects or metrics are given
-    in the parameters, the subcommands will apply to all available metrics of
-    all objects. You may use an asterisk
-    ("<computeroutput>*</computeroutput>") to explicitly specify that the
-    command should be applied to all objects or metrics. Use "host" as the
-    object name to limit the scope of the command to host-related metrics. To
-    limit the scope to a subset of metrics, use a metric list with names
-    separated by commas.</para>
-
-    <para>For example, to query metric data on the CPU time spent in user and
-    kernel modes by the virtual machine named "test", you can use the
-    following command:</para>
-
-    <screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
-
-    <para>The following list summarizes the available subcommands:</para>
-
-    <glosslist>
-      <glossentry>
-        <glossterm><computeroutput>list</computeroutput></glossterm>
-
-        <glossdef>
-          <para>This subcommand shows the parameters of the currently existing
-          metrics. Note that VM-specific metrics are only available when a
-          particular VM is running.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm><computeroutput>setup</computeroutput></glossterm>
-
-        <glossdef>
-          <para>This subcommand sets the interval between taking two samples
-          of metric data and the number of samples retained internally. The
-          retained data is available for displaying with the
-          <code>query</code> subcommand. The <computeroutput>--list
-          </computeroutput> option shows which metrics have been modified as
-          the result of the command execution.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm><computeroutput>enable</computeroutput></glossterm>
-
-        <glossdef>
-          <para>This subcommand "resumes" data collection after it has been
-          stopped with <code>disable</code> subcommand. Note that specifying
-          submetrics as parameters will not enable underlying metrics. Use
-          <computeroutput>--list</computeroutput> to find out if the command
-          did what was expected.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm><computeroutput>disable</computeroutput></glossterm>
-
-        <glossdef>
-          <para>This subcommand "suspends" data collection without affecting
-          collection parameters or collected data. Note that specifying
-          submetrics as parameters will not disable underlying metrics. Use
-          <computeroutput>--list</computeroutput> to find out if the command
-          did what was expected.</para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm><computeroutput>query</computeroutput></glossterm>
-
-        <glossdef>
-          <para>This subcommand retrieves and displays the currently retained
-          metric data.<note>
-              <para>The <code>query</code> subcommand does not remove or
-              "flush" retained data. If you query often enough you will see
-              how old samples are gradually being "phased out" by new
-              samples.</para>
-            </note></para>
-        </glossdef>
-      </glossentry>
-
-      <glossentry>
-        <glossterm><computeroutput>collect</computeroutput></glossterm>
-
-        <glossdef>
-          <para>This subcommand sets the interval between taking two samples
-          of metric data and the number of samples retained internally. The
-          collected data is displayed periodically until Ctrl-C is pressed
-          unless the <computeroutput>--detach</computeroutput> option is
-          specified. With the <computeroutput>--detach</computeroutput>
-          option, this subcommand operates the same way as <code>setup</code>
-          does. The <computeroutput>--list</computeroutput> option shows which
-          metrics match the specified filter.</para>
-        </glossdef>
-      </glossentry>
-    </glosslist>
+    <para>
+      This command supports monitoring the usage of system resources.
+      Resources are represented by various metrics associated with the
+      host system or a particular VM. For example, the host system has a
+      <computeroutput>CPU/Load/User</computeroutput> metric that shows
+      the percentage of time CPUs spend executing in user mode over a
+      specific sampling period.
+    </para>
+
+    <para>
+      Metric data is collected and retained internally; it may be
+      retrieved at any time with the <computeroutput>VBoxManage metrics
+      query</computeroutput> subcommand. The data is available as long
+      as the background <computeroutput>VBoxSVC</computeroutput> process
+      is alive. That process terminates shortly after all VMs and
+      frontends have been closed.
+    </para>
+
+    <para>
+      By default no metrics are collected at all. Metrics collection
+      does not start until <computeroutput>VBoxManage metrics
+      setup</computeroutput> is invoked with a proper sampling interval
+      and the number of metrics to be retained. The interval is measured
+      in seconds. For example, to enable collecting the host processor
+      and memory usage metrics every second and keeping the 5 most
+      current samples, the following command can be used:
+    </para>
+
+<screen>VBoxManage metrics setup --period 1 --samples 5 host CPU/Load,RAM/Usage</screen>
+
+    <para>
+      Metric collection can only be enabled for started VMs. Collected
+      data and collection settings for a particular VM will disappear as
+      soon as it shuts down. Use <computeroutput>VBoxManage metrics list
+      </computeroutput> subcommand to see which metrics are currently
+      available. You can also use
+      <computeroutput>--list</computeroutput> option with any subcommand
+      that modifies metric settings to find out which metrics were
+      affected.
+    </para>
+
+    <para>
+      Note that the <computeroutput>VBoxManage metrics
+      setup</computeroutput> subcommand discards all samples that may
+      have been previously collected for the specified set of objects
+      and metrics.
+    </para>
+
+    <para>
+      To enable or disable metrics collection without discarding the
+      data <computeroutput>VBoxManage metrics enable</computeroutput>
+      and <computeroutput>VBoxManage metrics disable</computeroutput>
+      subcommands can be used. Note that these subcommands expect
+      metrics, not submetrics, like <code>CPU/Load</code> or
+      <code>RAM/Usage</code> as parameters. In other words enabling
+      <code>CPU/Load/User</code> while disabling
+      <code>CPU/Load/Kernel</code> is not supported.
+    </para>
+
+    <para>
+      The host and VMs have different sets of associated metrics.
+      Available metrics can be listed with <computeroutput>VBoxManage
+      metrics list</computeroutput> subcommand.
+    </para>
+
+    <para>
+      A complete metric name may include an aggregate function. The name
+      has the following form:
+      <computeroutput>Category/Metric[/SubMetric][:aggregate]</computeroutput>.
+      For example, <computeroutput>RAM/Usage/Free:min</computeroutput>
+      stands for the minimum amount of available memory over all
+      retained data if applied to the host object.
+    </para>
+
+    <para>
+      Subcommands may apply to all objects and metrics or can be limited
+      to one object or/and a list of metrics. If no objects or metrics
+      are given in the parameters, the subcommands will apply to all
+      available metrics of all objects. You may use an asterisk
+      ("<computeroutput>*</computeroutput>") to explicitly specify that
+      the command should be applied to all objects or metrics. Use
+      "host" as the object name to limit the scope of the command to
+      host-related metrics. To limit the scope to a subset of metrics,
+      use a metric list with names separated by commas.
+    </para>
+
+    <para>
+      For example, to query metric data on the CPU time spent in user
+      and kernel modes by the virtual machine named "test", you can use
+      the following command:
+    </para>
+
+<screen>VBoxManage metrics query test CPU/Load/User,CPU/Load/Kernel</screen>
+
+    <para>
+      The following list summarizes the available subcommands:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>list</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This subcommand shows the parameters of the currently
+            existing metrics. Note that VM-specific metrics are only
+            available when a particular VM is running.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>setup</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This subcommand sets the interval between taking two samples
+            of metric data and the number of samples retained
+            internally. The retained data is available for displaying
+            with the <code>query</code> subcommand. The
+            <computeroutput>--list </computeroutput> option shows which
+            metrics have been modified as the result of the command
+            execution.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>enable</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This subcommand "resumes" data collection after it has been
+            stopped with <code>disable</code> subcommand. Note that
+            specifying submetrics as parameters will not enable
+            underlying metrics. Use
+            <computeroutput>--list</computeroutput> to find out if the
+            command did what was expected.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>disable</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This subcommand "suspends" data collection without affecting
+            collection parameters or collected data. Note that
+            specifying submetrics as parameters will not disable
+            underlying metrics. Use
+            <computeroutput>--list</computeroutput> to find out if the
+            command did what was expected.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>query</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This subcommand retrieves and displays the currently
+            retained metric data.
+
+            <note>
+              <para>
+                The <code>query</code> subcommand does not remove or
+                "flush" retained data. If you query often enough you
+                will see how old samples are gradually being "phased
+                out" by new samples.
+              </para>
+            </note>
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>collect</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            This subcommand sets the interval between taking two samples
+            of metric data and the number of samples retained
+            internally. The collected data is displayed periodically
+            until Ctrl-C is pressed unless the
+            <computeroutput>--detach</computeroutput> option is
+            specified. With the
+            <computeroutput>--detach</computeroutput> option, this
+            subcommand operates the same way as <code>setup</code> does.
+            The <computeroutput>--list</computeroutput> option shows
+            which metrics match the specified filter.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
   </sect1>
 
   <sect1 id="vboxmanage-natnetwork">
+
     <title>VBoxManage natnetwork</title>
 
-    <para>NAT networks use the Network Address Translation (NAT) service - which works in a
-    similar way to a home router. It groups systems using it into a network and prevents
-    outside systems from directly accessing those inside, while letting systems inside communicate
-    with each other and outside systems using TCP and UDP over IPv4 and IPv6.</para>
-
-    <para>A NAT service is attached to an internal network. Virtual machines to make use of one
-    should be attached to it. The name of an internal network is chosen when the NAT service is
-    created, and the internal network will be created if it does not already exist.
-    An example command to create a NAT network:</para>
-
-    <screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen>
-
-    <para>Here, "natnet1" is the name of the internal network to be used and "192.168.15.0/24" is the
-    network address and mask of the NAT service interface. By default, in this static configuration
-    - the gateway will be assigned the address 192.168.15.1 (the address after the interface address),
-    though this is subject to change.</para>
-
-    <para>To add a DHCP server to the NAT network after creation:</para>
-
-    <screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen>
-
-    <para>Below are the subcommands for <emphasis role="bold"><computeroutput>VBoxManage natnetwork </computeroutput></emphasis></para>
-
-    <screen>VBoxManage natnetwork add --netname &lt;name&gt;
+    <para>
+      NAT networks use the Network Address Translation (NAT) service,
+      which works in a similar way to a home router. It groups systems
+      using it into a network and prevents outside systems from directly
+      accessing those inside, while letting systems inside communicate
+      with each other and outside systems using TCP and UDP over IPv4
+      and IPv6.
+    </para>
+
+    <para>
+      A NAT service is attached to an internal network. Virtual machines
+      to make use of one should be attached to it. The name of an
+      internal network is chosen when the NAT service is created, and
+      the internal network will be created if it does not already exist.
+      An example command to create a NAT network:
+    </para>
+
+<screen>VBoxManage natnetwork add --netname natnet1 --network "192.168.15.0/24" --enable</screen>
+
+    <para>
+      Here, "natnet1" is the name of the internal network to be used and
+      "192.168.15.0/24" is the network address and mask of the NAT
+      service interface. By default, in this static configuration the
+      gateway will be assigned the address 192.168.15.1, the address
+      after the interface address, though this is subject to change.
+    </para>
+
+    <para>
+      To add a DHCP server to the NAT network after creation:
+    </para>
+
+<screen>VBoxManage natnetwork modify --netname natnet1 --dhcp on</screen>
+
+    <para>
+      Below are the subcommands for
+      <emphasis role="bold"><computeroutput>VBoxManage natnetwork
+      </computeroutput></emphasis>
+    </para>
+
+<screen>VBoxManage natnetwork add --netname &lt;name&gt;
                          [--network &lt;network&gt;]
                          [--enable|--disable]
@@ -5455,88 +8280,159 @@
     </screen>
 
-
-    <para><emphasis role="bold"><computeroutput>VBoxManage natnetwork add</computeroutput></emphasis>
-    Creates a new internal network interface, and adds a NAT network service. This command is a
-    prerequisite for enabling attachment of VMs to the NAT network. Parameters:</para>
-
-    <para>
-      <glosslist>
-        <glossentry>
-          <glossterm><computeroutput>--netname &lt;name&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Where &lt;name&gt; is the name of the new internal network interface on the host OS. </para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--network &lt;network&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Where &lt;network&gt; specifies the static(default)/DHCP network address and mask of
-            the NAT service interface.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--enable|--disable</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables/disables the NAT network service.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--dhcp on|off</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables/disables DHCP server specified by --netname; its use also indicates that it
-            is a DHCP server.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--port-forward-4 &lt;rule&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables IPv4 port forwarding, rule specified by &lt;rule&gt;.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--loopback-4 &lt;rule&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables IPv4 loopback interface, rule specified by &lt;rule&gt;.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--ipv6 on|off</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables/disables IPv6 (default is IPv4, disables gives IPv4).</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--port-forward-6 &lt;rule&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables IPv6 port forwarding, rule specified by &lt;rule&gt;.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--loopback-6 &lt;rule&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables IPv6 loopback interface, rule specified by &lt;rule&gt;.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-    </para>
-
-    <screen>VBoxManage natnetwork remove --netname &lt;name&gt; </screen>
-
-    <para><emphasis role="bold"><computeroutput>VBoxManage natnetwork remove</computeroutput></emphasis>
-    Removes a NAT network service, parameters:</para>
-
-    <para>
-      <glosslist>
-        <glossentry>
-          <glossterm><computeroutput>--netname &lt;name&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Where &lt;name&gt; specifies an existing NAT network service.
-            Does not remove any DHCP server enabled on the network.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-    </para>
-
-    <screen>VBoxManage natnetwork modify --netname &lt;name&gt;
+    <para>
+      <emphasis role="bold"><computeroutput>VBoxManage natnetwork
+      add</computeroutput></emphasis> Creates a new internal network
+      interface, and adds a NAT network service. This command is a
+      prerequisite for enabling attachment of VMs to the NAT network.
+      Parameters are as follows:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--netname &lt;name&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Where &lt;name&gt; is the name of the new internal network
+            interface on the host OS.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--network &lt;network&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Where &lt;network&gt; specifies the static(default)/DHCP
+            network address and mask of the NAT service interface.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--enable|--disable</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables/disables the NAT network service.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--dhcp on|off</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables/disables DHCP server specified by --netname; its use
+            also indicates that it is a DHCP server.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--port-forward-4 &lt;rule&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables IPv4 port forwarding, rule specified by
+            &lt;rule&gt;.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--loopback-4 &lt;rule&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables IPv4 loopback interface, rule specified by
+            &lt;rule&gt;.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--ipv6 on|off</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables/disables IPv6 (default is IPv4, disables gives
+            IPv4).
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--port-forward-6 &lt;rule&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables IPv6 port forwarding, rule specified by
+            &lt;rule&gt;.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--loopback-6 &lt;rule&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables IPv6 loopback interface, rule specified by
+            &lt;rule&gt;.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+<screen>VBoxManage natnetwork remove --netname &lt;name&gt; </screen>
+
+    <para>
+      <emphasis role="bold"><computeroutput>VBoxManage natnetwork
+      remove</computeroutput></emphasis> Removes a NAT network service.
+      Parameters are as follows:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--netname &lt;name&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Where &lt;name&gt; specifies an existing NAT network
+            service. Does not remove any DHCP server enabled on the
+            network.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+<screen>VBoxManage natnetwork modify --netname &lt;name&gt;
                             [--network &lt;network&gt;]
                             [--enable|--disable]
@@ -5549,278 +8445,465 @@
     </screen>
 
-    <para><emphasis role="bold"><computeroutput>VBoxManage natnetwork modify</computeroutput></emphasis>
-    Modifies an existing NAT network service, parameters:</para>
-
-    <para>
-      <glosslist>
-        <glossentry>
-          <glossterm><computeroutput>--netname &lt;name&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Where &lt;name&gt; specifies an existing NAT network service.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--network &lt;network&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Where &lt;network&gt; specifies the new static(default)/DHCP network address and mask
-            of the NAT service interface.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--enable|--disable</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables/disables the NAT network service.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--dhcp on|off</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables (and if absent, adds)/disables (if any) DHCP server.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--port-forward-4 &lt;rule&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables IPv4 port forwarding, rule specified by &lt;rule&gt;.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--loopback-4 &lt;rule&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables IPv4 loopback interface, rule specified by &lt;rule&gt;.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--ipv6 on|off</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables/disables IPv6 (default is IPv4, disables gives IPv4).</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--port-forward-6 &lt;rule&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables IPv6 port forwarding, rule specified by &lt;rule&gt;.</para>
-          </glossdef>
-        </glossentry>
-        <glossentry>
-          <glossterm><computeroutput>--loopback-6 &lt;rule&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Enables IPv6 loopback interface, rule specified by &lt;rule&gt;.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-    </para>
-
-    <screen>VBoxManage natnetwork start --netname &lt;name&gt;
+    <para>
+      <emphasis role="bold"><computeroutput>VBoxManage natnetwork
+      modify</computeroutput></emphasis> Modifies an existing NAT
+      network service. Parameters are as follows:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--netname &lt;name&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Where &lt;name&gt; specifies an existing NAT network
+            service.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--network &lt;network&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Where &lt;network&gt; specifies the new static(default)/DHCP
+            network address and mask of the NAT service interface.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--enable|--disable</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables/disables the NAT network service.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--dhcp on|off</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables (and if absent, adds)/disables (if any) DHCP server.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--port-forward-4 &lt;rule&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables IPv4 port forwarding, rule specified by
+            &lt;rule&gt;.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--loopback-4 &lt;rule&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables IPv4 loopback interface, rule specified by
+            &lt;rule&gt;.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--ipv6 on|off</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables/disables IPv6 (default is IPv4, disables gives
+            IPv4).
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--port-forward-6 &lt;rule&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables IPv6 port forwarding, rule specified by
+            &lt;rule&gt;.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--loopback-6 &lt;rule&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Enables IPv6 loopback interface, rule specified by
+            &lt;rule&gt;.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+<screen>VBoxManage natnetwork start --netname &lt;name&gt;
     </screen>
 
-    <para><emphasis  role="bold"><computeroutput>VBoxManage natnetwork start</computeroutput></emphasis>
-    Starts specified NAT network service and any associated DHCP server, parameters:</para>
-
-    <para>
-      <glosslist>
-        <glossentry>
-          <glossterm><computeroutput>--netname &lt;name&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Where &lt;name&gt; specifies an existing NAT network service.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-    </para>
-
-    <screen>VBoxManage natnetwork stop --netname &lt;name&gt;
+    <para>
+      <emphasis  role="bold"><computeroutput>VBoxManage natnetwork
+      start</computeroutput></emphasis> Starts specified NAT network
+      service and any associated DHCP server. Parameters are as follows:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--netname &lt;name&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Where &lt;name&gt; specifies an existing NAT network
+            service.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+<screen>VBoxManage natnetwork stop --netname &lt;name&gt;
     </screen>
 
-    <para><emphasis  role="bold"><computeroutput>VBoxManage natnetwork stop</computeroutput></emphasis>
-    Stops specified NAT network service and any DHCP server, parameters:</para>
-
-    <para>
-      <glosslist>
-        <glossentry>
-          <glossterm><computeroutput>--netname &lt;name&gt;</computeroutput></glossterm>
-          <glossdef>
-            <para>Where &lt;name&gt; specifies an existing NAT network service.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-    </para>
-
-    <screen>VBoxManage natnetwork list [&lt;pattern&gt;] </screen>
-
-    <para><emphasis  role="bold"><computeroutput>VBoxManage natnetwork list</computeroutput></emphasis>
-    Lists all NAT network services with optional filtering, parameters:</para>
-
-    <para>
-      <glosslist>
-        <glossentry>
-          <glossterm><computeroutput>[&lt;pattern&gt;]</computeroutput></glossterm>
-          <glossdef>
-            <para>Where &lt;pattern&gt; is optional filtering pattern.</para>
-          </glossdef>
-        </glossentry>
-      </glosslist>
-    </para>
+    <para>
+      <emphasis  role="bold"><computeroutput>VBoxManage natnetwork
+      stop</computeroutput></emphasis> Stops specified NAT network
+      service and any DHCP server. Parameters are as follows:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>--netname &lt;name&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Where &lt;name&gt; specifies an existing NAT network
+            service.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
+<screen>VBoxManage natnetwork list [&lt;pattern&gt;] </screen>
+
+    <para>
+      <emphasis  role="bold"><computeroutput>VBoxManage natnetwork
+      list</computeroutput></emphasis> Lists all NAT network services
+      with optional filtering. Parameters are as follows:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>[&lt;pattern&gt;]</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Where &lt;pattern&gt; is optional filtering pattern.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+
   </sect1>
 
   <sect1 id="vboxmanage-hostonlyif">
+
     <title>VBoxManage hostonlyif</title>
 
-    <para>With "hostonlyif" you can change the IP configuration of a host-only
-    network interface. For a description of host-only networking, please
-    refer to <xref linkend="network_hostonly" />. Each host-only interface is
-    identified by a name and can either use the internal DHCP server or a
-    manual IP configuration (both IP4 and IP6).</para>
-
-    <para>The following list summarizes the available subcommands:</para>
-
-    <glosslist>
-      <glossentry>
-        <glossterm><computeroutput>ipconfig "&lt;name&gt;"</computeroutput></glossterm>
-        <glossdef>
-          <para>Configure a hostonly interface</para>
-        </glossdef>
-      </glossentry>
-      <glossentry>
-        <glossterm><computeroutput>create</computeroutput></glossterm>
-        <glossdef>
-          <para>Creates a new vboxnet&lt;N&gt; interface on the host OS.
-            This command is essential before you can attach VMs to host-only network.</para>
-        </glossdef>
-      </glossentry>
-      <glossentry>
-        <glossterm><computeroutput>remove vboxnet&lt;N&gt;</computeroutput></glossterm>
-        <glossdef>
-          <para>Removes a vboxnet&lt;N&gt; interface from the host OS.</para>
-        </glossdef>
-      </glossentry>
-    </glosslist>
+    <para>
+      With "hostonlyif" you can change the IP configuration of a
+      host-only network interface. For a description of host-only
+      networking, see <xref linkend="network_hostonly" />. Each
+      host-only interface is identified by a name and can either use the
+      internal DHCP server or a manual IP configuration, both IP4 and
+      IP6.
+    </para>
+
+    <para>
+      The following list summarizes the available subcommands:
+    </para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term>
+          <computeroutput>ipconfig "&lt;name&gt;"</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Configure a host-only interface
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>create</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Creates a new vboxnet&lt;N&gt; interface on the host OS.
+            This command is essential before you can attach VMs to a
+            host-only network.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>
+          <computeroutput>remove vboxnet&lt;N&gt;</computeroutput>
+        </term>
+
+        <listitem>
+          <para>
+            Removes a vboxnet&lt;N&gt; interface from the host OS.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
 
   </sect1>
 
   <sect1 id="vboxmanage-dhcpserver">
+
     <title>VBoxManage dhcpserver</title>
 
-    <para>The "dhcpserver" commands allow you to control the DHCP server that
-    is built into VirtualBox. You may find this useful when using internal or
-    host-only networking. (Theoretically, you can enable it for a bridged
-    network as well, but that will likely cause conflicts with other DHCP
-    servers in your physical network.)</para>
-
-    <para>Use the following command line options:<itemizedlist>
-        <listitem>
-          <para>If you use internal networking for a virtual network adapter
-          of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
-          --netname &lt;network_name&gt;</computeroutput>, where
-          <computeroutput>&lt;network_name&gt;</computeroutput> is the same
-          network name you used with <computeroutput>VBoxManage modifyvm
-          &lt;vmname&gt; --intnet&lt;X&gt;
-          &lt;network_name&gt;</computeroutput>.</para>
-        </listitem>
-
-        <listitem>
-          <para>If you use host-only networking for a virtual network adapter
-          of a virtual machine, use <computeroutput>VBoxManage dhcpserver add
-          --ifname &lt;hostonly_if_name&gt;</computeroutput> instead, where
-          <computeroutput>&lt;hostonly_if_name&gt;</computeroutput> is the
-          same host-only interface name you used with
+    <para>
+      The "dhcpserver" commands allow you to control the DHCP server
+      that is built into VirtualBox. You may find this useful when using
+      internal or host-only networking. Theoretically, you can enable it
+      for a bridged network as well, but that will likely cause
+      conflicts with other DHCP servers in your physical network.
+    </para>
+
+    <para>
+      Use the following command line options:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          If you use internal networking for a virtual network adapter
+          of a virtual machine, use <computeroutput>VBoxManage
+          dhcpserver add --netname
+          &lt;network_name&gt;</computeroutput>, where
+          <computeroutput>&lt;network_name&gt;</computeroutput> is the
+          same network name you used with <computeroutput>VBoxManage
+          modifyvm &lt;vmname&gt; --intnet&lt;X&gt;
+          &lt;network_name&gt;</computeroutput>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          If you use host-only networking for a virtual network adapter
+          of a virtual machine, use <computeroutput>VBoxManage
+          dhcpserver add --ifname
+          &lt;hostonly_if_name&gt;</computeroutput> instead, where
+          <computeroutput>&lt;hostonly_if_name&gt;</computeroutput> is
+          the same host-only interface name you used with
           <computeroutput>VBoxManage modifyvm &lt;vmname&gt;
           --hostonlyadapter&lt;X&gt;
-          &lt;hostonly_if_name&gt;</computeroutput>.</para>
-
-          <para>Alternatively, you can also use the
+          &lt;hostonly_if_name&gt;</computeroutput>.
+        </para>
+
+        <para>
+          Alternatively, you can also use the
           <computeroutput>--netname</computeroutput> option as with
-          internal networks if you know the host-only network's name; you can
-          see the names with <computeroutput>VBoxManage list
-          hostonlyifs</computeroutput> (see <xref linkend="vboxmanage-list" />
-          above).</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>The following additional parameters are required when first adding a
-    DHCP server:<itemizedlist>
-        <listitem>
-          <para>With <computeroutput>--ip</computeroutput>, specify the IP
-          address of the DHCP server itself.</para>
-        </listitem>
-
-        <listitem>
-          <para>With <computeroutput>--netmask</computeroutput>, specify the
-          netmask of the network.</para>
-        </listitem>
-
-        <listitem>
-          <para>With <computeroutput>--lowerip</computeroutput> and
-          <computeroutput>--upperip</computeroutput>, you can specify the
-          lowest and highest IP address, respectively, that the DHCP server
-          will hand out to clients.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>Finally, you must specify <computeroutput>--enable</computeroutput>
-    or the DHCP server will be created in the disabled state, doing
-    nothing.</para>
-
-    <para>After this, VirtualBox will automatically start the DHCP server for
-    given internal or host-only network as soon as the first virtual machine
-    which uses that network is started.</para>
-
-    <para>Reversely, use <computeroutput>VBoxManage dhcpserver
-    remove</computeroutput> with the given <computeroutput>--netname
-    &lt;network_name&gt;</computeroutput> or <computeroutput>--ifname
-    &lt;hostonly_if_name&gt;</computeroutput> to remove the DHCP server again
-    for the given internal or host-only network.</para>
-
-    <para>To modify the settings of a DHCP server created earlier with
-    <computeroutput>VBoxManage dhcpserver add</computeroutput>, you can use
-    <computeroutput>VBoxManage dhcpserver modify</computeroutput> for a given
-    network or host-only interface name. This has the same parameters as
-    <computeroutput>VBoxManage dhcpserver add</computeroutput>.</para>
+          internal networks if you know the host-only network's name.
+          You can see the names with <computeroutput>VBoxManage list
+          hostonlyifs</computeroutput>. See
+          <xref linkend="vboxmanage-list" />.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      The following additional parameters are required when first adding
+      a DHCP server:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          With <computeroutput>--ip</computeroutput>, specify the IP
+          address of the DHCP server itself.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          With <computeroutput>--netmask</computeroutput>, specify the
+          netmask of the network.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          With <computeroutput>--lowerip</computeroutput> and
+          <computeroutput>--upperip</computeroutput>, you can specify
+          the lowest and highest IP address, respectively, that the DHCP
+          server will hand out to clients.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Finally, you must specify
+      <computeroutput>--enable</computeroutput> or the DHCP server will
+      be created in the disabled state, doing nothing.
+    </para>
+
+    <para>
+      After this, VirtualBox will automatically start the DHCP server
+      for given internal or host-only network as soon as the first
+      virtual machine which uses that network is started.
+    </para>
+
+    <para>
+      Reversely, use <computeroutput>VBoxManage dhcpserver
+      remove</computeroutput> with the given <computeroutput>--netname
+      &lt;network_name&gt;</computeroutput> or <computeroutput>--ifname
+      &lt;hostonly_if_name&gt;</computeroutput> to remove the DHCP
+      server again for the given internal or host-only network.
+    </para>
+
+    <para>
+      To modify the settings of a DHCP server created earlier with
+      <computeroutput>VBoxManage dhcpserver add</computeroutput>, you
+      can use <computeroutput>VBoxManage dhcpserver
+      modify</computeroutput> for a given network or host-only interface
+      name. This has the same parameters as <computeroutput>VBoxManage
+      dhcpserver add</computeroutput>.
+    </para>
+
   </sect1>
 
   <sect1 id="vboxmanage-usbdevsource">
+
     <title>VBoxManage usbdevsource</title>
 
-    <para>The "usbdevsource" commands enables you to add and remove USB devices
-    globally.</para>
-
-    <para>The following command adds a USB device.</para>
-
-    <screen>VBoxManage usbdevsource add &lt;source name&gt;
+    <para>
+      The "usbdevsource" commands enable you to add and remove USB
+      devices globally.
+    </para>
+
+    <para>
+      The following command adds a USB device.
+    </para>
+
+<screen>VBoxManage usbdevsource add &lt;source name&gt;
                             --backend &lt;backend&gt;
                             --address &lt;address&gt;
     </screen>
 
-    <para>Where the command line options are:<itemizedlist>
-        <listitem>
-          <para>&lt;source name&gt; specifies the ID of the 'source' USB
-          device to be added. Mandatory.</para>
-        </listitem>
-        <listitem>
-          <para>--backend &lt;backend&gt; specifies the USB proxy service
-          backend to use. Mandatory.</para>
-        </listitem>
-        <listitem>
-          <para>--address &lt;address&gt; specifies the backend specific
-          address. Mandatory.</para>
-        </listitem>
-      </itemizedlist></para>
-
-    <para>The following command removes a USB device.</para>
-
-    <screen>VBoxManage usbdevsource remove &lt;source name&gt;
+    <para>
+      Where the command line options are:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          &lt;source name&gt; specifies the ID of the 'source' USB
+          device to be added. Mandatory.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          --backend &lt;backend&gt; specifies the USB proxy service
+          backend to use. Mandatory.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          --address &lt;address&gt; specifies the backend specific
+          address. Mandatory.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      The following command removes a USB device.
+    </para>
+
+<screen>VBoxManage usbdevsource remove &lt;source name&gt;
     </screen>
 
-    <para>Where the command line options are:<itemizedlist>
-        <listitem>
-          <para>&lt;source name&gt; specifies the ID of the 'source' USB
-          device to be removed. Mandatory.</para>
-        </listitem>
-      </itemizedlist></para>
+    <para>
+      Where the command line options are:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          &lt;source name&gt; specifies the ID of the 'source' USB
+          device to be removed. Mandatory.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
   </sect1>
 
-
-  <xi:include href="user_man_VBoxManage-mediumio.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
-  <xi:include href="user_man_VBoxManage-debugvm.xml"    xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
-  <xi:include href="user_man_VBoxManage-extpack.xml"    xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
-  <xi:include href="user_man_VBoxManage-unattended.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
+  <xi:include href="user_man_VBoxManage-mediumio.xml"   xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_man_VBoxManage-debugvm.xml"    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_man_VBoxManage-extpack.xml"    xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+  <xi:include href="user_man_VBoxManage-unattended.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
 </chapter>
Index: /trunk/doc/manual/en_US/user_VirtualBoxAPI.xml
===================================================================
--- /trunk/doc/manual/en_US/user_VirtualBoxAPI.xml	(revision 73275)
+++ /trunk/doc/manual/en_US/user_VirtualBoxAPI.xml	(revision 73276)
@@ -1,25 +1,38 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-  "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
 <chapter id="VirtualBoxAPI">
-  <title>VirtualBox programming interfaces</title>
 
-  <para>VirtualBox comes with comprehensive support for third-party
-  developers. The so-called "Main API" of VirtualBox exposes the entire
-  feature set of the virtualization engine. It is completely documented and
-  available to anyone who wishes to control VirtualBox programmatically.
+  <title>VirtualBox Programming Interfaces</title>
+
+  <para>
+    VirtualBox comes with comprehensive support for third-party
+    developers. The so-called "Main API" of VirtualBox exposes the
+    entire feature set of the virtualization engine. It is completely
+    documented and available to anyone who wishes to control VirtualBox
+    programmatically.
   </para>
 
-  <para>The Main API is made available to C++ clients through COM (on Windows
-  hosts) or XPCOM (on other hosts). Bridges also exist for SOAP, Java and
-  Python.</para>
+  <para>
+    The Main API is made available to C++ clients through COM on Windows
+    hosts or XPCOM on other hosts. Bridges also exist for SOAP, Java and
+    Python.
+  </para>
 
-  <para>All programming information (documentation, reference information,
-  header and other interface files as well as samples) have been split out to
-  a separate <emphasis role="bold">Software Development Kit (SDK),</emphasis>
-  which is available for download from <ulink type=""
-  url="http://www.virtualbox.org">http://www.virtualbox.org</ulink>. In
-  particular, the SDK comes with a "Programming Guide and Reference" in PDF
-  format, which contains, among other things, the information that was
-  previously in this chapter of the User Manual.</para>
+  <para>
+    All programming information such as documentation, reference
+    information, header and other interface files, as well as samples
+    have been split out to a separate <emphasis role="bold">Software
+    Development Kit (SDK)</emphasis>. The SDK is available for download
+    from
+    <ulink 
+  url="http://www.virtualbox.org">http://www.virtualbox.org</ulink>.
+    In particular, the SDK comes with a Programming Guide and Reference
+    manual in PDF format. This manual contains, among other things, the
+    information that was previously in this chapter of the User Manual.
+  </para>
+
 </chapter>
Index: /trunk/doc/manual/ent-vbox-product.xml
===================================================================
--- /trunk/doc/manual/ent-vbox-product.xml	(revision 73276)
+++ /trunk/doc/manual/ent-vbox-product.xml	(revision 73276)
@@ -0,0 +1,1 @@
+<trademark class="registered">Oracle</trademark> VM <trademark class="registered">VirtualBox</trademark>
Index: /trunk/doc/manual/user_ChangeLogImpl.xml
===================================================================
--- /trunk/doc/manual/user_ChangeLogImpl.xml	(revision 73275)
+++ /trunk/doc/manual/user_ChangeLogImpl.xml	(revision 73276)
@@ -28,5 +28,5 @@
                            So, we use chapter and xpointer="xpointer(/chapter/)" with xi:include. -->
 
-   <sect1>
+  <sect1>
     <title>Version 5.3.0 (2018-xx-xx)</title>
 
@@ -41,6 +41,5 @@
 
     </itemizedlist>
-
-    <para>In addition, the following items were fixed and/or added:</para>
+  <para>In addition, the following items were fixed and/or added:</para>
 
     <itemizedlist>
@@ -53,10 +52,10 @@
       <listitem>
         <para>Guest Control: various new APIs and features were implemented
-          (see SDK documentation for more)</para>
-      </listitem>
-
-      <listitem>
+        (see SDK documentation for more)</para>
+      </listitem>
+
+    <listitem>
         <para>Networking: Added a workaround for older guests which do not enable
-          bus mastering for the virtio PCI device</para>
+        bus mastering for the virtio PCI device</para>
       </listitem>
 
@@ -73,6 +72,6 @@
 
       <listitem>
-        <para>GUI: fixed occasional screen corruption when host screen
-          resolution is changed</para>
+        <para>GUI: fixed occasional screen corruption when host screen resolution
+          is changed</para>
       </listitem>
 
@@ -432,5 +431,5 @@
       </listitem>
 
-      <listitem>
+    <listitem>
         <para>Audio: fixed playback with ALSA backend (5.1.28 regression)</para>
       </listitem>
Index: /trunk/src/VBox/Runtime/common/fs/isomakercmd-man.xml
===================================================================
--- /trunk/src/VBox/Runtime/common/fs/isomakercmd-man.xml	(revision 73275)
+++ /trunk/src/VBox/Runtime/common/fs/isomakercmd-man.xml	(revision 73276)
@@ -22,5 +22,5 @@
     terms and conditions of either the GPL or the CDDL or both.
  -->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <refentry id="viso" lang="en">
 
