Update bhyve chapter with note on CPU UG feature & zfs vol examples

[sd_beastie.io]

Summary

To run a bhyve guest with multiple vCPUs, the "VMX unrestriced mode" or "unrestricted guest privileges (UG)" mode is required from the CPU. The current section in the handbook doesn't mention this and may throw new folks off as they are getting started with FreeBSD and bhyve. See Peter Grehan's note in this thread: http://freebsd.1045724.n5.nabble.com/VM-unrestricted-guest-capability-required-td5953993.html

Also, since ZFS is getting quite popular within the FreeBSD community, it seems fit to show the user how to create a zfs volume for use with bhyve.

This change adds a couple sentences in the intro paragraph about the required CPU UG feature if they are planning on creating vms with multiple vCPUS and also adds a section titled "Using ZFS with Bhyve Guests".

Comments, feedback welcome. Happy to change as you guys see fit.

Test Plan

Ran igor
Build all of htdocs

[sd_beastie.io]

Removed igor cleanup for the rest of the file from this review, will submit in a separate review. Ran 'igor -z' for these changes.

[allanjude]

chapter.xml

1522 ↗

(On Diff #6983)

use the <replaceable> tags around anything the user is supposed to change, (16G and zroot/vdisk0)

1527 ↗

(On Diff #6983)

replaceable tags on the zvol path

1556 ↗

(On Diff #6983)

seems my original version missed the replaceable tag on ./linux.img

[wblock]

Don't panic.

chapter.xml

1331 ↗

(On Diff #6983)

When the content of a <link> is the same as the href, it can just be left empty:

<link xlink:href="http://something"></link>

or the even shorter form

<link xlink:href="http://something"/>

See https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/docbook-markup-links.html#idp60797136

1515 ↗

(On Diff #6983)

Reserved words should not be capitalized in titles. There is disagreement over how this should be handled, but I would use the man page reference here. Also, "ZFS" is an acronym:

<title>Using <acronym>ZFS</acronym> with &man.bhyve.8; Guests</title>

1517 ↗

(On Diff #6983)

This is kind of a confusing sentence. Really, I think it is trying to say:

<para>If the host machine has ZFS, using ZFS volumes

(Just an idea, you might have a better way to say that.)
(And add <acronym> tags...)

1518 ↗

(On Diff #6983)

"May" usually means permission. "Might" or "can" are usually better for probability. "Can" is good here:

instead of disk image files can provide significant

1519 ↗

(On Diff #6983)

<acronym> tags...

1522 ↗

(On Diff #6983)

The indent might not be right, but Phabricator is easily confused by that, so it's hard to tell. <screen> should be indented the same as the <para> tag above it.

Also, some of those parameters should have <replaceable> tags, showing that they are values the user would choose for themselves:

zfs create -V<replaceable>16G</replaceable> -o volmode=dev <replaceable>zroot/vdisk0</replaceable>

1524 ↗

(On Diff #6983)

"Once created" and "using bhyve" are kind of givens, here. Maybe just reword:

When starting the guest <acronym>VM</acronym>, specify the <acronym>ZFS</acronym> volume as the disk drive:

(Yes, "VM" is an acronym too. Pretend I noticed that above.)

1527 ↗

(On Diff #6983)

Indentation might be off. More of the parameters should be specified as replaceable (particularly the name of the ZFS volume).

Phabricator is probably "helping" with the line wrap after the backslash, so it's probably right but looks wrong.

1551 ↗

(On Diff #6983)

"The example below" is not terrible, but even better is to avoid the need to say that at all:

The &linux; guest created in the previous example can be started with the console redirected to the null modem:

1553 ↗

(On Diff #6983)

This is kind of confusing, especially when it is shown before the example. "Similarly" is also vague, meaning "like this, but different", so the reader (me, in this case) immediately asks "different how?"

Maybe make the paragraph leading up to this example more general. "Consoles of &os; and &linux; <acronym>VM</acronym> guests can be redirected to the null modem device. To redirect the console of the &linux; guest created in the previous example:

(this replaces the earlier two sentences, if you see what I mean)

1556 ↗

(On Diff #6983)

Same warning about <replaceables>, be consistent with what was shown earlier.

[sd_beastie.io]

chapter.xml

1515 ↗

(On Diff #6983)

To match what the rest of the document is doing, perhaps surrounding lowercased bhyve with the <application /> element might be reasonable. Similar to the section header.

1553 ↗

(On Diff #6983)

Removing my change here as it seems its already quite obvious.

[sd_beastie.io]

Rev 1: fixes based on review.

[wblock]

Could you update the diff again? Unless the path is the same, Phabricator loses its tiny little mind. It thinks these are from different files because the paths are chapter.xml versus virtualization/chapter.xml.

Also, remember to include context:

svn diff --diff-cmd=diff -x -U999999 virtualization/chapter.xml

Thanks!

[sd_beastie.io]

Full diff attached

[wblock]

Much better! I did not check the command line parameters, Allan is much more familiar with those.

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

1327

Needs a comma after E7:

i3/i5/i7 and &intel;&nbsp; &xeon; E3/E5/E7, support these

1332

s/Third/third/

1333

The "The easiest" sentence is backwards. First, tell the reader where to look, then tell them what to look for:

(leaving out markup for clarity)

The easiest way to tell if a processor will support bhyve is to run dmesg or look in /var/run/dmesg.boot for the...

1517

Nice!

[sd_beastie.io]

Rev 2 diff attached

[sd_beastie.io]

Switch to virtio-blk instead of ahci-hd for performance reasons.

[allanjude]

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

1475–1476

bhyve has deprecated the -I flag, and we should remove it from the examples (it only applied to 10.0)

1555–1557

lost a line return here?

[sd_beastie.io]

Rev3 diff attached

[sd_beastie.io]

Remove tabs/spaces from newlines in screen sections.

[allanjude]

the new zfs and bhyve commands look correct to me.

[sd_beastie.io]

Add one tab for command continuations.

[sd_beastie.io]

Update command continuation with 4 spaces on new line

[sd_beastie.io]

PR updated with latest patch (https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=201578)

[wblock]

Fun fact: a scallop can have over a hundred eyes.