diff --git a/documentation/content/en/books/handbook/virtualization/_index.adoc b/documentation/content/en/books/handbook/virtualization/_index.adoc --- a/documentation/content/en/books/handbook/virtualization/_index.adoc +++ b/documentation/content/en/books/handbook/virtualization/_index.adoc @@ -531,7 +531,7 @@ The package installation includes several dependencies. Once the installation is complete, create a link to the host version of QEMU that will be used most often. -If you are on an Intel(TM) or AMD(TM) 64 bit system that will be: +If the host is an Intel(TM) or AMD(TM) 64 bit system that will be: [source,shell] .... @@ -630,8 +630,8 @@ + . Set up networking for both virtual machines with the following commands. In this example the host network interface is `em0`. -If necessary, change it to fit the interface for your host system. -This must be done after every host machine restart to enble the QEMU guest VMs to communicate. +If necessary, change it to fit the interface for the host system. +This must be done after every host machine restart to enable the QEMU guest VMs to communicate. + [source,shell] .... @@ -675,7 +675,7 @@ Save the above into a file (for example `left.sh`) and simply run: % `/bin/sh left.sh` ==== -Qemu will start up a virtual machine in a separate window and boot the FreeBSD iso as shown in Figure xref:qemu-newboot-loader-menu[{counter:figure}]. +QEMU will start up a virtual machine in a separate window and boot the FreeBSD iso as shown in Figure xref:qemu-newboot-loader-menu[{counter:figure}]. All command options such as `-cpu` and `-boot` are fully described in the QEMU man page man:qemu[1]. [[qemu-newboot-loader-menu]] @@ -701,8 +701,10 @@ During the installation there are several points to note: -* Select to use UFS as the filesystem. ZFS does not perform well with small memory sizes. -* For networking use DHCP. If desired, configure IPv6 if supported by the local LAN. +* Select to use UFS as the filesystem. +ZFS does not perform well with small memory sizes. +* For networking use DHCP. +If desired, configure IPv6 if supported by the local LAN. * When adding the default user, ensure they are a member of the *wheel* group. Once the installation completes, the virtual machine reboots into the newly installed FreeBSD image. @@ -732,7 +734,7 @@ This completes the setup of the "left" VM. -To install the "right" VM, run the following script under sudo. +To install the "right" VM, run the following script under man:sudo[8]. This script has the modifications needed for tap1, format=qcow2, the image filename, the MAC address, and the terminal window name. If desired, include the "-runas" parameter as described in the above note. @@ -753,7 +755,7 @@ .... Once the installation is complete, the "left" and "right" machines can communicate with each other and with the host. -If there are strict firewall rules on the host, consider adding or modifying rules to allow the bridge and tap dvices to communicate with each other. +If there are strict firewall rules on the host, consider adding or modifying rules to allow the bridge and tap devices to communicate with each other. [[qemu-usage-tips]] === Usage Tips @@ -810,7 +812,7 @@ [TIP] ==== -Your current desktop manager or window manager may be already setup for another function with the kbd:[Alt+F1], kbd:[Alt+F2] key sequences. +The host current desktop manager or window manager may be already setup for another function with the kbd:[Alt+F1], kbd:[Alt+F2] key sequences. If so, try typing kbd:[Ctl+Alt+F1], kbd:[Ctl+Alt+F2], or some other similar key combination. Check the window manager or desktop manager documentation for details. ==== @@ -884,9 +886,9 @@ image::qemu-freebsd07.png[] In Figure xref:qemu-left-serial-port[{counter:figure}], the serial port is redirected to a TCP port on the host system at VM startup and the QEMU monitor waits (`wait=on`) to activate the guest VM until a man:telnet[1] connection occurs on the indicated localhost port. -After receiving a connection from a separate session, the FreeBSD system starts booting and recognizes the console directive in [.filename]#/boot/loader.conf#. -It then starts up a serial console. -The QEMU monitor detects this and directs the necessary character I/O on that serial port to the telnet sesson on the host. +After receiving a connection from a separate session, the FreeBSD system starts booting and looks for a console directive in [.filename]#/boot/loader.conf#. +With the directive "console=comconsole", FreeBSD starts up a console session on a serial port. +The QEMU monitor detects this and directs the necessary character I/O on that serial port to the telnet session on the host. The system boots and once finished, login prompts are enabled on the serial port (`ttyu0`) and on the console (`ttyv0`). It is important to note that the this serial redirect over TCP takes place outside the virtual machine. @@ -925,7 +927,7 @@ * Setting up a new QEMU script with the new architecture * Performing the install -In the following procedure a copy of OpenBSD 6.8 SPARC64 sofware is used for this QEMU User Mode Emulation exercise. +In the following procedure a copy of OpenBSD 6.8 SPARC64 software is used for this QEMU User Mode Emulation exercise. [NOTE] ==== @@ -954,7 +956,7 @@ .... . Use the script below for the new Sparc64 architecture. -As with above example, run the script, then start a new session and `telnet` to locahost on the port indicated: +As with above example, run the script, then start a new session and `telnet` to localhost on the port indicated: + [.programlisting] .... @@ -988,12 +990,11 @@ There is no graphical interface. * Networking is not set up through the man:tap[4] / man:if_bridge[4] combination. This example uses a separate method of QEMU networking known as "Serial Line Internet Protocol" (SLIRP), sometimes referred to as "User Mode Networking". -Documentation on this and other QEMU networking methods is here: -link:https://wiki.qemu.org/Documentation/Networking[QEMU Networking Documentation] +Documentation on this and other QEMU networking methods is here: link:https://wiki.qemu.org/Documentation/Networking[QEMU Networking Documentation] If everything is set correctly, the system will boot as shown in Figure xref:qemu-sparc64-boot-cdrom-installation[{counter:figure}]. [[qemu-sparc64-boot-cdrom-installation]] -.QEMU Booting OpenBSD 6.8 Sparc64 from CDROM During User Mode Emualation +.QEMU Booting OpenBSD 6.8 Sparc64 from CDROM During User Mode Emulation image::qemu-freebsd08.png[] Once the system is installed, modify the script and change the boot parameter to `-boot c`. @@ -1004,12 +1005,12 @@ [TIP] ==== -If you have halted the Sparc64 system and find yourself at the OpenBios console prompt `0 >`, enter `power-off` to exit the system. +If the system is halted at the OpenBios console prompt `0 >`, enter `power-off` to exit the system. ==== Figure xref:qemu-sparc64-login-to-installed-system[{counter:figure}] shows a root login to the installed system and running man:uname[1]. [[qemu-sparc64-login-to-installed-system]] -.QEMU Booting from CDROM During User Mode Emualation +.QEMU Booting from CDROM During User Mode Emulation image::qemu-freebsd09.png[] [[qemu-using-qemu-monitor]] @@ -1024,7 +1025,8 @@ * Gather information about the state of the VM and devices * Change device settings on the fly -and many other operations. +As well as many other operations. + The most common uses of the monitor are to examine the state of the VM, and to add, delete, or change devices. Some operations such as migrations are only available under hypervisor accelerators such as KVM, Xen, etc. and are not supported on FreeBSD hosts. @@ -1121,10 +1123,10 @@ . Observe that the restored VM does not have any packages During the "Prepare the environment" step, in a separate virtual console (ttyv1), an editing session with man:vi[1] is initiated simulating user activity. -Additional programs may be be started if desired. +Additional programs may be started if desired. The snapshot should account for the state of all applications running at the time the snapshot is taken. -Figure xref:qemu-using-monitor-snapshots[{counter:figure}] shows the newly installed FreeBSD system with no packages, and separately, the editing sesssion on ttyv1. +Figure xref:qemu-using-monitor-snapshots[{counter:figure}] shows the newly installed FreeBSD system with no packages, and separately, the editing session on ttyv1. The man:vi[1] editor is currently in `insert` mode with the typist typing the word "broadcast". [[qemu-using-monitor-snapshots]] @@ -1173,7 +1175,7 @@ The above steps show how a snapshot can be taken, the system modified, and then "rolled back" by restoring the previous snapshot. By default QEMU stores snapshot data in the same file as the image. -You can view the list of snapshots with man:qemu-img[1] as shown below in Figure xref:qemu-examine-monitor-snapshots[{counter:figure}]. +View the list of snapshots with man:qemu-img[1] as shown below in Figure xref:qemu-examine-monitor-snapshots[{counter:figure}]. [[qemu-examine-monitor-snapshots]] .QEMU Using man:qemu-img[1] to Examine Snapshots @@ -1207,7 +1209,7 @@ .... This configuration includes a `-drive` specification with the `id=usbstick`, raw format, and an image file (must be created by man:qemu-img[1]). -The next line contains the `-device usb-ehci` specification for a USB EHCI controller, with `id=ehci`. +The next line contains the `-device usb-ehci` specification for a USB EHCI controller, with `id=ehci`. Finally, a `-device usb-storage` specification ties the above drive to the EHCI USB bus. When the system is booted, FreeBSD will recognize a USB hub, add the attached USB device, and assign it to `da0` as shown in Figure xref:qemu-usb-internal-storage[{counter:figure}]. @@ -1225,11 +1227,11 @@ QEMU USB passthrough support is listed as experimental in version 9.0.1 (Summer, 2024). However, the following steps show how a USB stick mounted on the host can be used by the guest VM. -For more information and examples, see: +For more information and examples, see: * link:https://www.qemu.org/docs/master/system/devices/usb.html[] -The upper part of Figure xref:qemu-usb-passthrough[{counter:figure}] shows the the QEMU monitor commands: +The upper part of Figure xref:qemu-usb-passthrough[{counter:figure}] shows the QEMU monitor commands: * `info usbhost` shows information about all USB devices on the host system. Find the desired USB device on the host system and note the two hexadecimal values on that line. @@ -1274,11 +1276,8 @@ === QEMU on FreeBSD Summary As noted above, QEMU works with several different hypervisor accelerators. -All the examples use in this section used the `Tiny Code Generator (tcg)` accelerator as that is the only supported accelerator on FreeBSD at present. -The list of supported -link:https://www.qemu.org/docs/master/system/introduction.html#virtualisation-accelerators[Virtualization Accelerators] -includes: +The list of link:https://www.qemu.org/docs/master/system/introduction.html#virtualisation-accelerators[Virtualization Accelerators] supported by QEMU includes: * `KVM` on Linux supporting 64 bit Arm, MIPS, PPC, RISC-V, s390x, and x86 * `Xen` on Linux as dom0 supporting Arm, x86 @@ -1287,6 +1286,8 @@ * `NetBSD Virutal Machine Monitor (nvmm)` on NetBSD supporting x86 * `Tiny Code Generator (tcg)` on Linux and other POSIX, Windows, MacOS supporting Arm, x86, Loongarch64, MIPS, PPC, s390x, and Sparc64. +All the examples in this section used the `Tiny Code Generator (tcg)` accelerator as that is the only supported accelerator on FreeBSD at present. + [[virtualization-host-bhyve]] == FreeBSD as a Host with bhyve