Page MenuHomeFreeBSD

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

Authored by sd_beastie.io on Jul 15 2015, 9:57 PM.

Details

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

Diff Detail

Repository
rD FreeBSD doc repository - subversion
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

sd_beastie.io retitled this revision from to Update bhyve chapter with note on CPU UG feature & zfs vol examples.
sd_beastie.io updated this object.
sd_beastie.io edited the test plan for this revision. (Show Details)
sd_beastie.io added reviewers: wblock, allanjude.
sd_beastie.io set the repository for this revision to rD FreeBSD doc repository - subversion.
sd_beastie.io added a project: Doc Committers.
sd_beastie.io updated this object.

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

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

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 added inline comments.
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 edited the test plan for this revision. (Show Details)
sd_beastie.io edited edge metadata.
sd_beastie.io marked 2 inline comments as done.

Rev 1: fixes based on review.

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!

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
1328 ↗(On Diff #7023)

Needs a comma after E7:

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

1333 ↗(On Diff #7023)

s/Third/third/

1334 ↗(On Diff #7023)

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 ↗(On Diff #7023)

Nice!

sd_beastie.io marked 4 inline comments as done.

Rev 2 diff attached

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

en_US.ISO8859-1/books/handbook/virtualization/chapter.xml
1475 ↗(On Diff #7032)

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

1554 ↗(On Diff #7032)

lost a line return here?

sd_beastie.io marked 2 inline comments as done.

Rev3 diff attached

sd_beastie.io removed rD FreeBSD doc repository - subversion as the repository for this revision.

Remove tabs/spaces from newlines in screen sections.

allanjude edited edge metadata.

the new zfs and bhyve commands look correct to me.

This revision is now accepted and ready to land.Jul 20 2015, 5:26 PM
sd_beastie.io edited edge metadata.
sd_beastie.io set the repository for this revision to rD FreeBSD doc repository - subversion.

Add one tab for command continuations.

This revision now requires review to proceed.Jul 20 2015, 6:32 PM
sd_beastie.io edited edge metadata.

Update command continuation with 4 spaces on new line

wblock edited edge metadata.

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

This revision is now accepted and ready to land.Jul 20 2015, 7:45 PM
This revision was automatically updated to reflect the committed changes.