Date: Sun, 29 Sep 2024 17:05:55 GMT From: Fernando =?utf-8?Q?Apestegu=C3=ADa?= <fernape@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: f02284bf39 - main - [documentation][virtualization]: Fix links Message-ID: <202409291705.48TH5tgh000776@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by fernape: URL: https://cgit.FreeBSD.org/doc/commit/?id=f02284bf39162cb333e86b7bb1ca4e8e99268fb1 commit f02284bf39162cb333e86b7bb1ca4e8e99268fb1 Author: Fernando Apesteguía <fernape@FreeBSD.org> AuthorDate: 2024-09-29 17:03:43 +0000 Commit: Fernando Apesteguía <fernape@FreeBSD.org> CommitDate: 2024-09-29 17:03:43 +0000 [documentation][virtualization]: Fix links * Do not use xref since it does not create working links in all outputs. * Point to the proper X installation subparagraph. Fixes: 3de85d772f --- .../en/books/handbook/virtualization/_index.adoc | 51 +++++++++++++--------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/documentation/content/en/books/handbook/virtualization/_index.adoc b/documentation/content/en/books/handbook/virtualization/_index.adoc index 763a7ce62f..8c2cb783df 100644 --- a/documentation/content/en/books/handbook/virtualization/_index.adoc +++ b/documentation/content/en/books/handbook/virtualization/_index.adoc @@ -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]] @@ -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]] @@ -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. ==== @@ -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. @@ -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]] @@ -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] @@ -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 @@ -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. @@ -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] .... @@ -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[] @@ -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 @@ -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 @@ -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. @@ -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]] @@ -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 @@ -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 @@ -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 @@ -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. @@ -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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202409291705.48TH5tgh000776>