git: 50dd8d42f6 - main - Fix several small typos and improve wording in Handbook
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sat, 21 May 2022 15:14:19 UTC
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=50dd8d42f666922623424b9f8b310869ce415383
commit 50dd8d42f666922623424b9f8b310869ce415383
Author: Andreas Bjørnestad <panden (AT) gmail.com>
AuthorDate: 2022-05-21 15:13:51 +0000
Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2022-05-21 15:13:51 +0000
Fix several small typos and improve wording in Handbook
PR: 254153
---
.../books/handbook/advanced-networking/_index.adoc | 24 +++++++++++-----------
.../en/books/handbook/bibliography/_index.adoc | 5 +++--
.../en/books/handbook/firewalls/_index.adoc | 23 +++++++++++++--------
.../content/en/books/handbook/geom/_index.adoc | 2 +-
.../content/en/books/handbook/mail/_index.adoc | 2 +-
.../en/books/handbook/network-servers/_index.adoc | 23 +++++++++++----------
.../content/en/books/handbook/security/_index.adoc | 14 ++++++-------
.../en/books/handbook/usb-device-mode/_index.adoc | 4 ++--
8 files changed, 52 insertions(+), 45 deletions(-)
diff --git a/documentation/content/en/books/handbook/advanced-networking/_index.adoc b/documentation/content/en/books/handbook/advanced-networking/_index.adoc
index 8d30e5e8a0..743e6d03a0 100644
--- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc
+++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc
@@ -469,15 +469,15 @@ For users who do not want to use modules, it is possible to compile these driver
[.programlisting]
....
-device wlan # 802.11 support
-device wlan_wep # 802.11 WEP support
-device wlan_ccmp # 802.11 CCMP support
-device wlan_tkip # 802.11 TKIP support
-device wlan_amrr # AMRR transmit rate control algorithm
-device ath # Atheros pci/cardbus NIC's
-device ath_hal # pci/cardbus chip support
-options AH_SUPPORT_AR5416 # enable AR5416 tx/rx descriptors
-device ath_rate_sample # SampleRate tx rate control for ath
+device wlan # 802.11 support
+device wlan_wep # 802.11 WEP support
+device wlan_ccmp # 802.11 CCMP support
+device wlan_tkip # 802.11 TKIP support
+device wlan_amrr # AMRR transmit rate control algorithm
+device ath # Atheros pci/cardbus NIC's
+device ath_hal # pci/cardbus chip support
+options AH_SUPPORT_AR5416 # enable AR5416 tx/rx descriptors
+device ath_rate_sample # SampleRate tx rate control for ath
....
With this information in the kernel configuration file, recompile the kernel and reboot the FreeBSD machine.
@@ -1379,10 +1379,10 @@ Debugging support is provided by man:wpa_supplicant[8]. Try running this utility
net.wlan.0.debug: 0 => 0xc80000<assoc,auth,scan>
....
+
-Many useful statistics are maintained by the 802.11 layer and `wlanstats`, found in [.filename]#/usr/src/tools/tools/net80211#, will dump this information.
+Many useful statistics are maintained by the 802.11 layer and `wlanstats`, found in [.filename]#/usr/src/tools/tools/net80211#, will dump this information.
These statistics should display all errors identified by the 802.11 layer.
However, some errors are identified in the device drivers that lie below the 802.11 layer so they may not show up.
-To diagnose device-specific problems, refer to the drivers' documentation.
+To diagnose device-specific problems, refer to the driver documentation.
If the above information does not help to clarify the problem, submit a problem report and include output from the above tools.
@@ -1919,7 +1919,7 @@ In this situation, using a router-based firewall is difficult because of subnett
A bridge-based firewall can be configured without any IP addressing issues.
Network Tap::
-A bridge can join two network segments in order to inspect all Ethernet frames that pass between them using man:bpf[4] and man:tcpdump[1] on the bridge interface or by sending a copy of all frames out an additional interface known as a span port.
+A bridge can join two network segments in order to inspect all Ethernet frames that pass between them using man:bpf[4] and man:tcpdump[1] on the bridge interface, or by sending a copy of all frames out on an additional interface known as a span port.
Layer 2 VPN::
Two Ethernet networks can be joined across an IP link by bridging the networks to an EtherIP tunnel or a man:tap[4] based solution such as OpenVPN.
diff --git a/documentation/content/en/books/handbook/bibliography/_index.adoc b/documentation/content/en/books/handbook/bibliography/_index.adoc
index db52ba4fff..b5373676ae 100644
--- a/documentation/content/en/books/handbook/bibliography/_index.adoc
+++ b/documentation/content/en/books/handbook/bibliography/_index.adoc
@@ -76,10 +76,11 @@ International books:
English language books:
-* http://www.absoluteFreeBSD.com/[Absolute FreeBSD, 2nd Edition: The Complete Guide to FreeBSD], published by http://www.nostarch.com/[No Starch Press], 2007. ISBN: 978-1-59327-151-0
+* Absolute FreeBSD: The Complete Guide To FreeBSD, Third Edition, published by http://www.nostarch.com/[No Starch Press], 2018. ISBN: 9781593278922
+* The Complete FreeBSD, published by http://www.oreilly.com/[O'Reilly], 2003. ISBN: 0596005164
* http://www.freebsdmall.com/cgi-bin/fm/bsdcomp[The Complete FreeBSD], published by http://www.oreilly.com/[O'Reilly], 2003. ISBN: 0596005164
* http://www.freebsd-corp-net-guide.com/[The FreeBSD Corporate Networker's Guide], published by http://www.awl.com/aw/[Addison-Wesley], 2000. ISBN: 0201704811
-* http://andrsn.stanford.edu/FreeBSD/introbook/[FreeBSD: An Open-Source Operating System for Your Personal Computer], published by The Bit Tree Press, 2001. ISBN: 0971204500
+* FreeBSD: An Open-Source Operating System for Your Personal Computer, published by The Bit Tree Press, 2001. ISBN: 0971204500
* Teach Yourself FreeBSD in 24 Hours, published by http://www.samspublishing.com/[Sams], 2002. ISBN: 0672324245
* FreeBSD 6 Unleashed, published by http://www.samspublishing.com/[Sams], 2006. ISBN: 0672328755
* FreeBSD: The Complete Reference, published by http://books.mcgraw-hill.com[McGrawHill], 2003. ISBN: 0072224096
diff --git a/documentation/content/en/books/handbook/firewalls/_index.adoc b/documentation/content/en/books/handbook/firewalls/_index.adoc
index ec3bc64543..0d77039b67 100644
--- a/documentation/content/en/books/handbook/firewalls/_index.adoc
+++ b/documentation/content/en/books/handbook/firewalls/_index.adoc
@@ -502,8 +502,8 @@ The most common points against using FTP include:
* The protocol demands the use of at least two TCP connections (control and data) on separate ports.
* When a session is established, data is communicated using randomly selected ports.
-All of these points present security challenges, even before considering any potential security weaknesses in client or server software.
-More secure alternatives for file transfer exist, such as man:sftp[1] or man:scp[1], which both feature authentication and data transfer over encrypted connections..
+All of these points present security challenges, even before considering any potential security weaknesses in client or server software.
+More secure alternatives for file transfer exist, such as man:sftp[1] or man:scp[1], which both feature authentication and data transfer over encrypted connections.
For those situations when FTP is required, PF provides redirection of FTP traffic to a small proxy program called man:ftp-proxy[8], which is included in the base system of FreeBSD.
The role of the proxy is to dynamically insert and delete rules in the ruleset, using a set of anchors, to correctly handle FTP traffic.
@@ -515,7 +515,12 @@ To enable the FTP proxy, add this line to [.filename]#/etc/rc.conf#:
ftpproxy_enable="YES"
....
-Then start the proxy by running `service ftp-proxy start`.
+Then start the proxy by running:
+
+[source,bash]
+....
+# service ftp-proxy start
+....
For a basic configuration, three elements need to be added to [.filename]#/etc/pf.conf#.
First, the anchors which the proxy will use to insert the rules it generates for the FTP sessions:
@@ -1453,7 +1458,7 @@ net.inet.tcp.tso="0"
A NAT instance will also be configured.
It is possible to have multiple NAT instances each with their own configuration.
For this example only one NAT instance is needed, NAT instance number 1.
-The configuration can take a few options such as: `if` which indicates the public interface, `same_ports` which takes care that alliased ports and local port numbers are mapped the same, `unreg_only` will result in only unregistered (private) address spaces to be processed by the NAT instance, and `reset` which will help to keep a functioning NAT instance even when the public IP address of the IPFW machine changes.
+The configuration can take a few options such as: `if` which indicates the public interface, `same_ports` which takes care that aliased ports and local port numbers are mapped the same, `unreg_only` will result in only unregistered (private) address spaces to be processed by the NAT instance, and `reset` which will help to keep a functioning NAT instance even when the public IP address of the IPFW machine changes.
For all possible options that can be passed to a single NAT instance configuration consult man:ipfw[8].
When configuring a stateful NATing firewall, it is necessary to allow translated packets to be reinjected in the firewall for further processing.
This can be achieved by disabling `one_pass` behavior at the start of the firewall script.
@@ -2079,10 +2084,10 @@ All the rules use `quick` and specify the appropriate port numbers and, where ap
# firewall, destined for the Internet.
# Allow outbound access to public DNS servers.
-# Replace x.x.x. with address listed in /etc/resolv.conf.
+# Replace x.x.x.x with address listed in /etc/resolv.conf.
# Repeat for each DNS server.
-pass out quick on dc0 proto tcp from any to x.x.x. port = 53 flags S keep state
-pass out quick on dc0 proto udp from any to xxx port = 53 keep state
+pass out quick on dc0 proto tcp from any to x.x.x.x port = 53 flags S keep state
+pass out quick on dc0 proto udp from any to x.x.x.x port = 53 keep state
# Allow access to ISP's specified DHCP server for cable or DSL networks.
# Use the first rule, then check log for the IP address of DHCP server.
@@ -2680,6 +2685,6 @@ After identifying the address to be unblocked from the list, the following comma
# pfctl -a blacklistd/22 -t port22 -T delete 213.0.123.128/25
....
-The address is now removed from PF, but will still show up in the blacklistctl list, since it does not know about any changes made in PF.
-The entry in blacklistd's database will eventually expire and be removed from its output eventually.
+The address is now removed from PF, but will still show up in the blacklistctl list, since it does not know about any changes made in PF.
+The entry in blacklistd's database will eventually expire and be removed from its output.
The entry will be added again if the host is matching one of the block rules in blacklistd again.
diff --git a/documentation/content/en/books/handbook/geom/_index.adoc b/documentation/content/en/books/handbook/geom/_index.adoc
index b220487080..01a26d9ae5 100644
--- a/documentation/content/en/books/handbook/geom/_index.adoc
+++ b/documentation/content/en/books/handbook/geom/_index.adoc
@@ -621,7 +621,7 @@ Manual root filesystem specification:
Mount <device> using filesystem <fstype>
and with the specified (optional) option list.
- eg. ufs:/dev/da0s1a
+ e.g. ufs:/dev/da0s1a
zfs:tank
cd9660:/dev/acd0 ro
(which is equivalent to: mount -t cd9660 -o ro /dev/acd0 /)
diff --git a/documentation/content/en/books/handbook/mail/_index.adoc b/documentation/content/en/books/handbook/mail/_index.adoc
index 565e546b12..e433388bc6 100644
--- a/documentation/content/en/books/handbook/mail/_index.adoc
+++ b/documentation/content/en/books/handbook/mail/_index.adoc
@@ -567,7 +567,7 @@ Your ISP can provide this service.
[[mail-domain]]
=== Mail for a Domain
-When configuring a MTA for a network, any mail sent to hosts in its domain should be diverted to the MTA so that users can receive their mail on the master mail server.
+When configuring an MTA for a network, any mail sent to hosts in its domain should be diverted to the MTA so that users can receive their mail on the master mail server.
To make life easiest, a user account with the same _username_ should exist on both the MTA and the system with the MUA.
Use man:adduser[8] to create the user accounts.
diff --git a/documentation/content/en/books/handbook/network-servers/_index.adoc b/documentation/content/en/books/handbook/network-servers/_index.adoc
index 3bc99dd05b..1b8d48eb95 100644
--- a/documentation/content/en/books/handbook/network-servers/_index.adoc
+++ b/documentation/content/en/books/handbook/network-servers/_index.adoc
@@ -262,7 +262,7 @@ Some daemons, such as fingerd, can provide information that may be useful to an
Only enable the services which are needed and monitor the system for excessive connection attempts.
`max-connections-per-ip-per-minute`, `max-child` and `max-child-per-ip` can be used to limit such attacks.
-By default, TCP wrappers is enabled.
+By default, TCP wrappers are enabled.
Consult man:hosts_access[5] for more information on placing TCP restrictions on various inetd invoked daemons.
[[network-nfs]]
@@ -476,11 +476,13 @@ This chapter only describes the man:autofs[5] automounter.
The man:autofs[5] facility is a common name for several components that, together, allow for automatic mounting of remote and local filesystems whenever a file or directory within that file system is accessed.
It consists of the kernel component, man:autofs[5], and several userspace applications: man:automount[8], man:automountd[8] and man:autounmountd[8].
It serves as an alternative for man:amd[8] from previous FreeBSD releases.
-Amd is still provided for backward compatibility purposes, as the two use different map format; the one used by autofs is the same as with other SVR4 automounters, such as the ones in Solaris, MacOS X, and Linux.
+amd is still provided for backward compatibility purposes, as the two use different map formats; the one used by autofs is the same as with other SVR4 automounters, such as the ones in Solaris, MacOS X, and Linux.
The man:autofs[5] virtual filesystem is mounted on specified mountpoints by man:automount[8], usually invoked during boot.
-Whenever a process attempts to access file within the man:autofs[5] mountpoint, the kernel will notify man:automountd[8] daemon and pause the triggering process. The man:automountd[8] daemon will handle kernel requests by finding the proper map and mounting the filesystem according to it, then signal the kernel to release blocked process. The man:autounmountd[8] daemon automatically unmounts automounted filesystems after some time, unless they are still being used.
+Whenever a process attempts to access a file within the man:autofs[5] mountpoint, the kernel will notify man:automountd[8] daemon and pause the triggering process.
+The man:automountd[8] daemon will handle kernel requests by finding the proper map and mounting the filesystem according to it, then signal the kernel to release blocked process.
+The man:autounmountd[8] daemon automatically unmounts automounted filesystems after some time, unless they are still being used.
The primary autofs configuration file is [.filename]#/etc/auto_master#. It assigns individual maps to top-level mounts.
For an explanation of [.filename]#auto_master# and the map syntax, refer to man:auto_master[5].
@@ -1960,13 +1962,12 @@ Any existing nameservers in [.filename]#/etc/resolv.conf# will be configured as
If any of the listed nameservers do not support DNSSEC, local DNS resolution will fail.
Be sure to test each nameserver and remove any that fail the test.
The following command will show the trust tree or a failure for a nameserver running on `192.168.1.1`:
-====
-
[source,shell]
....
% drill -S FreeBSD.org @192.168.1.1
....
+====
Once each nameserver is confirmed to support DNSSEC, start Unbound:
@@ -2586,14 +2587,14 @@ Further documentation can be found in [.filename]#/usr/share/doc/ntp/# in HTML f
=== NTP Configuration
On FreeBSD, the built-in ntpd can be used to synchronize a system's clock.
-Ntpd is configured using man:rc.conf[5] variables and [.filename]#/etc/ntp.conf#, as detailed in the following sections.
+ntpd is configured using man:rc.conf[5] variables and [.filename]#/etc/ntp.conf#, as detailed in the following sections.
-Ntpd communicates with its network peers using UDP packets.
+ntpd communicates with its network peers using UDP packets.
Any firewalls between your machine and its NTP peers must be configured to allow UDP packets in and out on port 123.
==== The [.filename]#/etc/ntp.conf# file
-Ntpd reads [.filename]#/etc/ntp.conf# to determine which NTP servers to query.
+ntpd reads [.filename]#/etc/ntp.conf# to determine which NTP servers to query.
Choosing several NTP servers is recommended in case one of the servers becomes unreachable or its clock proves unreliable.
As ntpd receives responses, it favors reliable servers over the less reliable ones.
The servers which are queried can be local to the network, provided by an ISP, or selected from an http://support.ntp.org/bin/view/Servers/WebHome[ online list of publicly accessible NTP servers].
@@ -2645,7 +2646,7 @@ For more details, refer to the `Access Control Support` subsection of man:ntp.co
The `server` keyword specifies a single server to query.
The file can contain multiple server keywords, with one server listed on each line.
The `pool` keyword specifies a pool of servers.
-Ntpd will add one or more servers from this pool as needed to reach the number of peers specified using the `tos minclock` value.
+ntpd will add one or more servers from this pool as needed to reach the number of peers specified using the `tos minclock` value.
The `iburst` keyword directs ntpd to perform a burst of eight quick packet exchanges with a server when contact is first established, to help quickly synchronize system time.
The `leapfile` keyword specifies the location of a file containing information about leap seconds.
@@ -2679,9 +2680,9 @@ Set `ntpd_flags=` to contain any other ntpd flags as needed, but avoid using the
* `-c` (set `ntpd_config=` instead)
-==== Ntpd and the unpriveleged `ntpd` user
+==== ntpd and the unpriveleged `ntpd` user
-Ntpd on FreeBSD can start and run as an unpriveleged user.
+ntpd on FreeBSD can start and run as an unpriveleged user.
Doing so requires the man:mac_ntpd[4] policy module.
The [.filename]#/etc/rc.d/ntpd# startup script first examines the NTP configuration.
If possible, it loads the `mac_ntpd` module, then starts ntpd as unpriveleged user `ntpd` (user id 123).
diff --git a/documentation/content/en/books/handbook/security/_index.adoc b/documentation/content/en/books/handbook/security/_index.adoc
index 1e83b86411..d7affaa5df 100644
--- a/documentation/content/en/books/handbook/security/_index.adoc
+++ b/documentation/content/en/books/handbook/security/_index.adoc
@@ -1143,10 +1143,10 @@ If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:PA
-Locality Name (eg, city) []:Pittsburgh
-Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Company
-Organizational Unit Name (eg, section) []:Systems Administrator
-Common Name (eg, YOUR name) []:localhost.example.org
+Locality Name (e.g., city) []:Pittsburgh
+Organization Name (e.g., company) [Internet Widgits Pty Ltd]:My Company
+Organizational Unit Name (e.g., section) []:Systems Administrator
+Common Name (e.g., YOUR name) []:localhost.example.org
Email Address []:trhodes@FreeBSD.org
Please enter the following 'extra' attributes
@@ -1190,9 +1190,9 @@ If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:PA
-Locality Name (eg, city) []:Pittsburgh
-Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Company
-Organizational Unit Name (eg, section) []:Systems Administrator
+Locality Name (e.g., city) []:Pittsburgh
+Organization Name (e.g., company) [Internet Widgits Pty Ltd]:My Company
+Organizational Unit Name (e.g., section) []:Systems Administrator
Common Name (e.g. server FQDN or YOUR name) []:localhost.example.org
Email Address []:trhodes@FreeBSD.org
....
diff --git a/documentation/content/en/books/handbook/usb-device-mode/_index.adoc b/documentation/content/en/books/handbook/usb-device-mode/_index.adoc
index 11c65d34fb..ba62cedfc5 100644
--- a/documentation/content/en/books/handbook/usb-device-mode/_index.adoc
+++ b/documentation/content/en/books/handbook/usb-device-mode/_index.adoc
@@ -140,7 +140,7 @@ To load the module and set the template without rebooting use:
To connect to a board configured to provide USB device mode serial ports, connect the USB host, such as a laptop, to the boards USB OTG or USB client port.
Use `pstat -t` on the host to list the terminal lines.
-Near the end of the list you should see a USB serial port, eg "ttyU0".
+Near the end of the list you should see a USB serial port, e.g. "ttyU0".
To open the connection, use:
[source,shell]
@@ -240,7 +240,7 @@ The cfumass startup script sets the correct template number automatically when s
=== Configuring USB Mass Storage Using Other Means
The rest of this chapter provides detailed description of setting the target without using the cfumass rc file.
-This is necessary if eg one wants to provide a writeable LUN.
+This is necessary if e.g. one wants to provide a writeable LUN.
USB Mass Storage does not require the man:ctld[8] daemon to be running, although it can be used if desired.
This is different from iSCSI.