Add a new Xen section to the Virtualization chapter of the handbook

[bcr]

Summary

I converted the information in the FreeBSD Wiki and Xen's own page into a new section describing how to create a Dom0 machine and a FreeBSD Dom0.

I've tested it (this is basically a writeup of my experiences) on my own machines and took the example output and configs from there. This still needs some technical review (technical terms, descriptions, etc.) and language love. Especially section 21.8.1. is a bit short right now.

Much more could be added (i.e. running on a shared storage do live-migrations), but I have not tested that yet. People can get started with the instructions provided here and we can add those points later.

A rendered version of the output can be found here: https://people.freebsd.org/~bcr/virtualization-host-xen.html

Test Plan

1. Apply the attached patch on top of your doc tree
2. build the handbook
3. Review irtualization-host-xen.html in a browser of your choice

[lifanov]

en_US.ISO8859-1/books/handbook/virtualization/chapter.xml

1619 ↗

(On Diff #28464)

This amount is subtracted from the hypervisor's available memory, not memory of dom0. In the above loader example, dom0 is itself virtualized and provisioned 2048M.

[bcr]

Address lifanov's comment.

[royger]

Thanks you very much! The handbook looks fantastic, only some minor comments.

en_US.ISO8859-1/books/handbook/virtualization/chapter.xml

1394 ↗

(On Diff #28503)

s/domU/DomU (since Dom0 has the first capital 'D'.

1407 ↗

(On Diff #28503)

Although Xen is capable of PCI-passthrough (that includes GPU passthrough), this is not yet supported by the mode in which FreeBSD uses Xen. I would recommend that this paragraph is hidden until this is fixed.

1483 ↗

(On Diff #28503)

The example is actually giving Dom0 2GB (2048M) or RAM, not 8GB.

1506 ↗

(On Diff #28503)

xendriverdomain must not be enabled for Dom0, this is only to be used by DomUs acting as driver domains.

1523 ↗

(On Diff #28503)

If you use autobridge_*, do you still need the ifconfig_bridge0="addm igb0" (as opposed to ifconfig_bridge0="SYNCDHCP")?

1585 ↗

(On Diff #28503)

I would write this as:

vif = [ 'mac=00:16:3E:74:34:32,bridge=bridge0' ]

1605 ↗

(On Diff #28503)

"For CPUs that have virtualization extensions, this means..."

1613 ↗

(On Diff #28503)

The name is mandatory.

1624 ↗

(On Diff #28503)

"The number of virtual CPUs..." sounds better IMHO

1626 ↗

(On Diff #28503)

That's not true, Xen supports CPU overcommitting (having more virtual CPUs that physical CPUs), although the performance sucks for obvious reasons. I would write:

"For performance reasons, it is not recommended to create guests with a number of virtual CPUs greater than the total number of physical CPUs available on the system".

1632 ↗

(On Diff #28503)

I would add:

The mac parameter contains the MAC address used by the virtual network interface. This parameter is optional, if no MAC is provided Xen will generate a random one.

[bcr]

@royger: Thanks for the feedback. I've attached a new diff that should address all your comments. Specifically:

• commented out the parts about passthrough
• removed the xendriverdomain line
• changed the ifconfig_bridge0=SYNCDHCP line (it works like you said)
• all occurances of domU are now renamed to DomU to be consistent.

Additionally, I added an authorgroup entry and removed the bits about Xen not supported on FreeBSD at the beginning of the (newly added) Xen section, since that is no longer true.

[wblock]

/home/bcr/dochead/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml

1373 ↗

(On Diff #28560)

For those of us who can't recall the difference in type 1 and others, a link to a definition here would be nice. Wikipedia usually has decent definition pages.

1374 ↗

(On Diff #28560)

links for DomU and "Amazon EC2" definitions would be nice.

1379 ↗

(On Diff #28560)

This paragraph is pretty complicated, with a lot of asides. I think it is saying that FreeBSD can support Xen VMs since 8.0 and can be run in Xen since 11.0.

1381 ↗

(On Diff #28560)

s/baremetal/bare-metal/

1385 ↗

(On Diff #28560)

Eliminate the pause by redoing the second part of the sentence:

access the underlying physical hardware, making it a

1386 ↗

(On Diff #28560)

s/high performance/high-performance/

1387 ↗

(On Diff #28560)

I don't understand what "That way, it is able to use device drivers for accessing the disk controllers and network adapters." is trying to say.

1389 ↗

(On Diff #28560)

"The Xen management tools to manage and control the Xen hypervisor are also used by the Dom0."

Used how, or for what?

1393 ↗

(On Diff #28560)

"perform(s) the role of individual guest VMs." is unclear. Maybe

...while the DomU is where individual guest VMs are run.

1398 ↗

(On Diff #28560)

This requires a CPU, chipset, and BIOS with VT-D support and might require extra patches or not work with all graphics cards.

1404 ↗

(On Diff #28560)

s/PCI-passthrough/PCI passthrough/

...PCI passthrough to  give a DomU guest VM full, direct access to a PCI device like a NIC, disk controller, or sound card.

1409 ↗

(On Diff #28560)

Not sure if all the instances of Xen should be replaced with &xen;.

1435 ↗

(On Diff #28560)

The "including" part is an aside. Is it important to the reader to know what the metapackage contains? Is it important to them to know that it is a metapackage? We do not use that term widely elsewhere.

I suspect this can just say

<package>emulators/xen</package> is supported...

Although it's a little unclear what "is supported" means here. Works with?

1439 ↗

(On Diff #28560)

Passive -> active: s/will assume/assumes/

1440 ↗

(On Diff #28560)

Passive -> active: s/will be accessed/is accessed/

1444 ↗

(On Diff #28560)

Passive -> active and imperative:

<para>Install <package>emulators/xen</package>:</para>

1449 ↗

(On Diff #28560)

The introductory part can be skipped, we can assume it has been installed successfully or the reader will not proceed.
"a couple" is vague.

Configuration files must be edited to prepare the host

1452 ↗

(On Diff #28560)

<filename>/etc/sysctl.conf</filename> disables

1454 ↗

(On Diff #28560)

The last part is not needed:

An entry in <filename>/etc/sysctl.conf</filename> disables the limit on how many pages of memory are allowed to be wired:</para>

But why is that needed?

1459 ↗

(On Diff #28560)

s/ and/,/

1464 ↗

(On Diff #28560)

Passive -> active: s/make sure to/run/

1465 ↗

(On Diff #28560)

s/;//

Looks like a typo rather than a splice.

1472 ↗

(On Diff #28560)

Passive -> active:

Add an entry for the Xen console to

1478 ↗

(On Diff #28560)

"in terms of" is weird. Maybe

Selecting a Xen kernel in <filename>/boot/loader.conf</filename> activates the Dom0.

1479 ↗

(On Diff #28560)

s/some//

1480 ↗

(On Diff #28560)

s/to run/for/

1492 ↗

(On Diff #28560)

s/being//

1496 ↗

(On Diff #28560)

Should permissions be set on this directory for security?

1498 ↗

(On Diff #28560)

Avoid the possessive: s/its own/a/

1504 ↗

(On Diff #28560)

Activate the xencommons service at system start:</para>

<literal> is probably the wrong tag for the service name. Not sure what to use there.

1510 ↗

(On Diff #28560)

s/The above/These/

1513 ↗

(On Diff #28560)

s/that/which/

1515 ↗

(On Diff #28560)

Need to be clearer here: "with the host network interface name", or something like that.

1522 ↗

(On Diff #28560)

Be concise:

Restart the host to load the Xen kernel and start the Dom0.

1530 ↗

(On Diff #28560)

s/print/show/

1538 ↗

(On Diff #28560)

s/as/has/ maybe?

1539 ↗

(On Diff #28560)

s/in the running state/running/

1540 ↗

(On Diff #28560)

s/available//

1544 ↗

(On Diff #28560)

This last sentence isn't really doing anything useful. Maybe

DomU guest VMs can now be created.

1549 ↗

(On Diff #28560)

This title does not obviously say that it is about creating guest VMs.

1551 ↗

(On Diff #28560)

s/Domains/domains/

1552 ↗

(On Diff #28560)

s/logical/virtual/

1554 ↗

(On Diff #28560)

This is clunky. Maybe

Virtual disk storage for the DomU can be files created by &man.truncate.1;,
or ZFS volumes as described in <xref

1555 ↗

(On Diff #28560)

Don't use relative references ("the latter"):

In this example, a 20 GB ZFS volume is used.

1556 ↗

(On Diff #28560)

A VM is created with the ZFS volume, an ISO image, 1 GB of RAM, and two virtual CPUs.

1558 ↗

(On Diff #28560)

s/First, the/The/
s/using/with/

1570 ↗

(On Diff #28560)

The new DomU guest VM is defined in a file.  Some

1573 ↗

(On Diff #28560)

s/The following/This/

1575 ↗

(On Diff #28560)

s/our/this/

1581 ↗

(On Diff #28560)

The text says the VM has two vCPUs...

1592 ↗

(On Diff #28560)

s/The following/These/

1596 ↗

(On Diff #28560)

<para>Type of virtualization to use.  <literal>hvm</literal> refers to

What are the other possible values?

1599 ↗

(On Diff #28560)

machine.  Guest operating systems can run unmodified on CPUs with virtualization extensions, providing nearly the same performance as running on physical hardware.

1605 ↗

(On Diff #28560)

Name of this virtual machine to distinguish it from others running on the same Dom0.  Required.

1611 ↗

(On Diff #28560)

Quantity of RAM in megabytes to make available to the VM.

1613 ↗

(On Diff #28560)

Not clear how "the hypervisor's total available memory" is different from "the memory of the Dom0". Isn't the Dom0 the hypervisor?

1617 ↗

(On Diff #28560)

Number of virtual CPUs available to the guest VM.

1618 ↗

(On Diff #28560)

For best performance, do not create guests with more virtual CPUs than the number of physical CPUs on the host.

1625 ↗

(On Diff #28560)

Virtual network adapter.  This is the bridge connected to the network interface of the host.

1628 ↗

(On Diff #28560)

s/contains/is/
s/used by/set on/

1634 ↗

(On Diff #28560)

Full path to the disk, file, or ZFS volume of the disk storage for this VM.

1637 ↗

(On Diff #28560)

s/defintions/definitions/

Options and multiple disk definitions are separated by commas.

1642 ↗

(On Diff #28560)

Boot medium.

1650 ↗

(On Diff #28560)

Options controlling VNC connectivity to the

1651 ↗

(On Diff #28560)

s/These are (in order)/In order, these are/

1652 ↗

(On Diff #28560)

active VNC support, define IP address on which to listen, device node for the serial console, and the input method for precise positioning of the mouse and other input methods.
<literal>keymap> defines which keymap to use, and is <literal>english</literal> by default.

1662 ↗

(On Diff #28560)

Passive -> active: s/can be/is/

1669 ↗

(On Diff #28560)

s/needs to/must/

1677 ↗

(On Diff #28560)

s/DomU/guest VM/

1689 ↗

(On Diff #28560)

"hosts" should be possessive, except that's ugly.

start the VNC client, directing it to the main network address of the host or to the IP address defined on the <literal>vnclisten</literal> line of <filename>freebsd.cfg</filename>.

1696 ↗

(On Diff #28560)

The aside about commenting is disruptive.

Edit <filename>freebsd.cfg</filename>, removing the line with the
<literal>cdrom</literal> definition or commenting it out by inserting a
<literal>#</literal> character at the beginning of the line.

[bcr]

@wblock: Wow, thanks for the tremendous feedback. I went over your suggestions and comments and updated the diff to reflect the changes I made.

[bcr]

Mark items as done.

[bcr]

If no one has any further feedback, I will commit this by the end of the week. There is still time for people to review and comment.