Skip to content

Commit

Permalink
[documentation][virtualization]: Fix links
Browse files Browse the repository at this point in the history 
 * Do not use xref since it does not create working links in all outputs.
 * Point to the proper X installation subparagraph.

Fixes:	3de85d7
  • Loading branch information
@fernape
fernape committed Sep 29, 2024
1 parent fc928e7 commit f02284b
Showing 1 changed file with 31 additions and 20 deletions.
51 changes: 31 additions & 20 deletions documentation/content/en/books/handbook/virtualization/_index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -545,7 +545,9 @@ Test the installation by running the following command as a non-root user:
% qemu
....
This brings up a window with QEMU actively trying to boot from hard disk, floppy disk, DVD/CD, and PXE.
Nothing has been set up yet, so the command will produce several errors and end with "No bootable device" as shown in Figure xref:qemu-nullboot[{counter:figure}].
Nothing has been set up yet, so the command will produce several errors and end
with "No bootable device" as shown in
crossref:virtualization[qemu-nullboot,Figure {counter:figure}].
However, it does show that the QEMU software has been installed correctly.

[[qemu-nullboot]]
Expand Down Expand Up @@ -674,7 +676,8 @@ This script uses the QEMU raw disk format.
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 crossref:virtualization[qemu-newboot-loader-menu,Figure {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]]
Expand All @@ -683,7 +686,8 @@ image::qemu-freebsd02.png[The FreeBSD loader menu.]

[TIP]
====
If the mouse is clicked in the QEMU console window, QEMU will “grab” the mouse as shown in Figure xref:qemu-grab[{counter:figure}].
If the mouse is clicked in the QEMU console window, QEMU will “grab” the mouse
as shown in crossref:virtualization[qemu-grab,Figure {counter:figure}].
Type kbd:[Ctl]+kbd:[Alt]+kbd:[G]” to release the mouse.
====

Expand Down Expand Up @@ -761,7 +765,7 @@ If there are strict firewall rules on the host, consider adding or modifying rul
[[qemu-setting-up-x-windows]]
==== Using the X Window System

crossref:x11[x11,Installing Xorg] describes how to set up the `X Window` system.
crossref:x11[x-install,Installing Xorg] describes how to set up the `X Window` system.
Refer to that guide for initial `X Window` setup then consult crossref:desktop[desktop,Desktop Environments] on how to set up a complete desktop.

This section demonstrates use of the XFCE desktop.
Expand All @@ -773,7 +777,8 @@ Once the installation is complete, login as a regular user, then type:
% startx
....

The XFCE4 window manager should start up and present a functioning graphical desktop as in Figure xref:qemu-two-qemu[{counter:figure}].
The XFCE4 window manager should start up and present a functioning graphical
desktop as in crossref:virtualization[qemu-two-qemu,Figure {counter:figure}].
On initial startup, it may take up to a minute to display the desktop.
See the documentation at the link:https://www.xfce.org[XFCE website] for usage details.
[[qemu-two-qemu]]
Expand All @@ -794,7 +799,7 @@ The QEMU window functions as a full FreeBSD console, and is capable of running m

To switch to another virtual console, click into the QEMU window and type kbd:[Alt+F2] or kbd:[Alt+F3].
FreeBSD should switch to another virtual console.
Figure xref:qemu-console-ttyv3[{counter:figure}] shows the "left" VM displaying the virtual console on `ttyv3`.
crossref:virtualization[qemu-console-ttyv3,Figure {counter:figure}] shows the "left" VM displaying the virtual console on `ttyv3`.
[[qemu-console-ttyv3]]
.Switching to Another Virtual Console in the QEMU Window
image::qemu-freebsd05.png[Switching to Another Virtual Console in the QEMU Window]
Expand All @@ -812,7 +817,7 @@ Check the window manager or desktop manager documentation for details.
Another feature of the QEMU window is the `View` menu and the Zoom controls.
The most useful is `Zoom to Fit`.
When this menu selection is clicked, it is then possible to resize the QEMU window by clicking the window corner controls and resizing the window.
Figure xref:qemu-zoom-to-fit[{counter:figure}] shows the effect of resizing the "left" window while in graphics mode.
crossref:virtualization[qemu-zoom-to-fit,Figure {counter:figure}] shows the effect of resizing the "left" window while in graphics mode.

