diff options
Diffstat (limited to 'documentation/content/en/books')
18 files changed, 719 insertions, 92 deletions
diff --git a/documentation/content/en/books/developers-handbook/testing/_index.adoc b/documentation/content/en/books/developers-handbook/testing/_index.adoc index 4aae09a4ad..508268d60b 100644 --- a/documentation/content/en/books/developers-handbook/testing/_index.adoc +++ b/documentation/content/en/books/developers-handbook/testing/_index.adoc @@ -72,7 +72,9 @@ It is not possible to use all of the suggestions below every single time, but th * Remove all non-essential device drivers from the kernel. For instance if USB is not needed for the test, do not put USB in the kernel. Drivers which attach often have timeouts ticking away. * Unconfigure hardware that are not in use. Detach disks with man:atacontrol[8] and man:camcontrol[8] if the disks are not used for the test. * Do not configure the network unless it is being tested, or wait until after the test has been performed to ship the results off to another computer. -+ +* Disable "Turbo-modes" because they make the clock frequency explicitly depend on the environment. This means that benchmark runs on 100% identical + code, may depend on time of day, coffee vs. soda or even how many other people are in the office. + If the system must be connected to a public network, watch out for spikes of broadcast traffic. Even though it is hardly noticeable, it will take up CPU cycles. Multicast has similar caveats. * Put each file system on its own disk. This minimizes jitter from head-seek optimizations. * Minimize output to serial or VGA consoles. Running output into files gives less jitter. (Serial consoles easily become a bottleneck.) Do not touch keyboard while the test is running, even kbd:[space] or kbd:[back-space] shows up in the numbers. diff --git a/documentation/content/en/books/developers-handbook/tools/_index.adoc b/documentation/content/en/books/developers-handbook/tools/_index.adoc index c1dbec7094..4308c320fe 100644 --- a/documentation/content/en/books/developers-handbook/tools/_index.adoc +++ b/documentation/content/en/books/developers-handbook/tools/_index.adoc @@ -148,6 +148,13 @@ It is an excellent tool to work with when teaching programming to smaller age gr + The latest version of Logo for FreeBSD is available from the Ports Collection in package:lang/logo[]. +Lua:: +Lua is a lightweight embeddable scripting language. +It is widely portable and relatively simple. +Lua is available in the Ports Collection in package:lang/lua[]. +It is also included in the base system as [.filename]#/usr/libexec/flua# for use by base system components. +Third party software should not depend on [.filename]#flua#. + Python:: Python is an Object-Oriented, interpreted language. Its advocates argue that it is one of the best languages to start programming with, since it is relatively easy to start with, but is not limited in comparison to other popular interpreted languages that are used for the development of large, complex applications (Perl and Tcl are two other languages that are popular for such tasks). diff --git a/documentation/content/en/books/faq/_index.adoc b/documentation/content/en/books/faq/_index.adoc index c973d8a3ac..5664923581 100644 --- a/documentation/content/en/books/faq/_index.adoc +++ b/documentation/content/en/books/faq/_index.adoc @@ -100,7 +100,7 @@ Its adaptability, reliability, and open-source nature make FreeBSD a compelling FreeBSD is a community-driven open-source project with a decentralized structure. Its development and maintenance are carried out by a global community of dedicated volunteers, developers, and organizations who collaborate to enhance and expand the operating system. -The key decisions concerning the FreeBSD project, such as the overall direction of the project or who is allowed to add code to the source tree, are made by a elected Core Team of 9 people. +The key decisions concerning the FreeBSD project, such as the overall direction of the project or who is allowed to add code to the source tree, are made by an elected Core Team of nine people. This collaborative and community-driven approach has been fundamental to FreeBSD's success and longevity as a reliable and robust UNIX-like operating system. diff --git a/documentation/content/en/books/fdp-primer/editor-config/_index.adoc b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc index 181bc6495c..b89309e962 100644 --- a/documentation/content/en/books/fdp-primer/editor-config/_index.adoc +++ b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc @@ -175,25 +175,6 @@ In such cases properly mention that in the commit log. Install from package:editors/emacs[] or package:editors/emacs-devel[]. -[[editor-config-emacs-validation]] -=== Validation - -Emacs's nxml-mode uses compact relax NG schemas for validating XML. -A compact relax NG schema for FreeBSD's extension to DocBook 5.0 is included in the documentation repository. -To configure nxml-mode to validate using this schema, create [.filename]#~/.emacs.d/schema/schemas.xml# and add these lines to the file: - -[source,xml] -.`~/.emacs.d/schema/schemas.xml` -.... -<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"> - <documentElement localName="section" typeId="DocBook" /> - <documentElement localName="chapter" typeId="DocBook" /> - <documentElement localName="article" typeId="DocBook" /> - <documentElement localName="book" typeId="DocBook" /> - <typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc" /> -</locatingRules> -.... - [[editor-config-emacs-igor]] === Automated Proofreading with Flycheck and Igor diff --git a/documentation/content/en/books/handbook/bsdinstall/_index.adoc b/documentation/content/en/books/handbook/bsdinstall/_index.adoc index 8c5920c0c1..acd7e4cfaf 100644 --- a/documentation/content/en/books/handbook/bsdinstall/_index.adoc +++ b/documentation/content/en/books/handbook/bsdinstall/_index.adoc @@ -283,7 +283,7 @@ When booting from CD or DVD, turn on the computer and insert the media at the fi How to configure the system to boot from the inserted media depends upon the architecture. [[bsdinstall-view-probe]] -=== FreeBSD Boot Menu +=== FreeBSD Boot Loader Menu Once the system boots from the installation media, a menu similar to the following will be displayed: diff --git a/documentation/content/en/books/handbook/config/_index.adoc b/documentation/content/en/books/handbook/config/_index.adoc index 2e77ef70bf..ee25617ad0 100644 --- a/documentation/content/en/books/handbook/config/_index.adoc +++ b/documentation/content/en/books/handbook/config/_index.adoc @@ -434,6 +434,8 @@ For instance, to start package:www/nginx[] regardless of the current [.filename] .... ==== +It is also possible to put a service automatically into a jail, see the corresponding crossref:jails[service-jails,Service Jails] explanation. + [[configtuning-status-services]] === Status of a Service diff --git a/documentation/content/en/books/handbook/dtrace/_index.adoc b/documentation/content/en/books/handbook/dtrace/_index.adoc index cf6e5e1c42..797d27606c 100644 --- a/documentation/content/en/books/handbook/dtrace/_index.adoc +++ b/documentation/content/en/books/handbook/dtrace/_index.adoc @@ -153,6 +153,19 @@ This language is called the D language and it is very similar to C++. An in depth discussion of the language is beyond the scope of this document. It is covered extensively in the http://www.dtrace.org/guide[Illumos Dynamic Tracing Guide]. +[[dtrace-out-of-kernel]] +== Enabling DTrace in Out-of-Kernel Modules + +To add DTrace support to an out-of-kernel module, which is useful for development and debugging, include the following line in the module's Makefile: + +[.programlisting] +.... +CFLAGS+= -DKDTRACE_HOOKS +.... + +This flag enables DTrace hooks during compilation, allowing for advanced debugging and monitoring of the module. +Ensure to recompile the module after this modification to activate DTrace functionality. + [[dtrace-using]] == Using DTrace diff --git a/documentation/content/en/books/handbook/jails/_index.adoc b/documentation/content/en/books/handbook/jails/_index.adoc index bf17248179..fbf3b2b80d 100644 --- a/documentation/content/en/books/handbook/jails/_index.adoc +++ b/documentation/content/en/books/handbook/jails/_index.adoc @@ -137,6 +137,30 @@ Disadvantages of Thin Jails: * Dependency Conflicts: If multiple thin jails require different versions of the same libraries or software, managing dependencies can become complex. In some cases, this might require additional effort to ensure compatibility. * Compatibility Challenges: Applications within a thin jail might encounter compatibility issues if they assume a certain base system environment that differs from the shared components provided by the template. +[[service-jails]] +=== Service Jails + +A service jail shares the complete filesystem tree directly with the host (the jail root path is [.filename]#/#) and as such can access and modify any file on the host, and shares the same user accounts with the host. +By default it has no access to the network or other resources which are restricted in jails, but they can be configured to re-use the network of the host and to remove some of the jail-restrictions. +The use case for service jails is automatic confinement of services/daemons inside a jail with minimal configuration, and without any knowledge of the files needed by such service/daemon. +Service jails exist since FreeBSD 15. + +Advantages of Service Jails: + +* Zero Administration: A service jail ready service needs only one config line in [.filename]#/etc/rc.conf#, a service which is not service jails ready needs two config lines. +* Resource Efficiency: Service jails are more resource efficient than thin jails, as they do not need any additional disk space or network resource. +* Faster Deployment: Creating and launching service jails is generally faster compared to thin jails if only distinct services/daemons shall be jailed and no parallel instances of the same service/daemon is needed. +* Shared Resources: Service jails share all resources such as libraries and binaries with the host system. This can potentially lead to more efficient disk caching and improved performance for applications within the jail. +* Process Isolation: Service jails isolate a particular service, it can not see processes which are not a child of the service jail, even if they run within the same user account. + +Disadvantages of Service Jails: + +* Reduced Isolation: The primary disadvantage of service jails is that they offer no filesystem isolation compared to thick or thin jails. +* Security Concerns: The reduced isolation in service jails could pose security risks, as a compromise in one jail might have a greater potential to affect everything on the host system. + +Most of the configuration of jails which is discussed below is not needed for service jails. +To understand how jails work, it is recommended to understand those configuration possibilities. The details about what is needed to configure a service jail is in crossref:jails[service-jails-config, Configuring service jails]. + [[vnet-jails]] === VNET Jails @@ -867,6 +891,49 @@ The Ubuntu environment can be accessed using the following command: More information can be found in the chapter crossref:linuxemu[linuxemu,Linux Binary Compatibility]. +[[service-jails-config]] +=== Configuring Service Jails + +A service jail is configured completely via [.filename]#/etc/rc.conf# or man:sysrc[8]. +The base system services are service jails ready. +They contain a config line which enables networking or lift other restrictions of jails. +Base system services which do not make sense to run inside jails are configured to not be started as a service jail, even if enabled in [.filename]#/etc/rc.conf#. +Some examples of such a service are services which want to mount or unmount something in the start of stop method, or only configure something like a route, or firewall, or the like. + +Third party services may or may not be service jails ready. To check if a service is service jail ready, the following command can be used: + +[source,shell] +.... +# grep _svcj_options /path/to/rc.d/servicename +.... + +If there is no output, the service is not service jail ready, or does not need any additional privileges like e.g. network access. + +If the service is not service jail ready, and needs network access, it can be made ready by adding the necessary config to [.filename]#/etc/rc.conf#: + +[source,shell] +.... +# sysrc servicename_svcj_options=net_basic +.... + +For all possible `_svcj_options` see the man:rc.conf[5] man-page. + +To enable a service jail for a given service, the service needs to be stopped and the `servicename_svcj` variable needs to be set to YES. +To put man:syslogd[8] into a service jail, use the following sequence of commands: + +[source,shell] +.... +# service syslogd stop +# sysrc syslogd_svcj=YES +# service syslogd start +.... + +If the `servicename_svcj` variable is changed, the service needs to be stopped before it is changed. +If it is not stopped, the rc framework will not detect the correct state of the service and will not be able to do what is requested. + +Service jails are managed only via man:rc.conf[5]/man:sysrc[8] and the man:service[8] command. +The jail utilities, like man:jls[8] as described in crossref:jails[jail-management,Jail Management] can be used to investigate the operation, but the man:jail[8] command is not supposed to be used to manage them. + [[jail-management]] == Jail Management @@ -939,14 +1006,14 @@ The second step is to remove these flags with man:chflags[1] by executing the fo [source,shell] .... -# chflags -R 0 /usr/local/jails/classic +# chflags -R 0 /usr/local/jails/containers/classic .... The third step is to delete the directory where the jail was: [source,shell] .... -# rm -rf /usr/local/jails/classic +# rm -rf /usr/local/jails/containers/classic .... Finally, it will be necessary to remove the jail entry in [.filename]#/etc/jail.conf# or in [.filename]#jail.conf.d#. diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc index 2fc1e4a730..611a15c8db 100644 --- a/documentation/content/en/books/handbook/mirrors/_index.adoc +++ b/documentation/content/en/books/handbook/mirrors/_index.adoc @@ -197,7 +197,7 @@ Mirror list maintained by the community and other companies: | mirror.ps.kz | http://mirror.ps.kz/freebsd[http] link:ftp://mirror.ps.kz/freebsd[ftp] -| +| | mirror.neolabs.kz | link:http://mirror.neolabs.kz/freebsd[http] link:ftp://mirror.neolabs.kz/freebsd[ftp] @@ -316,7 +316,7 @@ As of April 2021, FreeBSD uses git as the only version control system for storin [NOTE] ==== Git is generally a developer tool. -Users may prefer to use `freebsd-update` (crossref:cutting-edge[updating-upgrading-freebsdupdate,“FreeBSD Update”]) to update the FreeBSD base system, and `git` (crossref:ports[ports-using,“Using the Ports Collection”]) to update the FreeBSD Ports Collection. +Users may prefer to use `freebsd-update` (crossref:cutting-edge[updating-upgrading-freebsdupdate,“FreeBSD Update”]) to update the FreeBSD base system. ==== This section demonstrates how to install Git on a FreeBSD system and use it to create a local copy of a FreeBSD source code repository. diff --git a/documentation/content/en/books/handbook/ports/_index.adoc b/documentation/content/en/books/handbook/ports/_index.adoc index 7ef3b47c7d..a32b0608ba 100644 --- a/documentation/content/en/books/handbook/ports/_index.adoc +++ b/documentation/content/en/books/handbook/ports/_index.adoc @@ -680,6 +680,9 @@ If more control over the ports tree is needed or if local changes need to be mai Git can be used to obtain the Ports Collection. Refer to extref:{committers-guide}[the Git Primer, git-primer] for a detailed description of Git. +We add --depth 1 to the git command line to clone the tree without obtaining the commit history, which saves time and is acceptable for most users. +If you have your own changes to the ports tree, or need the history for any reason, omit the --depth 1 argument below. + . Git must be installed before it can be used to check out the ports tree. If a copy of the ports tree is already present, install Git like this: + [source,shell] @@ -699,14 +702,14 @@ If the ports tree is not available, or pkg is being used to manage packages, Git + [source,shell] .... -# git clone https://git.FreeBSD.org/ports.git /usr/ports +# git clone --depth 1 https://git.FreeBSD.org/ports.git /usr/ports .... + . Or, check out a copy of a quarterly branch: + [source,shell] .... -# git clone https://git.FreeBSD.org/ports.git -b 2023Q1 /usr/ports +# git clone --depth 1 https://git.FreeBSD.org/ports.git -b 2023Q1 /usr/ports .... + . As needed, update `/usr/ports` after the initial Git checkout: diff --git a/documentation/content/en/books/handbook/printing/_index.adoc b/documentation/content/en/books/handbook/printing/_index.adoc index 21b1faa92e..58f6da8569 100644 --- a/documentation/content/en/books/handbook/printing/_index.adoc +++ b/documentation/content/en/books/handbook/printing/_index.adoc @@ -297,8 +297,6 @@ However, printing an entire graphic-based page on these printers is often very s Host-based printers are often more difficult to set up. Some cannot be used at all because of proprietary PDLs. Avoid these printers when possible. - -Descriptions of many PDLs can be found at http://www.undocprint.org/formats/page_description_languages[]. The particular `PDL` used by various models of printers can be found at http://www.openprinting.org/printers[]. [[printing-direct]] @@ -895,4 +893,4 @@ Configuration information is shown at https://developers.hp.com/hp-linux-imaging LPRng was developed as an enhanced alternative to man:lpd[8]. The port is package:sysutils/LPRng[]. -For details and documentation, see http://www.lprng.com/[]. +For details and documentation, see https://lprng.sourceforge.net/[]. diff --git a/documentation/content/en/books/handbook/security/_index.adoc b/documentation/content/en/books/handbook/security/_index.adoc index 9f7d1566be..e746ff1314 100644 --- a/documentation/content/en/books/handbook/security/_index.adoc +++ b/documentation/content/en/books/handbook/security/_index.adoc @@ -1478,7 +1478,7 @@ When using MIT Kerberos as a KDC on FreeBSD, execute the following commands to a [source,shell] .... -# sysrc kdc_program="/usr/local/sbin/kdc" +# sysrc kdc_program="/usr/local/sbin/krb5kdc" # sysrc kadmind_program="/usr/local/sbin/kadmind" # sysrc kdc_flags="" # sysrc kdc_enable="YES" diff --git a/documentation/content/en/books/handbook/virtualization/_index.adoc b/documentation/content/en/books/handbook/virtualization/_index.adoc index c567bd9c76..8082578062 100644 --- a/documentation/content/en/books/handbook/virtualization/_index.adoc +++ b/documentation/content/en/books/handbook/virtualization/_index.adoc @@ -136,9 +136,16 @@ kern.hz=100 + Without this setting, an idle FreeBSD Parallels guest will use roughly 15% of the CPU of a single processor iMac(R). After this change the usage will be closer to 5%. ++ +If installing FreeBSD 14.0 or later, and CPU utilization is still high, add the following additional line to [.filename]#/boot/loader.conf#: ++ +[.programlisting] +.... +debug.acpi.disabled="ged" +.... . Create a New Kernel Configuration File + -All of the SCSI, FireWire, and USB device drivers can be removed from a custom kernel configuration file. +All SCSI, FireWire, and USB device drivers can be removed from a custom kernel configuration file. Parallels provides a virtual network adapter used by the man:ed[4] driver, so all network devices except for man:ed[4] and man:miibus[4] can be removed from the kernel. . Configure Networking + @@ -244,7 +251,7 @@ Without this setting, an idle FreeBSD VMware Fusion guest will use roughly 15% o After this change, the usage will be closer to 5%. . Create a New Kernel Configuration File + -All of the FireWire, and USB device drivers can be removed from a custom kernel configuration file. +All FireWire, and USB device drivers can be removed from a custom kernel configuration file. VMware Fusion provides a virtual network adapter used by the man:em[4] driver, so all network devices except for man:em[4] can be removed from the kernel. . Configure Networking + @@ -493,14 +500,20 @@ perm pass* 0660 == FreeBSD as a Host with bhyve The bhyve BSD-licensed hypervisor became part of the base system with FreeBSD 10.0-RELEASE. -This hypervisor supports a number of guests, including FreeBSD, OpenBSD, many Linux(R) distributions, and Microsoft Windows(R). -By default, bhyve provides access to serial console and does not emulate a graphical console. +This hypervisor supports several guests, including FreeBSD, OpenBSD, many Linux(R) distributions, and Microsoft Windows(R). +By default, bhyve provides access to a serial console and does not emulate a graphical console. Virtualization offload features of newer CPUs are used to avoid the legacy methods of translating instructions and manually managing memory mappings. -The bhyve design requires a processor that supports Intel(R) Extended Page Tables (EPT) or AMD(R) Rapid Virtualization Indexing (RVI) or Nested Page Tables (NPT). +The bhyve design requires + +* an Intel(R) processor that supports Intel Extended Page Tables (EPT), +* or an AMD(R) processor that supports AMD Rapid Virtualization Indexing (RVI), or Nested Page Tables (NPT), +* or an ARM(R) aarch64 CPU. + +Only pure ARMv8.0 virtualization is supported on ARM, the Virtualization Host Extensions are not currently used. Hosting Linux(R) guests or FreeBSD guests with more than one vCPU requires VMX unrestricted mode support (UG). -The easiest way to tell if a processor supports bhyve is to run `dmesg` or look in [.filename]#/var/run/dmesg.boot# for the `POPCNT` processor feature flag on the `Features2` line for AMD(R) processors or `EPT` and `UG` on the `VT-x` line for Intel(R) processors. +The easiest way to tell if an Intel or AMD processor supports bhyve is to run `dmesg` or look in [.filename]#/var/run/dmesg.boot# for the `POPCNT` processor feature flag on the `Features2` line for AMD(R) processors or `EPT` and `UG` on the `VT-x` line for Intel(R) processors. [[virtualization-bhyve-prep]] === Preparing the Host @@ -514,7 +527,7 @@ First, load the bhyve kernel module: .... There are several ways to connect a virtual machine guest to a host's network; one straightforward way to accomplish this is to create a [.filename]#tap# interface for the network device in the virtual machine to attach to. -In order for the network device to participate in the network, also create a bridge interface containing the [.filename]#tap# interface and the physical interface as members. +For the network device to participate in the network, also create a bridge interface containing the [.filename]#tap# interface and the physical interface as members. In this example, the physical interface is _igb0_: [source,shell] @@ -548,7 +561,7 @@ FreeBSD-14.0-RELEASE-amd64-bootonly.iso 426 MB 16 MBps 22s FreeBSD comes with an example script `vmrun.sh` for running a virtual machine in bhyve. It will start the virtual machine and run it in a loop, so it will automatically restart if it crashes. -`vmrun.sh` takes a number of options to control the configuration of the machine, including: +`vmrun.sh` takes several options to control the configuration of the machine, including: * `-c` controls the number of virtual CPUs, * `-m` limits the amount of memory available to the guest, @@ -557,27 +570,28 @@ It will start the virtual machine and run it in a loop, so it will automatically * `-i` tells bhyve to boot from the CD image instead of the disk, and * `-I` defines which CD image to use. -The last parameter is the name of the virtual machine and used to track the running machines. -You can use the following command to get a list of all available program argument options: +The last parameter is the name of the virtual machine and is used to track the running machines. +The following command lists all available program argument options: [source,shell] .... -# sh /usr/share/examples/bhyve/vmrun.sh --usage +# sh /usr/share/examples/bhyve/vmrun.sh -h .... This example starts the virtual machine in installation mode: [source,shell] .... -# sh /usr/share/examples/bhyve/vmrun.sh -c 1 -m 1024M -t tap0 -d guest.img -i -I FreeBSD-14.0-RELEASE-amd64-bootonly.iso guestname +# sh /usr/share/examples/bhyve/vmrun.sh -c 1 -m 1024M -t tap0 -d guest.img \ + -i -I FreeBSD-14.0-RELEASE-amd64-bootonly.iso guestname .... The virtual machine will boot and start the installer. -After installing a system in the virtual machine, when the system asks about dropping in to a shell at the end of the installation, choose btn:[Yes]. +After installing a system in the virtual machine, when the system asks about dropping into a shell at the end of the installation, choose btn:[Yes]. Reboot the virtual machine. While rebooting the virtual machine causes bhyve to exit, the [.filename]#vmrun.sh# script runs `bhyve` in a loop and will automatically restart it. -When this happens, choose the reboot option from the boot loader menu in order to escape the loop. +When this happens, choose the reboot option from the boot loader menu to escape the loop. Now the guest can be started from the virtual disk: [source,shell] @@ -597,7 +611,7 @@ To do this, first ensure that the port is installed, then create a file to use a # truncate -s 16G linux.img .... -Starting a Linux virtual machine with `grub2-bhyve` is a two step process. +Starting a Linux virtual machine with `grub2-bhyve` is a two-step process. . First a kernel must be loaded, then the guest can be started. . The Linux(R) kernel is loaded with package:sysutils/grub2-bhyve[]. @@ -637,8 +651,9 @@ Now that the Linux(R) kernel is loaded, the guest can be started: [source,shell] .... -# bhyve -A -H -P -s 0:0,hostbridge -s 1:0,lpc -s 2:0,virtio-net,tap0 -s 3:0,virtio-blk,./linux.img \ - -s 4:0,ahci-cd,./somelinux.iso -l com1,stdio -c 4 -m 1024M linuxguest +# bhyve -A -H -P -s 0:0,hostbridge -s 1:0,lpc -s 2:0,virtio-net,tap0 \ + -s 3:0,virtio-blk,./linux.img -s 4:0,ahci-cd,./somelinux.iso \ + -l com1,stdio -c 4 -m 1024M linuxguest .... The system will boot and start the installer. @@ -693,7 +708,7 @@ Destroy the virtual machine instance: In addition to `bhyveload` and `grub-bhyve`, the bhyve hypervisor can also boot virtual machines using the UEFI firmware. This option may support guest operating systems that are not supported by the other loaders. -In order to make use of the UEFI support in bhyve, first obtain the UEFI firmware images. +To make use of the UEFI support in bhyve, first obtain the UEFI firmware images. This can be done by installing package:sysutils/bhyve-firmware[] port or package. With the firmware in place, add the flags `-l bootrom,_/path/to/firmware_` to your bhyve command line. @@ -702,10 +717,10 @@ The actual bhyve command may look like this: [source,shell] .... # bhyve -AHP -s 0:0,hostbridge -s 1:0,lpc \ --s 2:0,virtio-net,tap1 -s 3:0,virtio-blk,./disk.img \ --s 4:0,ahci-cd,./install.iso -c 4 -m 1024M \ --l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \ -guest + -s 2:0,virtio-net,tap1 -s 3:0,virtio-blk,./disk.img \ + -s 4:0,ahci-cd,./install.iso -c 4 -m 1024M \ + -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \ + guest .... To allow a guest to store UEFI variables, you can use a variables file appended to the `-l` flag. @@ -722,23 +737,29 @@ Then, add that variables file into your bhyve arguments: [source,shell] .... # bhyve -AHP -s 0:0,hostbridge -s 1:0,lpc \ --s 2:0,virtio-net,tap1 -s 3:0,virtio-blk,./disk.img \ --s 4:0,ahci-cd,./install.iso -c 4 -m 1024M \ --l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd,/path/to/vm-image/BHYVE_UEFI_VARS.fd \ -guest + -s 2:0,virtio-net,tap1 -s 3:0,virtio-blk,./disk.img \ + -s 4:0,ahci-cd,./install.iso -c 4 -m 1024M \ + -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd,/path/to/vm-image/BHYVE_UEFI_VARS.fd \ + guest .... -You can use man:efivar[8] to view and modify the variables file contents from the host. +[NOTE] +==== +Some Linux distributions require the use of UEFI variables to store the path for their UEFI boot file (using `linux64.efi` or `grubx64.efi` instead of `bootx64.efi`, for example). +It is therefore recommended to use a variables file for Linux virtual machines to avoid having to manually alter the boot partition files. +==== + +To view or modify the variables file contents, use man:efivar[8] from the host. package:sysutils/bhyve-firmware[] also contains a CSM-enabled firmware, to boot guests with no UEFI support in legacy BIOS mode: [source,shell] .... # bhyve -AHP -s 0:0,hostbridge -s 1:0,lpc \ --s 2:0,virtio-net,tap1 -s 3:0,virtio-blk,./disk.img \ --s 4:0,ahci-cd,./install.iso -c 4 -m 1024M \ --l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI_CSM.fd \ -guest + -s 2:0,virtio-net,tap1 -s 3:0,virtio-blk,./disk.img \ + -s 4:0,ahci-cd,./install.iso -c 4 -m 1024M \ + -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI_CSM.fd \ + guest .... [[virtualization-bhyve-framebuffer]] @@ -756,16 +777,62 @@ The resulting bhyve command would look like this: [source,shell] .... # bhyve -AHP -s 0:0,hostbridge -s 31:0,lpc \ --s 2:0,virtio-net,tap1 -s 3:0,virtio-blk,./disk.img \ --s 4:0,ahci-cd,./install.iso -c 4 -m 1024M \ --s 29,fbuf,tcp=0.0.0.0:5900,w=800,h=600,wait \ --s 30,xhci,tablet \ --l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \ -guest + -s 2:0,virtio-net,tap1 -s 3:0,virtio-blk,./disk.img \ + -s 4:0,ahci-cd,./install.iso -c 4 -m 1024M \ + -s 29,fbuf,tcp=0.0.0.0:5900,w=800,h=600,wait \ + -s 30,xhci,tablet \ + -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \ + guest .... Note, in BIOS emulation mode, the framebuffer will cease receiving updates once control is passed from firmware to guest operating system. +[[virtualization-bhyve-windows]] +=== Creating a Microsoft Windows(R) Guest === + +Setting up a guest for Windows versions 10 or earlier can be done directly from the original installation media and is a relatively straightforward process. +Aside from minimum resource requirements, running Windows as guest requires + +* wiring virtual machine memory (flag `-w`) and +* booting with an UEFI bootrom. + +An example for booting a virtual machine guest with a Windows installation ISO: + +[source,shell] +.... +bhyve \ + -c 2 \ + -s 0,hostbridge \ + -s 3,nvme,windows2016.img \ + -s 4,ahci-cd,install.iso \ + -s 10,virtio-net,tap0 \ + -s 31,lpc \ + -s 30,xhci,tablet \ + -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \ + -m 8G -H -w \ + windows2016 +.... + +Only one or two VCPUs should be used during installation but this number can be increased once Windows is installed. + +link:https://github.com/virtio-win/virtio-win-pkg-scripts/blob/master/README.md[VirtIO drivers] must be installed to use the defined `virtio-net` network interface. +An alternative is to switch to E1000 (Intel E82545) emulation by changing `virtio-net` to `e1000` in the above command line. +However, performance will be impacted. + +[[virtualization-bhyve-windows-win11]] +==== Creating a Windows 11 Guest ==== + +Beginning with Windows 11, Microsoft introduced a hardware requirement for a TPM 2 module. +bhyve supports passing a hardware TPM through to a guest. +The installation media can be modified to disable the relevant hardware checks. +A detailed description for this process can be found on the link:https://wiki.freebsd.org/bhyve/Windows#iso-remaster[FreeBSD Wiki]. + +[WARNING] +==== +Modifying Windows installation media and running Windows guests without a TPM module are unsupported by the manufacturer. +Consider your application and use case before implementing such approaches. +==== + [[virtualization-bhyve-zfs]] === Using ZFS with bhyve Guests @@ -781,8 +848,9 @@ When starting the VM, specify the ZFS volume as the disk drive: [source,shell] .... -# bhyve -A -H -P -s 0:0,hostbridge -s 1:0,lpc -s 2:0,virtio-net,tap0 -s3:0,virtio-blk,/dev/zvol/zroot/linuxdisk0 \ - -l com1,stdio -c 4 -m 1024M linuxguest +# bhyve -A -H -P -s 0:0,hostbridge -s 1:0,lpc -s 2:0,virtio-net,tap0 \ + -s3:0,virtio-blk,/dev/zvol/zroot/linuxdisk0 \ + -l com1,stdio -c 4 -m 1024M linuxguest .... If you are using ZFS for the host as well as inside a guest, keep in mind the competing memory pressure of both systems caching the virtual machine's contents. @@ -794,6 +862,442 @@ To do this, apply the following settings to ZFS filesystems on the host, replaci # zfs set primarycache=metadata <name> .... +[[virtualiziation-bhyve-snapshot]] +=== Creating a Virtual Machine Snapshot === + +Modern hypervisors allow their users to create "snapshots" of their state; +such a snapshot includes a guest's disk, CPU, and memory contents. +A snapshot can usually be taken independent of whether the guest is running or shut down. +One can then reset and return the virtual machine to the precise state when the snapshot was taken. + +[[virtualization-bhyve-snapshot-zfs]] +==== ZFS Snapshots ==== + +Using ZFS volumes as the backing storage for a virtual machine enables the snapshotting of the guest's disk. For example: + +[source,shell] +.... +zfs snapshot zroot/path/to/zvol@snapshot_name +.... + +Though it is possible to snapshot a ZFS volume this way while the guest is running, keep in mind that the contents of the virtual disk may be in an inconsistent state while the guest is active. +It is therefore recommended to first shutdown or pause the guest before executing this command. +Pausing a guest is not supported by default and needs to be enabled first (see crossref:virtualization[virtualization-bhyve-snapshot-builtin,Memory and CPU Snapshots]) + +[WARNING] +==== +Rolling back a ZFS zvol to a snapshot while a virtual machine is using it may corrupt the file system contents and crash the guest. +All unsaved data in the guest will be lost and modifications since the last snapshot may get destroyed. + +A second rollback may be required once the virtual machine is shut down to restore the file system to a useable state. +This in turn will ultimately destroy any changes made after the snapshot. +==== + +[[virtualization-bhyve-snapshot-builtin]] +==== Memory and CPU Snapshots (Experimental Feature) ==== + +As of FreeBSD 13, bhyve has an experimental "snapshot" feature for dumping a guest's memory and CPU state to a file and then halting the virtual machine. +The guest can be resumed from the snapshot file contents later. + +However, this feature is not enabled by default and requires the system to be rebuilt from source. +See crossref:cutting-edge[updating-src-building, Building from Source] for an in-depth description on the process of compiling the kernel with custom options. + +[WARNING] +==== +The functionality is not ready for production use and limited to work for specific virtual machine configurations. +There are multiple limitations: + +* `nvme` and `virtio-blk` storage backends do not work yet +* snapshots are only supported when the guest uses a single kind of each device, i.e. if there is more than one `ahci-hd` disk attached, snapshot creation will fail +* additionally, the feature may be reasonably stable on Intel, but it probably won't work on AMD CPUs. +==== + +[NOTE] +==== +Make sure the [.filename]#/usr/src# directory is up-to date before taking the following steps. See crossref:cutting-edge[updating-src-obtaining-src, Updating the Source] for the detailed procedure how to do this. +==== + +First, add the following to [.filename]#/etc/src.conf#: + +[.programlisting] +.... +WITH_BHYVE_SNAPHOT=yes +BHYVE_SNAPSHOT=1 +MK_BHYVE_SNAPSHOT=yes +.... + +[NOTE] +==== +If the system was partially or wholly rebuilt, it is recommended to run + +[source,shell] +.... +# cd /usr/src +# make cleanworld +.... + +before proceeding. +==== + +Then follow the steps outlined in the crossref:cutting-edge[updating-src-quick-start,"Quick Start section of the Updating FreeBSD from Source"] chapter to build and install world and kernel. + +To verify successful activation of the snapshot feature, enter + +[source,shell] +.... +# bhyvectl --usage +.... + +and check if the output lists a `--suspend` flag. +If the flag is missing, the feature did not activate correctly. + +Then, you can snapshot and suspend a running virtual machine of your choice: + +[source,shell] +.... +# bhyvectl --vm=vmname --suspend=/path/to/snapshot/filename +.... + +[NOTE] +==== +Provide an absolute path and filename to `--suspend`. +Otherwise, bhyve will write snapshot data to whichever directory bhyve was started from. + +Make sure to write the snapshot data to a secure directory. +The generated output contains a full memory dump of the guest and may thus contain sensitive data (i.e. passwords)! +==== + +This creates three files: + +* memory snapshot - named like the input to `--suspend` +* kernel file - name like the input to `--suspend` with the suffix [.filename]#.kern# +* metadata - contains meta data about the system state, named with the suffix [.filename]#.meta# + +To restore a guest from a snapshot, use the `-r` flag with `bhyve`: + +[source,shell] +.... +# bhyve -r /path/to/snapshot/filename +.... + +Restoring a guest snapshot on a different CPU architecture will not work. +Generally, attempting to restore on a system not identical to the snapshot creator will likely fail. + +[[virtualization-bhyve-jailed]] +=== Jailing bhyve === + +For improved security and separation of virtual machines from the host operating system, it is possible to run bhyve in a jail. +See crossref:jails[,Jails] for an in-depth description of jails and their security benefits. + +[[virtualization-bhyve-jailed-creation]] +==== Creating a Jail for bhyve ==== + +First, create a jail environment. If using a UFS file system, simply run: + +[source,shell] +.... +# mkdir -p /jails/bhyve +.... + +If using a crossref:zfs[,ZFS filesystem], use the following commands: + +[source,shell] +.... +# zfs create zroot/jails +# zfs create zroot/jails/bhyve +.... + +Then create a ZFS zvol for the virtual machine `bhyvevm0`: + +[source,shell] +.... +# zfs create zroot/vms +# zfs create -V 20G zroot/vms/bhyvevm0 +.... + +If not using ZFS, use the following commands to create a disk image file directly in the jail directory structure: + +[source,shell] +.... +# mkdir /jails/bhyve/vms +# truncate -s 20G /jails/bhyve/vms/bhyvevm0 +.... + +Download a FreeBSD image, preferably a version equal to or older than the host and extract it into the jail directory: + +[source,shell] +.... +# cd /jails +# fetch -o base.txz http://ftp.freebsd.org/pub/FreeBSD/releases/amd64/13.2-RELEASE/base.txz +# tar -C /jails/bhyve -xvf base.txz +.... + +[NOTE] +==== +Running a higher FreeBSD version in a jail than the host is unsupported (i.e. running 14.0-RELEASE in a jail, embedded in a 13.2-RELEASE host). +==== + +Next, add a devfs ruleset to [.filename]#/etc/devfs.rules#: + +[.programlisting] +.... +[devfsrules_jail_bhyve=100] +add include $devfsrules_hide_all +add include $devfsrules_unhide_login +add path 'urandom' unhide +add path 'random' unhide +add path 'crypto' unhide +add path 'shm' unhide +add path 'zero' unhide +add path 'null' unhide +add path 'mem' unhide +add path 'vmm' unhide +add path 'vmm/*' unhide +add path 'vmm.io' unhide +add path 'vmm.io/*' unhide +add path 'nmdmbhyve*' unhide +add path 'zvol' unhide +add path 'zvol/zroot' unhide +add path 'zvol/zroot/vms' unhide +add path 'zvol/zroot/vms/bhyvevm0' unhide +add path 'zvol/zroot/vms/bhyvevm1' unhide +add path 'tap10*' unhide +.... + +[NOTE] +==== +If there's another devfs rule with the numeric ID 100 in your [.filename]#/etc/devfs.rules# file, replace the one in the listing with another yet unused ID number. +==== + +[NOTE] +==== +If not using a ZFS filesystem, skip the related zvol rules in [.filename]#/etc/devfs.rules#: + +[.programlisting] +.... +add path 'zvol' unhide +add path 'zvol/zroot' unhide +add path 'zvol/zroot/vms' unhide +add path 'zvol/zroot/vms/bhyvevm0' unhide +add path 'zvol/zroot/vms/bhyvevm1' unhide +.... +==== + +These rules will cause bhyve to + +* create a virtual machine with disk volumes called `bhyvevm0` and `bhyvevm1`, +* use [.filename]#tap# network interfaces with the name prefix `tap10`. +That means, valid interface names will be `tap10`, `tap100`, `tap101`, ... `tap109`, `tap1000` and so on. ++ +Limiting the access to a subset of possible [.filename]#tap# interface names will prevent the jail (and thus bhyve) from seeing [.filename]#tap# interfaces of the host and other jails. +* use [.filename]#nmdm# devices prefixed with "bhyve", i.e. [.filename]#/dev/nmdmbhyve0#. + +Those rules can be expanded and varied with different guest and interface names as desired. + +[NOTE] +==== +If you intend to use bhyve on the host as well as in a one or more jails, remember that [.filename]#tap# and [.filename]#nmdm# interface names will operate in a shared environment. +For example, you can use [.filename]#/dev/nmdmbhyve0# only either for bhyve on the host or in a jail. +==== + +Restart devfs for the changes to be loaded: + +[source,shell] +.... +# service devfs restart +.... + +Then add a definition for your new jail into [.filename]#/etc/jail.conf# or [.filename]#/etc/jail.conf.d#. +Replace the interface number [.filename]#$if# and IP address with your personal variations. + +.Using NAT or routed traffic with a firewall +[example] +==== +[.programlisting] +.... +bhyve { + $if = 0; + exec.prestart = "/sbin/ifconfig epair${if} create up"; + exec.prestart += "/sbin/ifconfig epair${if}a up"; + exec.prestart += "/sbin/ifconfig epair${if}a name ${name}0"; + exec.prestart += "/sbin/ifconfig epair${if}b name jail${if}"; + exec.prestart += "/sbin/ifconfig ${name}0 inet 192.168.168.1/27"; + exec.prestart += "/sbin/sysctl net.inet.ip.forwarding=1"; + + exec.clean; + + host.hostname = "your-hostname-here"; + vnet; + vnet.interface = "em${if}"; + path = "/jails/${name}"; + persist; + securelevel = 3; + devfs_ruleset = 100; + mount.devfs; + + allow.vmm; + + exec.start += "/bin/sh /etc/rc"; + exec.stop = "/bin/sh /etc/rc.shutdown"; + + exec.poststop += "/sbin/ifconfig ${name}0 destroy"; +} +.... + +This example assumes use of a firewall like `pf` or `ipfw` to NAT your jail traffic. +See the crossref:firewalls[,Firewalls] chapter for more details on the available options to implement this. +==== +.Using a bridged network connection +[example] +==== +[.programlisting] +.... +bhyve { + $if = 0; + exec.prestart = "/sbin/ifconfig epair${if} create up"; + exec.prestart += "/sbin/ifconfig epair${if}a up"; + exec.prestart += "/sbin/ifconfig epair${if}a name ${name}0"; + exec.prestart += "/sbin/ifconfig epair${if}b name jail${if}"; + exec.prestart += "/sbin/ifconfig bridge0 addm ${name}0"; + exec.prestart += "/sbin/sysctl net.inet.ip.forwarding=1"; + + exec.clean; + + host.hostname = "your-hostname-here"; + vnet; + vnet.interface = "em${if}"; + path = "/jails/${name}"; + persist; + securelevel = 3; + devfs_ruleset = 100; + mount.devfs; + + allow.vmm; + + exec.start += "/bin/sh /etc/rc"; + exec.stop = "/bin/sh /etc/rc.shutdown"; + + exec.poststop += "/sbin/ifconfig ${name}0 destroy"; +} +.... +==== + +[NOTE] +==== +If you previously replaced the devfs ruleset ID 100 in [.filename]#/etc/devfs.rules# with your own unique number, remember to replace the numeric ID also in your [.filename]#jails.conf# too. +==== + +[[virtualization-bhyve-jailed-config]] +==== Configuring the Jail ==== + +To start the jail for the first time and do some additional configuration work, enter: + +[source,shell] +.... +# cp /etc/resolv.conf /jails/bhyve/etc +# service jail onestart bhyve +# jexec bhyve +# sysrc ifconfig_jail0="inet 192.168.168.2/27" +# sysrc defaultrouter="192.168.168.1" +# sysrc sendmail_enable=NONE +# sysrc cloned_interfaces="tap100" +# exit +.... + +Restart and enable the jail: + +[source,shell] +.... +# sysrc jail_enable=YES +# service jail restart bhyve +.... + +Afterwards, you can create a virtual machine within the jail. +For a FreeBSD guest, download an installation ISO first: + +[source,shell] +.... +# jexec bhyve +# cd /vms +# fetch -o freebsd.iso https://download.freebsd.org/releases/ISO-IMAGES/14.0/FreeBSD-14.0-RELEASE-amd64-bootonly.iso +.... + +[[virtualization-bhyve-jailed-createvm]] +==== Creating a Virtual Machine Inside the Jail ==== + +To create a virtual machine, use `bhyvectl` to initialize it first: + +[source,shell] +.... +# jexec bhyve +# bhyvectl --create --vm=bhyvevm0 +.... + +[NOTE] +==== +Creating the guest with `bhyvectl` may be required when initiating the virtual machine from a jail. +Skipping this step may cause the following error message when starting `bhyve`: + +`vm_open: vm-name could not be opened. No such file or directory` +==== + +Finally, use your preferred way of starting the guest. + +.Starting with `vmrun.sh` and ZFS +[example] +==== +Using `vmrun.sh` on a ZFS filesystems: + +[source,shell] +.... +# jexec bhyve +# sh /usr/share/examples/bhyve/vmrun.sh -c 1 -m 1024M \ + -t tap100 -d /dev/zvols/zroot/vms/bhyvevm0 -i -I /vms/FreeBSD-14.0-RELEASE-amd64-bootonly.iso bhyvevm0 +.... +==== + +.Starting with `vmrun.sh` and UFS +[example] +==== +Using `vmrun.sh` on a UFS filesystem: + +[source,shell] +.... +# jexec bhyve +# sh /usr/share/examples/bhyve/vmrun.sh -c 1 -m 1024M \ + -t tap100 -d /vms/bhyvevm0 -i -I /vms/FreeBSD-14.0-RELEASE-amd64-bootonly.iso bhyvevm0 +.... +==== + +.Starting bhyve for an UEFI guest with ZFS +[example] +==== +If instead you want to use an UEFI guest, remember to first install the required firmware package package:sysutils/bhyve-firmware[] in the jail: + +[source,shell] +.... +# pkg -j bhyve install bhyve-firmware +.... + +Then use `bhyve` directly: + +[source,shell] +.... +# bhyve -A -c 4 -D -H -m 2G \ + -s 0,hostbridge \ + -s 1,lpc \ + -s 2,virtio-net,tap100 \ + -s 3,virtio-blk,/dev/zvol/zroot/vms/bhyvevm0 \ + -s 4,ahci-cd,/vms/FreeBSD-14.0-RELEASE-amd64-bootonly.iso \ + -s 31,fbuf,tcp=127.0.0.1:5900,w=1024,h=800,tablet \ + -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \ + -l com1,/dev/nmdbbhyve0A \ + bhyvevm0 +.... + +This will allow you to connect to your virtual machine `bhyvevm0` through VNC as well as a serial console at [.filename]#/dev/nmdbbhyve0B#. +==== + [[virtualization-bhyve-nmdm]] === Virtual Machine Consoles @@ -816,7 +1320,7 @@ Ubuntu 13.10 handbook ttyS0 handbook login: .... -To disconnect from a console, enter a newline (i.e. press `RETURN`) follwed by tilde (`~`), and finally dot (`.`). +To disconnect from a console, enter a newline (i.e. press `RETURN`) followed by tilde (`~`), and finally dot (`.`). Keep in mind that only the connection is dropped while the login session remains active. Another user connecting to the same console could therefore make use of any active sessions without having to first authenticate. For security reasons, it's therefore recommended to logout before disconnecting. @@ -851,7 +1355,7 @@ A specified virtual machine can be destroyed using `bhyvectl`: .... Destroying a virtual machine this way means killing it immediately. Any unsaved data will be lost, open files and filesystems may get corrupted. -To gracefully shut down a virtual machine, you can instead send a `TERM` signal to its bhyve process. This triggers an ACPI shutdown event for the guest: +To gracefully shut down a virtual machine, send a `TERM` signal to its bhyve process instead. This triggers an ACPI shutdown event for the guest: [source,shell] .... @@ -905,11 +1409,13 @@ There are numerous utilities and applications available in ports to help simplif [[virtualization-bhyve-onboot]] === Persistent Configuration -In order to configure the system to start bhyve guests at boot time, the following configurations must be made in the specified files: +In order to configure the system to start bhyve guests at boot time, some configuration file changes are required. [.procedure] . [.filename]#/etc/sysctl.conf# + +When using [.filename]#tap# interfaces as network backend, you either need to manually set each used [.filename]#tap# interface to UP or simply set the following sysctl: ++ [.programlisting] .... net.link.tap.up_on_open=1 @@ -917,12 +1423,38 @@ net.link.tap.up_on_open=1 . [.filename]#/etc/rc.conf# + -[.programlisting] +To connect your virtual machine's [.filename]#tap# device to the network via a [.filename]#bridge#, you need to persist the device settings in [.filename]#/etc/rc.conf#. +Additionally, you can load the necessary kernel modules `vmm` for bhyve and `nmdm` for [.filename]#nmdm# devices through the `kld_list` configuration variable. +When configuring `ifconfig_bridge0`, make sure to replace `<ipaddr>/<netmask>` with the actual IP address of your physical interface ([.filename]#igb0# in this example) and remove IP settings from your physical device. ++ +[source,shell] +.... +# sysrc cloned_interfaces+="bridge0 tap0" +# sysrc ifconfig_bridge0="inet <ipaddr>/<netmask> addm igb0 addm tap0" +# sysrc kld_list+="nmdm vmm" +# sysrc ifconfig_igb0="up" +.... + +[[virtualization-bhyve-onboot-bridgenet]] +.Setting the IP for a bridge device +[example] +==== +For a host with an _igb0_ interface connected to the network with IP `10.10.10.1` and netmask `255.255.255.0`, you would use the following commands: + +[source,shell] .... -cloned_interfaces="bridge0 tap0" -ifconfig_bridge0="addm igb0 addm tap0" -kld_list="nmdm vmm" +# sysrc ifconfig_igb0="up" +# sysrc ifconfig_bridge0="inet 10.10.10.1/24 addm igb0 addm tap0" +# sysrc kld_list+="nmdm vmm" +# sysrc cloned_interfaces+="bridge0 tap0" .... +==== + +[WARNING] +==== +Modifying the IP address configuration of a system may lock you out if you are executing these commands while you are connected remotely (i.e. via SSH)! +Take precautions to maintain system access or make those modifications while logged in on a local terminal session. +==== [[virtualization-host-xen]] == FreeBSD as a Xen(TM)-Host @@ -993,7 +1525,7 @@ Selecting a Xen(TM) kernel in [.filename]#/boot/loader.conf# activates the Dom0. Xen(TM) also requires resources like CPU and memory from the host machine for itself and other DomU domains. How much CPU and memory depends on the individual requirements and hardware capabilities. In this example, 8 GB of memory and 4 virtual CPUs are made available for the Dom0. -The serial console is also activated and logging options are defined. +The serial console is also activated, and logging options are defined. The following command is used for Xen 4.7 packages: @@ -1165,9 +1697,9 @@ This section contains basic information in order to help troubleshoot issues fou ==== Host Boot Troubleshooting Please note that the following troubleshooting tips are intended for Xen(TM) 4.11 or newer. -If you are still using Xen(TM) 4.7 and having issues consider migrating to a newer version of Xen(TM). +If you are still using Xen(TM) 4.7 and having issues, consider migrating to a newer version of Xen(TM). -In order to troubleshoot host boot issues you will likely need a serial cable, or a debug USB cable. +In order to troubleshoot host boot issues, you will likely need a serial cable, or a debug USB cable. Verbose Xen(TM) boot output can be obtained by adding options to the `xen_cmdline` option found in [.filename]#loader.conf#. A couple of relevant debug options are: @@ -1210,7 +1742,7 @@ libxl: debug: libxl_dom.c:988:libxl__load_hvm_firmware_module: Loading BIOS: /us ... .... -If the verbose output does not help diagnose the issue there are also QEMU and Xen(TM) toolstack logs in [.filename]#/var/log/xen#. +If the verbose output does not help diagnose the issue, there are also QEMU and Xen(TM) toolstack logs in [.filename]#/var/log/xen#. Note that the name of the domain is appended to the log name, so if the domain is named `freebsd` you should find a [.filename]#/var/log/xen/xl-freebsd.log# and likely a [.filename]#/var/log/xen/qemu-dm-freebsd.log#. Both log files can contain useful information for debugging. If none of this helps solve the issue, please send the description of the issue you are facing and as much information as possible to mailto:freebsd-xen@FreeBSD.org[freebsd-xen@FreeBSD.org] and mailto:xen-devel@lists.xenproject.org[xen-devel@lists.xenproject.org] in order to get help. diff --git a/documentation/content/en/books/handbook/wayland/_index.adoc b/documentation/content/en/books/handbook/wayland/_index.adoc index 2b1721c845..ce5b1aa0f3 100644 --- a/documentation/content/en/books/handbook/wayland/_index.adoc +++ b/documentation/content/en/books/handbook/wayland/_index.adoc @@ -49,7 +49,29 @@ include::../../../../../shared/asciidoctor.adoc[] endif::[] [[wayland-synopsis]] -== Wayland Synopsis +== Synopsis + +An installation of FreeBSD using bsdinstall does not automatically install a graphical user interface. +This chapter describes how to select, install, and configure a Wayland compositor, which provides a graphical environment. + +Before reading this chapter, you should: + +* Know how to install crossref:ports[ports,additional third-party software]. + +* How to identify and configure crossref:x11[x-graphic-card-drivers,drivers for your graphics hardware]. + +After reading this chapter, you will know: + +* How to configure FreeBSD to host a Wayland graphical environment. + +* How to install and configure a Wayland compositor. + +* How to run programs designed for the older X Window System. + +* How to configure remote desktop access to a Wayland graphical environment. + +[[wayland-overview]] +== Wayland Overview Wayland is a new display server, but it differs from Xorg in several important ways. First, Wayland is only a protocol that acts as an intermediary between clients using a different mechanism which removes the dependency on an X server. Xorg includes both the X11 protocol, used to run remote displays and the X server will accept connections and display windows. diff --git a/documentation/content/en/books/handbook/wine/_index.adoc b/documentation/content/en/books/handbook/wine/_index.adoc index 24b89b3777..f146bd6265 100644 --- a/documentation/content/en/books/handbook/wine/_index.adoc +++ b/documentation/content/en/books/handbook/wine/_index.adoc @@ -52,7 +52,7 @@ endif::[] == Synopsis https://www.winehq.org/[WINE], which stands for Wine Is Not an Emulator, is technically a software translation layer. -It enables to install and run some software written for Windows(R) on FreeBSD (and other) systems. +It allows installing and running software written for Windows(R) on FreeBSD (and other) systems. It operates by intercepting system calls, or requests from the software to the operating system, and translating them from Windows(R) calls to calls that FreeBSD understands. It will also translate any responses as needed into what the Windows(R) software is expecting. @@ -483,7 +483,7 @@ The below sections include a selection of the most popular. === Winetricks The `winetricks` tool is a cross-platform, general purpose helper program for WINE. -It is not developed by the WINE project proper, but rather maintained on https://github.com/Winetricks/winetricks[Github] by a group of contributors. +It is not developed by the WINE project proper, but rather maintained on https://github.com/Winetricks/winetricks[GitHub] by a group of contributors. It contains some automated "recipes" for getting common applications to work on WINE, both by optimizing the settings as well as acquiring some DLL libraries automatically. [[installing-winetricks]] @@ -556,7 +556,7 @@ image::winetricks-uninstall-3.png[] [[homura]] === Mizutamari -Mizutamari is an application similar to `winetricks`, although it was inspired by the https://lutris.net/[Lutris] gaming system for Linux. +https://codeberg.org/Alexander88207/Mizutamari[Mizutamari] is an application similar to `winetricks`, although it was inspired by the https://lutris.net/[Lutris] gaming system for Linux. But while it is focused on games, there are also non-gaming applications available for install through Mizutamari. [[installing-homura]] @@ -890,5 +890,5 @@ There are plenty of places FreeBSD users discuss issues related to WINE that can There are a number of resources focused on other operating systems that may be useful for FreeBSD users: * https://wiki.winehq.org/[The WINE Wiki] has a wealth of information on using WINE, much of which is applicable across many of WINE's supported operating systems. -* Similarly, the documentation available from other OS projects can also be of good value. https://wiki.archlinux.org/index.php/wine[The WINE page] on the Arch Linux Wiki is a particularly good example, although some of the "Third-party applications" (i.e., "companion applications") are obviously not available on FreeBSD. +* Similarly, the documentation available from other OS projects can also be of good value. https://wiki.archlinux.org/title/wine[The WINE page] on the Arch Linux Wiki is a particularly good example, although some of the "Third-party applications" (i.e., "companion applications") are obviously not available on FreeBSD. * Finally, Codeweavers (a developer of a commercial version of WINE) is an active upstream contributor. Oftentimes answers to questions in https://www.codeweavers.com/support/forums[their support forum] can be of aid in troubleshooting problems with the open source version of WINE. diff --git a/documentation/content/en/books/handbook/zfs/_index.adoc b/documentation/content/en/books/handbook/zfs/_index.adoc index 8dc05c7c06..2a44acce94 100644 --- a/documentation/content/en/books/handbook/zfs/_index.adoc +++ b/documentation/content/en/books/handbook/zfs/_index.adoc @@ -2813,7 +2813,7 @@ A configuration of two RAID-Z2 vdevs consisting of 8 disks each would create som |Instead of a consistency check like man:fsck[8], ZFS has `scrub`. `scrub` reads all data blocks stored on the pool and verifies their checksums against the known good checksums stored in the metadata. A periodic check of all the data stored on the pool ensures the recovery of any corrupted blocks before needing them. A scrub is not required after an unclean shutdown, but good practice is at least once every three months. ZFS verifies the checksum of each block during normal use, but a scrub makes certain to check even infrequently used blocks for silent corruption. ZFS improves data security in archival storage situations. Adjust the relative priority of `scrub` with <<zfs-advanced-tuning-scrub_delay,`vfs.zfs.scrub_delay`>> to prevent the scrub from degrading the performance of other workloads on the pool. |[[zfs-term-quota]]Dataset Quota -|ZFS provides fast and accurate dataset, user, and group space accounting as well as quotas and space reservations. This gives the administrator fine grained control over space allocation and allows reserving space for critical file systems. +a|ZFS provides fast and accurate dataset, user, and group space accounting as well as quotas and space reservations. This gives the administrator fine grained control over space allocation and allows reserving space for critical file systems. ZFS supports different types of quotas: the dataset quota, the <<zfs-term-refquota,reference quota (refquota)>>, the <<zfs-term-userquota,user quota>>, and the <<zfs-term-groupquota,group quota>>. diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc index c571a7d15a..ce23b68af7 100644 --- a/documentation/content/en/books/porters-handbook/uses/_index.adoc +++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc @@ -1692,7 +1692,7 @@ If Python is only needed at build time, run time or for the tests, it can be set If Python is also needed during the patch phase, use `patch`. See crossref:special[using-python, Using Python] for more information. -`PYTHON_NO_DEPENDS=yes` can be used when the variables exported by the framework are needed but a dependency on Python is not. +`USES=python:env` can be used when the variables exported by the framework are needed but a dependency on Python is not. It can happen when using with <<uses-shebangfix,`USES=shebangfix`>>, and the goal is only to fix the shebangs but not add a dependency on Python. [[uses-qmail]] @@ -1929,7 +1929,7 @@ Correct paths for supported interpreters are available in `_interp__CMD`. [TIP] ==== -When used with <<uses-python,`USES=python`>>, and the aim is only to fix the shebangs but a dependency on Python itself is not wanted, use `PYTHON_NO_DEPENDS=yes`. +When used with <<uses-python,`USES=python`>>, and the aim is only to fix the shebangs but a dependency on Python itself is not wanted, use `USES=python:env` instead. ==== [[uses-shebangfix-ex-lua]] diff --git a/documentation/content/en/books/porters-handbook/uses/_index.po b/documentation/content/en/books/porters-handbook/uses/_index.po index c7618a006d..59f08e0103 100644 --- a/documentation/content/en/books/porters-handbook/uses/_index.po +++ b/documentation/content/en/books/porters-handbook/uses/_index.po @@ -4715,7 +4715,7 @@ msgstr "" #. type: Plain text #: documentation/content/en/books/porters-handbook/uses/_index.adoc:1695 msgid "" -"`PYTHON_NO_DEPENDS=yes` can be used when the variables exported by the " +"`USES=python:env` can be used when the variables exported by the " "framework are needed but a dependency on Python is not. It can happen when " "using with <<uses-shebangfix,`USES=shebangfix`>>, and the goal is only to " "fix the shebangs but not add a dependency on Python." @@ -5242,7 +5242,7 @@ msgstr "" msgid "" "When used with <<uses-python,`USES=python`>>, and the aim is only to fix the " "shebangs but a dependency on Python itself is not wanted, use " -"`PYTHON_NO_DEPENDS=yes`." +"`USES=python:env` instead." msgstr "" #. type: Block title |