From nobody Sun Sep 29 17:05:55 2024 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4XGrFH5yrSz5XvfR for ; Sun, 29 Sep 2024 17:05:55 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4XGrFH5NSKz47cr; Sun, 29 Sep 2024 17:05:55 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1727629555; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=UZo5LxtO5EahGQF6hwjZPqlONwmzC+XhH+W8MKYBfrE=; b=KJfsluH+ocVGZpaTAOyXGl+66jychFnFaB37U9RnokLNo5+wgdzNAb25e0PGMRZtFtK3AD o+G00XB339i2Uq3bAw1pX9vT1JMB++fx27LdU+YGRO+OOwHBPj5yjCjnmfT40sxUrg+S1T cZQRxSTQlcmc1v0HXO7NzSQSJgtiiTFoe3VR6cY1b1C5t7cVJz9YZ26qPmy/E5ObJLP+kZ +khDg0l/68ZbnnD+ElM6eLsa0VKfBryGCVqnUKVMpThoXEk5gHyEXCxfaZkIqCJXG78RC0 t9h3H31FCBYbMtBLnbaAILfgefOlMzofprf4Hfcax4OCS7eN26sKcSS9XRm76w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1727629555; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=UZo5LxtO5EahGQF6hwjZPqlONwmzC+XhH+W8MKYBfrE=; b=PYp1JPLdakHOtmxGF65vXbJjsLlYH8iSGm/SOkvEvIt3B82nIfNq9PYGK7Zg6zYKPl6nOT ieJbbxkTN1HmWF5n6S/scE0TWtR7+PJ+4G25sEAPRovh8DoTfbRG4Qq0C5hefgTEnVjFyZ f7dq++I+vqY5SIS3/rwPIssZ5QKSheXoXOKySTQYDZtV8ZAQkmW7XWxTbZRMX9Rvhke1/n bsMic1IRoN6++rqirysgYCutTqXAYz87HVuFJsvPTCSAIXIjcFI0MK38vnQPn7dPxX1Dqz mofbmwbmRkJI9mtDjAFee+Gd2TbesYvrrQJavHREhWx3ppJMNBqj8PT6xUsm4g== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1727629555; a=rsa-sha256; cv=none; b=eJCn2JRzSPTWK1YMlaIOwwvVTcdvoRlhhrt/Vwby//oXW6wlpuomY1E9HZbAe/EwdpAchL cGvAwMJoW9vGRvbAFkZWMIS1Wl9nUL/2NsRAy3lY9VamNEbY+eAnz2ZXkqUFzlt1unD7Ee WvbpWC5bYU+VqIgHGuyptX50Y9cBeoVDaVPZ6U05Cgqjbeqt7GyItRPJjAnh2khDYv285o vrNxmsKVTUIvdReeuSOylVb2FBuhwd5tRmvLZ6SUdAgCFqKatrQZ5+FqVOWbaKrykxvQdh uJ1GlOzeVXxH77jQJyFcBhpiXnQQ9SbMH+haPxRty5SsEDZqxnaUqZHMtNabGA== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4XGrFH4tVrzHCh; Sun, 29 Sep 2024 17:05:55 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 48TH5tVh000779; Sun, 29 Sep 2024 17:05:55 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 48TH5tgh000776; Sun, 29 Sep 2024 17:05:55 GMT (envelope-from git) Date: Sun, 29 Sep 2024 17:05:55 GMT Message-Id: <202409291705.48TH5tgh000776@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Fernando =?utf-8?Q?Apestegu=C3=ADa?= Subject: git: f02284bf39 - main - [documentation][virtualization]: Fix links List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: fernape X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: f02284bf39162cb333e86b7bb1ca4e8e99268fb1 Auto-Submitted: auto-generated The branch main has been updated by fernape: URL: https://cgit.FreeBSD.org/doc/commit/?id=f02284bf39162cb333e86b7bb1ca4e8e99268fb1 commit f02284bf39162cb333e86b7bb1ca4e8e99268fb1 Author: Fernando Apesteguía AuthorDate: 2024-09-29 17:03:43 +0000 Commit: Fernando Apesteguía 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