diff options
Diffstat (limited to 'documentation/content/en/books')
28 files changed, 181 insertions, 188 deletions
diff --git a/documentation/content/en/books/developers-handbook/secure/_index.adoc b/documentation/content/en/books/developers-handbook/secure/_index.adoc index 738a18988c..a871193a5b 100644 --- a/documentation/content/en/books/developers-handbook/secure/_index.adoc +++ b/documentation/content/en/books/developers-handbook/secure/_index.adoc @@ -69,7 +69,7 @@ UNIX(R) processes do not execute synchronously so logical operations are rarely [[secure-bufferov]] == Buffer Overflows -Buffer Overflows have been around since the very beginnings of the von Neumann crossref:bibliography[cod,1] architecture. +Buffer Overflows have been around since the very beginnings of the von Neumann crossref:bibliography[COD,1] architecture. They first gained widespread notoriety in 1988 with the Morris Internet worm. Unfortunately, the same basic attack remains effective today. By far the most common type of buffer overflow attack is based on corrupting the stack. @@ -81,7 +81,7 @@ This stack frame consists of the arguments passed to the function as well as a d The "stack pointer" is a register that holds the current location of the top of the stack. Since this value is constantly changing as new values are pushed onto the top of the stack, many implementations also provide a "frame pointer" that is located near the beginning of a stack frame so that local variables can more easily be addressed relative to this value. -crossref:bibliography[cod,1] The return address for function calls is also stored on the stack, and this is the cause of stack-overflow exploits since overflowing a local variable in a function can overwrite the return address of that function, potentially allowing a malicious user to execute any code he or she wants. +crossref:bibliography[COD,1] The return address for function calls is also stored on the stack, and this is the cause of stack-overflow exploits since overflowing a local variable in a function can overwrite the return address of that function, potentially allowing a malicious user to execute any code he or she wants. Although stack-based attacks are by far the most common, it would also be possible to overrun the stack with a heap-based (malloc/free) attack. diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc index ac4afa350c..cdd9147acb 100644 --- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc +++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc @@ -309,13 +309,9 @@ We are going to use as an example the header of the extref:{freebsd-releng}[Free :images-path: articles/freebsd-releng/ <1> -ifdef::env-beastie[] -ifdef::backend-html5[] - [...] :imagesdir: ../../../images/{images-path} <2> -endif::[] [...] diff --git a/documentation/content/en/books/handbook/advanced-networking/_index.adoc b/documentation/content/en/books/handbook/advanced-networking/_index.adoc index 42125e86d7..7090c1cd39 100644 --- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc +++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc @@ -758,7 +758,7 @@ The client machine found the AP and can be associated with it: This section focuses on setting up a FreeBSD access point using the WPA2 security protocol. More details regarding WPA and the configuration of WPA-based wireless clients -can be found in crossref:advanced-networking[network-wireless-wpa, WPA with EAP-TLS]. +can be found in crossref:advanced-networking[network-wireless-wpa-eap-tls, WPA with EAP-TLS]. The man:hostapd[8] daemon is used to deal with client authentication and key management on the WPA2-enabled AP. diff --git a/documentation/content/en/books/handbook/audit/_index.adoc b/documentation/content/en/books/handbook/audit/_index.adoc index 0c25670f22..e76b9b6b36 100644 --- a/documentation/content/en/books/handbook/audit/_index.adoc +++ b/documentation/content/en/books/handbook/audit/_index.adoc @@ -60,13 +60,13 @@ FreeBSD implements Sun(TM)'s published Basic Security Module (BSM) Application P This chapter focuses on the installation and configuration of event auditing. It explains audit policies and provides an example audit configuration. -After reading this chapter, you will know: +Read this chapter to learn: * What event auditing is and how it works. * How to configure event auditing on FreeBSD for users and processes. * How to review the audit trail using the audit reduction and review tools. -Before reading this chapter, you should: +Before reading this chapter: * Understand UNIX(R) and FreeBSD basics (crossref:basics[basics,FreeBSD Basics]). * Be familiar with the basics of kernel configuration/compilation (crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]). diff --git a/documentation/content/en/books/handbook/boot/_index.adoc b/documentation/content/en/books/handbook/boot/_index.adoc index 92a300d167..b8fe0c7e7c 100644 --- a/documentation/content/en/books/handbook/boot/_index.adoc +++ b/documentation/content/en/books/handbook/boot/_index.adoc @@ -59,7 +59,7 @@ This chapter details the configuration options that can be set. It demonstrates how to customize the FreeBSD boot process, including everything that happens until the FreeBSD kernel has started, probed for devices, and started man:init[8]. This occurs when the text color of the boot messages changes from bright white to grey. -After reading this chapter, you will recognize: +Read this chapter to learn: * The components of the FreeBSD bootstrap system and how they interact. * The options that can be passed to the components in the FreeBSD bootstrap in order to control the boot process. diff --git a/documentation/content/en/books/handbook/config/_index.adoc b/documentation/content/en/books/handbook/config/_index.adoc index 7675b13762..6089cf402d 100644 --- a/documentation/content/en/books/handbook/config/_index.adoc +++ b/documentation/content/en/books/handbook/config/_index.adoc @@ -55,11 +55,11 @@ endif::[] One of the important aspects of FreeBSD is proper system configuration. This chapter explains much of the FreeBSD configuration process, including some of the parameters which can be set to tune a FreeBSD system. -Before reading this chapter, you should: +Before reading this chapter: * Understand UNIX(R) and FreeBSD basics (crossref:basics[basics,FreeBSD Basics]). -After reading this chapter, you will know: +Read this chapter to learn: * How to use the various configuration files in [.filename]#/etc#. * The basics of [.filename]#rc.conf# configuration and [.filename]#/usr/local/etc/rc.d# startup scripts. diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc index 59e38e2bc9..04f7e9d37d 100644 --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -58,7 +58,7 @@ However, even official releases are often updated with security and other critic Regardless of the version used, FreeBSD provides all the necessary tools to keep the system updated, and allows for easy upgrades between versions. This chapter describes how to track the development system and the basic tools for keeping a FreeBSD system up-to-date. -After reading this chapter, you will know: +Read this chapter to learn: * How to keep a FreeBSD system up-to-date with freebsd-update or Git. * How to compare the state of an installed system against a known pristine copy. @@ -66,7 +66,7 @@ After reading this chapter, you will know: * The difference between the two development branches: FreeBSD-STABLE and FreeBSD-CURRENT. * How to rebuild and reinstall the entire base system. -Before reading this chapter, you should: +Before reading this chapter: * Properly set up the network connection (crossref:advanced-networking[advanced-networking,Advanced Networking]). * Know how to install additional third-party software (crossref:ports[ports,Installing Applications: Packages and Ports]). @@ -269,7 +269,7 @@ For example: * a kernel module that is built on 13.1 might *not* be suitable for 13.2. -So, with any minor or major OS upgrade, if your package requirements include any kernel module: +So, with any minor or major OS upgrade, if the package requirements include any kernel module: * *be prepared to build the module from source*. @@ -687,8 +687,8 @@ For example: Usually this number is not all that important. However, when bug fixes are committed, this number makes it easy to quickly determine whether the fix is present in the currently running system. Developers will often refer to the hash of the commit (or provide a URL which has that hash), but not the n-number since the hash is the easily visible identifier for a change while the n-number is not. -Security advisories and errata notices will also note an n-number, which can be directly compared against your system. -When you need to use shallow Git clones, you cannot compare n-numbers reliably as the `git rev-list` command counts all the revisions in the repository which a shallow clone omits. +Security advisories and errata notices will also note an n-number, which can be directly compared against the system. +When shallow Git clones are used, n-numbers cannot be compared reliably, as the git rev-list command counts all revisions in the repository, which a shallow clone omits. [[makeworld]] == Updating FreeBSD from Source @@ -1235,7 +1235,7 @@ To create a new boot environment using the man:bectl[8] tool run: Use this boot environment to start the system as it was before the update if something goes wrong. -Save a list of your non-base packages in case you need that later: +Save a list of the non-base packages in case they are needed later: [source,shell] .... @@ -1255,22 +1255,22 @@ FreeBSD-base { } .... -The next step will upgrade your system to the specified version. +The next step will upgrade the system to the specified version. [WARNING] ==== -This step might remove non-base packages, which could include your running desktop environment. +This step might remove non-base packages, which could include the running desktop environment. Be careful. ==== -Set the environment variable ABI to upgrade the major version (replace amd64 with your architecture and 15 with your targeted version). +Set the environment variable ABI to upgrade the major version (replace amd64 with the architecture and 15 with the targeted version). [source,shell] .... # env ABI=FreeBSD:15:amd64 pkg-static upgrade -r FreeBSD-base .... -There will be a prompt to ask if you want to ignore the version mismatch looking like this: +There will be a prompt to ask about ignoring the version mismatch looking like this: [source,shell] .... @@ -1303,12 +1303,12 @@ If something broke, go back and activate the backup boot environment created bef .... Reboot, and the system will be back to the state before upgrading. -If you haven't created a boot environment, you might want to consider getting help from link:https://www.freebsd.org/support/[FreeBSD Support]. +If no boot environment was created before, consider getting help from link:https://www.freebsd.org/support/[FreeBSD Support]. [[build-pkgbase-packages-locally]] === Manually building pkgbase and publishing it to the local network -If you want to start building your own pkgbase packages clone the FreeBSD source tree: +When building custom pkgbase packages clone the FreeBSD source tree: [source,shell] .... diff --git a/documentation/content/en/books/handbook/desktop/_index.adoc b/documentation/content/en/books/handbook/desktop/_index.adoc index 829a63d77c..fd6e26e695 100644 --- a/documentation/content/en/books/handbook/desktop/_index.adoc +++ b/documentation/content/en/books/handbook/desktop/_index.adoc @@ -813,7 +813,7 @@ Functionalities included with Qt Creator are: * code editor with C++, QML and ECMAscript support; * rapid code navigation tools; -* static code checking and style hints as you type; +* static code checking and style hints when typing; * context sensitive help; * visual debugger; * integrated GUI layout and forms designer. diff --git a/documentation/content/en/books/handbook/dtrace/_index.adoc b/documentation/content/en/books/handbook/dtrace/_index.adoc index 755a21404e..b2a8fb93b1 100644 --- a/documentation/content/en/books/handbook/dtrace/_index.adoc +++ b/documentation/content/en/books/handbook/dtrace/_index.adoc @@ -65,13 +65,13 @@ Some ports, such as package:databases/postgresql12-server[] and package:lang/php The official guide to DTrace is maintained by the illumos project at https://illumos.org/books/dtrace/bookinfo.html[illumos Dynamic Tracing Guide]. -After reading this chapter, you will know: +Read this chapter to learn: * What DTrace is and what features it provides. * Differences between the Solaris(TM) DTrace implementation and the one provided by FreeBSD. * How to enable and use DTrace on FreeBSD. -Before reading this chapter, you should: +Before reading this chapter: * Understand UNIX(R) and FreeBSD basics (crossref:basics[basics,FreeBSD Basics]). * Have some familiarity with security and how it pertains to FreeBSD (crossref:security[security,Security]). diff --git a/documentation/content/en/books/handbook/eresources/_index.adoc b/documentation/content/en/books/handbook/eresources/_index.adoc index d237a62b71..b63222c1af 100644 --- a/documentation/content/en/books/handbook/eresources/_index.adoc +++ b/documentation/content/en/books/handbook/eresources/_index.adoc @@ -96,10 +96,10 @@ When in doubt about what list to post a question to, see extref:{freebsd-questio Before posting to any list, please: * learn about how to best use the mailing lists, such as how to help avoid frequently-repeated discussions, by reading the extref:{mailing-list-faq}[Mailing List Frequently Asked Questions] (FAQ) document -* search the archives, to tell whether someone else has already posted what you intend to post. +* search the archives, to tell whether someone else has already posted the same. + +Archive search interfaces include: -Archive search interfaces include: - - https://lists.freebsd.org/search[] (FreeBSD, experimental) - https://www.freebsd.org/search/[] (DuckDuckGo) diff --git a/documentation/content/en/books/handbook/filesystems/_index.adoc b/documentation/content/en/books/handbook/filesystems/_index.adoc index 5e15895838..85652391bc 100644 --- a/documentation/content/en/books/handbook/filesystems/_index.adoc +++ b/documentation/content/en/books/handbook/filesystems/_index.adoc @@ -63,13 +63,13 @@ See crossref:zfs[zfs,The Z File System (ZFS)] for more details. In addition to its native file systems, FreeBSD supports a broad range of file systems from other operating systems. Support for these file systems varies, some require loading kernel modules, while others need additional userland tools. -Before reading this chapter, you should: +Before reading this chapter: * Be familiar with UNIX(R) concepts and crossref:basics[basics,FreeBSD basics]. * Feel comfortable crossref:ports[ports,installing software] in FreeBSD. * Have some understanding of crossref:disks[disks,disks], storage devices, and FreeBSD's naming conventions for devices. -After reading this chapter, you will: +Read this chapter to: * Understand the differences between native and supported file systems. * Know which file systems are supported by FreeBSD and the level of support available. diff --git a/documentation/content/en/books/handbook/firewalls/_index.adoc b/documentation/content/en/books/handbook/firewalls/_index.adoc index 00e7f7688d..399eb35317 100644 --- a/documentation/content/en/books/handbook/firewalls/_index.adoc +++ b/documentation/content/en/books/handbook/firewalls/_index.adoc @@ -71,7 +71,7 @@ Each firewall uses rules to control the access of packets to and from a FreeBSD FreeBSD provides multiple firewalls in order to meet the different requirements and preferences for a wide variety of users. Each user should evaluate which firewall best meets their needs. -After reading this chapter, you will know: +Read this chapter to learn: * How to define packet filtering rules. * The differences between the firewalls built into FreeBSD. @@ -79,7 +79,7 @@ After reading this chapter, you will know: * How to use and configure the IPFW firewall. * How to use and configure the IPFILTER firewall. -Before reading this chapter, you should: +Before reading this chapter: * Understand basic FreeBSD and Internet concepts. diff --git a/documentation/content/en/books/handbook/geom/_index.adoc b/documentation/content/en/books/handbook/geom/_index.adoc index a13b1d626c..47fc93b6e4 100644 --- a/documentation/content/en/books/handbook/geom/_index.adoc +++ b/documentation/content/en/books/handbook/geom/_index.adoc @@ -59,14 +59,14 @@ This chapter covers the use of disks under the GEOM framework in FreeBSD. This includes the major RAID control utilities which use the framework for configuration. This chapter is not a definitive guide to RAID configurations and only GEOM-supported RAID classifications are discussed. -After reading this chapter, you will know: +Read this chapter to learn: * What type of RAID support is available through GEOM. * How to use the base utilities to configure, maintain, and manipulate the various RAID levels. * How to mirror, stripe, encrypt, and remotely connect disk devices through GEOM. * How to troubleshoot disks attached to the GEOM framework. -Before reading this chapter, you should: +Before reading this chapter: * Understand how FreeBSD treats disk devices (crossref:disks[disks,Storage]). * Know how to configure and install a new kernel (crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]). diff --git a/documentation/content/en/books/handbook/glossary.adoc b/documentation/content/en/books/handbook/glossary.adoc index 005a10e66f..28439170fa 100644 --- a/documentation/content/en/books/handbook/glossary.adoc +++ b/documentation/content/en/books/handbook/glossary.adoc @@ -310,6 +310,7 @@ See crossref:glossary[elf-glossary,Executable and Linking Format]. ESP:: See crossref:glossary[esp-glossary,Encapsulated Security Payload]. +[[esp-glossary]] Encapsulated Security Payload:: {empty} diff --git a/documentation/content/en/books/handbook/jails/_index.adoc b/documentation/content/en/books/handbook/jails/_index.adoc index fd652694cc..ecc10a1a79 100644 --- a/documentation/content/en/books/handbook/jails/_index.adoc +++ b/documentation/content/en/books/handbook/jails/_index.adoc @@ -361,19 +361,19 @@ The userland for the jail can be obtained from the official FreeBSD download ser Execute the following command to download the userland: -[source,shell] +[source,shell,subs=attributes] .... -# fetch https://download.freebsd.org/ftp/releases/amd64/amd64/14.2-RELEASE/base.txz -o /usr/local/jails/media/14.2-RELEASE-base.txz +# fetch https://download.freebsd.org/ftp/releases/amd64/amd64/{betarel-current}-RELEASE/base.txz -o /usr/local/jails/media/{betarel-current}-RELEASE-base.txz .... Once the download is complete, it will be necessary to extract the contents into the jail directory. Execute the following commands to extract the userland into the jail's directory: -[source,shell] +[source,shell,subs=attributes] .... # mkdir -p /usr/local/jails/containers/classic -# tar -xf /usr/local/jails/media/14.2-RELEASE-base.txz -C /usr/local/jails/containers/classic --unlink +# tar -xf /usr/local/jails/media/{betarel-current}-RELEASE-base.txz -C /usr/local/jails/containers/classic --unlink .... With the userland extracted in the jail directory, it will be necessary to copy the timezone and DNS server files: @@ -449,56 +449,56 @@ For this reason they are created in "read-only" mode so that jails are created w To create the dataset for the template, execute the following command: -[source,shell] +[source,shell,subs=attributes] .... -# zfs create -p zroot/jails/templates/14.2-RELEASE +# zfs create -p zroot/jails/templates/{betarel-current}-RELEASE .... Then execute the following command to download the userland: -[source,shell] +[source,shell,subs=attributes] .... -# fetch https://download.freebsd.org/ftp/releases/amd64/amd64/14.2-RELEASE/base.txz -o /usr/local/jails/media/14.2-RELEASE-base.txz +# fetch https://download.freebsd.org/ftp/releases/amd64/amd64/{betarel-current}-RELEASE/base.txz -o /usr/local/jails/media/{betarel-current}-RELEASE-base.txz .... Once the download is complete, it will be necessary to extract the contents in the template directory by executing the following command: -[source,shell] +[source,shell,subs=attributes] .... -# tar -xf /usr/local/jails/media/14.2-RELEASE-base.txz -C /usr/local/jails/templates/14.2-RELEASE --unlink +# tar -xf /usr/local/jails/media/{betarel-current}-RELEASE-base.txz -C /usr/local/jails/templates/{betarel-current}-RELEASE --unlink .... With the userland extracted in the templates directory, it will be necessary to copy the timezone and DNS server files to the template directory by executing the following command: -[source,shell] +[source,shell,subs=attributes] .... -# cp /etc/resolv.conf /usr/local/jails/templates/14.2-RELEASE/etc/resolv.conf -# cp /etc/localtime /usr/local/jails/templates/14.2-RELEASE/etc/localtime +# cp /etc/resolv.conf /usr/local/jails/templates/{betarel-current}-RELEASE/etc/resolv.conf +# cp /etc/localtime /usr/local/jails/templates/{betarel-current}-RELEASE/etc/localtime .... The next thing to do is update to the latest patch level by executing the following command: -[source,shell] +[source,shell,subs=attributes] .... -# freebsd-update -b /usr/local/jails/templates/14.2-RELEASE/ fetch install +# freebsd-update -b /usr/local/jails/templates/{betarel-current}-RELEASE/ fetch install .... Once the update is finished, the template is ready. To create an OpenZFS Snapshot from the template, execute the following command: -[source,shell] +[source,shell,subs=attributes] .... -# zfs snapshot zroot/jails/templates/14.2-RELEASE@base +# zfs snapshot zroot/jails/templates/{betarel-current}-RELEASE@base .... Once the OpenZFS Snapshot has been created, infinite jails can be created using the OpenZFS clone function. To create a Thin Jail named `thinjail`, execute the following command: -[source,shell] +[source,shell,subs=attributes] .... -# zfs clone zroot/jails/templates/14.2-RELEASE@base zroot/jails/containers/thinjail +# zfs clone zroot/jails/templates/{betarel-current}-RELEASE@base zroot/jails/containers/thinjail .... The last step is to configure the jail. @@ -546,45 +546,45 @@ A jail can be created with reduced duplication of system files by using the Thin The first step is to create the dataset to save the template, execute the following command if using OpenZFS: -[source,shell] +[source,shell,subs=attributes] .... -# zfs create -p zroot/jails/templates/14.2-RELEASE-base +# zfs create -p zroot/jails/templates/{betarel-current}-RELEASE-base .... Or this one if using UFS: -[source,shell] +[source,shell,subs=attributes] .... -# mkdir /usr/local/jails/templates/14.2-RELEASE-base +# mkdir /usr/local/jails/templates/{betarel-current}-RELEASE-base .... Then execute the following command to download the userland: -[source,shell] +[source,shell,subs=attributes] .... -# fetch https://download.freebsd.org/ftp/releases/amd64/amd64/14.2-RELEASE/base.txz -o /usr/local/jails/media/14.2-RELEASE-base.txz +# fetch https://download.freebsd.org/ftp/releases/amd64/amd64/{betarel-current}-RELEASE/base.txz -o /usr/local/jails/media/{betarel-current}-RELEASE-base.txz .... Once the download is complete, it will be necessary to extract the contents in the template directory by executing the following command: -[source,shell] +[source,shell,subs=attributes] .... -# tar -xf /usr/local/jails/media/14.2-RELEASE-base.txz -C /usr/local/jails/templates/14.2-RELEASE-base --unlink +# tar -xf /usr/local/jails/media/{betarel-current}-RELEASE-base.txz -C /usr/local/jails/templates/{betarel-current}-RELEASE-base --unlink .... Once the userland is extracted in the templates directory, it will be necessary to copy the timezone and DNS server files to the template directory by executing the following command: -[source,shell] +[source,shell,subs=attributes] .... -# cp /etc/resolv.conf /usr/local/jails/templates/14.2-RELEASE-base/etc/resolv.conf -# cp /etc/localtime /usr/local/jails/templates/14.2-RELEASE-base/etc/localtime +# cp /etc/resolv.conf /usr/local/jails/templates/{betarel-current}-RELEASE-base/etc/resolv.conf +# cp /etc/localtime /usr/local/jails/templates/{betarel-current}-RELEASE-base/etc/localtime .... With the files moved to the template, the next thing to do is update to the latest patch level by executing the following command: -[source,shell] +[source,shell,subs=attributes] .... -# freebsd-update -b /usr/local/jails/templates/14.2-RELEASE-base/ fetch install +# freebsd-update -b /usr/local/jails/templates/{betarel-current}-RELEASE-base/ fetch install .... In addition to the base template, it is also necessary to create a directory where the `skeleton` will be located. @@ -592,16 +592,16 @@ Some directories will be copied from the template to the `skeleton`. Execute the following command to create the dataset for the `skeleton` in case of using OpenZFS: -[source,shell] +[source,shell,subs=attributes] .... -# zfs create -p zroot/jails/templates/14.2-RELEASE-skeleton +# zfs create -p zroot/jails/templates/{betarel-current}-RELEASE-skeleton .... Or this one in case of using UFS: -[source,shell] +[source,shell,subs=attributes] .... -# mkdir /usr/local/jails/templates/14.2-RELEASE-skeleton +# mkdir /usr/local/jails/templates/{betarel-current}-RELEASE-skeleton .... Then create the `skeleton` directories. @@ -609,22 +609,22 @@ The `skeleton` directories will hold the local directories of the jails. Execute the following commands to create the directories: -[source,shell] +[source,shell,subs=attributes] .... -# mkdir -p /usr/local/jails/templates/14.2-RELEASE-skeleton/home -# mkdir -p /usr/local/jails/templates/14.2-RELEASE-skeleton/usr -# mv /usr/local/jails/templates/14.2-RELEASE-base/etc /usr/local/jails/templates/14.2-RELEASE-skeleton/etc -# mv /usr/local/jails/templates/14.2-RELEASE-base/usr/local /usr/local/jails/templates/14.2-RELEASE-skeleton/usr/local -# mv /usr/local/jails/templates/14.2-RELEASE-base/tmp /usr/local/jails/templates/14.2-RELEASE-skeleton/tmp -# mv /usr/local/jails/templates/14.2-RELEASE-base/var /usr/local/jails/templates/14.2-RELEASE-skeleton/var -# mv /usr/local/jails/templates/14.2-RELEASE-base/root /usr/local/jails/templates/14.2-RELEASE-skeleton/root +# mkdir -p /usr/local/jails/templates/{betarel-current}-RELEASE-skeleton/home +# mkdir -p /usr/local/jails/templates/{betarel-current}-RELEASE-skeleton/usr +# mv /usr/local/jails/templates/{betarel-current}-RELEASE-base/etc /usr/local/jails/templates/{betarel-current}-RELEASE-skeleton/etc +# mv /usr/local/jails/templates/{betarel-current}-RELEASE-base/usr/local /usr/local/jails/templates/{betarel-current}-RELEASE-skeleton/usr/local +# mv /usr/local/jails/templates/{betarel-current}-RELEASE-base/tmp /usr/local/jails/templates/{betarel-current}-RELEASE-skeleton/tmp +# mv /usr/local/jails/templates/{betarel-current}-RELEASE-base/var /usr/local/jails/templates/{betarel-current}-RELEASE-skeleton/var +# mv /usr/local/jails/templates/{betarel-current}-RELEASE-base/root /usr/local/jails/templates/{betarel-current}-RELEASE-skeleton/root .... The next step is to create the symlinks to the `skeleton` by executing the following commands: -[source,shell] +[source,shell,subs=attributes] .... -# cd /usr/local/jails/templates/14.2-RELEASE-base/ +# cd /usr/local/jails/templates/{betarel-current}-RELEASE-base/ # mkdir skeleton # ln -s skeleton/etc etc # ln -s skeleton/home home @@ -638,17 +638,17 @@ With the `skeleton` ready, it will be necessary to copy the data to the jail dir In case of using OpenZFS, OpenZFS snapshots can be used to easily create as many jails as necessary by executing the following commands: -[source,shell] +[source,shell,subs=attributes] .... -# zfs snapshot zroot/jails/templates/14.2-RELEASE-skeleton@base -# zfs clone zroot/jails/templates/14.2-RELEASE-skeleton@base zroot/jails/containers/thinjail +# zfs snapshot zroot/jails/templates/{betarel-current}-RELEASE-skeleton@base +# zfs clone zroot/jails/templates/{betarel-current}-RELEASE-skeleton@base zroot/jails/containers/thinjail .... In case of using UFS the man:cp[1] program can be used by executing the following command: -[source,shell] +[source,shell,subs=attributes] .... -# cp -R /usr/local/jails/templates/14.2-RELEASE-skeleton /usr/local/jails/containers/thinjail +# cp -R /usr/local/jails/templates/{betarel-current}-RELEASE-skeleton /usr/local/jails/containers/thinjail .... Then create the directory in which the base template and the skeleton will be mounted: @@ -688,9 +688,9 @@ thinjail { Then the create the [.filename]#/usr/local/jails/thinjail-nullfs-base.fstab# file as follows: -[.programlisting] +[.programlisting,subs=attributes] .... -/usr/local/jails/templates/14.2-RELEASE-base /usr/local/jails/thinjail-nullfs-base/ nullfs ro 0 0 +/usr/local/jails/templates/{betarel-current}-RELEASE-base /usr/local/jails/thinjail-nullfs-base/ nullfs ro 0 0 /usr/local/jails/containers/thinjail /usr/local/jails/thinjail-nullfs-base/skeleton nullfs rw 0 0 .... diff --git a/documentation/content/en/books/handbook/kernelconfig/_index.adoc b/documentation/content/en/books/handbook/kernelconfig/_index.adoc index 5e035105b6..9769a57018 100644 --- a/documentation/content/en/books/handbook/kernelconfig/_index.adoc +++ b/documentation/content/en/books/handbook/kernelconfig/_index.adoc @@ -56,7 +56,7 @@ The kernel is the core of the FreeBSD operating system. It is responsible for managing memory, enforcing security controls, networking, disk access, and much more. While much of FreeBSD is dynamically configurable, some users may wish to configure and compile a custom kernel. -After reading this chapter, you will know: +Read this chapter to learn: * When to build a custom kernel. * How to take a hardware inventory. @@ -204,7 +204,7 @@ The format of the kernel configuration file is simple. Each line contains a keyword that represents a device or subsystem, an argument, and a brief description. Any text after a `+#+` is considered a comment and ignored. To remove kernel support for a device or subsystem, put a `+#+` at the beginning of the line representing that device or subsystem. -Do not add or remove a `+#+` for any line that you do not understand. +Do not add or remove a `+#+` for any line that is not understand. [WARNING] ==== diff --git a/documentation/content/en/books/handbook/l10n/_index.adoc b/documentation/content/en/books/handbook/l10n/_index.adoc index 83ce371621..73d5f3cd99 100644 --- a/documentation/content/en/books/handbook/l10n/_index.adoc +++ b/documentation/content/en/books/handbook/l10n/_index.adoc @@ -61,7 +61,8 @@ L10n uses the same naming scheme, but from `localization`. The i18n/L10n methods, protocols, and applications allow users to use languages of their choice. This chapter discusses the internationalization and localization features of FreeBSD. -After reading this chapter, you will know: + +Read this chapter to learn: * How locale names are constructed. * How to set the locale for a login shell. @@ -70,7 +71,7 @@ After reading this chapter, you will know: * How to find i18n-compliant applications. * Where to find more information for configuring specific languages. -Before reading this chapter, you should: +Before reading this chapter: * Know how to crossref:ports[ports,install additional third-party applications]. diff --git a/documentation/content/en/books/handbook/linuxemu/_index.adoc b/documentation/content/en/books/handbook/linuxemu/_index.adoc index 1f0c07c540..292af09e70 100644 --- a/documentation/content/en/books/handbook/linuxemu/_index.adoc +++ b/documentation/content/en/books/handbook/linuxemu/_index.adoc @@ -56,11 +56,11 @@ FreeBSD provides *optional* binary compatibility with Linux(R), commonly referre It is available for the x86 (both 32 and 64 bit) and AArch64 architectures. Some Linux-specific operating system features are not yet supported; this mostly happens with functionality specific to hardware or related to system management, such as cgroups or namespaces. -Before reading this chapter, you should: +Before reading this chapter: * Know how to install crossref:ports[ports,additional third-party software]. -After reading this chapter, you will know: +Read this chapter to learn: * How to enable Linux binary compatibility on a FreeBSD system. * How to install additional Linux shared libraries. diff --git a/documentation/content/en/books/handbook/mac/_index.adoc b/documentation/content/en/books/handbook/mac/_index.adoc index 8a99185537..79745411de 100644 --- a/documentation/content/en/books/handbook/mac/_index.adoc +++ b/documentation/content/en/books/handbook/mac/_index.adoc @@ -62,7 +62,7 @@ This is in contrast to the default security mechanism of Discretionary Access Co This chapter focuses on the MAC framework and the set of pluggable security policy modules FreeBSD provides for enabling various security mechanisms. -After reading this chapter, you will know: +Read this chapter to learn: * The terminology associated with the MAC framework. * The capabilities of MAC security policy modules as well as the difference between a labeled and non-labeled policy. @@ -71,7 +71,7 @@ After reading this chapter, you will know: * How to implement a more secure environment using the MAC framework. * How to test the MAC configuration to ensure the framework has been properly implemented. -Before reading this chapter, you should: +Before reading this chapter: * Understand UNIX(R) and FreeBSD basics (crossref:basics[basics,FreeBSD Basics]). * Have some familiarity with security and how it pertains to FreeBSD (crossref:security[security,Security]). diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc index e60a92988d..a43bbecb46 100644 --- a/documentation/content/en/books/handbook/mirrors/_index.adoc +++ b/documentation/content/en/books/handbook/mirrors/_index.adoc @@ -257,10 +257,6 @@ Mirror list maintained by the community and other companies: | link:http://ftp.si.FreeBSD.org/pub/FreeBSD[http] link:http://ftp.si.FreeBSD.org/pub/FreeBSD[http_v6] link:ftp://ftp.si.FreeBSD.org/pub/FreeBSD[ftp] link:ftp://ftp.si.FreeBSD.org/pub/FreeBSD[ftp_v6] | South Africa icon:envelope[link=mailto:{mirrors-south-africa-email}, title="mirror contact"] -| ftp.za.FreeBSD.org -| link:https://ftp.za.FreeBSD.org/pub/FreeBSD[https] link:https://ftp.za.FreeBSD.org/pub/FreeBSD[https_v6] link:rsync://ftp.za.FreeBSD.org[rsync] link:rsync://ftp.za.FreeBSD.org[rsync_v6] - -| | ftp2.za.FreeBSD.org | link:http://ftp2.za.FreeBSD.org/pub/FreeBSD[http] link:http://ftp2.za.FreeBSD.org/pub/FreeBSD[http_v6] link:ftp://ftp2.za.FreeBSD.org/pub/FreeBSD[ftp_v6] diff --git a/documentation/content/en/books/handbook/ports/_index.adoc b/documentation/content/en/books/handbook/ports/_index.adoc index a6e68a7137..0aea47b7b5 100644 --- a/documentation/content/en/books/handbook/ports/_index.adoc +++ b/documentation/content/en/books/handbook/ports/_index.adoc @@ -201,7 +201,7 @@ To switch man:pkg[8] from Quarterly to Latest run the following commands: [source,shell] .... # mkdir -p /usr/local/etc/pkg/repos -# echo 'FreeBSD: { url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest" }' > /usr/local/etc/pkg/repos/FreeBSD.conf +# echo 'FreeBSD: { url: "pkg+https://pkg.FreeBSD.org/${ABI}/latest" }' > /usr/local/etc/pkg/repos/FreeBSD.conf .... Then run this command to update the local package repositories catalogues for the Latest branch: @@ -1303,13 +1303,13 @@ FreeBSD: { Usually it is easiest to serve a poudriere repository to the client machines via HTTP. Set up a webserver to serve up the package directory, for instance: `/usr/local/poudriere/data/packages/13amd64`, where `13amd64` is the name of the build. -If the URL to the package repository is: `http://pkg.example.com/13amd64`, +If the URL to the package repository is: `https://pkg.example.com/13amd64`, then the repository configuration file in `/usr/local/etc/pkg/repos/custom.conf` would look like: [.programlisting] .... custom: { - url: "http://pkg.example.com/13amd64", + url: "https://pkg.example.com/13amd64", enabled: yes, } .... diff --git a/documentation/content/en/books/handbook/preface/_index.adoc b/documentation/content/en/books/handbook/preface/_index.adoc index dfed27ebd1..0c9fcd9dfb 100644 --- a/documentation/content/en/books/handbook/preface/_index.adoc +++ b/documentation/content/en/books/handbook/preface/_index.adoc @@ -74,7 +74,7 @@ These are the major updates since the fourth edition of the Handbook. * The crossref:desktop[desktop, Desktop] chapter has been updated with upgraded installation instructions for KDE Plasma, GNOME, XFCE, MATE, Cinnamon, and LXQT, expanded browser options, a new development tools section, and updates to office productivity, document viewers, and finance sections. * The crossref:multimedia[multimedia, Multimedia] chapter has been reworked with updates to the sound section, new tables for sound mixers, audio players, and video players, guidance on automatic headphone switching, a new conferencing and meetings section, and a revised image scanners section. * The crossref:linuxemu[linuxemu, Linuxemu] chapter has been improved with updated instructions for setting up a Debian/Ubuntu base system using debootstrap. -* The crossref:config[config, Config] chapter has been renamed for accuracy, with updates to service management, cron and periodic, syslog, power management, and swap sections. A new entry on config files was added, and the outdated tuning section was removed. +* The crossref:config[config-tuning, Config] chapter has been renamed for accuracy, with updates to service management, cron and periodic, syslog, power management, and swap sections. A new entry on config files was added, and the outdated tuning section was removed. * The crossref:security[security, Security] chapter has been updated with enhancements to VPN over IPSec, securing accounts, password hashes, sudo/doas, and OpenSSH/OpenSSL. New sections have been added covering IDS, secure levels, file flags, Capsicum, NFSv4 ACLs, and resource limits. * The crossref:jails[jails, Jails] chapter has been updated to include details on jail types (Thick, Thin, VNET, and Linux Jails), host system configuration, networking options, the jail configuration file, setup procedures, upgrade methods, resource limits, and different jail managers and container solutions. * The crossref:mail[mail, Mail] chapter has been updated to include information on DMA, upgrades to Sendmail, instructions for changing DMA and Sendmail to use different MTAs, and the removal of Dialup and Fetchmail sections, along with a reorganization of the chapter. diff --git a/documentation/content/en/books/handbook/wayland/_index.adoc b/documentation/content/en/books/handbook/wayland/_index.adoc index aa402971ff..4d57d605c7 100644 --- a/documentation/content/en/books/handbook/wayland/_index.adoc +++ b/documentation/content/en/books/handbook/wayland/_index.adoc @@ -55,13 +55,13 @@ endif::[] 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: +Before reading this chapter: * 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]. +* Know how to identify and configure crossref:x11[x-graphic-card-drivers,drivers for the graphics hardware]. -After reading this chapter, you will know: +Read this chapter to learn: * How to configure FreeBSD to host a Wayland graphical environment. @@ -376,7 +376,7 @@ The Sway compositor is a tiling compositor that attempts to replace the i3 windo It should work with the user's current i3 configuration; however, new features may require some additional setup. Before starting the Sway installation, ensure that a graphics card (GPU) is installed and configured correctly. -Refer to the section crossref:x11[x-graphic-card-drivers,drivers for your graphics hardware] for guidance. +Refer to the section crossref:x11[x-graphic-card-drivers,drivers for the graphics hardware] for guidance. This step is essential for the Sway compositor to function properly. In the forthcoming examples, a fresh installation without migrating any i3 configuration will be assumed. @@ -403,7 +403,7 @@ Several important changes should be made like the following: # Logo key. Use Mod1 for Alt. input * xkb_rules evdev set $mod Mod4 -# Your preferred terminal emulator +# The preferred terminal emulator set $term alacritty set $lock swaylock -f -c 000000 output "My Workstation" mode 1366x768@60Hz position 1366 0 diff --git a/documentation/content/en/books/handbook/x11/_index.adoc b/documentation/content/en/books/handbook/x11/_index.adoc index 0cefe7bbcd..f549ceffec 100644 --- a/documentation/content/en/books/handbook/x11/_index.adoc +++ b/documentation/content/en/books/handbook/x11/_index.adoc @@ -59,14 +59,14 @@ This chapter describes how to install and configure the man:Xorg[1] server, which provides the open source X Window System (colloquially X11) used to provide a graphical environment. -Before reading this chapter, you should: +Before reading this chapter: * Know how to install additional third-party software as described in crossref:ports[ports,Installing Applications: Packages and Ports]. -After reading this chapter, you will know: +Read this chapter to learn: -* How to select and install drivers for your graphics processor (GPU). +* How to select and install drivers for the graphics processor (GPU). * The various components of the X Window System, and how they interoperate. * How to install and configure the X.org server. @@ -75,7 +75,7 @@ and how they interoperate. [[x-graphic-card-drivers]] == Graphics Drivers -_**abstract**: Identify your GPU, the port providing a driver for it, +_**abstract**: Identify the GPU, the port providing a driver for it, install it, then enable it to run at subsequent boot with man:sysrc[8]._ Before FreeBSD can render a graphical environment, @@ -308,7 +308,7 @@ To enable the driver, add the module to # sysrc kld_list+=nvidia-drm .... -This is the direct rendering crossref:glossary[glossary-kms,KMS] driver. +This is the direct rendering crossref:glossary[kms-glossary,KMS] driver. Kernel modesetting is the option to set the graphics mode in the kernel. Enable it for subsequent boots with the following man:loader.conf[5] @@ -403,7 +403,7 @@ Some applications require these additional components to function. [[x-config]] == X.org Configuration -_**abstract**: If the defaults for your monitor or input devices, +_**abstract**: If the defaults for the monitor or input devices, are not satisfactory, crossref:desktop[desktop-synopsis,desktops] include GUIs for configuring them, or they can be configured manually._ @@ -701,7 +701,7 @@ library, a cross-platform effort to support all touch, pointing, and keyboard devices under a unified library. Unless specified otherwise, this is loaded automatically. -Individual device settings for man:libinput[4] can be tuned in your +Individual device settings for man:libinput[4] can be tuned in the crossref:desktop[desktop-synopsis,desktop's] GUI, or manually with package:x11/xinput[xinput] and package:x11/setxkbmap[setxkbmap]. @@ -716,7 +716,7 @@ Both are described in this subsection. ==== Using Atomic Input Configuration Devices supported by man:libinput[4] can be configured -with graphical utilities included with your +with graphical utilities included with the crossref:desktop[desktop-synopsis,desktop] of choice, or manually and atomically at runtime with package:x11/xinput[] and package:x11/setxkbmap[]. @@ -751,9 +751,9 @@ All settings supported by these devices are provided as properties, which can be listed and set atomically. Pointing devices have many configurable properties, keyboards usually need none. -To customize your keyboard, take a look at man:setxkbmap[1]. +To customize the keyboard, take a look at man:setxkbmap[1]. -Once satisfied with your configuration, simply add the lines to your +Once satisfied with the configuration, simply add the lines to the X initialization script such as [.filename]#~/.Xsession# or [.filename]#~/.xinitrc#. [[x-config-input-file]] diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc index e98d2ff336..e6842bec60 100644 --- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc +++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc @@ -1073,7 +1073,11 @@ In addition, proposed category changes just naturally seem to attract controvers Here is the procedure: [.procedure] -. Propose the new category on {freebsd-ports}. Include a detailed rationale for the new category, including why the existing categories are not sufficient, and the list of existing ports proposed to move. (If there are new ports pending in Bugzilla that would fit this category, list them too.) If you are the maintainer and/or submitter, respectively, mention that as it may help the case. +. Propose the new category on {freebsd-ports}. Include a detailed rationale + for the new category, including why the existing categories are not + sufficient, and the list of existing ports proposed to move. (If there are + new ports pending in Bugzilla that would fit this category, list them + too.) Indicating that the updater is also the maintainer or submitter may be helpful to the case. . Participate in the discussion. . If it seems that there is support for the idea, file a PR which includes both the rationale and the list of existing ports that need to be moved. Ideally, this PR would also include these patches: @@ -1121,7 +1125,7 @@ If `DISTVERSION` does not derive a correct `PORTVERSION`, do not use `DISTVERSIO ==== If the upstream version scheme can be derived into a ports-compatible version scheme, set some variable to the upstream version, _do not_ use `DISTVERSION` as the variable name. -Set `PORTVERSION` to the computed version based on the variable you created, and set `DISTNAME` accordingly. +Set `PORTVERSION` to the computed version based on the created variable and set `DISTNAME` accordingly. If the upstream version scheme cannot easily be coerced into a ports-compatible value, set `PORTVERSION` to a sensible value, and set `DISTNAME` with `PORTNAME` with the verbatim upstream version. @@ -2202,7 +2206,7 @@ This is a very interesting feature which can decrease that endless search for th Just picture 2 files in `DISTFILES` and 20 sites in `MASTER_SITES`, the sites slow as hell where [.filename]#beta# is carried by all sites in `MASTER_SITES`, and [.filename]#alpha# can only be found in the 20th site. It would be such a waste to check all of them if the maintainer knew this beforehand, would it not? Not a good start for that lovely weekend! -Now that you have the idea, just imagine more `DISTFILES` and more `MASTER_SITES`. +Once the concept is clear, just imagine more `DISTFILES` and more `MASTER_SITES`. Surely our "distfiles survey meister" would appreciate the relief to network strain that this would bring. In the next sections, information will follow on the FreeBSD implementation of this idea. @@ -2286,8 +2290,7 @@ Furthermore, `DEFAULT` is a special purpose word (check item crossref:makefiles[porting-master-sites-n-DEFAULT-group,3]). . Elements postfixed with `:n` belong to the group `n`, `:m` belong to group `m` and so forth. + -[[porting-master-sites-n-DEFAULT-group]] -. Elements without a postfix are groupless, they all belong to the special group +. [[porting-master-sites-n-DEFAULT-group]] Elements without a postfix are groupless, they all belong to the special group `DEFAULT`. Any elements postfixed with `DEFAULT`, is just being redundant unless an element belongs to both `DEFAULT` and other groups at the same time (check item crossref:makefiles[porting-master-sites-n-comma-operator,5]). @@ -2306,8 +2309,7 @@ MASTER_SITES= alpha:DEFAULT . Groups are not exclusive, an element may belong to several different groups at the same time and a group can either have either several different elements or none at all. + -[[porting-master-sites-n-comma-operator]] -. When an element belongs to several groups at the same time, use the comma operator (`,`). +. [[porting-master-sites-n-comma-operator]] When an element belongs to several groups at the same time, use the comma operator (`,`). + Instead of repeating it several times, each time with a different postfix, we can list several groups at once in a single postfix. For instance, `:m,n,o` marks an element that belongs to group `m`, `n` and `o`. @@ -2336,8 +2338,7 @@ MASTER_SITES= alpha:DEFAULT,SOME_SITE . All sites within a given group are sorted according to `MASTER_SORT_AWK`. All groups within `MASTER_SITES` and `PATCH_SITES` are sorted as well. + -[[porting-master-sites-n-group-semantics]] -. Group semantics can be used in any of the variables `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR`, `PATCH_SITE_SUBDIR`, `DISTFILES`, and `PATCHFILES` according to this syntax: +. [[porting-master-sites-n-group-semantics]] Group semantics can be used in any of the variables `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR`, `PATCH_SITE_SUBDIR`, `DISTFILES`, and `PATCHFILES` according to this syntax: .. All `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR` elements must be terminated with the forward slash `/` character. If any elements belong to any groups, the group postfix `:__n__` @@ -2488,8 +2489,7 @@ PATCHFILES= patch1:test according to the aforementioned syntax rules, especially as shown in item crossref:makefiles[porting-master-sites-n-group-semantics, 7]. + -[[porting-master-sites-n-what-changes-in-port-targets]] -. The port targets remain the same: `checksum`, `makesum`, `patch`, `configure`, `build`, etc. With the obvious exceptions of `do-fetch`, `fetch-list`, `master-sites` and `patch-sites`. +. [[porting-master-sites-n-what-changes-in-port-targets]] The port targets remain the same: `checksum`, `makesum`, `patch`, `configure`, `build`, etc. With the obvious exceptions of `do-fetch`, `fetch-list`, `master-sites` and `patch-sites`. ** `do-fetch`: deploys the new grouping postfixed `DISTFILES` and `PATCHFILES` with their matching group elements within both `MASTER_SITES` and @@ -2507,8 +2507,7 @@ crossref:makefiles[porting-master-sites-n-new-port-targets-master-sites-all, B] . New port targets .. There are `master-sites-_n_` and `patch-sites-_n_` targets which will list the elements of the respective group _n_ within `MASTER_SITES` and `PATCH_SITES` respectively. For instance, both `master-sites-DEFAULT` and `patch-sites-DEFAULT` will return the elements of group `DEFAULT`, `master-sites-test` and `patch-sites-test` of group `test`, and thereon. + -[[porting-master-sites-n-new-port-targets-master-sites-all]] -.. There are new targets `master-sites-all` and `patch-sites-all` which do the work of the old `master-sites` and `patch-sites` ones. They return the elements of all groups as if they all belonged to the same group with the caveat that it lists as many `MASTER_SITE_BACKUP` and `MASTER_SITE_OVERRIDE` as there are groups defined within either `DISTFILES` or `PATCHFILES`; respectively for `master-sites-all` and `patch-sites-all`. +.. [[porting-master-sites-n-new-port-targets-master-sites-all]] There are new targets `master-sites-all` and `patch-sites-all` which do the work of the old `master-sites` and `patch-sites` ones. They return the elements of all groups as if they all belonged to the same group with the caveat that it lists as many `MASTER_SITE_BACKUP` and `MASTER_SITE_OVERRIDE` as there are groups defined within either `DISTFILES` or `PATCHFILES`; respectively for `master-sites-all` and `patch-sites-all`. [[makefile-dist_subdir]] === `DIST_SUBDIR` @@ -2527,7 +2526,7 @@ This does not affect `MASTER_SITES` defined in the [.filename]#Makefile#. [[makefile-maintainer]] == `MAINTAINER` -Set your mail-address here. Please. _:-)_ +Set the mail-address here. Please. _:-)_ Only a single address without the comment part is allowed as a `MAINTAINER` value. The format used is `user@hostname.domain`. @@ -3713,7 +3712,7 @@ Perl related variables are described in crossref:special[using-perl,Using Perl]. X11 variables are listed in crossref:special[using-x11,Using X11]. crossref:special[using-gnome,Using Gnome] deals with GNOME and crossref:special[using-kde,Using KDE] with KDE related variables. crossref:special[using-java,Using Java] documents Java variables, while crossref:special[using-php,Web Applications, Apache and PHP] contains information on Apache, PHP and PEAR modules. -Python is discussed in crossref:special[using-python,Using Python], while Ruby in crossref:special[using-ruby,Using Ruby]. +Python is discussed in crossref:special[using-python,Using Python], while Ruby in crossref:uses[uses-ruby,Ruby]. crossref:special[using-sdl,Using SDL] provides variables used for SDL applications and finally, crossref:special[using-xfce,Using Xfce] contains information on Xfce. [[makefile-version-dependency]] diff --git a/documentation/content/en/books/porters-handbook/testing/_index.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc index 4c94b4fc85..85433d1df0 100644 --- a/documentation/content/en/books/porters-handbook/testing/_index.adoc +++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc @@ -293,41 +293,41 @@ Create the base jails which poudriere will use for building: [source,shell] .... -# poudriere jail -c -j 131Ramd64 -v 13.1-RELEASE -a amd64 +# poudriere jail -c -j 143Ramd64 -v 14.3-RELEASE -a amd64 .... -Fetch a `13.1-RELEASE` for `amd64` from the FTP server given by `FREEBSD_HOST` in [.filename]#poudriere.conf#, -create the zfs file system `tank/poudriere/jails/131Ramd64`, -mount it on [.filename]#/poudriere/jails/131Ramd64# and extract the `13.1-RELEASE` tarballs into this file system. +Fetch a `14.3-RELEASE` for `amd64` from the HTTPS server given by `FREEBSD_HOST` in [.filename]#poudriere.conf#, +create the zfs file system `tank/poudriere/jails/143Ramd64`, +mount it on [.filename]#/poudriere/jails/143Ramd64# and extract the `14.3-RELEASE` tarballs into this file system. [source,shell] .... -# poudriere jail -c -j 12i386 -v stable/12 -a i386 -m git+https +# poudriere jail -c -j 13i386 -v stable/13 -a i386 -m git+https .... -Create `tank/poudriere/jails/12i386`, mount it on [.filename]#/poudriere/jails/12i386#, -then check out the tip of the Git branch of `FreeBSD-12-STABLE` from `GIT_HOST` in [.filename]#poudriere.conf# or the default `git.freebsd.org` into [.filename]#/poudriere/jails/12i386/usr/src#, -then complete a `buildworld` and install it into [.filename]#/poudriere/jails/12i386#. +Create `tank/poudriere/jails/13i386`, mount it on [.filename]#/poudriere/jails/13i386#, +then check out the tip of the Git branch of `FreeBSD-13-STABLE` from `GIT_HOST` in [.filename]#poudriere.conf# or the default `git.freebsd.org` into [.filename]#/poudriere/jails/13i386/usr/src#, +then complete a `buildworld` and install it into [.filename]#/poudriere/jails/13i386#. [NOTE] ==== While it is possible to build a newer version of FreeBSD on an older version, most of the time it will not run. -For example, if a `stable/13` jail is needed, the host will have to run `stable/13` too. -Running `13.1-RELEASE` is not enough. +For example, if a `stable/14` jail is needed, the host will have to run `stable/14` too. +Running `14.3-RELEASE` is not enough. ==== [NOTE] ==== -To create a poudriere jail for `14.0-CURRENT`: +To create a poudriere jail for `16.0-CURRENT`: [source,shell] .... -# poudriere jail -c -j 14amd64 -v main -a amd64 -m git+https +# poudriere jail -c -j 16amd64 -v main -a amd64 -m git+https .... -In order to run a `14.0-CURRENT` poudriere jail the host must be running `14.0-CURRENT`. +In order to run a `16.0-CURRENT` poudriere jail the host must be running `16.0-CURRENT`. In general, newer kernels can build and run older jails. -For instance, a `14.0-CURRENT` kernel can build and run a `12.4-STABLE` if the `COMPAT_FREEBSD12` kernel option was compiled in (on by default in `14.0-CURRENT`[.filename]#GENERIC# kernel config). +For instance, a `16.0-CURRENT` kernel can build and run a `14.3-STABLE` if the `COMPAT_FREEBSD14` kernel option was compiled in (on by default in `16.0-CURRENT`[.filename]#GENERIC# kernel config). ==== A list of jails currently known to poudriere can be shown with `poudriere jail -l`: @@ -336,8 +336,8 @@ A list of jails currently known to poudriere can be shown with `poudriere jail - .... # poudriere jail -l JAILNAME VERSION ARCH METHOD -131Ramd64 13.1-RELEASE amd64 ftp -12i386 12.4-STABLE i386 git+https +143Ramd64 14.3-RELEASE amd64 http +13i386 13.5-STABLE i386 git+https .... [[testing-poudriere-maintaining-jails]] @@ -385,7 +385,7 @@ Afterward it is included in the list of known ports trees: .... # poudriere ports -l PORTSTREE METHOD TIMESTAMP PATH -default git+https 2020-07-20 04:23:56 /poudriere/ports/default +default git+https 2025-07-20 04:23:56 /poudriere/ports/default .... [NOTE] @@ -416,7 +416,7 @@ This will be listed in the table of known trees: .... # poudriere ports -l PORTSTREE METHOD TIMESTAMP PATH -development null 2020-07-20 05:06:33 /work/ports +development null 2025-07-20 05:06:33 /work/ports .... [NOTE] @@ -448,11 +448,11 @@ crossref:testing[testing-poudriere-ports-tree-manual, Using Manually Managed Por After jails and ports trees have been set up, the result of a contributor's modifications to the ports tree can be tested. -For example, local modifications to the package:www/firefox[] port located in [.filename]#/work/ports/www/firefox# can be tested in the previously created 13.1-RELEASE jail: +For example, local modifications to the package:www/firefox[] port located in [.filename]#/work/ports/www/firefox# can be tested in the previously created 14.3-RELEASE jail: [source,shell] .... -# poudriere testport -j 131Ramd64 -p development -o www/firefox +# poudriere testport -j 143Ramd64 -p development -o www/firefox .... This will build all dependencies of Firefox. @@ -460,10 +460,10 @@ If a dependency has been built previously and is still up-to-date, the pre-built If a dependency has no up-to-date package, one will be built with default options in a jail. Then Firefox itself is built. -The complete build of every port is logged to [.filename]#/poudriere/data/logs/bulk/131Ri386-development/build-time/logs#. +The complete build of every port is logged to [.filename]#/poudriere/data/logs/bulk/143Ri386-development/build-time/logs#. -The directory name `131Ri386-development` is derived from the arguments to `-j` and `-p`, respectively. -For convenience, a symbolic link [.filename]#/poudriere/data/logs/bulk/131Ri386-development/latest# is also maintained. +The directory name `143Ri386-development` is derived from the arguments to `-j` and `-p`, respectively. +For convenience, a symbolic link [.filename]#/poudriere/data/logs/bulk/143Ri386-development/latest# is also maintained. The link points to the latest _build-time_ directory. Also in this directory is an [.filename]#index.html# for observing the build process with a web browser. @@ -472,7 +472,7 @@ To ease investigation, jails can be kept running after the build by adding `-i` [source,shell] .... -# poudriere testport -j 131Ramd64 -p development -i -o www/firefox +# poudriere testport -j 143Ramd64 -p development -i -o www/firefox .... After the build completes, and regardless of whether it was successful, a shell is provided within the jail. @@ -483,16 +483,16 @@ It is then possible to man:jexec[8] into it: [source,shell] .... -# poudriere testport -j 131Ramd64 -p development -I -o www/firefox +# poudriere testport -j 143Ramd64 -p development -I -o www/firefox [...] ====>> Installing local Pkg repository to /usr/local/etc/pkg/repos -====>> Leaving jail 131Ramd64-development-n running, mounted at /poudriere/data/.m/131Ramd64-development/ref for interactive run testing -====>> To enter jail: jexec 131Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root -====>> To stop jail: poudriere jail -k -j 131Ramd64 -p development -# jexec 131Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root +====>> Leaving jail 143Ramd64-development-n running, mounted at /poudriere/data/.m/143Ramd64-development/ref for interactive run testing +====>> To enter jail: jexec 143Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root +====>> To stop jail: poudriere jail -k -j 143Ramd64 -p development +# jexec 143Ramd64-development-n env -i TERM=$TERM /usr/bin/login -fp root # [do some stuff in the jail] # exit -# poudriere jail -k -j 131Ramd64 -p development +# poudriere jail -k -j 143Ramd64 -p development ====>> Umounting file systems .... @@ -502,7 +502,7 @@ Adding the `-c`: [source,shell] .... -# poudriere testport -j 131Ramd64 -c -o www/firefox +# poudriere testport -j 143Ramd64 -c -o www/firefox .... Presents the port configuration dialog before the port is built. @@ -531,17 +531,17 @@ For instance, testing package:www/firefox[] in a specific set named `devset`, ad [source,shell] .... -# poudriere testport -j 131Ramd64 -p development -z devset -o www/firefox +# poudriere testport -j 143Ramd64 -p development -z devset -o www/firefox .... This will look for the existence of these directories in this order: -* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-devset-options# -* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-devset-options# -* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-options# +* [.filename]#/usr/local/etc/poudriere.d/143Ramd64-development-devset-options# +* [.filename]#/usr/local/etc/poudriere.d/143Ramd64-devset-options# +* [.filename]#/usr/local/etc/poudriere.d/143Ramd64-development-options# * [.filename]#/usr/local/etc/poudriere.d/devset-options# * [.filename]#/usr/local/etc/poudriere.d/development-options# -* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-options# +* [.filename]#/usr/local/etc/poudriere.d/143Ramd64-options# * [.filename]#/usr/local/etc/poudriere.d/options# From this list, poudriere man:nullfs[5]-mounts the _first existing_ directory tree into the [.filename]#/var/db/ports# directory of the build jails. @@ -575,7 +575,7 @@ For instance: [source,shell] .... -# poudriere testport -j 131Ramd64 -p development -z devset -o www/firefox +# poudriere testport -j 143Ramd64 -p development -z devset -o www/firefox .... causes poudriere to check for the existence of these files in this order: @@ -583,14 +583,14 @@ causes poudriere to check for the existence of these files in this order: * [.filename]#/usr/local/etc/poudriere.d/make.conf# * [.filename]#/usr/local/etc/poudriere.d/devset-make.conf# * [.filename]#/usr/local/etc/poudriere.d/development-make.conf# -* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-make.conf# -* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-make.conf# -* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-devset-make.conf# -* [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-devset-make.conf# +* [.filename]#/usr/local/etc/poudriere.d/143Ramd64-make.conf# +* [.filename]#/usr/local/etc/poudriere.d/143Ramd64-development-make.conf# +* [.filename]#/usr/local/etc/poudriere.d/143Ramd64-devset-make.conf# +* [.filename]#/usr/local/etc/poudriere.d/143Ramd64-development-devset-make.conf# Unlike with sets, all of the found files will be appended, _in that order_, into one [.filename]#make.conf# inside the build jails. It is hence possible to have general make variables, intended to affect all builds in [.filename]#/usr/local/etc/poudriere.d/make.conf#. -Special variables, intended to affect only certain jails or sets can be set in specialised [.filename]#make.conf# files, such as [.filename]#/usr/local/etc/poudriere.d/131Ramd64-development-devset-make.conf#. +Special variables, intended to affect only certain jails or sets can be set in specialised [.filename]#make.conf# files, such as [.filename]#/usr/local/etc/poudriere.d/143Ramd64-development-devset-make.conf#. [[testing-poudriere-sets-perl]] .Using [.filename]#make.conf# to Change Default Perl diff --git a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc index e61a88dbaf..3da3d330c5 100644 --- a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc +++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc @@ -64,7 +64,7 @@ If there is no pending PR, the next step is to send an email to the port's maint That person may already be working on an upgrade, or have a reason to not upgrade the port right now (because of, for example, stability problems of the new version), and there is no need to duplicate their work. Note that unmaintained ports are listed with a maintainer of `ports@FreeBSD.org`, which is just the general ports mailing list, so sending mail there probably will not help in this case. -If the maintainer asks you to do the upgrade or there is no maintainer, then help out FreeBSD by preparing the update! Please do this by using the man:diff[1] command in the base system. +If the maintainer requests to do the upgrade or there is no maintainer, then help out FreeBSD by preparing the update! Please do this by using the man:diff[1] command in the base system. To create a suitable `diff` for a single patch, copy the file that needs patching to [.filename]#something.orig#, save the changes to [.filename]#something# and then create the patch: @@ -88,7 +88,7 @@ To simplify common operations with patch files, use `make makepatch` as describe Other tools exists, like [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Before using it, please read [.filename]#/usr/ports/Tools/scripts/README.patchtool#. -If the port is unmaintained, and you are actively using it, please consider volunteering to become its maintainer. +If the port is unmaintained, and it is actively being used, please consider volunteering to become its maintainer. FreeBSD has over 4000 ports without maintainers, and this is an area where more volunteers are always needed. (For a detailed description of the responsibilities of maintainers, refer to the section in the extref:{developers-handbook}[Developer's Handbook, POLICIES-MAINTAINER].) @@ -125,8 +125,8 @@ They are easier to handle than diffs between "new and old" directories. It is easier to see what has changed, and to update the diff if something was modified in the Ports Collection since the work on it began, or if the committer asks for something to be fixed. Also, a patch generated with man:git-format-patch[1] or man:git-diff[1] can be easily applied with man:git-am[1] or man:git-apply[1] and will save some time for the committer. -Finally, the git patch generated by man:git-format-patch[1] includes your author information and commit messages. -These will be recorded in the log of the repository and this is the recommended way to submit your changes. +Finally, the git patch generated by man:git-format-patch[1] includes the author information and commit messages. +These will be recorded in the log of the repository and this is the recommended way to submit the changes. [source,shell] .... @@ -154,7 +154,7 @@ Also, update the checksum reference in distinfo with `make makesum`. Before making the patch, fetch the latest repository and rebase the changes on top of it. Watch and follow the output carefully. -If any of the files failed to rebase, it means that the upstream files changed while you were editing the same file, and the conflicts need to be resolved manually. +If any of the files failed to rebase, it means that the upstream files changed while local changes happened in the same file, and the conflicts need to be resolved manually. [source,shell] .... @@ -182,7 +182,7 @@ To generate a patch with man:git-format-patch[1]: This will generate a patch named like `0001-foo.patch`. This is the preferred way as it would include author identity, -and it is also easier when you are making a series of changes that +and it is also easier when making a series of changes that are not meant to be squashed together. Alternatively, to generate an unified diff with man:git-diff[1]: @@ -193,13 +193,13 @@ Alternatively, to generate an unified diff with man:git-diff[1]: This will generate a diff named like `foo-1.2.3.diff`. Where `foo` is replaced with the first line of the commit message, i.e., the subject of the commit message. -After patch has been created, you can switch to the main branch for starting other developments. +After patch has been created, switch to the main branch for starting other developments. [source,shell] .... % git checkout main .... -Once the patch is accepted and merged, you can delete the local development branch if you want: +Once the patch is accepted and merged, delete the local development branch if desired: [source,shell] .... % git branch -D my_branch @@ -227,7 +227,7 @@ The format of an entry in this file is: .... YYYYMMDD: AFFECTS: users of portcategory/portname - AUTHOR: Your name <Your email address> + AUTHOR: the name <the email address> Special instructions .... diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc index fbdb346372..84c6123b80 100644 --- a/documentation/content/en/books/porters-handbook/uses/_index.adoc +++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc @@ -1331,7 +1331,7 @@ The framework provides the following variables to be set by the port: `JAVA_VERSION`:: List of space-separated suitable java versions for the port. An optional `\+` -allows you to specify a range of versions. (allowed values `8[+]`, `11[\+]`, +allows specifying a range of versions. (allowed values `8[+]`, `11[\+]`, `17[+]`, `18[\+]`, `19[+]`, `20[\+]`, `21[+]`, `22[\+]`, `22[+]`) `JAVA_OS`:: @@ -1984,7 +1984,7 @@ If the `findplist` argument is provided then contents of the `findlib` target di If the `ldconfig` argument is provided then OCaml's [.filename]#ld.conf# file will be automatically processed. When `dune` is used Dune may install stublibs in site-lib package directory(ies) or in a single directory below `DUNE_LIBDIR` site-lib directory. -Set if your port installs shared libraries into ocaml +Set if the port installs shared libraries into ocaml If the `run` argument is provided add ocamlc to `RUN_DEPENDS`. |