diff options
Diffstat (limited to 'documentation/content/en/articles')
19 files changed, 68 insertions, 68 deletions
diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc index 26bb41e98b..07cece334d 100644 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -532,7 +532,7 @@ e.g.: .... so that won't be covered in depth here. -If you want to build a custom kernel, extref:{handbook}[the kernel config section, kernelconfig] of the FreeBSD Handbook recommends creating a file MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC. +If you want to build a custom kernel, extref:{handbook}kernelconfig[the kernel config section, kernelconfig] of the FreeBSD Handbook recommends creating a file MYKERNEL under sys/${ARCH}/conf with your changes against GENERIC. To have MYKERNEL disregarded by Git, it can be added to .git/info/exclude. ===== Updating @@ -687,9 +687,9 @@ The ports tree operates the same way. The branch names are different and the repositories are in different locations. The cgit repository web interface for use with web browsers is at https://cgit.FreeBSD.org/ports/ . -The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or anongit@git.FreeBSD.org:ports.git). +The production Git repository is at https://git.FreeBSD.org/ports.git and at ssh://anongit@git.FreeBSD.org/ports.git (or `anongit@git.FreeBSD.org:ports.git`). -There is also a mirror on GitHub, see extref:{handbook}/mirrors[External mirrors, mirrors] for an overview. +There is also a mirror on GitHub, see extref:{handbook}mirrors[External mirrors, mirrors] for an overview. The _latest_ branch is `main`. The _quarterly_ branches are named `yyyyQn` for year 'yyyy' and quarter 'n'. @@ -1975,11 +1975,11 @@ Before you begin, make sure that your local Git repo is up to date and has the correct origins set crossref:committers-guide[keeping_current,as shown above]. [source,shell] -```` +.... % git remote -v freebsd https://git.freebsd.org/src.git (fetch) freebsd ssh://git@gitrepo.freebsd.org/src.git (push) -```` +.... The first step is to create a fork of https://github.com/freebsd/freebsd-src[FreeBSD] on GitHub following these https://docs.github.com/en/github/getting-started-with-github/fork-a-repo[guidelines]. The destination of the fork should be your own, personal, GitHub account (gvnn3 in my case). @@ -3157,7 +3157,7 @@ When in doubt, ask for review! . Respect existing maintainers if listed. + Many parts of FreeBSD are not "owned" in the sense that any specific individual will jump up and yell if you commit a change to "their" area, but it still pays to check first. -One convention we use is to put a maintainer line in the [.filename]#Makefile# for any package or subtree which is being actively maintained by one or more people; see extref:{developers-handbook}[Source Tree Guidelines and Policies, policies] for documentation on this. +One convention we use is to put a maintainer line in the [.filename]#Makefile# for any package or subtree which is being actively maintained by one or more people; see extref:{developers-handbook}policies[Source Tree Guidelines and Policies, policies] for documentation on this. Where sections of code have several maintainers, commits to affected areas by one maintainer need to be reviewed by at least one other maintainer. In cases where the "maintainer-ship" of something is not clear, look at the repository logs for the files in question and see if someone has been working recently or predominantly in that area. . Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer. Security related changes may override a maintainer's wishes at the Security Officer's discretion. @@ -3653,7 +3653,7 @@ The `-x` parameter ensures the hash `$HASH` of the `main` branch is included in [[ports-qa-new-category-how]] ==== What is the procedure for creating a new category? -Please see extref:{porters-handbook}[Proposing a New Category, proposing-categories] in the Porter's Handbook. +Please see extref:{porters-handbook}makefiles[Proposing a New Category, proposing-categories] in the Porter's Handbook. Once that procedure has been followed and the PR has been assigned to the {portmgr}, it is their decision whether or not to approve it. If they do, it is their responsibility to: @@ -3687,7 +3687,7 @@ To do this, use the [.filename]#chkorigin.sh# tool: `env PORTSDIR=/path/to/ports . Once this is done, you can commit the updated [.filename]#ports/Makefile# to connect the new category to the build and also commit the [.filename]#Makefile# changes for the old category or categories. . Add appropriate entries to [.filename]#ports/MOVED#. . Update the documentation by modifying: -** the extref:{porters-handbook}[list of categories, PORTING-CATEGORIES] in the Porter's Handbook +** the extref:{porters-handbook}makefiles[list of categories, porting-categories] in the Porter's Handbook + . Only once all the above have been done, and no one is any longer reporting problems with the new ports, should the old ports be deleted from their previous locations in the repository. ==== @@ -3696,7 +3696,7 @@ To do this, use the [.filename]#chkorigin.sh# tool: `env PORTSDIR=/path/to/ports This is much simpler than a physical category. Only a few modifications are needed: -* the extref:{porters-handbook}[list of categories, PORTING-CATEGORIES] in the Porter's Handbook +* the extref:{porters-handbook}makefiles[list of categories, porting-categories] in the Porter's Handbook [[ports-qa-misc-questions]] === Miscellaneous Questions @@ -3722,7 +3722,7 @@ No unauthorized commits may ever be made to ports maintained by those groups. The packages are built multiple times each week. If a port fails, the maintainer will receive an email from `pkg-fallout@FreeBSD.org`. -Reports for all the package builds (official, experimental, and non-regression) are aggregated at link:pkg-status.FreeBSD.org[pkg-status.FreeBSD.org]. +Reports for all the package builds (official, experimental, and non-regression) are aggregated at link:https://pkg-status.FreeBSD.org[pkg-status.FreeBSD.org]. [[ports-qa-misc-INDEX]] ==== I added a new port. Do I need to add it to the [.filename]#INDEX#? diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc index d98ff31de0..022dc29e2e 100644 --- a/documentation/content/en/articles/contributing/_index.adoc +++ b/documentation/content/en/articles/contributing/_index.adoc @@ -93,7 +93,7 @@ If anything is poorly explained, ambiguous, out of date or incorrect, let us kno Even better, send us a fix (AsciiDoc is not difficult to learn, but there is no objection to plain text submissions). . Help translate FreeBSD documentation into your native language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date and correct. -First take a look at the extref:{fdp-primer}[Translations FAQ, translations] in the FreeBSD Documentation Project Primer. +First take a look at the extref:{fdp-primer}translations[Translations FAQ, translations] in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this - as a volunteer, you can do as much or as little translation as you desire. Once someone begins translating, others almost always join the effort. If you only have the time or energy to translate one part of the documentation, please translate the installation instructions. @@ -169,7 +169,7 @@ Contributions to the system generally fall into one or more of the following 5 c An idea or suggestion of _general_ technical interest should be mailed to the {freebsd-hackers}. Likewise, people with an interest in such things (and a tolerance for a _high_ volume of mail!) may subscribe to the {freebsd-hackers}. -See extref:{handbook}[The FreeBSD Handbook, eresources-mail] for more information about this and other mailing lists. +See extref:{handbook}eresources[The FreeBSD Handbook, eresources-mail] for more information about this and other mailing lists. If you are submitting a simple patch to the src repo, please consider submitting it to the project's GitHub mirror as https://github.com/freebsd/freebsd-src/pulls[a pull request]. Suitable submissions should: @@ -223,7 +223,7 @@ Send submissions and changes (even small ones are welcome!) using the same metho An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. There is a special on-going release of FreeBSD known as "FreeBSD-CURRENT" which is made available in a variety of ways for the convenience of developers working actively on the system. -See extref:{handbook}[The FreeBSD Handbook, current-stable] for more information about getting and using FreeBSD-CURRENT. +See extref:{handbook}cutting-edge[The FreeBSD Handbook, current-stable] for more information about getting and using FreeBSD-CURRENT. Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the {freebsd-announce} and the {freebsd-current} lists, where discussions on the current state of the system take place. @@ -432,7 +432,7 @@ Please refer to extref:{problem-reports}[Writing FreeBSD Problem Reports] for in ====== Please do not submit a man:shar[1] archive of the entire port; instead, use man:git-format-patch[1] or man:diff[1] `-ruN`. In this way, committers can much more easily see exactly what changes are being made. -The Porter's Handbook section on extref:{porters-handbook}[Upgrading, port-upgrading] has more information. +The Porter's Handbook section on extref:{porters-handbook}upgrading[Upgrading, port-upgrading] has more information. ====== . Wait + diff --git a/documentation/content/en/articles/filtering-bridges/_index.adoc b/documentation/content/en/articles/filtering-bridges/_index.adoc index 1ef6adc085..64c7bd781b 100644 --- a/documentation/content/en/articles/filtering-bridges/_index.adoc +++ b/documentation/content/en/articles/filtering-bridges/_index.adoc @@ -96,7 +96,7 @@ options IPFIREWALL_VERBOSE The first line is to compile the bridge support, the second one is the firewall and the third one is the logging functions of the firewall. Now it is necessary to build and install the new kernel. -You may find detailed instructions in the extref:{handbook}[Building and Installing a Custom Kernel, kernelconfig-building] section of the FreeBSD Handbook. +You may find detailed instructions in the extref:{handbook}kernelconfig[Building and Installing a Custom Kernel, kernelconfig-building] section of the FreeBSD Handbook. [[filtering-bridges-modules]] === Modules Loading diff --git a/documentation/content/en/articles/freebsd-questions/_index.adoc b/documentation/content/en/articles/freebsd-questions/_index.adoc index 2869c685ab..052c202ffd 100644 --- a/documentation/content/en/articles/freebsd-questions/_index.adoc +++ b/documentation/content/en/articles/freebsd-questions/_index.adoc @@ -101,7 +101,7 @@ The following criteria should help for 99% of all questions, however: . If the question relates to a bug, and you are _sure_ that it is a bug (for example, you can pinpoint the place in the code where it happens, and you maybe have a fix), then send the message to `FreeBSD-hackers`. . If the question relates to enhancements to FreeBSD, and you can make suggestions about how to implement them, then send the message to `FreeBSD-hackers`. -There are also a number of other extref:{handbook}[specialized mailing lists, eresources-mail], which caters to more specific interests. +There are also a number of other extref:{handbook}eresources[specialized mailing lists, eresources-mail], which caters to more specific interests. The criteria above still apply, and it is in your interest to stick to them, since you are more likely to get good results that way. == Before Submitting a Question @@ -110,7 +110,7 @@ You can (and should) do some things yourself before asking a question on one of * Try solving the problem on your own. If you post a question which shows that you have tried to solve the problem, your question will generally attract more positive attention from people reading it. Trying to solve the problem yourself will also enhance your understanding of FreeBSD, and will eventually let you use your knowledge to help others by answering questions posted to the mailing lists. * Read the manual pages, and the FreeBSD documentation (either installed in [.filename]#/usr/doc# or accessible via WWW at http://www.FreeBSD.org[http://www.FreeBSD.org]), especially the extref:{handbook}[handbook] and the extref:{faq}[FAQ]. -* Browse and/or search the archives for the mailing list, to see if your question or a similar one has been asked (and possibly answered) on the list. You can browse and/or search the mailing list archives at https://www.FreeBSD.org/mail[https://www.FreeBSD.org/mail] and https://www.FreeBSD.org/search/#mailinglists[https://www.FreeBSD.org/search/#mailinglists] respectively. +* Browse and/or search the archives for the mailing list, to see if your question or a similar one has been asked (and possibly answered) on the list. You can browse and/or search the mailing list archives at https://www.FreeBSD.org/mail[https://www.FreeBSD.org/mail] and https://www.FreeBSD.org/search/#mailinglists[https://www.FreeBSD.org/search/#mailinglists] respectively. * Use a search engine such as http://www.google.com[Google] or http://www.yahoo.com[Yahoo] to find answers to your question. == How to Submit a Question diff --git a/documentation/content/en/articles/freebsd-update-server/_index.adoc b/documentation/content/en/articles/freebsd-update-server/_index.adoc index 78f44784c8..fd7c066605 100644 --- a/documentation/content/en/articles/freebsd-update-server/_index.adoc +++ b/documentation/content/en/articles/freebsd-update-server/_index.adoc @@ -88,7 +88,7 @@ At a minimum, updates require building on a FreeBSD release greater than or equa ==== * A user account with at least 4 GB of available space. This will allow the creation of updates for 7.1 and 7.2, but the exact space requirements may change from version to version. * An man:ssh[1] account on a remote machine to upload distributed updates. -* A web server, like extref:{handbook}[Apache, network-apache], with over half of the space required for the build. For instance, test builds for 7.1 and 7.2 consume a total amount of 4 GB, and the webserver space needed to distribute these updates is 2.6 GB. +* A web server, like extref:{handbook}network-servers[Apache, network-apache], with over half of the space required for the build. For instance, test builds for 7.1 and 7.2 consume a total amount of 4 GB, and the webserver space needed to distribute these updates is 2.6 GB. * Basic knowledge of shell scripting with Bourne shell, man:sh[1]. [[Configuration]] @@ -402,9 +402,9 @@ In the event update code needs to be re-uploaded, this may be done by changing t The uploaded files will need to be in the document root of the webserver in order for updates to be distributed. The exact configuration will vary depending on the web server used. -For the Apache web server, please refer to the extref:{handbook}[Configuration of Apache servers, network-apache] section in the Handbook. +For the Apache web server, please refer to the extref:{handbook}network-servers[Configuration of Apache servers, network-apache] section in the Handbook. -Update client's `KeyPrint` and `ServerName` in [.filename]#/etc/freebsd-update.conf#, and perform updates as instructed in the extref:{handbook}[FreeBSD Update, updating-upgrading-freebsdupdate] section of the Handbook. +Update client's `KeyPrint` and `ServerName` in [.filename]#/etc/freebsd-update.conf#, and perform updates as instructed in the extref:{handbook}cutting-edge[FreeBSD Update, updating-upgrading-freebsdupdate] section of the Handbook. [IMPORTANT] ==== @@ -437,7 +437,7 @@ Create the patch directory of the respective release under [.filename]#/usr/loca As an example, take the patch for man:named[8]. Read the advisory, and grab the necessary file from link:https://www.FreeBSD.org/security/advisories/[FreeBSD Security Advisories]. -More information on interpreting the advisory, can be found in the extref:{handbook}[FreeBSD Handbook, security-advisories]. +More information on interpreting the advisory, can be found in the extref:{handbook}security[FreeBSD Handbook, security-advisories]. In the https://security.freebsd.org/advisories/FreeBSD-SA-09:12.bind.asc[security brief], this advisory is called `SA-09:12.bind`. After downloading the file, it is required to rename the file to an appropriate patch level. @@ -631,7 +631,7 @@ addextradocs () { make ${COMPATFLAGS} release.1 release.2 2>&1 .... -* Create an appropriate extref:{handbook}[DNS, network-dns] SRV record for the update server, and put others behind it with variable weights. Using this facility will provide update mirrors, however this tip is not necessary unless you wish to provide a redundant service. +* Create an appropriate extref:{handbook}network-servers[DNS, network-dns] SRV record for the update server, and put others behind it with variable weights. Using this facility will provide update mirrors, however this tip is not necessary unless you wish to provide a redundant service. + [.programlisting] .... diff --git a/documentation/content/en/articles/geom-class/_index.adoc b/documentation/content/en/articles/geom-class/_index.adoc index cf10202e74..7613cb780a 100644 --- a/documentation/content/en/articles/geom-class/_index.adoc +++ b/documentation/content/en/articles/geom-class/_index.adoc @@ -152,7 +152,7 @@ This is controlled with two [.filename]#/etc/rc.conf# variables: [.programlisting] .... dumpdev="/dev/ad0s4b" -dumpdir="/usr/core +dumpdir="/usr/core" .... The `dumpdev` variable specifies the swap partition and `dumpdir` tells the system where in the filesystem to relocate the core dump on reboot. @@ -241,7 +241,7 @@ Structure `bio` is used for any and all Input/Output operations concerning GEOM. It basically contains information about what device ('provider') should satisfy the request, request type, offset, length, pointer to a buffer, and a bunch of "user-specific" flags and fields that can help implement various hacks. The important thing here is that ``bio``s are handled asynchronously. -That means that, in most parts of the code, there is no analogue to userland's man:read[2] and man:write[2] calls that do not return until a request is done. +That means that, in most parts of the code, there is no analogue to userland's man:read[2] and man:write[2] calls that do not return until a request is done. Rather, a developer-supplied function is called as a notification when the request gets completed (or results in error). The asynchronous programming model (also called "event-driven") is somewhat harder than the much more used imperative one used in userland (at least it takes a while to get used to it). diff --git a/documentation/content/en/articles/gjournal-desktop/_index.adoc b/documentation/content/en/articles/gjournal-desktop/_index.adoc index 1f8c15f843..164c92985b 100644 --- a/documentation/content/en/articles/gjournal-desktop/_index.adoc +++ b/documentation/content/en/articles/gjournal-desktop/_index.adoc @@ -61,7 +61,7 @@ On rare occasions, file system corruption reaches a point where user interventio The new journaling capability provided by GEOM can greatly assist in such scenarios, by virtually eliminating the time required for file system checking, and ensuring that the file system is quickly restored to a consistent state. -This article describes a procedure for implementing UFS journaling on a typical desktop PC scenario (one hard disk used for both operating system and data). +This article describes a procedure for implementing UFS journaling on a typical desktop PC scenario (one hard disk used for both operating system and data). It should be followed during a fresh installation of FreeBSD. The steps are simple enough and do not require overly complex interaction with the command line. @@ -106,14 +106,14 @@ For example: * You reserved some free disk space in a partition in [.filename]#/dev/ad0s1g#. * Using `gjournal`, a new [.filename]#/dev/ad0s1f.journal# device is created where [.filename]#/dev/ad0s1f# is the data provider, and [.filename]#/dev/ad0s1g# is the journal provider. This new device is then used for all subsequent file operations. -The amount of disk space you need to reserve for the journal provider depends on the usage load of the file system and not on the size of the data provider. +The amount of disk space you need to reserve for the journal provider depends on the usage load of the file system and not on the size of the data provider. For example on a typical office desktop, a 1 GB journal provider for the [.filename]#/usr# file system will suffice, while a machine that deals with heavy disk I/O (i.e. video editing) may need more. A kernel panic will occur if the journal space is exhausted before it has a chance to be committed. [NOTE] ==== The journal sizes suggested here, are highly unlikely to cause problems in typical desktop use (such as web browsing, word processing and playback of media files). -If your workload includes intense disk activity, use the following rule for maximum reliability: Your RAM size should fit in 30% of the journal provider's space. +If your workload includes intense disk activity, use the following rule for maximum reliability: Your RAM size should fit in 30% of the journal provider's space. For example, if your system has 1 GB RAM, create an approximately 3.3 GB journal provider. (Multiply your RAM size with 3.3 to obtain the size of the journal). ==== @@ -197,7 +197,7 @@ We would however suggest you postpone installation of third party software (pack [[first-boot]] === Booting for the first time -Your system will come up normally, but you will need to edit [.filename]#/etc/fstab# and remove the extra swap partitions you created for the journals. +Your system will come up normally, but you will need to edit [.filename]#/etc/fstab# and remove the extra swap partitions you created for the journals. Normally, the swap partition you will actually use is the one with the "b" suffix (i.e. ad0s1b in our example). Remove all other swap space entries and reboot so that FreeBSD will stop using them. @@ -371,7 +371,7 @@ options UFS_GJOURNAL # Note: This is already in GENERIC options GEOM_JOURNAL # You will have to add this one .... -Rebuild and reinstall your kernel following the relevant extref:{handbook}[instructions in the FreeBSD Handbook., kernelconfig] +Rebuild and reinstall your kernel following the relevant extref:{handbook}kernelconfig[instructions in the FreeBSD Handbook., kernelconfig] Do not forget to remove the relevant "load" entry from [.filename]#/boot/loader.conf# if you have previously used it. @@ -504,7 +504,7 @@ Finally, edit [.filename]#/boot/loader.conf#, remove the entry that loads the `g Journaling is a fairly new feature of FreeBSD, and as such, it is not very well documented yet. You may however find the following additional references useful: -* A extref:{handbook}[new section on journaling, geom-gjournal] is now part of the FreeBSD Handbook. +* A extref:{handbook}geom[new section on journaling, geom-gjournal] is now part of the FreeBSD Handbook. * https://lists.freebsd.org/pipermail/freebsd-current/2006-June/064043.html[This post] in {freebsd-current} by man:gjournal[8]'s developer, `{pjd}`. * https://lists.freebsd.org/pipermail/freebsd-questions/2008-April/173501.html[This post] in {freebsd-questions} by `{ivoras}`. * The manual pages of man:gjournal[8] and man:geom[8]. diff --git a/documentation/content/en/articles/hubs/_index.adoc b/documentation/content/en/articles/hubs/_index.adoc index 1ddbe3065a..8445423a5d 100644 --- a/documentation/content/en/articles/hubs/_index.adoc +++ b/documentation/content/en/articles/hubs/_index.adoc @@ -392,7 +392,7 @@ Tier-1 mirrors are required to: * provide FTP and rsync access Furthermore, admins should be subscribed to the {freebsd-hubs}. -See extref:{handbook}[this link, eresources-mail] for details, how to subscribe. +See extref:{handbook}eresources[this link, eresources-mail] for details, how to subscribe. [IMPORTANT] ==== diff --git a/documentation/content/en/articles/ipsec-must/_index.adoc b/documentation/content/en/articles/ipsec-must/_index.adoc index dbca759c6e..262ffef368 100644 --- a/documentation/content/en/articles/ipsec-must/_index.adoc +++ b/documentation/content/en/articles/ipsec-must/_index.adoc @@ -144,7 +144,7 @@ IPsec encrypts everything between two hosts. Most of the modern versions of FreeBSD have IPsec support in their base source. So you will need to include the `IPSEC` option in your kernel config and, after kernel rebuild and reinstall, configure IPsec connections using man:setkey[8] command. -A comprehensive guide on running IPsec on FreeBSD is provided in extref:{handbook}[FreeBSD Handbook, ipsec]. +A comprehensive guide on running IPsec on FreeBSD is provided in extref:{vpn-ipsec}[VPN over IPsec]. [[kernel]] == src/sys/i386/conf/KERNELNAME diff --git a/documentation/content/en/articles/leap-seconds/_index.adoc b/documentation/content/en/articles/leap-seconds/_index.adoc index d28629b005..55a1dfb5fc 100644 --- a/documentation/content/en/articles/leap-seconds/_index.adoc +++ b/documentation/content/en/articles/leap-seconds/_index.adoc @@ -56,7 +56,7 @@ Also see man:time2posix[3]. [[leapseconds-posix]] == Default Leap Second Handling on FreeBSD -The easiest way to handle leap seconds is with the POSIX time rules FreeBSD uses by default, combined with extref:{handbook}[NTP, network-ntp]. +The easiest way to handle leap seconds is with the POSIX time rules FreeBSD uses by default, combined with extref:{handbook}network-servers[NTP, network-ntp]. When man:ntpd[8] is running and the time is synchronized with upstream NTP servers that handle leap seconds correctly, the leap second will cause the system time to automatically repeat the last second of the day. No other adjustments are necessary. diff --git a/documentation/content/en/articles/linux-emulation/_index.adoc b/documentation/content/en/articles/linux-emulation/_index.adoc index a252df5f54..f225c23fe4 100644 --- a/documentation/content/en/articles/linux-emulation/_index.adoc +++ b/documentation/content/en/articles/linux-emulation/_index.adoc @@ -1008,7 +1008,7 @@ Newer glibc in a case of 2.6 kernel uses `clone` to implement man:fork[2] and ma The locking is implemented to be per-subsystem because we do not expect a lot of contention on these. There are two locks: `emul_lock` used to protect manipulating of `linux_emuldata` and `emul_shared_lock` used to manipulate `linux_emuldata_shared`. The `emul_lock` is a nonsleepable blocking mutex while `emul_shared_lock` is a sleepable blocking `sx_lock`. -Due to of the per-subsystem locking we can coalesce some locks and that is why the em find offers the non-locking access. +Due to of the per-subsystem locking we can coalesce some locks and that is why the em_find offers the non-locking access. [[tls]] === TLS @@ -1431,6 +1431,6 @@ I would like to thank all those people for their advice, code reviews and genera [[literatures]] == Literatures -. Marshall Kirk McKusick - George V. Nevile-Neil. Design and Implementation of the FreeBSD operating system. Addison-Wesley, 2005. +. Marshall Kirk McKusick - George V. Neville-Neil. Design and Implementation of the FreeBSD operating system. Addison-Wesley, 2005. . https://tldp.org[https://tldp.org] . https://www.kernel.org[https://www.kernel.org] diff --git a/documentation/content/en/articles/linux-users/_index.adoc b/documentation/content/en/articles/linux-users/_index.adoc index 50a0c2d54f..343b523c6b 100644 --- a/documentation/content/en/articles/linux-users/_index.adoc +++ b/documentation/content/en/articles/linux-users/_index.adoc @@ -54,7 +54,7 @@ toc::[] This document highlights some of the technical differences between FreeBSD and Linux(R) so that intermediate to advanced Linux(R) users can quickly familiarize themselves with the basics of FreeBSD. This document assumes that FreeBSD is already installed. -Refer to the extref:{handbook}[Installing FreeBSD, bsdinstall] chapter of the FreeBSD Handbook for help with the installation process. +Refer to the extref:{handbook}bsdinstall[Installing FreeBSD, bsdinstall] chapter of the FreeBSD Handbook for help with the installation process. [[shells]] == Default Shell @@ -66,7 +66,7 @@ The root shell is man:tcsh[1] by default on FreeBSD 13 and earlier and man:sh[1] man:sh[1] is very similar to Bash but with a much smaller feature-set. Generally shell scripts written for man:sh[1] will run in Bash, but the reverse is not always true. -However, Bash and other shells are available for installation using the FreeBSD extref:{handbook}[Packages and Ports Collection, ports]. +However, Bash and other shells are available for installation using the FreeBSD extref:{handbook}ports[Packages and Ports Collection, ports]. After installing another shell, use man:chsh[1] to change a user's default shell. It is recommended that the `root` user's default shell remain unchanged since shells which are not included in the base distribution are installed to [.filename]#/usr/local/bin#. @@ -106,7 +106,7 @@ For example, the following command installs Apache 2.4: # pkg install apache24 .... -For more information on packages refer to section 5.4 of the FreeBSD Handbook: extref:{handbook}[Using pkgng for Binary Package Management, pkgng-intro]. +For more information on packages refer to section 4.4 of the FreeBSD Handbook: extref:{handbook}ports[Using pkgng for Binary Package Management, pkgng-intro]. [[ports]] === Ports @@ -115,7 +115,7 @@ The FreeBSD Ports Collection is a framework of [.filename]#Makefiles# and patche When installing a port, the system will fetch the source code, apply any required patches, compile the code, and install the application and any required dependencies. The Ports Collection, sometimes referred to as the ports tree, can be installed to [.filename]#/usr/ports# using link:{handbook}mirrors/#git[Git]. -Detailed instructions for installing the Ports Collection can be found in extref:{handbook}[section 4.5.1, ports-using-installation-methods] of the FreeBSD Handbook. +Detailed instructions for installing the Ports Collection can be found in extref:{handbook}ports[section 4.5.1, ports-using-installation-methods] of the FreeBSD Handbook. To compile a port, change to the port's directory and start the build process. The following example installs Apache 2.4 from the Ports Collection: @@ -134,7 +134,7 @@ This example specifies that the mod_ldap module should also be installed: # make WITH_LDAP="YES" install clean .... -Refer to extref:{handbook}[Using the Ports Collection, ports-using] for more information. +Refer to extref:{handbook}ports[Using the Ports Collection, ports-using] for more information. [[startup]] == System Startup @@ -149,7 +149,7 @@ The scripts found in [.filename]#/etc/rc.d/# are for applications that are part The scripts in [.filename]#/usr/local/etc/rc.d/# are for user-installed applications such as Apache and Squid. Since FreeBSD is developed as a complete operating system, user-installed applications are not considered to be part of the "base" system. -User-installed applications are generally installed using extref:{handbook}[Packages or Ports, ports-using]. +User-installed applications are generally installed using extref:{handbook}ports[Packages or Ports, ports-using]. In order to keep them separate from the base system, user-installed applications are installed under [.filename]#/usr/local/#. Therefore, user-installed binaries reside in [.filename]#/usr/local/bin/#, configuration files are in [.filename]#/usr/local/etc/#, and so on. @@ -232,9 +232,9 @@ ifconfig_em0="DHCP" FreeBSD does not use Linux(R) IPTABLES for its firewall. Instead, FreeBSD offers a choice of three kernel level firewalls: -* extref:{handbook}[PF, firewalls-pf] -* extref:{handbook}[IPFILTER, firewalls-ipf] -* extref:{handbook}[IPFW, firewalls-ipfw] +* extref:{handbook}firewalls[PF, firewalls-pf] +* extref:{handbook}firewalls[IPFILTER, firewalls-ipf] +* extref:{handbook}firewalls[IPFW, firewalls-ipfw] PF is developed by the OpenBSD project and ported to FreeBSD. PF was created as a replacement for IPFILTER and its syntax is similar to that of IPFILTER. @@ -291,7 +291,7 @@ When using man:cron[8] to schedule updates, use `freebsd-update cron` in the man ==== -For more information on source and binary updates, refer to extref:{handbook}[the chapter on updating, updating-upgrading-freebsdupdate] in the FreeBSD Handbook. +For more information on source and binary updates, refer to extref:{handbook}cutting-edge[the chapter on updating, updating-upgrading-freebsdupdate] in the FreeBSD Handbook. [[procfs]] == procfs: Gone But Not Forgotten diff --git a/documentation/content/en/articles/mailing-list-faq/_index.adoc b/documentation/content/en/articles/mailing-list-faq/_index.adoc index ab708fc0e4..64595b6bb0 100644 --- a/documentation/content/en/articles/mailing-list-faq/_index.adoc +++ b/documentation/content/en/articles/mailing-list-faq/_index.adoc @@ -43,8 +43,8 @@ Abstract This is the FAQ for the FreeBSD mailing lists. If you are interested in helping with this project, send email to the {freebsd-doc}. -The latest version of this document is always available from the link:.[FreeBSD World Wide Web server]. -It may also be downloaded as one large link:.[HTML] file with HTTP or as plain text, PostScript, PDF, etc. from the https://download.freebsd.org/doc/[FreeBSD FTP server]. +The latest version of this document is always available from the extref:{mailing-list-faq}[FreeBSD World Wide Web server]. +It may also be downloaded as one large extref:{mailing-list-faq}[HTML] file with HTTP or as plain text, PostScript, PDF, etc. from the https://download.freebsd.org/doc/[FreeBSD FTP server]. You may also want to link:https://www.FreeBSD.org/search/[Search the FAQ]. ''' diff --git a/documentation/content/en/articles/pr-guidelines/_index.adoc b/documentation/content/en/articles/pr-guidelines/_index.adoc index b6729150cd..d645d4637b 100644 --- a/documentation/content/en/articles/pr-guidelines/_index.adoc +++ b/documentation/content/en/articles/pr-guidelines/_index.adoc @@ -208,7 +208,7 @@ this will avoid duplicate emails sent to the mailing list. [NOTE] ==== -Since the list of individuals who have volunteered to be the default assignee for certain types of PRs changes so often, it is much more suitable for https://wiki.freebsd.org/AssigningPRs[the FreeBSD wiki]. +Since the list of individuals who have volunteered to be the default assignee for certain types of PRs changes so often, it is much more suitable for https://wiki.freebsd.org/AssigningPRs[the FreeBSD wiki]. ==== Here is a sample list of such entities; it is probably not complete. @@ -438,7 +438,7 @@ Here is a sample list of such entities; it is probably not complete. |mailing list |=== -Ports PRs which have a maintainer who is a ports committer may be reassigned by anyone (but note that not every FreeBSD committer is necessarily a ports committer, so you cannot simply go by the email address alone.) +Ports PRs which have a maintainer who is a ports committer may be reassigned by anyone (but note that not every FreeBSD committer is necessarily a ports committer, so you cannot simply go by the email address alone.) For other PRs, please do not reassign them to individuals (other than yourself) unless you are certain that the assignee really wants to track the PR. This will help to avoid the case where no one looks at fixing a particular problem because everyone assumes that the assignee is already working on it. @@ -500,7 +500,7 @@ This means that spammers found them. Whenever you close one of these PRs, please do the following: -* Set the component to `junk` (under `Supporting Services`. +* Set the component to `junk` (under `Supporting Services`). * Set Responsible to `nobody@FreeBSD.org`. * Set State to `Issue Resolved`. diff --git a/documentation/content/en/articles/rc-scripting/_index.adoc b/documentation/content/en/articles/rc-scripting/_index.adoc index 14e0ad4bb4..dbb718ebb9 100644 --- a/documentation/content/en/articles/rc-scripting/_index.adoc +++ b/documentation/content/en/articles/rc-scripting/_index.adoc @@ -590,7 +590,7 @@ After a script has been written, it needs to be integrated into [.filename]#rc.d The crucial step is to install the script in [.filename]#/etc/rc.d# (for the base system) or [.filename]#/usr/local/etc/rc.d# (for ports). Both [.filename]#bsd.prog.mk# and [.filename]#bsd.port.mk# provide convenient hooks for that, and usually you do not have to worry about the proper ownership and mode. System scripts should be installed from [.filename]#src/libexec/rc/rc.d# through the [.filename]#Makefile# found there. -Port scripts can be installed using `USE_RC_SUBR` as described extref:{porters-handbook}[in the Porter's Handbook, rc-scripts]. +Port scripts can be installed using `USE_RC_SUBR` as described extref:{porters-handbook}special[in the Porter's Handbook, rc-scripts]. However, we should consider beforehand the place of our script in the system startup sequence. The service handled by our script is likely to depend on other services. @@ -852,7 +852,7 @@ A script with a long running service which needs to do something listed above be By default, only the start and stop parts of a script are run within a service jail, the rest is run outside the jail. As such any setting used in the start/stop parts of the script can not be set from e.g. a precommand. -To make a script ready for use with extref:../../books/handbook/jails/#service-jails[Service Jails], only one more config line needs to be inserted: +To make a script ready for use with extref:{handbook}jails[Service Jails, service-jails], only one more config line needs to be inserted: [.programlisting] .... diff --git a/documentation/content/en/articles/releng/_index.adoc b/documentation/content/en/articles/releng/_index.adoc index f19ccb2bdd..56cacf4f0f 100644 --- a/documentation/content/en/articles/releng/_index.adoc +++ b/documentation/content/en/articles/releng/_index.adoc @@ -86,7 +86,7 @@ The ABI stability has improved greatly from the compared to previous releases. In most cases, binaries from the older _STABLE_ systems run unmodified on newer systems, including __HEAD__, assuming that the system management interfaces are not used. In the interim period between releases, weekly snapshots are built automatically by the FreeBSD Project build machines and made available for download from `https:/download.FreeBSD.org/snapshots/`. -The widespread availability of binary release snapshots, and the tendency of our user community to keep up with -STABLE development with Subversion and "`make buildworld`" footnote:[extref:{handbook}[Rebuilding world, makeworld]] helps to keep FreeBSD-STABLE in a very reliable condition even before the quality assurance activities ramp up pending a major release. +The widespread availability of binary release snapshots, and the tendency of our user community to keep up with -STABLE development with Subversion and "`make buildworld`" footnote:[extref:{handbook}cutting-edge[Rebuilding world, makeworld]] helps to keep FreeBSD-STABLE in a very reliable condition even before the quality assurance activities ramp up pending a major release. In addition to installation ISO snapshots, weekly virtual machine images are also provided for use with VirtualBox, qemu, or other popular emulation software. The virtual machine images can be downloaded from `https://download.FreeBSD.org/snapshots/VM-IMAGES/`. @@ -412,7 +412,7 @@ We certainly encourage innovation in the form of advanced installation and admin === Scripting `bsdinstall` The FreeBSD system installation and configuration tool, man:bsdinstall[8], can be scripted to provide automated installs for large sites. -This functionality can be used in conjunction with Intel(R) PXE footnote:[extref:{handbook}[Diskless Operation with PXE, network-diskless]] to bootstrap systems from the network. +This functionality can be used in conjunction with Intel(R) PXE footnote:[extref:{handbook}advanced-networking[Diskless Operation with PXE, network-diskless]] to bootstrap systems from the network. [[lessons-learned]] == Lessons Learned from FreeBSD 4.4 diff --git a/documentation/content/en/articles/remote-install/_index.adoc b/documentation/content/en/articles/remote-install/_index.adoc index ba9bf48256..2575637b94 100644 --- a/documentation/content/en/articles/remote-install/_index.adoc +++ b/documentation/content/en/articles/remote-install/_index.adoc @@ -233,7 +233,7 @@ Repeat the following command for each hard drive: Next, create slices and label them with your preferred tool. While it is considered easier to use `sysinstall`, a powerful and also probably less buggy method will be to use standard text-based UNIX(R) tools, such as man:fdisk[8] and man:bsdlabel[8], which will also be covered in this section. -The former option is well documented in the extref:{handbook}[Installing FreeBSD, install-steps] chapter of the FreeBSD Handbook. +The former option is well documented in the extref:{handbook}install[Installing FreeBSD, install-steps] chapter of the FreeBSD Handbook. As it was mentioned in the introduction, this article will present how to set up a system with RAID-1 and ZFS capabilities. Our set up will consist of a small man:gmirror[8] mirrored [.filename]#/# (root), [.filename]#/usr# and [.filename]#/var# dataset, and the rest of the disk space will be allocated for a man:zpool[8] mirrored ZFS file system. Please note, that the ZFS file system will be configured after the FreeBSD operating system is successfully installed and booted. diff --git a/documentation/content/en/articles/serial-uart/_index.adoc b/documentation/content/en/articles/serial-uart/_index.adoc index 3852251b85..e953644b93 100644 --- a/documentation/content/en/articles/serial-uart/_index.adoc +++ b/documentation/content/en/articles/serial-uart/_index.adoc @@ -445,7 +445,7 @@ Modems operating at 28,800 and higher speeds have variable Symbol rates, but the === The IBM Personal Computer UART -Starting with the original IBM Personal Computer, IBM selected the National Semiconductor INS8250 UART for use in the IBM PC Parallel/Serial Adapter. +Starting with the original IBM Personal Computer, IBM selected the National Semiconductor INS8250 UART for use in the IBM PC Parallel/Serial Adapter. Subsequent generations of compatible computers from IBM and other vendors continued to use the INS8250 or improved versions of the National Semiconductor UART family. ==== National Semiconductor UART Family Tree @@ -815,7 +815,7 @@ Bit 0 -> Delta Clear To Send (DCTS). Set to "1" if the -CTS line has changed sta === Beyond the 16550A UART -Although National Semiconductor has not offered any components compatible with the 16550 that provide additional features, various other vendors have. +Although National Semiconductor has not offered any components compatible with the 16550 that provide additional features, various other vendors have. Some of these components are described below. It should be understood that to effectively utilize these improvements, drivers may have to be provided by the chip vendor since most of the popular operating systems do not support features beyond those provided by the 16550. @@ -839,7 +839,7 @@ This leaves the designer free to components that may have better performance cha [[sio]] == Configuring the [.filename]#sio# driver -The [.filename]#sio# driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. +The [.filename]#sio# driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. Several multiport cards are supported as well. See the man:sio[4] manual page for detailed technical documentation. @@ -878,12 +878,12 @@ One important note - the actual UART chips for the Boca 16 are in the connector So if you have it unplugged, probes of those ports will fail. I have never tested booting with the box unplugged and plugging it back in, and I suggest you do not either. -If you do not already have a custom kernel configuration file set up, refer to extref:{handbook}[Kernel Configuration, kernelconfig] chapter of the FreeBSD Handbook for general procedures. +If you do not already have a custom kernel configuration file set up, refer to extref:{handbook}kernelconfig[Kernel Configuration, kernelconfig] chapter of the FreeBSD Handbook for general procedures. The following are the specifics for the Boca 16 board and assume you are using the kernel name MYKERNEL and editing with vi. [.procedure] ==== -. Add the line +. Add the line + [.programlisting] .... @@ -905,7 +905,7 @@ device sio16 at isa? port 0x178 flags 0x1005 irq 3 + The flags entry _must_ be changed from this example unless you are using the exact same sio assignments. Flags are set according to 0x``__MYY__`` where _M_ indicates the minor number of the master port (the last port on a Boca 16) and _YY_ indicates if FIFO is enabled or disabled(enabled), IRQ sharing is used(yes) and if there is an AST/4 compatible IRQ control register(no). -In this example, +In this example, + [.programlisting] .... @@ -953,7 +953,7 @@ sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa sio16: type 16550A (multiport master) .... + -If the messages go by too fast to see, +If the messages go by too fast to see, + [source,shell] .... @@ -976,7 +976,7 @@ If you do need to create the [.filename]#/dev# entries, run the following as `ro .... + If you do not want or need call-out devices for some reason, you can dispense with making the [.filename]#cua*# devices. -. If you want a quick and sloppy way to make sure the devices are working, you can simply plug a modem into each port and (as root) +. If you want a quick and sloppy way to make sure the devices are working, you can simply plug a modem into each port and (as root) + [source,shell] .... diff --git a/documentation/content/en/articles/vinum/_index.adoc b/documentation/content/en/articles/vinum/_index.adoc index e1c87acf48..6c078fa1c6 100644 --- a/documentation/content/en/articles/vinum/_index.adoc +++ b/documentation/content/en/articles/vinum/_index.adoc @@ -74,7 +74,7 @@ Users are advised to migrate to man:gconcat[8], man:gmirror[8], man:gstripe[8], [NOTE] ==== -Starting with FreeBSD 5, [.filename]#vinum# has been rewritten to fit into the extref:{handbook}[GEOM architecture, geom], while retaining the original ideas, terminology, and on-disk metadata. +Starting with FreeBSD 5, [.filename]#vinum# has been rewritten to fit into the extref:{handbook}geom[GEOM architecture, geom], while retaining the original ideas, terminology, and on-disk metadata. This rewrite is called _gvinum_ (for _GEOM vinum_). While this chapter uses the term [.filename]#vinum#, any command invocations should be performed with `gvinum`. The name of the kernel module has changed from the original [.filename]#vinum.ko# to [.filename]#geom_vinum.ko#, and all device nodes reside under [.filename]#/dev/gvinum# instead of [.filename]#/dev/vinum#. @@ -545,7 +545,7 @@ This enables [.filename]#vinum# to identify drives correctly even if they have b _Gvinum_ always features an automatic startup once the kernel module is loaded, via man:loader.conf[5]. To load the _Gvinum_ module at boot time, add `geom_vinum_load="YES"` to [.filename]#/boot/loader.conf#. -When [.filename]#vinum# is started with `gvinum start`, [.filename]#vinum# reads the configuration database from one of the [.filename]#vinum# drives. +When [.filename]#vinum# is started with `gvinum start`, [.filename]#vinum# reads the configuration database from one of the [.filename]#vinum# drives. Under normal circumstances, each drive contains an identical copy of the configuration database, so it does not matter which drive is read. After a crash, however, [.filename]#vinum# must determine which drive was updated most recently and read the configuration from this drive. It then updates the configuration, if necessary, from progressively older drives. @@ -563,7 +563,7 @@ In the following sections, the term "root volume" is generally used to describe === Starting up [.filename]#vinum# Early Enough for the Root File System -[.filename]#vinum# must be available early in the system boot as man:loader[8] must be able to load the vinum kernel module before starting the kernel. +[.filename]#vinum# must be available early in the system boot as man:loader[8] must be able to load the vinum kernel module before starting the kernel. This can be accomplished by putting this line in [.filename]#/boot/loader.conf#: [.programlisting] @@ -707,7 +707,7 @@ If this file system is to be mounted read-write later on, it is necessary to rem ==== Only Primary Bootstrap Loads If [.filename]#/boot/loader# fails to load, but the primary bootstrap still loads (visible by a single dash in the left column of the screen right after the boot process starts), an attempt can be made to interrupt the primary bootstrap by pressing kbd:[space]. -This will make the bootstrap stop in extref:{handbook}[stage two, boot-boot1]. +This will make the bootstrap stop in extref:{handbook}boot[stage two, boot-boot1]. An attempt can be made here to boot off an alternate partition, like the partition containing the previous root file system that has been moved away from `a`. [[vinum-root-panic]] @@ -718,6 +718,6 @@ Unfortunately, [.filename]#vinum# accidentally leaves only 4 KB at the beginning However, the stage one and two bootstraps plus the bsdlabel require 8 KB. So if a [.filename]#vinum# partition was started at offset 0 within a slice or disk that was meant to be bootable, the [.filename]#vinum# setup will trash the bootstrap. -Similarly, if the above situation has been recovered, by booting from a "Fixit" media, and the bootstrap has been re-installed using `bsdlabel -B` as described in extref:{handbook}[stage two, boot-boot1], the bootstrap will trash the [.filename]#vinum# header, and [.filename]#vinum# will no longer find its disk(s). +Similarly, if the above situation has been recovered, by booting from a "Fixit" media, and the bootstrap has been re-installed using `bsdlabel -B` as described in extref:{handbook}boot[stage two, boot-boot1], the bootstrap will trash the [.filename]#vinum# header, and [.filename]#vinum# will no longer find its disk(s). Though no actual [.filename]#vinum# configuration data or data in [.filename]#vinum# volumes will be trashed, and it would be possible to recover all the data by entering exactly the same [.filename]#vinum# configuration data again, the situation is hard to fix. It is necessary to move the entire [.filename]#vinum# partition by at least 4 KB, to have the [.filename]#vinum# header and the system bootstrap no longer collide. |