[[qemu-zoom-to-fit]]
.Using the View Menu `Zoom to Fit` Option
Expand Down Expand Up @@ -874,7 +879,7 @@ echo
.Enabling a Serial Port over TCP
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.
In crossref:virtualization[qemu-notes-on-serial-console,Figure {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 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.
Expand Down Expand Up @@ -945,7 +950,7 @@ qemu-img create -f qcow2 -o preallocation=full,lazy_refcounts=on sparc64.qcow2 1
....

. Use the script below for the new Sparc64 architecture.
As with above example, run the script, then start a new session and `telnet` to localhost on the port indicated:
As with the above example, run the script, then start a new session and `telnet` to localhost on the port indicated:
+
[.programlisting]
....
Expand Down Expand Up @@ -981,7 +986,8 @@ There is no graphical interface.
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]

If everything is set correctly, the system will boot as shown in Figure xref:qemu-sparc64-boot-cdrom-installation[{counter:figure}].
If everything is set correctly, the system will boot as shown in
crossref:virtualization[qemu-sparc64-boot-cdrom-installation,Figure {counter:figure}].
[[qemu-sparc64-boot-cdrom-installation]]
.QEMU Booting OpenBSD 6.8 Sparc64 from CDROM During User Mode Emulation
image::qemu-freebsd08.png[]
Expand All @@ -996,7 +1002,7 @@ However, the underlying architecture of the guest is Sparc64, not x86_64.
====
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].
crossref:virtualization[qemu-sparc64-login-to-installed-system,Figure {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 Emulation
Expand Down Expand Up @@ -1030,7 +1036,8 @@ When using a graphical desktop environment, the simplest way to use the QEMU mon
...
....

This results in a new prompt `(qemu)` in the terminal window as shown in Figure xref:qemu-monitor-operation[{counter:figure}].
This results in a new prompt `(qemu)` in the terminal window as shown in
crossref:virtualization[qemu-monitor-operation,Figure {counter:figure}].

[[qemu-monitor-operation]]
.QEMU Monitor Prompt and "stop" Command
Expand All @@ -1050,7 +1057,7 @@ To add a new disk to a running VM, the disk needs to be prepared as above:
% qemu-img create -f raw new10G.img 10G
....

Figure xref:qemu-add-new-disk-figure[{counter:figure}] shows the monitor command sequence needed to add a new disk in the VM.
crossref:virtualization[qemu-add-new-disk-figure,Figure {counter:figure}] shows the monitor command sequence needed to add a new disk in the VM.
Once the device has been added with the `device_add` command in the monitor it shows up on the FreeBSD system console shown in the lower part of the figure.
The disk can be configured as needed.

Expand Down Expand Up @@ -1115,7 +1122,7 @@ During the "Prepare the environment" step, in a separate virtual console (ttyv1)
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 session on ttyv1.
crossref:virtualization[qemu-using-monitor-snapshots,Figure {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]]
Expand All @@ -1135,7 +1142,7 @@ QEMU 9.0.1 monitor - type 'help' for more information
Next, in the main console window, install a package, such as man:zip[1] which has no dependencies.
Once that completes, renter the monitor and create another snapshot (`snap1_pkg+zip`).

Figure xref:qemu-after-monitor-snapshots[{counter:figure}] shows the results of the above commands and the output of the `info shapshots` command.
crossref:virtualization[qemu-after-monitor-snapshots,Figure {counter:figure}] shows the results of the above commands and the output of the `info shapshots` command.

[[qemu-after-monitor-snapshots]]
.QEMU Using Monitor Commands for Snapshots
Expand Down Expand Up @@ -1164,7 +1171,8 @@ Any other programs running at the time the snapshot was taken should be unaffect
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.
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
crossref:virtualization[qemu-examine-monitor-snapshots,Figure {counter:figure}].

[[qemu-examine-monitor-snapshots]]
.QEMU Using man:qemu-img[1] to Examine Snapshots
Expand Down Expand Up @@ -1201,7 +1209,9 @@ This configuration includes a `-drive` specification with the `id=usbstick`, raw
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}].
When the system is booted, FreeBSD will recognize a USB hub, add the attached
USB device, and assign it to `da0` as shown in
crossref:virtualization[qemu-usb-internal-storage,Figure {counter:figure}].

[[qemu-usb-internal-storage]]
.QEMU Created USB Hub and Mass Storage Device
Expand All @@ -1220,7 +1230,7 @@ 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 QEMU monitor commands:
The upper part of crossref:virtualization[qemu-usb-passthrough,Figure {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.
Expand All @@ -1232,9 +1242,10 @@ Use the two values shown by the `info usbhost` command in the `device_add` step
.QEMU Monitor Commands to Access a USB Device on the Host
image::qemu-freebsd18.png[]

As before, once `device_add` completes, the FreeBSD kernel recognizes a new USB device, as shown in the lower half of the Figure.
As before, once `device_add` completes, the FreeBSD kernel recognizes a new USB device, as shown in the lower half of the .

Using the new device is shown in Figure xref:qemu-usb-passthrough2[{counter:figure}].
Using the new device is shown in
crossref:virtualization[qemu-usb-passthrough2,Figure {counter:figure}].

[[qemu-usb-passthrough2]]
.Using the Host USB Device via Passthrough
Expand Down

0 comments on commit f02284b

Please sign in to comment.