diff options
| author | Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> | 2023-07-06 12:04:54 +0000 |
|---|---|---|
| committer | Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> | 2023-07-06 12:04:54 +0000 |
| commit | b113509f32da681db41fd60594b723c13334df8e (patch) | |
| tree | 642f984f78a3d19e46a79fa76b48662bb35e6f46 | |
| parent | 3ba5fc40d0f5a946ffb89268c319c8967365d5fb (diff) | |
| download | doc-b113509f32.tar.gz doc-b113509f32.zip | |
Handbook WG - Create a new network chapter
Create a new chaper with the basic configuration of a wired
and wireless networks in FreeBSD.
Sections of the new chapter:
- Synopsis
- Setting up the Network
- Wired Networks
- Wireless Networks
- Hostname
- DNS
- Troubleshooting
Changes:
- Move wired network section from config to network
- Move virtual hosts section from config to advanced networking
- Move basic wireless section from advanced networking to network
- Move IPv6 from advanced networking to network
- Upgrade all command outputs
- Use sysrc
- Improve AsciiDoc syntax
Differential Revision: https://reviews.freebsd.org/D40546
Reviewed by: bcr, dbaio, fernape, karels
Sponsored by: Daifressh
41 files changed, 1202 insertions, 1546 deletions
diff --git a/documentation/content/en/books/handbook/advanced-networking/_index.adoc b/documentation/content/en/books/handbook/advanced-networking/_index.adoc index 732de75166..b9194449cd 100644 --- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc +++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 33. Advanced Networking +title: Chapter 34. Advanced Networking part: IV. Network Communication prev: books/handbook/firewalls next: books/handbook/partv description: "Advanced networking in FreeBSD: basics of gateways and routes, CARP, how to configure multiple VLANs on FreeBSD, etc" -tags: ["Advanced Networking", "Handbook", "gateway", "routes", "wireless", "tethering", "bluetooth", "bridging", "ipv6", "CARP", "VLAN"] +tags: ["Advanced Networking", "Handbook", "gateway", "routes", "wireless", "tethering", "bluetooth", "bridging", "CARP", "VLAN"] showBookMenu: true -weight: 38 +weight: 39 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 33 +:sectnumoffset: 34 :partnums: :source-highlighter: rouge :experimental: @@ -60,7 +60,6 @@ After reading this chapter, you will know: * How to set up IEEE(R) 802.11 and Bluetooth(R) devices. * How to make FreeBSD act as a bridge. * How to set up network PXE booting. -* How to set up IPv6 on a FreeBSD machine. * How to enable and utilize the features of the Common Address Redundancy Protocol (CARP) in FreeBSD. * How to configure multiple VLANs on FreeBSD. * Configure bluetooth headset. @@ -69,6 +68,7 @@ Before reading this chapter, you should: * Understand the basics of the [.filename]#/etc/rc# scripts. * Be familiar with basic network terminology. +* Understand basic network configuration on FreeBSD (crossref:network[network,FreeBSD network]). * Know how to configure and install a new FreeBSD kernel (crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]). * Know how to install additional third-party software (crossref:ports[ports,Installing Applications: Packages and Ports]). @@ -329,500 +329,65 @@ DVMRP has largely been replaced by the PIM protocol in many multicast installati Refer to man:pim[4] for more information. ==== -[[network-wireless]] -== Wireless Networking +[[configtuning-virtual-hosts]] +== Virtual Hosts -=== Wireless Networking Basics +A common use of FreeBSD is virtual site hosting, where one server appears to the network as many servers. +This is achieved by assigning multiple network addresses to a single interface. -Most wireless networks are based on the IEEE(R) 802.11 standards. -A basic wireless network consists of multiple stations communicating with radios that broadcast in either the 2.4GHz or 5GHz band, though this varies according to the locale and is also changing to enable communication in the 2.3GHz and 4.9GHz ranges. - -802.11 networks are organized in two ways. -In _infrastructure mode_, one station acts as a master with all the other stations associating to it, the network is known as a BSS, and the master station is termed an access point (AP). -In a BSS, all communication passes through the AP; even when one station wants to communicate with another wireless station, messages must go through the AP. -In the second form of network, there is no master and stations communicate directly. -This form of network is termed an IBSS and is commonly known as an _ad-hoc network_. - -802.11 networks were first deployed in the 2.4GHz band using protocols defined by the IEEE(R) 802.11 and 802.11b standard. -These specifications include the operating frequencies and the MAC layer characteristics, including framing and transmission rates, as communication can occur at various rates. -Later, the 802.11a standard defined operation in the 5GHz band, including different signaling mechanisms and higher transmission rates. -Still later, the 802.11g standard defined the use of 802.11a signaling and transmission mechanisms in the 2.4GHz band in such a way as to be backwards compatible with 802.11b networks. - -Separate from the underlying transmission techniques, 802.11 networks have a variety of security mechanisms. -The original 802.11 specifications defined a simple security protocol called WEP. -This protocol uses a fixed pre-shared key and the RC4 cryptographic cipher to encode data transmitted on a network. -Stations must all agree on the fixed key in order to communicate. -This scheme was shown to be easily broken and is now rarely used except to discourage transient users from joining networks. -Current security practice is given by the IEEE(R) 802.11i specification that defines new cryptographic ciphers and an additional protocol to authenticate stations to an access point and exchange keys for data communication. -Cryptographic keys are periodically refreshed and there are mechanisms for detecting and countering intrusion attempts. -Another security protocol specification commonly used in wireless networks is termed WPA, which was a precursor to 802.11i. -WPA specifies a subset of the requirements found in 802.11i and is designed for implementation on legacy hardware. -Specifically, WPA requires only the TKIP cipher that is derived from the original WEP cipher. -802.11i permits use of TKIP but also requires support for a stronger cipher, AES-CCM, for encrypting data. -The AES cipher was not required in WPA because it was deemed too computationally costly to be implemented on legacy hardware. - -The other standard to be aware of is 802.11e. It defines protocols for deploying multimedia applications, such as streaming video and voice over IP (VoIP), in an 802.11 network. -Like 802.11i, 802.11e also has a precursor specification termed WME (later renamed WMM) that has been defined by an industry group as a subset of 802.11e that can be deployed now to enable multimedia applications while waiting for the final ratification of 802.11e. -The most important thing to know about 802.11e and WME/WMM is that it enables prioritized traffic over a wireless network through Quality of Service (QoS) protocols and enhanced media access protocols. -Proper implementation of these protocols enables high speed bursting of data and prioritized traffic flow. - -FreeBSD supports networks that operate using 802.11a, 802.11b, and 802.11g. -The WPA and 802.11i security protocols are likewise supported (in conjunction with any of 11a, 11b, and 11g) and QoS and traffic prioritization required by the WME/WMM protocols are supported for a limited set of wireless devices. - -[[network-wireless-quick-start]] -=== Quick Start - -Connecting a computer to an existing wireless network is a very common situation. -This procedure shows the steps required. - -[.procedure] -. Obtain the SSID (Service Set Identifier) and PSK (Pre-Shared Key) for the wireless network from the network administrator. -. Identify the wireless adapter. The FreeBSD [.filename]#GENERIC# kernel includes drivers for many common wireless adapters. -If the wireless adapter is one of those models, it will be listed in the man:sysctl[8] `net.wlan.devices` variable: -+ -[source,shell] -.... -% sysctl net.wlan.devices -.... -+ -If a wireless adapter is not listed, an additional kernel module might be required, or it might be a model not supported by FreeBSD. -+ -This example shows the Atheros `ath0` wireless adapter. -. Add an entry for this network to [.filename]#/etc/wpa_supplicant.conf#. If the file does not exist, create it. Replace _myssid_ and _mypsk_ with the SSID and PSK provided by the network administrator. -+ -[.programlisting] -.... -network={ - ssid="myssid" - psk="mypsk" -} -.... - -. Add entries to [.filename]#/etc/rc.conf# to configure the network on startup: -+ -[.programlisting] -.... -wlans_ath0="wlan0" -ifconfig_wlan0="WPA SYNCDHCP" -.... - -. Restart the computer, or restart the network service to connect to the network: -+ -[source,shell] -.... -# service netif restart -.... - -[[network-wireless-basic]] -=== Basic Setup - -==== Kernel Configuration - -To use wireless networking, a wireless networking card is needed and the kernel needs to be configured with the appropriate wireless networking support. -The kernel is separated into multiple modules so that only the required support needs to be configured. - -The most commonly used wireless devices are those that use parts made by Atheros. -These devices are supported by man:ath[4] and require the following line to be added to [.filename]#/boot/loader.conf#: - -[.programlisting] -.... -if_ath_load="YES" -.... - -The Atheros driver is split up into three separate pieces: the driver (man:ath[4]), the hardware support layer that handles chip-specific functions (man:ath_hal[4]), and an algorithm for selecting the rate for transmitting frames. -When this support is loaded as kernel modules, any dependencies are automatically handled. -To load support for a different type of wireless device, specify the module for that device. -This example is for devices based on the Intersil Prism parts (man:wi[4]) driver: - -[.programlisting] -.... -if_wi_load="YES" -.... - -[NOTE] -==== -The examples in this section use an man:ath[4] device and the device name in the examples must be changed according to the configuration. -A list of available wireless drivers and supported adapters can be found in the FreeBSD Hardware Notes, available on the https://www.FreeBSD.org/releases/[Release Information] page of the FreeBSD website. -If a native FreeBSD driver for the wireless device does not exist, it may be possible to use the Windows(R) driver with the help of the crossref:config[config-network-ndis,NDIS] driver wrapper. -==== - -In addition, the modules that implement cryptographic support for the security protocols to use must be loaded. -These are intended to be dynamically loaded on demand by the man:wlan[4] module, but for now they must be manually configured. -The following modules are available: man:wlan_wep[4], man:wlan_ccmp[4], and man:wlan_tkip[4]. -The man:wlan_ccmp[4] and man:wlan_tkip[4] drivers are only needed when using the WPA or 802.11i security protocols. -If the network does not use encryption, man:wlan_wep[4] support is not needed. -To load these modules at boot time, add the following lines to [.filename]#/boot/loader.conf#: - -[.programlisting] -.... -wlan_wep_load="YES" -wlan_ccmp_load="YES" -wlan_tkip_load="YES" -.... - -Once this information has been added to [.filename]#/boot/loader.conf#, reboot the FreeBSD box. -Alternately, load the modules by hand using man:kldload[8]. - -[NOTE] -==== -For users who do not want to use modules, it is possible to compile these drivers into the kernel by adding the following lines to a custom kernel configuration file: - -[.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 -.... - -With this information in the kernel configuration file, recompile the kernel and reboot the FreeBSD machine. -==== - -Information about the wireless device should appear in the boot messages, like this: - -[source,shell] -.... -ath0: <Atheros 5212> mem 0x88000000-0x8800ffff irq 11 at device 0.0 on cardbus1 -ath0: [ITHREAD] -ath0: AR2413 mac 7.9 RF2413 phy 4.5 -.... - -==== Setting the Correct Region - -Since the regulatory situation is different in various parts of the world, it is necessary to correctly set the domains that apply to your location to have the correct information about what channels can be used. - -The available region definitions can be found in [.filename]#/etc/regdomain.xml#. -To set the data at runtime, use `ifconfig`: - -[source,shell] -.... -# ifconfig wlan0 regdomain ETSI country AT -.... - -To persist the settings, add it to [.filename]#/etc/rc.conf#: - -[source,shell] -.... -# sysrc create_args_wlan0="country AT regdomain ETSI" -.... - -=== Infrastructure Mode - -Infrastructure (BSS) mode is the mode that is typically used. -In this mode, a number of wireless access points are connected to a wired network. -Each wireless network has its own name, called the SSID. -Wireless clients connect to the wireless access points. - -==== FreeBSD Clients - -===== How to Find Access Points - -To scan for available networks, use man:ifconfig[8]. -This request may take a few moments to complete as it requires the system to switch to each available wireless frequency and probe for available access points. -Only the superuser can initiate a scan: - -[source,shell] -.... -# ifconfig wlan0 create wlandev ath0 -# ifconfig wlan0 up -# ifconfig wlan0 scan -SSID/MESH ID BSSID CHAN RATE S:N INT CAPS -dlinkap 00:13:46:49:41:76 11 54M -90:96 100 EPS WPA WME -freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 100 EPS WPA -.... - -[NOTE] -==== -The interface must be `up` before it can scan. -Subsequent scan requests do not require the interface to be marked as up again. -==== - -The output of a scan request lists each BSS/IBSS network found. -Besides listing the name of the network, the `SSID`, the output also shows the `BSSID`, which is the MAC address of the access point. -The `CAPS` field identifies the type of each network and the capabilities of the stations operating there (see the definition of `list scan` in man:ifconfig[8] for more details). - -One can also display the current list of known networks with: - -[source,shell] -.... -# ifconfig wlan0 list scan -.... - -This information may be updated automatically by the adapter or manually with a `scan` request. -Old data is automatically removed from the cache, so over time this list may shrink unless more scans are done. - -===== Basic Settings - -This section provides a simple example of how to make the wireless network adapter work in FreeBSD without encryption. -Once familiar with these concepts, it is strongly recommend to use <<network-wireless-wpa,WPA>> to set up the wireless network. - -There are three basic steps to configure a wireless network: select an access point, authenticate the station, and configure an IP address. -The following sections discuss each step. - -====== Selecting an Access Point - -Most of the time, it is sufficient to let the system choose an access point using the builtin heuristics. -This is the default behavior when an interface is marked as up or it is listed in [.filename]#/etc/rc.conf#: - -[.programlisting] -.... -wlans_ath0="wlan0" -ifconfig_wlan0="DHCP" -.... - -If there are multiple access points, a specific one can be selected by its SSID: - -[.programlisting] -.... -wlans_ath0="wlan0" -ifconfig_wlan0="ssid your_ssid_here DHCP" -.... - -In an environment where there are multiple access points with the same SSID, which is often done to simplify roaming, it may be necessary to associate to one specific device. -In this case, the BSSID of the access point can be specified, with or without the SSID: - -[.programlisting] -.... -wlans_ath0="wlan0" -ifconfig_wlan0="ssid your_ssid_here bssid xx:xx:xx:xx:xx:xx DHCP" -.... - -There are other ways to constrain the choice of an access point, such as limiting the set of frequencies the system will scan on. -This may be useful for a multi-band wireless card as scanning all the possible channels can be time-consuming. -To limit operation to a specific band, use the `mode` parameter: - -[.programlisting] -.... -wlans_ath0="wlan0" -ifconfig_wlan0="mode 11g ssid your_ssid_here DHCP" -.... - -This example will force the card to operate in 802.11g, which is defined only for 2.4GHz frequencies so any 5GHz channels will not be considered. -This can also be achieved with the `channel` parameter, which locks operation to one specific frequency, and the `chanlist` parameter, to specify a list of channels for scanning. -More information about these parameters can be found in man:ifconfig[8]. - -====== Authentication - -Once an access point is selected, the station needs to authenticate before it can pass data. -Authentication can happen in several ways. -The most common scheme, open authentication, allows any station to join the network and communicate. -This is the authentication to use for test purposes the first time a wireless network is setup. -Other schemes require cryptographic handshakes to be completed before data traffic can flow, either using pre-shared keys or secrets, or more complex schemes that involve backend services such as RADIUS. -Open authentication is the default setting. -The next most common setup is WPA-PSK, also known as WPA Personal, which is described in <<network-wireless-wpa-wpa-psk>>. - -[NOTE] -==== -If using an Apple(R) AirPort(R) Extreme base station for an access point, shared-key authentication together with a WEP key needs to be configured. -This can be configured in [.filename]#/etc/rc.conf# or by using man:wpa_supplicant[8]. -For a single AirPort(R) base station, access can be configured with: - -[.programlisting] -.... -wlans_ath0="wlan0" -ifconfig_wlan0="authmode shared wepmode on weptxkey 1 wepkey 01234567 DHCP" -.... - -In general, shared key authentication should be avoided because it uses the WEP key material in a highly-constrained manner, making it even easier to crack the key. -If WEP must be used for compatibility with legacy devices, it is better to use WEP with `open` authentication. -More information regarding WEP can be found in <<network-wireless-wep>>. -==== - -====== Getting an IP Address with DHCP - -Once an access point is selected and the authentication parameters are set, an IP address must be obtained in order to communicate. -Most of the time, the IP address is obtained via DHCP. -To achieve that, edit [.filename]#/etc/rc.conf# and add `DHCP` to the configuration for the device: - -[.programlisting] -.... -wlans_ath0="wlan0" -ifconfig_wlan0="DHCP" -.... - -The wireless interface is now ready to bring up: +A given network interface has one "real" address, and may have any number of "alias" addresses. +These aliases are normally added by placing alias entries in [.filename]#/etc/rc.conf#, as seen in this example: [source,shell] .... -# service netif start +# sysrc ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx" .... -Once the interface is running, use man:ifconfig[8] to see the status of the interface [.filename]#ath0#: +Alias entries must start with `alias__0__` using a sequential number such as `alias0`, `alias1`, and so on. +The configuration process will stop at the first missing number. -[source,shell] -.... -# ifconfig wlan0 -wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 - ether 00:11:95:d5:43:62 - inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255 - media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g - status: associated - ssid dlinkap channel 11 (2462 Mhz 11g) bssid 00:13:46:49:41:76 - country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7 - scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 - roam:rate 5 protmode CTS wme burst -.... - -The `status: associated` line means that it is connected to the wireless network. -The `bssid 00:13:46:49:41:76` is the MAC address of the access point and `authmode OPEN` indicates that the communication is not encrypted. - -====== Static IP Address - -If an IP address cannot be obtained from a DHCP server, set a fixed IP address. -Replace the `DHCP` keyword shown above with the address information. -Be sure to retain any other parameters for selecting the access point: - -[.programlisting] -.... -wlans_ath0="wlan0" -ifconfig_wlan0="inet 192.168.1.100 netmask 255.255.255.0 ssid your_ssid_here" -.... - -[[network-wireless-wpa]] -===== WPA - -Wi-Fi Protected Access (WPA) is a security protocol used together with 802.11 networks to address the lack of proper authentication and the weakness of WEP. -WPA leverages the 802.1X authentication protocol and uses one of several ciphers instead of WEP for data integrity. -The only cipher required by WPA is the Temporary Key Integrity Protocol (TKIP). -TKIP is a cipher that extends the basic RC4 cipher used by WEP by adding integrity checking, tamper detection, and measures for responding to detected intrusions. -TKIP is designed to work on legacy hardware with only software modification. -It represents a compromise that improves security but is still not entirely immune to attack. -WPA also specifies the AES-CCMP cipher as an alternative to TKIP, and that is preferred when possible. -For this specification, the term WPA2 or RSN is commonly used. +The calculation of alias netmasks is important. +For a given interface, there must be one address which correctly represents the network's netmask. +Any other addresses which fall within this network must have a netmask of all ``1``s, expressed as either `255.255.255.255` or `0xffffffff`. -WPA defines authentication and encryption protocols. -Authentication is most commonly done using one of two techniques: by 802.1X and a backend authentication service such as RADIUS, or by a minimal handshake between the station and the access point using a pre-shared secret. -The former is commonly termed WPA Enterprise and the latter is known as WPA Personal. -Since most people will not set up a RADIUS backend server for their wireless network, WPA-PSK is by far the most commonly encountered configuration for WPA. - -The control of the wireless connection and the key negotiation or authentication with a server is done using man:wpa_supplicant[8]. -This program requires a configuration file, [.filename]#/etc/wpa_supplicant.conf#, to run. -More information regarding this file can be found in man:wpa_supplicant.conf[5]. - -[[network-wireless-wpa-wpa-psk]] -====== WPA-PSK - -WPA-PSK, also known as WPA Personal, is based on a pre-shared key (PSK) which is generated from a given password and used as the master key in the wireless network. -This means every wireless user will share the same key. -WPA-PSK is intended for small networks where the use of an authentication server is not possible or desired. - -[WARNING] -==== -Always use strong passwords that are sufficiently long and made from a rich alphabet so that they will not be easily guessed or attacked. -==== - -The first step is the configuration of [.filename]#/etc/wpa_supplicant.conf# with the SSID and the pre-shared key of the network: - -[.programlisting] -.... -network={ - ssid="freebsdap" - psk="freebsdmall" -} -.... - -Then, in [.filename]#/etc/rc.conf#, indicate that the wireless device configuration will be done with WPA and the IP address will be obtained with DHCP: - -[.programlisting] -.... -wlans_ath0="wlan0" -ifconfig_wlan0="WPA DHCP" -.... - -Then, bring up the interface: - -[source,shell] -.... -# service netif start -Starting wpa_supplicant. -DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 5 -DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 6 -DHCPOFFER from 192.168.0.1 -DHCPREQUEST on wlan0 to 255.255.255.255 port 67 -DHCPACK from 192.168.0.1 -bound to 192.168.0.254 -- renewal in 300 seconds. -wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 - ether 00:11:95:d5:43:62 - inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 - media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g - status: associated - ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac - country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF - AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan - bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS - wme burst roaming MANUAL -.... +For example, consider the case where the `fxp0` interface is connected to two networks: `10.1.1.0` with a netmask of `255.255.255.0` and `202.0.75.16` with a netmask of `255.255.255.240`. +The system is to be configured to appear in the ranges `10.1.1.1` through `10.1.1.5` and `202.0.75.17` through `202.0.75.20`. +Only the first address in a given network range should have a real netmask. +All the rest (`10.1.1.2` through `10.1.1.5` and `202.0.75.18` through `202.0.75.20`) must be configured with a netmask of `255.255.255.255`. -Or, try to configure the interface manually using the information in [.filename]#/etc/wpa_supplicant.conf#: +The following [.filename]#/etc/rc.conf# entries configure the adapter correctly for this scenario: [source,shell] .... -# wpa_supplicant -i wlan0 -c /etc/wpa_supplicant.conf -Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz) -Associated with 00:11:95:c3:0d:ac -WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=CCMP GTK=CCMP] -CTRL-EVENT-CONNECTED - Connection to 00:11:95:c3:0d:ac completed (auth) [id=0 id_str=] +# sysrc ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0" +# sysrc ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255" +# sysrc ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255" +# sysrc ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255" +# sysrc ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255" +# sysrc ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240" +# sysrc ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255" +# sysrc ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255" +# sysrc ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255" .... -The next operation is to launch man:dhclient[8] to get the IP address from the DHCP server: +A simpler way to express this is with a space-separated list of IP address ranges. +The first address will be given the indicated subnet mask and the additional addresses will have a subnet mask of `255.255.255.255`. [source,shell] .... -# dhclient wlan0 -DHCPREQUEST on wlan0 to 255.255.255.255 port 67 -DHCPACK from 192.168.0.1 -bound to 192.168.0.254 -- renewal in 300 seconds. -# ifconfig wlan0 -wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 - ether 00:11:95:d5:43:62 - inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 - media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g - status: associated - ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac - country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF - AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan - bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS - wme burst roaming MANUAL +# sysrc ifconfig_fxp0_aliases="inet 10.1.1.1-5/24 inet 202.0.75.17-20/28" .... -[NOTE] -==== -If [.filename]#/etc/rc.conf# has an `ifconfig_wlan0="DHCP"` entry, man:dhclient[8] will be launched automatically after man:wpa_supplicant[8] associates with the access point. -==== - -If DHCP is not possible or desired, set a static IP address after man:wpa_supplicant[8] has authenticated the station: - -[source,shell] -.... -# ifconfig wlan0 inet 192.168.0.100 netmask 255.255.255.0 -# ifconfig wlan0 -wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 - ether 00:11:95:d5:43:62 - inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255 - media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g - status: associated - ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac - country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF - AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan - bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS - wme burst roaming MANUAL -.... +[[network-advanced-wireless]] +== Wireless Advanced Authentication -When DHCP is not used, the default gateway and the nameserver also have to be manually set: +FreeBSD supports different ways of connecting to a wireless network. +This section describes how to perform advanced authentication to a Wireless Network. -[source,shell] -.... -# route add default your_default_router -# echo "nameserver your_DNS_server" >> /etc/resolv.conf -.... +To make a connection and basic authentication to a wireless network the section crossref:network[wireless-authentication,Connection and Authentication to a Wireless Network] in the Network Chapter describes how to do it. [[network-wireless-wpa-eap-tls]] -====== WPA with EAP-TLS +=== WPA with EAP-TLS The second way to use WPA is with an 802.1X backend authentication server. In this case, WPA is called WPA Enterprise to differentiate it from the less secure WPA Personal. @@ -896,7 +461,7 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 It is also possible to bring up the interface manually using man:wpa_supplicant[8] and man:ifconfig[8]. [[network-wireless-wpa-eap-ttls]] -====== WPA with EAP-TTLS +=== WPA with EAP-TTLS With EAP-TLS, both the authentication server and the client need a certificate. With EAP-TTLS, a client certificate is optional. @@ -957,7 +522,7 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 .... [[network-wireless-wpa-eap-peap]] -====== WPA with EAP-PEAP +=== WPA with EAP-PEAP [NOTE] ==== @@ -1027,54 +592,8 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 wme burst roaming MANUAL .... -[[network-wireless-wep]] -===== WEP - -Wired Equivalent Privacy (WEP) is part of the original 802.11 standard. -There is no authentication mechanism, only a weak form of access control which is easily cracked. - -WEP can be set up using man:ifconfig[8]: - -[source,shell] -.... -# ifconfig wlan0 create wlandev ath0 -# ifconfig wlan0 inet 192.168.1.100 netmask 255.255.255.0 \ - ssid my_net wepmode on weptxkey 3 wepkey 3:0x3456789012 -.... - -* The `weptxkey` specifies which WEP key will be used in the transmission. This example uses the third key. This must match the setting on the access point. When unsure which key is used by the access point, try `1` (the first key) for this value. -* The `wepkey` selects one of the WEP keys. It should be in the format _index:key_. Key `1` is used by default; the index only needs to be set when using a key other than the first key. -+ -[NOTE] -==== -Replace the `0x3456789012` with the key configured for use on the access point. -==== - -Refer to man:ifconfig[8] for further information. - -The man:wpa_supplicant[8] facility can be used to configure a wireless interface with WEP. -The example above can be set up by adding the following lines to [.filename]#/etc/wpa_supplicant.conf#: - -[.programlisting] -.... -network={ - ssid="my_net" - key_mgmt=NONE - wep_key3=3456789012 - wep_tx_keyidx=3 -} -.... - -Then: - -[source,shell] -.... -# wpa_supplicant -i wlan0 -c /etc/wpa_supplicant.conf -Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz) -Associated with 00:13:46:49:41:76 -.... - -=== Ad-hoc Mode +[[wireless-ad-hoc-mode]] +== Wireless Ad-hoc Mode IBSS mode, also called ad-hoc mode, is designed for point to point connections. For example, to establish an ad-hoc network between the machines `A` and `B`, choose two IP addresses and a SSID. @@ -1308,85 +827,6 @@ Once the AP is running, the clients can associate with it. See <<network-wireless-wpa>> for more details. It is possible to see the stations associated with the AP using `ifconfig _wlan0_ list sta`. -==== WEP Host-based Access Point - -It is not recommended to use WEP for setting up an AP since there is no authentication mechanism and the encryption is easily cracked. -Some legacy wireless cards only support WEP and these cards will only support an AP without authentication or encryption. - -The wireless device can now be put into hostap mode and configured with the correct SSID and IP address: - -[source,shell] -.... -# ifconfig wlan0 create wlandev ath0 wlanmode hostap -# ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 \ - ssid freebsdap wepmode on weptxkey 3 wepkey 3:0x3456789012 mode 11g -.... - -* The `weptxkey` indicates which WEP key will be used in the transmission. This example uses the third key as key numbering starts with `1`. This parameter must be specified in order to encrypt the data. -* The `wepkey` sets the selected WEP key. It should be in the format _index:key_. If the index is not given, key `1` is set. The index needs to be set when using keys other than the first key. - -Use man:ifconfig[8] to see the status of the [.filename]#wlan0# interface: - -[source,shell] -.... -# ifconfig wlan0 - wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 - ether 00:11:95:c3:0d:ac - inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 - media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> - status: running - ssid freebsdap channel 4 (2427 Mhz 11g) bssid 00:11:95:c3:0d:ac - country US ecm authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit - txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs -.... - -From another wireless machine, it is now possible to initiate a scan to find the AP: - -[source,shell] -.... -# ifconfig wlan0 create wlandev ath0 -# ifconfig wlan0 up scan -SSID BSSID CHAN RATE S:N INT CAPS -freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS -.... - -In this example, the client machine found the AP and can associate with it using the correct parameters. -See <<network-wireless-wep>> for more details. - -=== Using Both Wired and Wireless Connections - -A wired connection provides better performance and reliability, while a wireless connection provides flexibility and mobility. -Laptop users typically want to roam seamlessly between the two types of connections. - -On FreeBSD, it is possible to combine two or even more network interfaces together in a "failover" fashion. -This type of configuration uses the most preferred and available connection from a group of network interfaces, and the operating system switches automatically when the link state changes. - -Link aggregation and failover is covered in <<network-aggregation>> and an example for using both wired and wireless connections is provided at <<networking-lagg-wired-and-wireless>>. - -=== Troubleshooting - -This section describes a number of steps to help troubleshoot common wireless networking problems. - -* If the access point is not listed when scanning, check that the configuration has not limited the wireless device to a limited set of channels. -* If the device cannot associate with an access point, verify that the configuration matches the settings on the access point. This includes the authentication scheme and any security protocols. Simplify the configuration as much as possible. If using a security protocol such as WPA or WEP, configure the access point for open authentication and no security to see if traffic will pass. -+ -Debugging support is provided by man:wpa_supplicant[8]. Try running this utility manually with `-dd` and look at the system logs. -* Once the system can associate with the access point, diagnose the network configuration using tools like man:ping[8]. -* There are many lower-level debugging tools. Debugging messages can be enabled in the 802.11 protocol support layer using man:wlandebug[8]. For example, to enable console messages related to scanning for access points and the 802.11 protocol handshakes required to arrange communication: -+ -[source,shell] -.... -# wlandebug -i wlan0 +scan+auth+debug+assoc - 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. -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 driver documentation. - -If the above information does not help to clarify the problem, submit a problem report and include output from the above tools. - [[network-usb-tethering]] == USB Tethering @@ -2742,255 +2182,6 @@ The `BUGS` sections in man:tftpd[8] and man:tftp[1] document some limitations wi .... **** -[[network-ipv6]] -== IPv6 - -IPv6 is the new version of the well known IP protocol, also known as IPv4. -IPv6 provides several advantages over IPv4 as well as many new features: - -* Its 128-bit address space allows for 340,282,366,920,938,463,463,374,607,431,768,211,456 addresses. This addresses the IPv4 address shortage and eventual IPv4 address exhaustion. -* Routers only store network aggregation addresses in their routing tables, thus reducing the average space of a routing table to 8192 entries. This addresses the scalability issues associated with IPv4, which required every allocated block of IPv4 addresses to be exchanged between Internet routers, causing their routing tables to become too large to allow efficient routing. - -* Address autoconfiguration (http://www.ietf.org/rfc/rfc2462.txt[RFC2462]). -* Mandatory multicast addresses. -* Built-in IPsec (IP security). -* Simplified header structure. -* Support for mobile IP. -* IPv6-to-IPv4 transition mechanisms. - -FreeBSD includes the http://www.kame.net/[http://www.kame.net/] IPv6 reference implementation and comes with everything needed to use IPv6. -This section focuses on getting IPv6 configured and running. - -=== Background on IPv6 Addresses - -There are three different types of IPv6 addresses: - -Unicast:: -A packet sent to a unicast address arrives at the interface belonging to the address. - -Anycast:: -These addresses are syntactically indistinguishable from unicast addresses but they address a group of interfaces. -The packet destined for an anycast address will arrive at the nearest router interface. -Anycast addresses are only used by routers. - -Multicast:: -These addresses identify a group of interfaces. -A packet destined for a multicast address will arrive at all interfaces belonging to the multicast group. -The IPv4 broadcast address, usually `xxx.xxx.xxx.255`, is expressed by multicast addresses in IPv6. - -When reading an IPv6 address, the canonical form is represented as `x:x:x:x:x:x:x:x`, where each `x` represents a 16 bit hex value. -An example is `FEBC:A574:382B:23C1:AA49:4592:4EFE:9982`. - -Often, an address will have long substrings of all zeros. -A `::` (double colon) can be used to replace one substring per address. -Also, up to three leading ``0``s per hex value can be omitted. -For example, `fe80::1` corresponds to the canonical form `fe80:0000:0000:0000:0000:0000:0000:0001`. - -A third form is to write the last 32 bits using the well known IPv4 notation. -For example, `2002::10.0.0.1` corresponds to the hexadecimal canonical representation `2002:0000:0000:0000:0000:0000:0a00:0001`, which in turn is equivalent to `2002::a00:1`. - -To view a FreeBSD system's IPv6 address, use man:ifconfig[8]: - -[source,shell] -.... -# ifconfig -.... - -[.programlisting] -.... -rl0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500 - inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255 - inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1 - ether 00:00:21:03:08:e1 - media: Ethernet autoselect (100baseTX ) - status: active -.... - -In this example, the [.filename]#rl0# interface is using `fe80::200:21ff:fe03:8e1%rl0`, an auto-configured link-local address which was automatically generated from the MAC address. - -Some IPv6 addresses are reserved. -A summary of these reserved addresses is seen in <<reservedip6>>: - -[[reservedip6]] -.Reserved IPv6 Addresses -[cols="1,1,1,1", frame="none", options="header"] -|=== -| IPv6 address -| Prefixlength (Bits) -| Description -| Notes - -|`::` -|128 bits -|unspecified -|Equivalent to `0.0.0.0` in IPv4. - -|`::1` -|128 bits -|loopback address -|Equivalent to `127.0.0.1` in IPv4. - -|`::00:xx:xx:xx:xx` -|96 bits -|embedded IPv4 -|The lower 32 bits are the compatible IPv4 address. - -|`::ff:xx:xx:xx:xx` -|96 bits -|IPv4 mapped IPv6 address -|The lower 32 bits are the IPv4 address for hosts which do not support IPv6. - -|`fe80::/10` -|10 bits -|link-local -|Equivalent to 169.254.0.0/16 in IPv4. - -|`fc00::/7` -|7 bits -|unique-local -|Unique local addresses are intended for local communication and are only routable within a set of cooperating sites. - -|`ff00::` -|8 bits -|multicast -| - -|``2000::-3fff::`` -|3 bits -|global unicast -|All global unicast addresses are assigned from this pool. The first 3 bits are `001`. -|=== - -For further information on the structure of IPv6 addresses, refer to http://www.ietf.org/rfc/rfc3513.txt[RFC3513]. - -=== Configuring IPv6 - -To configure a FreeBSD system as an IPv6 client, add these two lines to [.filename]#rc.conf#: - -[.programlisting] -.... -ifconfig_rl0_ipv6="inet6 accept_rtadv" -rtsold_enable="YES" -.... - -The first line enables the specified interface to receive router advertisement messages. -The second line enables the router solicitation daemon, man:rtsol[8]. - -If the interface needs a statically assigned IPv6 address, add an entry to specify the static address and associated prefix length: - -[.programlisting] -.... -ifconfig_rl0_ipv6="inet6 2001:db8:4672:6565:2026:5043:2d42:5344 prefixlen 64" -.... - -To assign a default router, specify its address: - -[.programlisting] -.... -ipv6_defaultrouter="2001:db8:4672:6565::1" -.... - -=== Connecting to a Provider - -In order to connect to other IPv6 networks, one must have a provider or a tunnel that supports IPv6: - -* Contact an Internet Service Provider to see if they offer IPv6. -* http://www.tunnelbroker.net[Hurricane Electric] offers tunnels with end-points all around the globe. - -[NOTE] -==== -Install the package:net/freenet6[] package or port for a dial-up connection. -==== - -This section demonstrates how to take the directions from a tunnel provider and convert them into [.filename]#/etc/rc.conf# settings that will persist through reboots. - -The first [.filename]#/etc/rc.conf# entry creates the generic tunneling interface [.filename]#gif0#: - -[.programlisting] -.... -cloned_interfaces="gif0" -.... - -Next, configure that interface with the IPv4 addresses of the local and remote endpoints. -Replace `_MY_IPv4_ADDR_` and `_REMOTE_IPv4_ADDR_` with the actual IPv4 addresses: - -[.programlisting] -.... -create_args_gif0="tunnel MY_IPv4_ADDR REMOTE_IPv4_ADDR" -.... - -To apply the IPv6 address that has been assigned for use as the IPv6 tunnel endpoint, add this line, replacing `_MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR_` with the assigned address: - -[.programlisting] -.... -ifconfig_gif0_ipv6="inet6 MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR" -.... - -Then, set the default route for the other side of the IPv6 tunnel. -Replace `_MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR_` with the default gateway address assigned by the provider: - -[.programlisting] -.... -ipv6_defaultrouter="MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR" -.... - -If the FreeBSD system will route IPv6 packets between the rest of the network and the world, enable the gateway using this line: - -[.programlisting] -.... -ipv6_gateway_enable="YES" -.... - -=== Router Advertisement and Host Auto Configuration - -This section demonstrates how to setup man:rtadvd[8] to advertise the IPv6 default route. - -To enable man:rtadvd[8], add the following to [.filename]#/etc/rc.conf#: - -[.programlisting] -.... -rtadvd_enable="YES" -.... - -It is important to specify the interface on which to do IPv6 router advertisement. -For example, to tell man:rtadvd[8] to use [.filename]#rl0#: - -[.programlisting] -.... -rtadvd_interfaces="rl0" -.... - -Next, create the configuration file, [.filename]#/etc/rtadvd.conf# as seen in this example: - -[.programlisting] -.... -rl0:\ - :addrs#1:addr="2001:db8:1f11:246::":prefixlen#64:tc=ether: -.... - -Replace [.filename]#rl0# with the interface to be used and `2001:db8:1f11:246::` with the prefix of the allocation. - -For a dedicated `/64` subnet, nothing else needs to be changed. -Otherwise, change the `prefixlen#` to the correct value. - -=== IPv6 and IPv4 Address Mapping - -When IPv6 is enabled on a server, there may be a need to enable IPv4 mapped IPv6 address communication. -This compatibility option allows for IPv4 addresses to be represented as IPv6 addresses. -Permitting IPv6 applications to communicate with IPv4 and vice versa may be a security issue. - -This option may not be required in most cases and is available only for compatibility. -This option will allow IPv6-only applications to work with IPv4 in a dual stack environment. -This is most useful for third party applications which may not support an IPv6-only environment. -To enable this feature, add the following to [.filename]#/etc/rc.conf#: - -[.programlisting] -.... -ipv6_ipv4mapping="YES" -.... - -Reviewing the information in RFC 3493, section 3.6 and 3.7 as well as RFC 4038 section 4.2 may be useful to some administrators. - [[carp]] == Common Address Redundancy Protocol (CARP) diff --git a/documentation/content/en/books/handbook/audit/_index.adoc b/documentation/content/en/books/handbook/audit/_index.adoc index b6b4845bbe..923b28f2e4 100644 --- a/documentation/content/en/books/handbook/audit/_index.adoc +++ b/documentation/content/en/books/handbook/audit/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 18. Security Event Auditing +title: Chapter 19. Security Event Auditing part: Part III. System Administration prev: books/handbook/mac next: books/handbook/disks description: FreeBSD security event auditing supports reliable, fine-grained, and configurable logging of a variety of security-relevant system events, including logins, configuration changes, and file and network access tags: ["audit", "terms", "configuration", "guide", "audit trails"] showBookMenu: true -weight: 22 +weight: 23 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 18 +:sectnumoffset: 19 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/bibliography/_index.adoc b/documentation/content/en/books/handbook/bibliography/_index.adoc index 6115f85a8c..4d76ee48f3 100644 --- a/documentation/content/en/books/handbook/bibliography/_index.adoc +++ b/documentation/content/en/books/handbook/bibliography/_index.adoc @@ -6,7 +6,7 @@ next: books/handbook/eresources description: FreeBSD Handbook Bibliography tags: ["appendix", "bibliography", "handbook", "books", "guides", "security", "periodicals", "journals", "magazines"] showBookMenu: true -weight: 41 +weight: 42 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/book.adoc b/documentation/content/en/books/handbook/book.adoc index a50ba2aaa5..f25c133e39 100644 --- a/documentation/content/en/books/handbook/book.adoc +++ b/documentation/content/en/books/handbook/book.adoc @@ -72,6 +72,8 @@ include::{chapters-path}x11/_index.adoc[leveloffset=+1] include::{chapters-path}wayland/_index.adoc[leveloffset=+1] +include::{chapters-path}network/_index.adoc[leveloffset=+1] + // Section two include::{chapters-path}partii.adoc[] diff --git a/documentation/content/en/books/handbook/boot/_index.adoc b/documentation/content/en/books/handbook/boot/_index.adoc index 4076aa7ff9..c1884b5441 100644 --- a/documentation/content/en/books/handbook/boot/_index.adoc +++ b/documentation/content/en/books/handbook/boot/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 14. The FreeBSD Booting Process +title: Chapter 15. The FreeBSD Booting Process part: Part III. System Administration prev: books/handbook/config next: books/handbook/security description: An introduction to the FreeBSD Booting Process, demonstrates how to customize the FreeBSD boot process, including everything that happens until the FreeBSD kernel has started, probed for devices, and started init tags: ["boot", "boot process", "device hints", "x86", "amd64", "MBR", "GPT", "UEFI", "bsdlabel", "boot0", "Single-User Mode", "Multi-User Mode"] showBookMenu: true -weight: 18 +weight: 19 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 14 +:sectnumoffset: 15 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/colophon.adoc b/documentation/content/en/books/handbook/colophon.adoc index 877cdd0a7c..51999d245d 100644 --- a/documentation/content/en/books/handbook/colophon.adoc +++ b/documentation/content/en/books/handbook/colophon.adoc @@ -3,7 +3,7 @@ title: Colophon prev: books/handbook/glossary description: FreeBSD Handbook Colophon showBookMenu: true -weight: 45 +weight: 46 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/config/_index.adoc b/documentation/content/en/books/handbook/config/_index.adoc index f14ca70e6d..71ed091867 100644 --- a/documentation/content/en/books/handbook/config/_index.adoc +++ b/documentation/content/en/books/handbook/config/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 13. Configuration and Tuning +title: Chapter 14. Configuration and Tuning part: Part III. System Administration prev: books/handbook/partiii next: books/handbook/boot description: This chapter explains much of the FreeBSD configuration process, including some of the parameters which can be set to tune a FreeBSD system. -tags: ["configuration", "tuning", "services", "cron", "virtual hosts", "logging", "configuration files", "sysctl", "tuning disks", "kernel limits", "swap", "power management"] +tags: ["configuration", "tuning", "services", "cron", "logging", "configuration files", "sysctl", "tuning disks", "kernel limits", "swap", "power management"] showBookMenu: true -weight: 17 +weight: 18 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 13 +:sectnumoffset: 14 :partnums: :source-highlighter: rouge :experimental: @@ -54,20 +54,18 @@ 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: + +* Understand UNIX(R) and FreeBSD basics (crossref:basics[basics,FreeBSD Basics]). +* Be familiar with the basics of kernel configuration and compilation (crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]). + After reading this chapter, you will know: * The basics of [.filename]#rc.conf# configuration and [.filename]#/usr/local/etc/rc.d# startup scripts. -* How to configure and test a network card. -* How to configure virtual hosts on network devices. * How to use the various configuration files in [.filename]#/etc#. * How to tune FreeBSD using man:sysctl[8] variables. * How to tune disk performance and modify kernel limitations. -Before reading this chapter, you should: - -* Understand UNIX(R) and FreeBSD basics (crossref:basics[basics,FreeBSD Basics]). -* Be familiar with the basics of kernel configuration and compilation (crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]). - [[configtuning-starting-services]] == Starting Services @@ -378,382 +376,6 @@ This allows system operators to create complex configuration scenarios. Refer to man:rc.conf[5] for further information on this topic. ==== -[[config-network-setup]] -== Setting Up Network Interface Cards - -Adding and configuring a network interface card (NIC) is a common task for any FreeBSD administrator. - -=== Locating the Correct Driver - -First, determine the model of the NIC and the chip it uses. -FreeBSD supports a wide variety of NICs. -Check the Hardware Compatibility List for the FreeBSD release to see if the NIC is supported. - -If the NIC is supported, determine the name of the FreeBSD driver for the NIC. -Refer to [.filename]#/usr/src/sys/conf/NOTES# and [.filename]#/usr/src/sys/arch/conf/NOTES# for the list of NIC drivers with some information about the supported chipsets. -When in doubt, read the manual page of the driver as it will provide more information about the supported hardware and any known limitations of the driver. - -The drivers for common NICs are already present in the [.filename]#GENERIC# kernel, meaning the NIC should be probed during boot. -The system's boot messages can be viewed by typing `more /var/run/dmesg.boot` and using the spacebar to scroll through the text. -In this example, two Ethernet NICs using the man:dc[4] driver are present on the system: - -[source,shell] -.... -dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38 -000ff irq 15 at device 11.0 on pci0 -miibus0: <MII bus> on dc0 -bmtphy0: <BCM5201 10/100baseTX PHY> PHY 1 on miibus0 -bmtphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto -dc0: Ethernet address: 00:a0:cc:da:da:da -dc0: [ITHREAD] -dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30 -000ff irq 11 at device 12.0 on pci0 -miibus1: <MII bus> on dc1 -bmtphy1: <BCM5201 10/100baseTX PHY> PHY 1 on miibus1 -bmtphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto -dc1: Ethernet address: 00:a0:cc:da:da:db -dc1: [ITHREAD] -.... - -If the driver for the NIC is not present in [.filename]#GENERIC#, but a driver is available, the driver will need to be loaded before the NIC can be configured and used. -This may be accomplished in one of two ways: - -* The easiest way is to load a kernel module for the NIC using man:kldload[8]. To also automatically load the driver at boot time, add the appropriate line to [.filename]#/boot/loader.conf#. Not all NIC drivers are available as modules. -* Alternatively, statically compile support for the NIC into a custom kernel. Refer to [.filename]#/usr/src/sys/conf/NOTES#, [.filename]#/usr/src/sys/arch/conf/NOTES# and the manual page of the driver to determine which line to add to the custom kernel configuration file. For more information about recompiling the kernel, refer to crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]. If the NIC was detected at boot, the kernel does not need to be recompiled. - -[[config-network-ndis]] -==== Using Windows(R) NDIS Drivers - -Unfortunately, there are still many vendors that do not provide schematics for their drivers to the open source community because they regard such information as trade secrets. -Consequently, the developers of FreeBSD and other operating systems are left with two choices: develop the drivers by a long and pain-staking process of reverse engineering or using the existing driver binaries available for Microsoft(R) Windows(R) platforms. - -FreeBSD provides "native" support for the Network Driver Interface Specification (NDIS). -It includes man:ndisgen[8] which can be used to convert a Windows(R) XP driver into a format that can be used on FreeBSD. -As the man:ndis[4] driver uses a Windows(R) XP binary, it only runs on i386(TM) and amd64 systems. -PCI, CardBus, PCMCIA, and USB devices are supported. - -To use man:ndisgen[8], three things are needed: - -. FreeBSD kernel sources. -. A Windows(R) XP driver binary with a [.filename]#.SYS# extension. -. A Windows(R) XP driver configuration file with a [.filename]#.INF# extension. - -Download the [.filename]#.SYS# and [.filename]#.INF# files for the specific NIC. -Generally, these can be found on the driver CD or at the vendor's website. -The following examples use [.filename]#W32DRIVER.SYS# and [.filename]#W32DRIVER.INF#. - -The driver bit width must match the version of FreeBSD. -For FreeBSD/i386, use a Windows(R) 32-bit driver. -For FreeBSD/amd64, a Windows(R) 64-bit driver is needed. - -The next step is to compile the driver binary into a loadable kernel module. -As `root`, use man:ndisgen[8]: - -[source,shell] -.... -# ndisgen /path/to/W32DRIVER.INF /path/to/W32DRIVER.SYS -.... - -This command is interactive and prompts for any extra information it requires. -A new kernel module will be generated in the current directory. -Use man:kldload[8] to load the new module: - -[source,shell] -.... -# kldload ./W32DRIVER_SYS.ko -.... - -In addition to the generated kernel module, the [.filename]#ndis.ko# and [.filename]#if_ndis.ko# modules must be loaded. -This should happen automatically when any module that depends on man:ndis[4] is loaded. -If not, load them manually, using the following commands: - -[source,shell] -.... -# kldload ndis -# kldload if_ndis -.... - -The first command loads the man:ndis[4] miniport driver wrapper and the second loads the generated NIC driver. - -Check man:dmesg[8] to see if there were any load errors. -If all went well, the output should be similar to the following: - -[source,shell] -.... -ndis0: <Wireless-G PCI Adapter> mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1 -ndis0: NDIS API version: 5.0 -ndis0: Ethernet address: 0a:b1:2c:d3:4e:f5 -ndis0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps -ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps -.... - -From here, [.filename]#ndis0# can be configured like any other NIC. - -To configure the system to load the man:ndis[4] modules at boot time, copy the generated module, [.filename]#W32DRIVER_SYS.ko#, to [.filename]#/boot/modules#. -Then, add the following line to [.filename]#/boot/loader.conf#: - -[.programlisting] -.... -W32DRIVER_SYS_load="YES" -.... - -=== Configuring the Network Card - -Once the right driver is loaded for the NIC, the card needs to be configured. -It may have been configured at installation time by man:bsdinstall[8]. - -To display the NIC configuration, enter the following command: - -[source,shell] -.... -% ifconfig -dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 - options=80008<VLAN_MTU,LINKSTATE> - ether 00:a0:cc:da:da:da - inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255 - media: Ethernet autoselect (100baseTX <full-duplex>) - status: active -dc1: flags=8802<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 - options=80008<VLAN_MTU,LINKSTATE> - ether 00:a0:cc:da:da:db - inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255 - media: Ethernet 10baseT/UTP - status: no carrier -lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 - options=3<RXCSUM,TXCSUM> - inet6 fe80::1%lo0 prefixlen 64 scopeid 0x4 - inet6 ::1 prefixlen 128 - inet 127.0.0.1 netmask 0xff000000 - nd6 options=3<PERFORMNUD,ACCEPT_RTADV> -.... - -In this example, the following devices were displayed: - -* [.filename]#dc0#: The first Ethernet interface. -* [.filename]#dc1#: The second Ethernet interface. -* [.filename]#lo0#: The loopback device. - -FreeBSD uses the driver name followed by the order in which the card is detected at boot to name the NIC. -For example, [.filename]#sis2# is the third NIC on the system using the man:sis[4] driver. - -In this example, [.filename]#dc0# is up and running. -The key indicators are: - -. `UP` means that the card is configured and ready. -. The card has an Internet (`inet`) address, `192.168.1.3`. -. It has a valid subnet mask (`netmask`), where `0xffffff00` is the same as `255.255.255.0`. -. It has a valid broadcast address, `192.168.1.255`. -. The MAC address of the card (`ether`) is `00:a0:cc:da:da:da`. -. The physical media selection is on autoselection mode (`media: Ethernet autoselect (100baseTX <full-duplex>)`). In this example, [.filename]#dc1# is configured to run with `10baseT/UTP` media. For more information on available media types for a driver, refer to its manual page. -. The status of the link (`status`) is `active`, indicating that the carrier signal is detected. For [.filename]#dc1#, the `status: no carrier` status is normal when an Ethernet cable is not plugged into the card. - -If the man:ifconfig[8] output had shown something similar to: - -[source,shell] -.... -dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> metric 0 mtu 1500 - options=80008<VLAN_MTU,LINKSTATE> - ether 00:a0:cc:da:da:da - media: Ethernet autoselect (100baseTX <full-duplex>) - status: active -.... - -it would indicate the card has not been configured. - -The card must be configured as `root`. -The NIC configuration can be performed from the command line with man:ifconfig[8] but will not persist after a reboot unless the configuration is also added to [.filename]#/etc/rc.conf#. -If a DHCP server is present on the LAN, just add this line: - -[.programlisting] -.... -ifconfig_dc0="DHCP" -.... - -Replace _dc0_ with the correct value for the system. - -The line added, then, follow the instructions given in <<config-network-testing>>. - -[NOTE] -==== -If the network was configured during installation, some entries for the NIC(s) may be already present. -Double check [.filename]#/etc/rc.conf# before adding any lines. -==== - -If there is no DHCP server, the NIC(s) must be configured manually. -Add a line for each NIC present on the system, as seen in this example: - -[.programlisting] -.... -ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0" -ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP" -.... - -Replace [.filename]#dc0# and [.filename]#dc1# and the IP address information with the correct values for the system. -Refer to the man page for the driver, man:ifconfig[8], and man:rc.conf[5] for more details about the allowed options and the syntax of [.filename]#/etc/rc.conf#. - -If the network is not using DNS, edit [.filename]#/etc/hosts# to add the names and IP addresses of the hosts on the LAN, if they are not already there. -For more information, refer to man:hosts[5] and to [.filename]#/usr/share/examples/etc/hosts#. - -[NOTE] -==== -If there is no DHCP server and access to the Internet is needed, manually configure the default gateway and the nameserver: - -[source,shell] -.... -# sysrc defaultrouter="your_default_router" -# echo 'nameserver your_DNS_server' >> /etc/resolv.conf -.... - -==== - -[[config-network-testing]] -=== Testing and Troubleshooting - -Once the necessary changes to [.filename]#/etc/rc.conf# are saved, a reboot can be used to test the network configuration and to verify that the system restarts without any configuration errors. -Alternatively, apply the settings to the networking system with this command: - -[source,shell] -.... -# service netif restart -.... - -[NOTE] -==== -If a default gateway has been set in [.filename]#/etc/rc.conf#, also issue this command: - -[source,shell] -.... -# service routing restart -.... - -==== - -Once the networking system has been relaunched, test the NICs. - -==== Testing the Ethernet Card - -To verify that an Ethernet card is configured correctly, man:ping[8] the interface itself, and then man:ping[8] another machine on the LAN: - -[source,shell] -.... -% ping -c5 192.168.1.3 -PING 192.168.1.3 (192.168.1.3): 56 data bytes -64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms -64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms -64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms -64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms -64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms - ---- 192.168.1.3 ping statistics --- -5 packets transmitted, 5 packets received, 0% packet loss -round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms -.... - -[source,shell] -.... -% ping -c5 192.168.1.2 -PING 192.168.1.2 (192.168.1.2): 56 data bytes -64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms -64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms -64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms -64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms -64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms - ---- 192.168.1.2 ping statistics --- -5 packets transmitted, 5 packets received, 0% packet loss -round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms -.... - -To test network resolution, use the host name instead of the IP address. -If there is no DNS server on the network, [.filename]#/etc/hosts# must first be configured. -To this purpose, edit [.filename]#/etc/hosts# to add the names and IP addresses of the hosts on the LAN, if they are not already there. -For more information, refer to man:hosts[5] and to [.filename]#/usr/share/examples/etc/hosts#. - -==== Troubleshooting - -When troubleshooting hardware and software configurations, check the simple things first. -Is the network cable plugged in? -Are the network services properly configured? -Is the firewall configured correctly? -Is the NIC supported by FreeBSD? -Before sending a bug report, always check the Hardware Notes, update the version of FreeBSD to the latest STABLE version, check the mailing list archives, and search the Internet. - -If the card works, yet performance is poor, read through man:tuning[7]. -Also, check the network configuration as incorrect network settings can cause slow connections. - -Some users experience one or two `device timeout` messages, which is normal for some cards. -If they continue, or are bothersome, determine if the device is conflicting with another device. -Double check the cable connections. -Consider trying another card. - -To resolve `watchdog timeout` errors, first check the network cable. -Many cards require a PCI slot which supports bus mastering. -On some old motherboards, only one PCI slot allows it, usually slot 0. -Check the NIC and the motherboard documentation to determine if that may be the problem. - -`No route to host` messages occur if the system is unable to route a packet to the destination host. -This can happen if no default route is specified or if a cable is unplugged. -Check the output of `netstat -rn` and make sure there is a valid route to the host. -If there is not, read crossref:advanced-networking[network-routing,“Gateways and Routes”]. - -`ping: sendto: Permission denied` error messages are often caused by a misconfigured firewall. -If a firewall is enabled on FreeBSD but no rules have been defined, the default policy is to deny all traffic, even man:ping[8]. -Refer to crossref:firewalls[firewalls,Firewalls] for more information. - -Sometimes performance of the card is poor or below average. -In these cases, try setting the media selection mode from `autoselect` to the correct media selection. -While this works for most hardware, it may or may not resolve the issue. -Again, check all the network settings, and refer to man:tuning[7]. - -[[configtuning-virtual-hosts]] -== Virtual Hosts - -A common use of FreeBSD is virtual site hosting, where one server appears to the network as many servers. -This is achieved by assigning multiple network addresses to a single interface. - -A given network interface has one "real" address, and may have any number of "alias" addresses. -These aliases are normally added by placing alias entries in [.filename]#/etc/rc.conf#, as seen in this example: - -[.programlisting] -.... -ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx" -.... - -Alias entries must start with `alias__0__` using a sequential number such as `alias0`, `alias1`, and so on. -The configuration process will stop at the first missing number. - -The calculation of alias netmasks is important. -For a given interface, there must be one address which correctly represents the network's netmask. -Any other addresses which fall within this network must have a netmask of all ``1``s, expressed as either `255.255.255.255` or `0xffffffff`. - -For example, consider the case where the [.filename]#fxp0# interface is connected to two networks: `10.1.1.0` with a netmask of `255.255.255.0` and `202.0.75.16` with a netmask of `255.255.255.240`. -The system is to be configured to appear in the ranges `10.1.1.1` through `10.1.1.5` and `202.0.75.17` through `202.0.75.20`. -Only the first address in a given network range should have a real netmask. -All the rest (`10.1.1.2` through `10.1.1.5` and `202.0.75.18` through `202.0.75.20`) must be configured with a netmask of `255.255.255.255`. - -The following [.filename]#/etc/rc.conf# entries configure the adapter correctly for this scenario: - -[.programlisting] -.... -ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0" -ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255" -ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255" -ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255" -ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255" -ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240" -ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255" -ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255" -ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255" -.... - -A simpler way to express this is with a space-separated list of IP address ranges. -The first address will be given the indicated subnet mask and the additional addresses will have a subnet mask of `255.255.255.255`. - -[.programlisting] -.... -ifconfig_fxp0_aliases="inet 10.1.1.1-5/24 inet 202.0.75.17-20/28" -.... - [[configtuning-syslog]] == Configuring System Logging @@ -1134,102 +756,6 @@ These include: |Automatically generated system-specific database files, such as the package database and the man:locate[1] database. |=== -=== Hostnames - -==== [.filename]#/etc/resolv.conf# - -How a FreeBSD system accesses the Internet Domain Name System (DNS) is controlled by man:resolv.conf[5]. - -The most common entries to [.filename]#/etc/resolv.conf# are: - -[.informaltable] -[cols="1,1", frame="none"] -|=== - -|`nameserver` -|The IP address of a name server the resolver should query. The servers are queried in the order listed with a maximum of three. - -|`search` -|Search list for hostname lookup. This is normally determined by the domain of the local hostname. - -|`domain` -|The local domain name. -|=== - -A typical [.filename]#/etc/resolv.conf# looks like this: - -[.programlisting] -.... -search example.com -nameserver 147.11.1.11 -nameserver 147.11.100.30 -.... - -[NOTE] -==== -Only one of the `search` and `domain` options should be used. -==== - -When using DHCP, man:dhclient[8] usually rewrites [.filename]#/etc/resolv.conf# with information received from the DHCP server. - -==== [.filename]#/etc/hosts# - -[.filename]#/etc/hosts# is a simple text database which works in conjunction with DNS and NIS to provide host name to IP address mappings. -Entries for local computers connected via a LAN can be added to this file for simplistic naming purposes instead of setting up a man:named[8] server. -Additionally, [.filename]#/etc/hosts# can be used to provide a local record of Internet names, reducing the need to query external DNS servers for commonly accessed names. - -[.programlisting] -.... -# $FreeBSD$ -# -# -# Host Database -# -# This file should contain the addresses and aliases for local hosts that -# share this file. Replace 'my.domain' below with the domainname of your -# machine. -# -# In the presence of the domain name service or NIS, this file may -# not be consulted at all; see /etc/nsswitch.conf for the resolution order. -# -# -::1 localhost localhost.my.domain -127.0.0.1 localhost localhost.my.domain -# -# Imaginary network. -#10.0.0.2 myname.my.domain myname -#10.0.0.3 myfriend.my.domain myfriend -# -# According to RFC 1918, you can use the following IP networks for -# private nets which will never be connected to the Internet: -# -# 10.0.0.0 - 10.255.255.255 -# 172.16.0.0 - 172.31.255.255 -# 192.168.0.0 - 192.168.255.255 -# -# In case you want to be able to connect to the Internet, you need -# real official assigned numbers. Do not try to invent your own network -# numbers but instead get one from your network provider (if any) or -# from your regional registry (ARIN, APNIC, LACNIC, RIPE NCC, or AfriNIC.) -# -.... - -The format of [.filename]#/etc/hosts# is as follows: - -[.programlisting] -.... -[Internet address] [official hostname] [alias1] [alias2] ... -.... - -For example: - -[.programlisting] -.... -10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2 -.... - -Consult man:hosts[5] for more information. - [[configtuning-sysctl]] == Tuning with man:sysctl[8] diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc index b1b07c7f6a..c4505f0dd5 100644 --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 25. Updating and Upgrading FreeBSD +title: Chapter 26. Updating and Upgrading FreeBSD part: Part III. System Administration prev: books/handbook/l10n next: books/handbook/dtrace description: Information about how to keep a FreeBSD system up-to-date with freebsd-update or Git, how to rebuild and reinstall the entire base system, etc tags: ["updating", "upgrading", "documentation", "FreeBSD-STABLE", "FreeBSD-CURRENT", "Security Patches"] showBookMenu: true -weight: 29 +weight: 30 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 25 +:sectnumoffset: 26 :partnums: :source-highlighter: rouge :experimental: @@ -810,7 +810,7 @@ STABLE branches occasionally have bugs or incompatibilities which might affect u |`_X_-CURRENT` |`main` -|The latest unreleased development version of FreeBSD. The `main` branch can have major bugs or incompatibilities and is recommended only for advanced users. +|The latest unreleased development version of FreeBSD. The CURRENT branch can have major bugs or incompatibilities and is recommended only for advanced users. |=== Determine which version of FreeBSD is being used with man:uname[1]: diff --git a/documentation/content/en/books/handbook/desktop/_index.adoc b/documentation/content/en/books/handbook/desktop/_index.adoc index da7e54c226..f4af398651 100644 --- a/documentation/content/en/books/handbook/desktop/_index.adoc +++ b/documentation/content/en/books/handbook/desktop/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 7. Desktop Environments +title: Chapter 8. Desktop Environments part: Part II. Common Tasks prev: books/handbook/partii next: books/handbook/multimedia description: This chapter demonstrates how to install numerous desktop environments, including web browsers, productivity software, document viewers, and financial software tags: ["desktop", "KDE Plasma", "GNOME", "XFCE", "MATE", "Cinnamon", "LXQT", "browsers", "Firefox", "Chromium", "Iridium", "Falkon", "Konqueror", "Epiphany", "qutebrowser", "Dillo", "Links", "w3m", "Development tools", "Visual Studio Code", "Qt Creator", "Kdevelop", "Eclipse IDE", "Vim", "Neovim", "GNU Emacs", "Productivity", "LibreOffice", "Calligra", "AbiWord", "Viewers", "Okular", "Evince", "ePDFView", "Xpdf", "Finance", "KMyMoney", "GnuCash"] showBookMenu: true -weight: 10 +weight: 11 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 7 +:sectnumoffset: 8 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/disks/_index.adoc b/documentation/content/en/books/handbook/disks/_index.adoc index c8ae31ed8a..225f4be937 100644 --- a/documentation/content/en/books/handbook/disks/_index.adoc +++ b/documentation/content/en/books/handbook/disks/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 19. Storage +title: Chapter 20. Storage part: Part III. System Administration prev: books/handbook/audit next: books/handbook/geom description: This chapter covers the use of disks and storage media in FreeBSD. This includes SCSI and IDE disks, CD and DVD media, memory-backed disks, and USB storage devices. tags: ["storage", "disks", "gpart", "mount", "quotas", "encrypt", "GPT", "cdrecord", "NTFS", "quotas", "swap", "HAST", "CD", "DVD", "resizing", "growing"] showBookMenu: true -weight: 23 +weight: 24 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 19 +:sectnumoffset: 20 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/dtrace/_index.adoc b/documentation/content/en/books/handbook/dtrace/_index.adoc index db8b873c69..11ed575cf8 100644 --- a/documentation/content/en/books/handbook/dtrace/_index.adoc +++ b/documentation/content/en/books/handbook/dtrace/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 26. DTrace +title: Chapter 27. DTrace part: Part III. System Administration prev: books/handbook/cutting-edge next: books/handbook/usb-device-mode description: This chapter explains how to use DTrace in FreeBSD tags: ["DTrace", "features", "guide", "tutorial", "kldload"] showBookMenu: true -weight: 30 +weight: 31 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 26 +:sectnumoffset: 27 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/eresources/_index.adoc b/documentation/content/en/books/handbook/eresources/_index.adoc index 5cf1921125..cb654fe60d 100644 --- a/documentation/content/en/books/handbook/eresources/_index.adoc +++ b/documentation/content/en/books/handbook/eresources/_index.adoc @@ -6,7 +6,7 @@ next: books/handbook/pgpkeys description: FreeBSD additional resources on internet like websites, mailing lists, mirrors, etc tags: ["eresources", "Websites", "Mailing Lists", "Usenet", "Newsgroups"] showBookMenu: true -weight: 42 +weight: 43 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/filesystems/_index.adoc b/documentation/content/en/books/handbook/filesystems/_index.adoc index ed11d6968e..6f6875b31b 100644 --- a/documentation/content/en/books/handbook/filesystems/_index.adoc +++ b/documentation/content/en/books/handbook/filesystems/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 22. Other File Systems +title: Chapter 23. Other File Systems part: Part III. System Administration prev: books/handbook/zfs next: books/handbook/virtualization description: This chapter shows the other filesystems supported by FreeBSD tags: ["filesystem", "ext2", "ext3", "ext4", "ext2fs"] showBookMenu: true -weight: 26 +weight: 27 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 22 +:sectnumoffset: 23 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/firewalls/_index.adoc b/documentation/content/en/books/handbook/firewalls/_index.adoc index d1cd63e497..fa7e2500d2 100644 --- a/documentation/content/en/books/handbook/firewalls/_index.adoc +++ b/documentation/content/en/books/handbook/firewalls/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 32. Firewalls +title: Chapter 33. Firewalls part: IV. Network Communication prev: books/handbook/network-servers next: books/handbook/advanced-networking description: "FreeBSD has three firewalls built into the base system: PF, IPFW, and IPFILTER. This chapter covers how to define packet filtering rules, the differences between the firewalls built into FreeBSD and how to use them" tags: ["firewall", "pf", "ipfw", "ipfilter", "blacklistd", "filtering"] showBookMenu: true -weight: 37 +weight: 38 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 32 +:sectnumoffset: 33 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/geom/_index.adoc b/documentation/content/en/books/handbook/geom/_index.adoc index c6faa541a5..36b427eb84 100644 --- a/documentation/content/en/books/handbook/geom/_index.adoc +++ b/documentation/content/en/books/handbook/geom/_index.adoc @@ -1,12 +1,12 @@ --- -title: "Chapter 20. GEOM: Modular Disk Transformation Framework" +title: "Chapter 21. GEOM: Modular Disk Transformation Framework" part: Part III. System Administration prev: books/handbook/disks next: books/handbook/zfs description: In FreeBSD, the GEOM framework permits access and control to classes, such as Master Boot Records and BSD labels, through the use of providers, or the disk devices in /dev. tags: ["GEOM", "RAID", "RAID0", "RAID1", "RAID3", "Striping", "bsdlabel", "newfs", "labelling", "UFS", "journaling"] showBookMenu: true -weight: 24 +weight: 25 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 20 +:sectnumoffset: 21 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/glossary.adoc b/documentation/content/en/books/handbook/glossary.adoc index 24669e2d4a..bcbaefc956 100644 --- a/documentation/content/en/books/handbook/glossary.adoc +++ b/documentation/content/en/books/handbook/glossary.adoc @@ -4,7 +4,7 @@ prev: books/handbook/pgpkeys next: books/handbook/colophon description: FreeBSD Handbook Glossary showBookMenu: true -weight: 44 +weight: 45 path: "/books/handbook/" --- @@ -582,7 +582,7 @@ Massachusetts Institute of Technology:: [[mfc-glossary]] Merge From Current:: -To merge functionality or a patch from the `main` branch (-CURRENT) to another, most often -STABLE. +To merge functionality or a patch from the -CURRENT branch to another, most often -STABLE. [[mfh-glossary]] Merge From Head:: diff --git a/documentation/content/en/books/handbook/jails/_index.adoc b/documentation/content/en/books/handbook/jails/_index.adoc index a53c90ea97..2a51f99432 100644 --- a/documentation/content/en/books/handbook/jails/_index.adoc +++ b/documentation/content/en/books/handbook/jails/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 16. Jails +title: Chapter 17. Jails part: Part III. System Administration prev: books/handbook/security next: books/handbook/mac description: Jails improve on the concept of the traditional chroot environment in several ways tags: ["jails", "creating", "managing", "updating", "ezjail"] showBookMenu: true -weight: 20 +weight: 21 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 16 +:sectnumoffset: 17 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/kernelconfig/_index.adoc b/documentation/content/en/books/handbook/kernelconfig/_index.adoc index 9b5c761547..53a0098ac4 100644 --- a/documentation/content/en/books/handbook/kernelconfig/_index.adoc +++ b/documentation/content/en/books/handbook/kernelconfig/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 9. Configuring the FreeBSD Kernel +title: Chapter 10. Configuring the FreeBSD Kernel part: Part II. Common Tasks prev: books/handbook/multimedia next: books/handbook/printing description: This chapter covers how to configure the FreeBSD Kernel. When to build a custom kernel, how to take a hardware inventory, how to customize a kernel configuration file, etc tags: ["configuring", "kernel", "custom kernel", "hardware requirements", "pciconf"] showBookMenu: true -weight: 12 +weight: 13 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 9 +:sectnumoffset: 10 :partnums: :source-highlighter: rouge :experimental: @@ -64,10 +64,7 @@ After reading this chapter, you will know: * How to install the new kernel. * How to troubleshoot if things go wrong. -[NOTE] -==== All of the commands listed in the examples in this chapter should be executed as `root`. -==== [[kernelconfig-custom-kernel]] == Why Build a Custom Kernel? @@ -85,35 +82,29 @@ Some security environments prevent the loading and unloading of kernel modules a Building a custom kernel is often a rite of passage for advanced BSD users. This process, while time consuming, can provide benefits to the FreeBSD system. -Unlike the `GENERIC` kernel, which must support a wide range of hardware, a custom kernel can be stripped down to only provide support for that computer's hardware. - +Unlike the [.filename]#GENERIC# kernel, which must support a wide range of hardware, a custom kernel can be stripped down to only provide support for that computer's hardware. This has a number of benefits, such as: * Faster boot time. Since the kernel will only probe the hardware on the system, the time it takes the system to boot can decrease. -* Lower memory usage. A custom kernel often uses less memory than the `GENERIC` kernel by omitting unused features and device drivers. This is important because the kernel code remains resident in physical memory at all times, preventing that memory from being used by applications. For this reason, a custom kernel is useful on a system with a small amount of RAM. -* Additional hardware support. A custom kernel can add support for devices which are not present in the `GENERIC` kernel. +* Lower memory usage. A custom kernel often uses less memory than the [.filename]#GENERIC# kernel by omitting unused features and device drivers. This is important because the kernel code remains resident in physical memory at all times, preventing that memory from being used by applications. For this reason, a custom kernel is useful on a system with a small amount of RAM. +* Additional hardware support. A custom kernel can add support for devices which are not present in the [.filename]#GENERIC# kernel. -[NOTE] -==== Before building a custom kernel, consider the reason for doing so. If there is a need for specific hardware support, it may already exist as a module. -==== Kernel modules exist in [.filename]#/boot/kernel# and may be dynamically loaded into the running kernel using man:kldload[8]. Most kernel drivers have a loadable module and manual page. - For example, the man:ath[4] wireless network driver has the following information in its manual page: -[.programlisting] +[source,shell,subs="macros"] .... Alternatively, to load the driver as a module at boot time, place the following line in man:loader.conf[5]: - if_ath_load="YES" - if_ath_pci_load="YES" + if_ath_load="YES" .... -Adding `if_ath_load="YES"` and `if_ath_pci_load="YES"` to [.filename]#/boot/loader.conf# will load these modules dynamically at boot time. +Adding `if_ath_load="YES"` to [.filename]#/boot/loader.conf# will load this module dynamically at boot time. In some cases, there is no associated module in [.filename]#/boot/kernel#. This is mostly true for certain subsystems. @@ -125,11 +116,16 @@ Before editing the kernel configuration file, it is recommended to perform an in On a dual-boot system, the inventory can be created from the other operating system. For example, Microsoft(R)'s Device Manager contains information about installed devices. +[NOTE] +==== +Some versions of Microsoft(R) Windows(R) have a System icon which can be used to access Device Manager. +==== + If FreeBSD is the only installed operating system, use man:dmesg[8] to determine the hardware that was found and listed during the boot probe. Most device drivers on FreeBSD have a manual page which lists the hardware supported by that driver. For example, the following lines indicate that the man:psm[4] driver found a mouse: -[.programlisting] +[source,shell] .... psm0: <PS/2 Mouse> irq 12 on atkbdc0 psm0: [GIANT-LOCKED] @@ -147,12 +143,6 @@ For example: [source,shell] .... % pciconf -lv -.... - -The output should be similar to the following: - -[.programlisting] -.... ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 vendor = 'Atheros Communications Inc.' device = 'AR5212 Atheros AR5212 802.11abg wireless' @@ -160,7 +150,7 @@ ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 subclass = ethernet .... -This output shows that the `ath` driver located a wireless Ethernet device. +This output shows that the [.filename]#ath# driver located a wireless Ethernet device. The `-k` flag of man:man[1] can be used to provide useful information. For example, it can be used to display a list of manual pages which contain a particular device brand or name: @@ -168,12 +158,6 @@ For example, it can be used to display a list of manual pages which contain a pa [source,shell] .... # man -k Atheros -.... - -The output should be similar to the following: - -[.programlisting] -.... ath(4) - Atheros IEEE 802.11 wireless network driver ath_hal(4) - Atheros Hardware Access Layer (HAL) .... @@ -189,7 +173,7 @@ If [.filename]#/usr/src/# does not exist or it is empty, source has not been ins Source can be installed with Git using the instructions in crossref:mirrors[git,“Using Git”]. Once source is installed, review the contents of [.filename]#/usr/src/sys#. -This directory contains a number of subdirectories, including those which represent the FreeBSD supported architectures. +This directory contains a number of subdirectories, including those which represent the following supported architectures: [.filename]#amd64#, [.filename]#i386#, [.filename]#powerpc#, and [.filename]#sparc64#. Everything inside a particular architecture's directory deals with that architecture only and the rest of the code is machine independent code common to all platforms. Each supported architecture has a [.filename]#conf# subdirectory which contains the [.filename]#GENERIC# kernel configuration file for that architecture. @@ -205,14 +189,14 @@ This example creates a copy, named [.filename]#MYKERNEL#, of the [.filename]#GEN # cp GENERIC MYKERNEL .... -The [.filename]#MYKERNEL# file can now be customized with any text editor. +[.filename]#MYKERNEL# can now be customized with any `ASCII` text editor. +The default editor is vi, though an easier editor for beginners, called ee, is also installed with FreeBSD. 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. -More information about the configuration kernel file can be found in man:config[5]. [WARNING] ==== @@ -227,6 +211,7 @@ For architecture independent options, refer to [.filename]#/usr/src/sys/conf/NOT [TIP] ==== When finished customizing the kernel configuration file, save a backup copy to a location outside of [.filename]#/usr/src#. + Alternately, keep the kernel configuration file elsewhere and create a symbolic link to the file: [source,shell] @@ -256,113 +241,101 @@ options IPDIVERT Using this method, the local configuration file expresses local differences from a [.filename]#GENERIC# kernel. As upgrades are performed, new features added to [.filename]#GENERIC# will also be added to the local kernel unless they are specifically prevented using `nooptions` or `nodevice`. - A comprehensive list of configuration directives and their descriptions may be found in man:config[5]. +[NOTE] +==== +To build a file which contains all available options, run the following command as `root`: + +[source,shell] +.... +# cd /usr/src/sys/arch/conf && make LINT +.... + +==== + [[kernelconfig-building]] == Building and Installing a Custom Kernel Once the edits to the custom configuration file have been saved, the source code for the kernel can be compiled using the following steps: -Move to [.filename]#/usr/src#: +[.procedure] +==== +*Procedure: Building a Kernel* +. Change to this directory: ++ [source,shell] .... # cd /usr/src .... - -Compile the new kernel by specifying the name of the custom kernel configuration file: - ++ +. Compile the new kernel by specifying the name of the custom kernel configuration file: ++ [source,shell] .... # make buildkernel KERNCONF=MYKERNEL .... - -Install the new kernel associated with the specified kernel configuration file. This command will copy the new kernel to [.filename]#/boot/kernel/kernel# and save the old kernel to [.filename]#/boot/kernel.old/kernel#: - ++ +. Install the new kernel associated with the specified kernel configuration file. This command will copy the new kernel to [.filename]#/boot/kernel/kernel# and save the old kernel to [.filename]#/boot/kernel.old/kernel#: ++ [source,shell] .... # make installkernel KERNCONF=MYKERNEL .... - -Shutdown the system and reboot into the new kernel. If something goes wrong, refer to <<kernelconfig-noboot, The kernel does not boot>>. - -[TIP] ++ +. Shutdown the system and reboot into the new kernel. If something goes wrong, refer to <<kernelconfig-noboot, The kernel does not boot>>. ==== + By default, when a custom kernel is compiled, all kernel modules are rebuilt. To update a kernel faster or to build only custom modules, edit [.filename]#/etc/make.conf# before starting to build the kernel. + For example, this variable specifies the list of modules to build instead of using the default of building all modules: [.programlisting] .... -MODULES_OVERRIDE= linux ipfw +MODULES_OVERRIDE = linux acpi .... Alternately, this variable lists which modules to exclude from the build process: [.programlisting] .... -WITHOUT_MODULES= linux acpi sound -.... - -This variable instructs the build to skip kernel modules and compile only the kernel itself: - -[.programlisting] -.... -NO_MODULES= yes -.... - -The Ports Framework includes drivers and other modules that depend on kernel interfaces, such as package:graphics/drm-kmod[] or package:emulators/virtualbox-ose-kmod[]. -With the `PORTS_MODULES` variable every time the kernel is built, the ports containing kernel modules are re-built against the updated sources. -This ensures the kernel module stays in-sync with the kernel itself. -The kernel and ports trees should be updated together for maximum compatibility. -`PORTS_MODULES` can be added to [.filename]#/etc/make.conf# file to ensure all kernels you build rebuild this module. - -[.programlisting] -.... -PORTS_MODULES= drm-kmod virtualbox-ose-kmod +WITHOUT_MODULES = linux acpi sound .... Additional variables are available. Refer to man:make.conf[5] for details. -==== [[kernelconfig-trouble]] == If Something Goes Wrong There are four categories of trouble that can occur when building a custom kernel: -=== `config` fails - -If man:config[5] fails, it will print the line number that is incorrect. - -As an example, for the following message, make sure that line 32 is typed correctly by comparing it to [.filename]#GENERIC# or [.filename]#NOTES#: - +`config` fails:: +If `config` fails, it will print the line number that is incorrect. +As an example, for the following message, make sure that line 17 is typed correctly by comparing it to [.filename]#GENERIC# or [.filename]#NOTES#: ++ [source,shell] .... -config: /usr/src/sys/amd64/conf/GENERIC:32: syntax error +config: line 17: syntax error .... -=== `make` fails - -If man:make[1] fails, it is usually due to an error in the kernel configuration file which is not severe enough for `config` to catch. - +`make` fails:: +If `make` fails, it is usually due to an error in the kernel configuration file which is not severe enough for `config` to catch. Review the configuration, and if the problem is not apparent, send an email to the {freebsd-questions} which contains the kernel configuration file. [[kernelconfig-noboot]] -=== The kernel does not boot - +The kernel does not boot:: If the new kernel does not boot or fails to recognize devices, do not panic! Fortunately, FreeBSD has an excellent mechanism for recovering from incompatible kernels. - Simply choose the kernel to boot from at the FreeBSD boot loader. -This can be accessed when the system boot menu appears by selecting the "Kernel:" option, which initially displays "Kernel: default/kernel". -Each time the option is selected, another choice appears, for example "kernel.old". -When the desired kernel is listed, press return to boot. - +This can be accessed when the system boot menu appears by selecting the "Escape to a loader prompt" option. +At the prompt, type `boot _kernel.old_`, or the name of any other kernel that is known to boot properly. ++ After booting with a good kernel, check over the configuration file and try to build it again. One helpful resource is [.filename]#/var/log/messages# which records the kernel messages from every successful boot. Also, man:dmesg[8] will print the kernel messages from the current boot. - ++ [NOTE] ==== When troubleshooting a kernel make sure to keep a copy of a kernel that is known to work, such as [.filename]#GENERIC#. @@ -374,4 +347,10 @@ As soon as possible, move the working kernel by renaming the directory containin # mv /boot/kernel /boot/kernel.bad # mv /boot/kernel.good /boot/kernel .... + ==== + +The kernel works, but man:ps[1] does not:: +If the kernel version differs from the one that the system utilities have been built with, for example, a kernel built from -CURRENT sources is installed on a -RELEASE system, many system status commands like man:ps[1] and man:vmstat[8] will not work. +To fix this, crossref:cutting-edge[makeworld,recompile and install a world] built with the same version of the source tree as the kernel. +It is never a good idea to use a different version of the kernel than the rest of the operating system. diff --git a/documentation/content/en/books/handbook/l10n/_index.adoc b/documentation/content/en/books/handbook/l10n/_index.adoc index a691169b5b..d18b4490ae 100644 --- a/documentation/content/en/books/handbook/l10n/_index.adoc +++ b/documentation/content/en/books/handbook/l10n/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 24. Localization - i18n/L10n Usage and Setup +title: Chapter 25. Localization - i18n/L10n Usage and Setup part: Part III. System Administration prev: books/handbook/virtualization next: books/handbook/cutting-edge description: FreeBSD supports localization into many languages, allowing users to view, input, or process data in non-English languages tags: ["i18n", "L10n", "localization", "Locale", "LANG", "MM_CHARSET", "cap_mkdb"] showBookMenu: true -weight: 28 +weight: 29 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 24 +:sectnumoffset: 25 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/linuxemu/_index.adoc b/documentation/content/en/books/handbook/linuxemu/_index.adoc index 0f21401e8d..a122ca0546 100644 --- a/documentation/content/en/books/handbook/linuxemu/_index.adoc +++ b/documentation/content/en/books/handbook/linuxemu/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 11. Linux Binary Compatibility +title: Chapter 12. Linux Binary Compatibility part: Part II. Common Tasks prev: books/handbook/printing next: books/handbook/wine description: FreeBSD provides binary compatibility with Linux, allowing users to install and run most Linux binaries on a FreeBSD system without having to first modify the binary tags: ["linux", "linuxulator", "emulation", "binary", "compatibility"] showBookMenu: true -weight: 14 +weight: 15 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 11 +:sectnumoffset: 12 :partnums: :source-highlighter: rouge :experimental: @@ -78,7 +78,7 @@ To enable the Linux ABI at boot time, execute the following command: # sysrc linux_enable="YES" .... -Once configured, it can be enabled without rebooting by executing the following command: +Once enabled, it can be started without rebooting executing the following command: [source,shell] .... @@ -88,7 +88,7 @@ Once configured, it can be enabled without rebooting by executing the following This is enough for statically linked Linux binaries to work. The Linux service will load necessary kernel modules and mount filesystems expected by Linux applications under [.filename]#/compat/linux#. -Linux binaries can then be started in the same way that native FreeBSD binaries can; they behave almost exactly like native processes and can be traced and debugged the usual way. +They can be started in the same way native FreeBSD binaries can; they behave almost exactly like native processes and can be traced and debugged the usual way. The current content of [.filename]#/compat/linux# can be checked executing the following command: @@ -110,12 +110,12 @@ dr-xr-xr-x 1 root wheel 0 Apr 11 21:03 sys [[linux-userlands]] == Linux userlands -Most Linux software requires more than just an ABI to work, depending perhaps on common libraries. -In order to run such Linux software, a Linux userland must be installed first. +Linux software requires more than just an ABI to work. +In order to run Linux software a Linux userland must be installed first. [TIP] ==== -If all that is wanted is to run some software already included in the Ports tree, it can be installed via the man:pkg[8] package manager which will automatically setup the required Linux userland. +If all that is wanted is to run some software already included in the Ports tree, it can be installed via package manager and man:pkg[8] will automatically setup the required Linux userland. For example, to install Sublime Text 4, along with all the Linux libraries it depends on, run this command: @@ -177,7 +177,7 @@ To install debootstrap execute the following command: # pkg install debootstrap .... -man:debootstrap[8] needs man:linux[4] ABI support to be enabled as per the instructions above. +man:debootstrap[8] needs man:linux[4] ABI enabled. Once enabled, execute the following command to install Ubuntu or Debian in [.filename]#/compat/ubuntu#: [source,shell] @@ -216,7 +216,7 @@ Then set up mounts in [.filename]#/etc/fstab#. [TIP] ==== -If the contents of the home directory should be shared, or to be able to run X11 applications, [.filename]#/home# and [.filename]#/tmp# should be mounted in the linux compat area using man:nullfs[5] for loopback. +If the contents of the home directory should be shared and to be able to run X11 applications, [.filename]#/home# and [.filename]#/tmp# should be mounted in the linux compat area using man:nullfs[5] for loopback. The following example can be added to [.filename]#/etc/fstab#: @@ -261,7 +261,7 @@ The output should be similar to the following: Linux 3.17.0 x86_64 .... -Once inside the chroot, the system behaves as per a normal Ubuntu installation. +Once inside the chroot, the system behaves as in a normal Ubuntu installation While systemd doesn't work, the man:service[8] command works as usual. [TIP] @@ -357,8 +357,8 @@ This example will result in the following files on the FreeBSD system: .... If a Linux shared library already exists with a matching major revision number to the first column of the `ldd` output, it does not need to be copied to the file named in the last column, as the existing library should work. -It is advisable to copy the shared library if it is a newer version. -The old one can be removed if the symbolic link points to the new one. +It is advisable to copy the shared library if it is a newer version, though. +The old one can be removed, as long as the symbolic link points to the new one. For example, these libraries already exist on the FreeBSD system: @@ -384,18 +384,24 @@ However, it is safe to replace the existing [.filename]#libc.so# with the newer /compat/linux/lib/libc.so.4 -> libc.so.4.6.29 .... -Generally, it is only necessary to look for the shared libraries that Linux binaries depend on the first few times that a Linux program is installed on FreeBSD. +Generally, one will need to look for the shared libraries that Linux binaries depend on only the first few times that a Linux program is installed on FreeBSD. After a while, there will be a sufficient set of Linux shared libraries on the system to be able to run newly installed Linux binaries without any extra work. === Branding Linux ELF Binaries The FreeBSD kernel uses several methods to determine if the binary to be executed is a Linux one: it checks the brand in the ELF file header, looks for known ELF interpreter paths and checks ELF notes; finally, by default, unbranded ELF executables are assumed to be Linux anyway. -Should all those methods fail, an attempt to execute the binary might result in an error message: +Should all those methods fail, an attempt to execute the binary might result in error message: [source,shell] .... % ./my-linux-elf-binary +.... + +The output should be similar to the following: + +[.programlisting] +.... ELF binary type not known Abort .... @@ -419,11 +425,11 @@ Once installed, `root` can use this command to install a [.filename]#.rpm#: .... If necessary, `brandelf` the installed ELF binaries. -Note that this will prevent a clean uninstall as the binaries are modified by the `brandelf` program. +Note that this will prevent a clean uninstall. === Configuring the Hostname Resolver -When using Linux binaries, if DNS does not work or this error appears: +If DNS does not work or this error appears: [.programlisting] .... @@ -440,7 +446,7 @@ multi on .... This specifies that [.filename]#/etc/hosts# is searched first and DNS is searched second. -When [.filename]#/compat/linux/etc/host.conf# does not exist, Linux applications try to use [.filename]#/etc/host.conf# in the host system but they complain since that file does not exist in FreeBSD. +When [.filename]#/compat/linux/etc/host.conf# does not exist, Linux applications use [.filename]#/etc/host.conf# in the host system but they complain since that file does not exist in FreeBSD. Remove `bind` if a name server is not configured using [.filename]#/etc/resolv.conf#. [[linuxemu-misc]] diff --git a/documentation/content/en/books/handbook/mac/_index.adoc b/documentation/content/en/books/handbook/mac/_index.adoc index 24ab4120c0..3f01f207d0 100644 --- a/documentation/content/en/books/handbook/mac/_index.adoc +++ b/documentation/content/en/books/handbook/mac/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 17. Mandatory Access Control +title: Chapter 18. Mandatory Access Control part: Part III. System Administration prev: books/handbook/jails next: books/handbook/audit description: "This chapter focuses on the MAC framework and the set of pluggable security policy modules FreeBSD provides for enabling various security mechanisms" tags: ["MAC", "labels", "security", "configuration", "nagios"] showBookMenu: true -weight: 21 +weight: 22 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 17 +:sectnumoffset: 18 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/mail/_index.adoc b/documentation/content/en/books/handbook/mail/_index.adoc index aa05ce5dc2..8951247621 100644 --- a/documentation/content/en/books/handbook/mail/_index.adoc +++ b/documentation/content/en/books/handbook/mail/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 30. Electronic Mail +title: Chapter 31. Electronic Mail part: IV. Network Communication prev: books/handbook/ppp-and-slip next: books/handbook/network-servers description: This chapter provides a basic introduction to running a mail server on FreeBSD, as well as an introduction to sending and receiving email using FreeBSD tags: ["mail", "sendmail", "MTA", "SMTP", "user agents", "fetchmail", "procmail", "alpine", "mut"] showBookMenu: true -weight: 35 +weight: 36 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 30 +:sectnumoffset: 31 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc index d6aad98c43..ae79f9d00b 100644 --- a/documentation/content/en/books/handbook/mirrors/_index.adoc +++ b/documentation/content/en/books/handbook/mirrors/_index.adoc @@ -6,7 +6,7 @@ next: books/handbook/bibliography description: "How to get FreeBSD: CD and DVD sets, FTP sites and how to install and use Git" tags: ["Obtaining", "CD", "DVD", "FTP", "Git"] showBookMenu: true -weight: 40 +weight: 41 path: "/books/handbook/" --- @@ -75,14 +75,12 @@ Official mirrors service: | **vuxml.FreeBSD.org** / **www.VuXML.org** | link:https://www.vuxml.org/[https] | FreeBSD Project VuXML web page. `pkg audit` fetches the list of vulnerabilities from this service. - -| **www.FreeBSD.org** / **docs.FreeBSD.org** -| `https` -| link:https://www.freebsd.org/[FreeBSD Web Site] and the link:https://docs.freebsd.org/[FreeBSD Documentation Portal]. |=== All official mirrors support IPv4 and IPv6. +The FreeBSD website (https://www.FreeBSD.org and https://docs.FreeBSD.org) are not hosted in the GeoDNS Infrastructure; there are ongoing studies of its implementation. + http://ftp-archive.FreeBSD.org is not in the GeoDNS Infrastructure, hosted in only one location (US). The project is looking for new locations; those willing to sponsor, please reach out to the Cluster Administrators team for more information. diff --git a/documentation/content/en/books/handbook/multimedia/_index.adoc b/documentation/content/en/books/handbook/multimedia/_index.adoc index b9c5d272b2..618aa6dd6c 100644 --- a/documentation/content/en/books/handbook/multimedia/_index.adoc +++ b/documentation/content/en/books/handbook/multimedia/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 8. Multimedia +title: Chapter 9. Multimedia part: Part II. Common Tasks prev: books/handbook/desktop next: books/handbook/kernelconfig description: The multimedia chapter provides an overview of multimedia support on FreeBSD tags: ["multimedia", "sound card", "Audio players", "scanner", "SANE", "Video players", "Conferencing and Meetings", "Setting Up the Webcam"] showBookMenu: true -weight: 11 +weight: 12 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 8 +:sectnumoffset: 9 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/network-servers/_index.adoc b/documentation/content/en/books/handbook/network-servers/_index.adoc index 1bfbbd85a8..37ba19b0e3 100644 --- a/documentation/content/en/books/handbook/network-servers/_index.adoc +++ b/documentation/content/en/books/handbook/network-servers/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 31. Network Servers +title: Chapter 32. Network Servers part: IV. Network Communication prev: books/handbook/mail next: books/handbook/firewalls description: This chapter covers some of the more frequently used network services on UNIX systems tags: ["network", "servers", "inetd", "NFS", "NIS", "LDAP", "DHCP", "DNS", "Apache HTTP", "FTP", "Samba", "NTP", "iSCSI"] showBookMenu: true -weight: 36 +weight: 37 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 31 +:sectnumoffset: 32 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/network/_index.adoc b/documentation/content/en/books/handbook/network/_index.adoc new file mode 100644 index 0000000000..45e4a1a6bd --- /dev/null +++ b/documentation/content/en/books/handbook/network/_index.adoc @@ -0,0 +1,951 @@ +--- +title: Chapter 7. Network +part: Part I. Getting Started +prev: books/handbook/wayland +next: books/handbook/partii +description: This chapter delves into the topic of network configuration and performance, showcasing the robust networking capabilities of the FreeBSD operating system. +tags: ["network", "ipv4", "ipv6", "wireless", "wpa_supplicant", "static ip", "dynamic ip"] +showBookMenu: true +weight: 9 +path: "/books/handbook/" +--- + +[[network]] += Network +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 7 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/handbook/network/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[network-synopsis]] +== Synopsis + +This chapter delves into the topic of network configuration and performance, showcasing the robust networking capabilities of the FreeBSD operating system. +Whether working with wired or wireless networks, this chapter provides a comprehensive guide to configuring and optimizing network connectivity in FreeBSD. + +Before diving into the details, it is beneficial for readers to have a basic understanding of networking concepts such as protocols, network interfaces, and addressing. + +This chapter covers: + +* The ability to configure wired networks in FreeBSD, including network interface setup, addressing, and customization options. +* The skills to configure wireless networks in FreeBSD, encompassing wireless network interface setup, security protocols, and troubleshooting techniques. +* FreeBSD's networking capabilities and its reputation for excellent network performance. +* An understanding of various network services and protocols supported by FreeBSD, with configuration instructions for DNS, DHCP and more. + +More information about how to make advanced network configurations in crossref:advanced-networking[advanced-networking,Advanced Networking]. + +[[config-network-setup]] +== Setting up the Network + +Setting up a wired or wireless connection is a common task for a FreeBSD user. +This section will show how to identify the wired and wireless network adapters and how to configure them. + +Before starting with the configuration it is necessary to know the following network data: + +* If the network has DHCP +* If the network does not have DHCP, the static IP to be used +* The netmask +* The IP address of the default gateway + +[TIP] +==== +The network connection may have been configured at installation time by man:bsdinstall[8]. +==== + +[[config-identify-network-adapter]] +=== Identify Network Adapters + +FreeBSD supports a wide variety of network adapters for both wired and wireless networks. +Check the Hardware Compatibility List for the used link:https://www.freebsd.org/releases/[FreeBSD release] to see if the network adapter is supported. + +To get the network adapters used by our system execute the following command: + +[source,shell] +.... +% pciconf -lv | grep -A1 -B3 network +.... + +The output should be similar to the following: + +[.programlisting] +.... +em0@pci0:0:25:0: class=0x020000 rev=0x03 hdr=0x00 vendor=0x8086 device=0x10f5 subvendor=0x17aa subdevice=0x20ee + vendor = 'Intel Corporation' <1> + device = '82567LM Gigabit Network Connection' <2> + class = network + subclass = ethernet +-- +iwn0@pci0:3:0:0: class=0x028000 rev=0x00 hdr=0x00 vendor=0x8086 device=0x4237 subvendor=0x8086 subdevice=0x1211 + vendor = 'Intel Corporation' <1> + device = 'PRO/Wireless 5100 AGN [Shiloh] Network Connection' <2> + class = networ +.... + +The text before the '@' symbol is the name of the driver controlling the device. +In this case these are man:em[4] and man:iwn[4]. + +<1> Shows the name of the vendor +<2> Shows the name of the device + +[NOTE] +==== +It is only necessary to load the network interface card module if FreeBSD has not detected it correctly. + +For example, to load the man:alc[4] module, execute the following command: + +[source,shell] +.... +# kldload if_alc +.... + +Alternatively, to load the driver as a module at boot time, place the following line in [.filename]#/boot/loader.conf#: + +[.programlisting] +.... +if_alc_load="YES" +.... +==== + +[[config-network-connection]] +== Wired Networks + +Once the right driver is loaded the network adapter needs to be configured. +FreeBSD uses the driver name followed by a unit number to name the network interface adapter. +The unit number represents the order in which the adapter is detected at boot time, or is later discovered. + +For example, `em0` is the first network interface card (NIC) on the system using the man:em[4] driver. + +To display the network interface configuration, enter the following command: + +[source,shell] +.... +% ifconfig +.... + +The output should be similar to the following: + +[.programlisting] +.... +em0: flags=8863<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=481249b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,LRO,WOL_MAGIC,VLAN_HWFILTER,NOMAP> + ether 00:1f:16:0f:27:5a + inet6 fe80::21f:16ff:fe0f:275a%em0 prefixlen 64 scopeid 0x1 + inet 192.168.1.19 netmask 0xffffff00 broadcast 192.168.1.255 + media: Ethernet autoselect (1000baseT <full-duplex>) + status: active + nd6 options=23<PERFORMNUD,ACCEPT_RTADV,AUTO_LINKLOCAL> +lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 + options=680003<RXCSUM,TXCSUM,LINKSTATE,RXCSUM_IPV6,TXCSUM_IPV6> + inet6 ::1 prefixlen 128 + inet6 fe80::1%lo0 prefixlen 64 scopeid 0x2 + inet 127.0.0.1 netmask 0xff000000 + groups: lo + nd6 options=21<PERFORMNUD,AUTO_LINKLOCAL> +.... + +In this example, the following devices were displayed: + +* `em0`: The Ethernet interface. +* `lo0`: The loop interface is a software loopback mechanism which may be used for performance analysis, software testing, and/or local communication. More information in man:lo[4]. + +The example shows that `em0` is up and running. + +The key indicators are: + +. `UP` means that the interface is configured and ready. +. The interface has an IPv4 Internet (`inet`) address, `192.168.1.19`. +. The interface has an IPv6 Internet (`inet6`) address, `fe80::21f:16ff:fe0f:275a%em0`. +. It has a valid subnet mask (`netmask`), where `0xffffff00` is the same as `255.255.255.0`. +. It has a valid broadcast address, `192.168.1.255`. +. The MAC address of the interface (`ether`) is `00:1f:16:0f:27:5a`. +. The physical media selection is on autoselection mode (`media: Ethernet autoselect (1000baseT <full-duplex>)`). +. The status of the link (`status`) is `active`, indicating that the carrier signal is detected. For `em0`, the `status: no carrier` status is normal when an Ethernet cable is not plugged into the interface. + +If the man:ifconfig[8] output had shown something similar to the next output it would indicate the interface has not been configured: + +[.programlisting] +.... +em0: flags=8822<BROADCAST,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=481249b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,LRO,WOL_MAGIC,VLAN_HWFILTER,NOMAP> + ether 00:1f:16:0f:27:5a + media: Ethernet autoselect + status: no carrier + nd6 options=29<PERFORMNUD,IFDISABLED,AUTO_LINKLOCAL> +.... + +[[config-static-ip-v4]] +=== Configuring Static IPv4 Address + +This section provides a guide to configuring a static IPv4 address on a FreeBSD system. + +The network interface card (NIC) configuration can be performed from the command line with man:ifconfig[8] but will not persist after a reboot unless the configuration is also added to [.filename]#/etc/rc.conf#. + +[NOTE] +==== +If the network was configured during installation by man:bsdinstall[8], some entries for the network interface card (NICs) may be already present. +Double check [.filename]#/etc/rc.conf# before executing man:sysrc[8]. +==== + +The IP address can be set executing the following command: + +[source,shell] +.... +# ifconfig em0 inet 192.168.1.150/24 +.... + +To make the change persist across reboots execute the following command: + +[source,shell] +.... +# sysrc ifconfig_em0="inet 192.168.1.150 netmask 255.255.255.0" +.... + +Add the default router executing the following command: + +[source,shell] +.... +# sysrc defaultrouter="192.168.1.1" +.... + +Add the DNS records to [.filename]#/etc/resolv.conf#: + +[.programlisting] +.... +nameserver 8.8.8.8 +nameserver 8.8.4.4 +.... + +Then restart `netif` and `routing` executing the following command: + +[source,shell] +.... +# service netif restart && service routing restart +.... + +The connection can be tested using man:ping[8]: + +[source,shell] +.... +% ping -c2 www.FreeBSD.org +.... + +The output should be similar to the following: + +[.programlisting] +.... +PING web.geo.FreeBSD.org (147.28.184.45): 56 data bytes +64 bytes from 147.28.184.45: icmp_seq=0 ttl=51 time=55.173 ms +64 bytes from 147.28.184.45: icmp_seq=1 ttl=51 time=53.093 ms + +--- web.geo.FreeBSD.org ping statistics --- +2 packets transmitted, 2 packets received, 0.0% packet loss +round-trip min/avg/max/stddev = 53.093/54.133/55.173/1.040 ms +.... + +[[config-dynamic-ip-v4]] +=== Configuring Dynamic IPv4 Address + +If the network has a DHCP server, it is very easy to configure the network interface to use DHCP. +FreeBSD uses man:dhclient[8] as the DHCP client. +man:dhclient[8] will automatically provide the IP, the netmask and the default router. + +To make the interface work with DHCP execute the following command: + +[source,shell] +.... +# sysrc ifconfig_em0="DHCP" +.... + +man:dhclient[8] can be used manually by running the following command: + +[source,shell] +.... +# dhclient em0 +.... + +The output should be similar to the following: + +[.programlisting] +.... +DHCPREQUEST on em0 to 255.255.255.255 port 67 +DHCPACK from 192.168.1.1 +unknown dhcp option value 0x7d +bound to 192.168.1.19 -- renewal in 43200 seconds. +.... + +In this way it can be verified that the address assignment using DHCP works correctly. + +[TIP] +==== +man:dhclient[8] client can be started in background. +This can cause trouble with applications depending on a working network, but it will provide a faster startup in many cases. + +To execute man:dhclient[8] in background execute the following command: + +[source,shell] +.... +# sysrc background_dhclient="YES" +.... +==== + +Then restart `netif` executing the following command: + +[source,shell] +.... +# service netif restart +.... + +The connection can be tested using man:ping[8]: + +[source,shell] +.... +% ping -c2 www.FreeBSD.org +.... + +The output should be similar to the following: + +[.programlisting] +.... +PING web.geo.FreeBSD.org (147.28.184.45): 56 data bytes +64 bytes from 147.28.184.45: icmp_seq=0 ttl=51 time=55.173 ms +64 bytes from 147.28.184.45: icmp_seq=1 ttl=51 time=53.093 ms + +--- web.geo.FreeBSD.org ping statistics --- +2 packets transmitted, 2 packets received, 0.0% packet loss +round-trip min/avg/max/stddev = 53.093/54.133/55.173/1.040 ms +.... + +[[network-ipv6]] +=== IPv6 + +IPv6 is the new version of the well-known IP protocol, also known as IPv4. + +IPv6 provides several advantages over IPv4 as well as many new features: + +* Its 128-bit address space allows for 340,282,366,920,938,463,463,374,607,431,768,211,456 addresses. This addresses the IPv4 address shortage and eventual IPv4 address exhaustion. +* Routers only store network aggregation addresses in their routing tables, thus reducing the average space of a routing table to 8192 entries. This addresses the scalability issues associated with IPv4, which required every allocated block of IPv4 addresses to be exchanged between Internet routers, causing their routing tables to become too large to allow efficient routing. +* Address autoconfiguration (http://www.ietf.org/rfc/rfc2462.txt[RFC2462]). +* Mandatory multicast addresses. +* Built-in IPsec (IP security). +* Simplified header structure. +* Support for mobile IP. +* IPv6-to-IPv4 transition mechanisms. + +FreeBSD includes the http://www.kame.net/[KAME project] IPv6 reference implementation and comes with everything needed to use IPv6. + +This section focuses on getting IPv6 configured and running. + +There are three different types of IPv6 addresses: + +Unicast:: +A packet sent to a unicast address arrives at the interface belonging to the address. + +Anycast:: +These addresses are syntactically indistinguishable from unicast addresses but they address a group of interfaces. +The packet destined for an anycast address will arrive at the nearest router interface. +Anycast addresses are only used by routers. + +Multicast:: +These addresses identify a group of interfaces. +A packet destined for a multicast address will arrive at all interfaces belonging to the multicast group. +The IPv4 broadcast address, usually `xxx.xxx.xxx.255`, is expressed by multicast addresses in IPv6. + +When reading an IPv6 address, the canonical form is represented as `x:x:x:x:x:x:x:x`, where each `x` represents a 16 bit hex value. +An example is `FEBC:A574:382B:23C1:AA49:4592:4EFE:9982`. + +Often, an address will have long substrings of all zeros. +A `::` (double colon) can be used to replace one substring per address. +Also, up to three leading ``0``s per hex value can be omitted. +For example, `fe80::1` corresponds to the canonical form `fe80:0000:0000:0000:0000:0000:0000:0001`. + +A third form is to write the last 32 bits using the well known IPv4 notation. +For example, `2002::10.0.0.1` corresponds to the hexadecimal canonical representation `2002:0000:0000:0000:0000:0000:0a00:0001`, which in turn is equivalent to `2002::a00:1`. + +To view a FreeBSD system's IPv6 address execute the following command: + +[source,shell] +.... +# ifconfig +.... + +The output should be similar to the following: + +[.programlisting] +.... +em0: flags=8863<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=481249b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,LRO,WOL_MAGIC,VLAN_HWFILTER,NOMAP> + ether 00:1f:16:0f:27:5a + inet 192.168.1.150 netmask 0xffffff00 broadcast 192.168.1.255 + inet6 fe80::21f:16ff:fe0f:275a%em0 prefixlen 64 scopeid 0x1 + media: Ethernet autoselect (1000baseT <full-duplex>) + status: active + nd6 options=23<PERFORMNUD,ACCEPT_RTADV,AUTO_LINKLOCAL> +.... + +In this example, the `em0` interface is using `fe80::21f:16ff:fe0f:275a%em0`, an auto-configured link-local address which was automatically generated from the MAC address. + +Some IPv6 addresses are reserved. +A list of reserved addresses can be checked in the following table: + +[[reservedip6]] +.Example IPv6 Reserved Addresses +[cols="1,1,1,1", frame="none", options="header"] +|=== +| IPv6 address +| Prefixlength (Bits) +| Description +| Notes + +|`::` +|128 bits +|unspecified +|Equivalent to `0.0.0.0` in IPv4. + +|`::1` +|128 bits +|loopback address +|Equivalent to `127.0.0.1` in IPv4. + +|`::00:xx:xx:xx:xx` +|96 bits +|embedded IPv4 +|The lower 32 bits are the compatible IPv4 address. + +|`::ff:xx:xx:xx:xx` +|96 bits +|IPv4 mapped IPv6 address +|The lower 32 bits are the IPv4 address for hosts which do not support IPv6. + +|`fe80::/10` +|10 bits +|link-local +|Equivalent to 169.254.0.0/16 in IPv4. + +|`fc00::/7` +|7 bits +|unique-local +|Unique local addresses are intended for local communication and are only routable within a set of cooperating sites. + +|`ff00::` +|8 bits +|multicast +| + +|``2000::-3fff::`` +|3 bits +|global unicast +|All global unicast addresses are assigned from this pool. The first 3 bits are `001`. +|=== + +For further information on the structure of IPv6 addresses, refer to http://www.ietf.org/rfc/rfc3513.txt[RFC3513]. + +[[config-static-ip-v6]] +==== Configuring Static IPv6 Address + +To configure a FreeBSD system as an IPv6 client with a static IPv6 address it is necessary to set the IPv6 address. + +Execute the following commands to meet the requirements: + +[source,shell] +.... +# sysrc ifconfig_em0_ipv6="inet6 2001:db8:4672:6565:2026:5043:2d42:5344 prefixlen 64" +.... + +To assign a default router, specify its address executing the following command: + +[source,shell] +.... +# sysrc ipv6_defaultrouter="2001:db8:4672:6565::1" +.... + +[[config-dynamic-ip-v6]] +=== Configuring Dynamic IPv6 Address + +If the network has a DHCP server, it is very easy to configure the network interface to use DHCP. +FreeBSD uses man:dhclient[8] as the DHCP client. +man:dhclient[8] will provide automatically the IP, the netmask and the default router. + +To make the interface works with DHCP execute the following command: + +[source,shell] +.... +# sysrc ifconfig_em0_ipv6="inet6 DHCP accept_rtadv" +# sysrc rtsold_enable="YES" +.... + +=== Router Advertisement and Host Auto Configuration + +This section demonstrates how to setup man:rtadvd[8] to advertise the IPv6 default route. + +To enable man:rtadvd[8], execute the following command: + +[source,shell] +.... +# sysrc rtadvd_enable="YES" +.... + +It is important to specify the interface on which to do IPv6 router advertisement. +For example, to tell man:rtadvd[8] to use `em0`: + +[source,shell] +.... +# sysrc rtadvd_interfaces="em0" +.... + +Next, create the configuration file, [.filename]#/etc/rtadvd.conf# as seen in this example: + +[.programlisting] +.... +em0:\ + :addrs#1:addr="2001:db8:1f11:246::":prefixlen#64:tc=ether: +.... + +Replace `em0` with the interface to be used and `2001:db8:1f11:246::` with the prefix of the allocation. + +For a dedicated `/64` subnet, nothing else needs to be changed. +Otherwise, change the `prefixlen#` to the correct value. + +=== IPv6 and IPv4 Address mapping + +When IPv6 is enabled on a server, there may be a need to enable IPv4 mapped IPv6 address communication. +This compatibility option allows for IPv4 addresses to be represented as IPv6 addresses. +Permitting IPv6 applications to communicate with IPv4 and vice versa may be a security issue. + +This option may not be required in most cases and is available only for compatibility. +This option will allow IPv6-only applications to work with IPv4 in a dual stack environment. +This is most useful for third party applications which may not support an IPv6-only environment. + +To enable this feature execute the following command: + +[source,shell] +.... +# sysrc ipv6_ipv4mapping="YES" +.... + +[[network-wireless]] +== Wireless Networks + +Most wireless networks are based on the link:https://en.wikipedia.org/wiki/IEEE_802.11[IEEE(R) 802.11 standards]. + +FreeBSD supports networks that operate using link:https://en.wikipedia.org/wiki/IEEE_802.11a-1999[802.11a], link:https://en.wikipedia.org/wiki/IEEE_802.11b-1999[802.11b], link:https://en.wikipedia.org/wiki/IEEE_802.11g-2003[802.11g] and link:https://en.wikipedia.org/wiki/IEEE_802.11n-2009[802.11n]. + +[NOTE] +==== +link:https://en.wikipedia.org/wiki/IEEE_802.11ac-2013[802.11ac] support on FreeBSD is currently under development. +==== + +A basic wireless network consists of multiple stations communicating with radios that broadcast in either the 2.4GHz or 5GHz band, though this varies according to the locale and is also changing to enable communication in the 2.3GHz and 4.9GHz ranges. + +There are three basic steps to configure a wireless network: + +1. Scan and select an access point +2. Authenticate the station +3. Configure an IP address or use DHCP. + +The following sections discuss each step. + +[[network-wireless-quick-start]] +=== Quick Start to Connect to a Wireless Network + +Connecting FreeBSD to an existing wireless network is a very common situation. + +This procedure shows the steps required: + +* The first step will be to obtain the SSID (Service Set Identifier) and PSK (Pre-Shared Key) for the wireless network from the network administrator. + +* The second step will be to add an entry for this network to [.filename]#/etc/wpa_supplicant.conf#. If the file does not exist, create it: + +[.programlisting] +.... +network={ + ssid="myssid" <.> + psk="mypsk" <.> +} +.... + +<.> Is the SSID of the wireless network. Replace it with the name of the wireless network. +<.> Is the PSK of the wireless network. Replace it with the password of the wireless network. + +* The third step will be to add the network entry to configure the network on startup: + +[source,shell] +.... +# sysrc wlans_iwn0="wlan0" +# sysrc ifconfig_wlan0="WPA DHCP" +.... + +* And the last step will be the restart `netif` service executing the following command: + +[source,shell] +.... +# service netif restart +.... + +[[basic-wireless-configuration]] +=== Basic Wireless Configuration + +The first step will be to configure the wireless network card to an interface. +To find out what wireless network cards are in the system check the section <<config-identify-network-adapter>>. + +[source,shell] +.... +# ifconfig wlan0 create wlandevice iwm0 +.... + +To make the change persist across reboots execute the following command: + +[source,shell] +.... +# sysrc wlans_iwn0="wlan0" +.... + +[NOTE] +==== +Since the regulatory situation is different in various parts of the world, it is necessary to correctly set the domains that apply to your location to have the correct information about what channels can be used. + +The available region definitions can be found in [.filename]#/etc/regdomain.xml#. +To set the data at runtime, use `ifconfig`: + +[source,shell] +.... +# ifconfig wlan0 regdomain ETSI country AT +.... + +To persist the settings, add it to [.filename]#/etc/rc.conf#: + +[source,shell] +.... +# sysrc create_args_wlan0="country AT regdomain ETSI" +.... +==== + +[[scan-wireless-networks]] +=== Scan Wireless Networks + +Available wireless networks can be scanned using man:ifconfig[8]. + +To list the wireless networks execute the following command: + +[source,shell] +.... +# ifconfig wlan0 up list scan +.... + +The output should be similar to the following: + +[.programlisting] +.... +SSID/MESH ID BSSID CHAN RATE S:N INT CAPS +FreeBSD e8:d1:1b:1b:58:ae 1 54M -47:-96 100 EP RSN BSSLOAD HTCAP WPS WME +NetBSD d4:b9:2f:35:fe:08 1 54M -80:-96 100 EP RSN BSSLOAD HTCAP WPS WME +OpenBSD fc:40:09:c6:31:bd 36 54M -94:-96 100 EPS VHTPWRENV APCHANREP RSN WPS BSSLOAD HTCAP VHTCAP VHTOPMODE WME +GNU-Linux dc:f8:b9:a0:a8:e0 44 54M -95:-96 100 EP WPA RSN WPS HTCAP VHTCAP VHTOPMODE WME VHTPWRENV +Windows 44:48:b9:b3:c3:ff 44 54M -84:-96 100 EP BSSLOAD VHTPWRENV HTCAP WME RSN VHTCAP VHTOPMODE WPS +MacOS 46:48:b9:b3:c3:ff 44 54M -84:-96 100 EP BSSLOAD VHTPWRENV HTCAP WME RSN VHTCAP VHTOPMODE WPS +.... + +. SSID/MESH ID identifies the name of the network. +. BSSID identifies the MAC address of the access point. +. CAPS field identifies the type of each network and the capabilities of the stations operating there (see the definition of `list scan` in man:ifconfig[8] for more details). + +[[wireless-authentication]] +=== Connection and Authentication to a Wireless Network + +Once a wireless network has been selected from the list of scanned networks, it is necessary to perform the connection ant the authentication. +In the vast majority of wireless networks, authentication is done with a password configured in the router. +Other schemes require cryptographic handshakes to be completed before data traffic can flow, either using pre-shared keys or secrets, or more complex schemes that involve backend services such as RADIUS. + +[[authenticate-wpa2-wpa-personal]] +==== Authenticate with WPA2/WPA/Personal + +The authentication process in a wireless network is managed by man:wpa_supplicant[8]. + +The man:wpa_supplicant[8] configuration will be made in the [.filename]#/etc/wpa_supplicant.conf# file. +For more information, see man:wpa_supplicant.conf[5]. + +Once the scanning of the wireless networks has been carried out, a network has been chosen and have the password (PSK), that information will be added to the file [.filename]#/etc/wpa_supplicant.conf# as in the following example: + +[.programlisting] +.... +network={ + scan_ssid=1 <.> + ssid="FreeBSD" <.> + psk="12345678" <.> +} +.... + +<.> SSID scan technique. Only need to use this option if the network is hidden. +<.> Network name. +<.> Passwork of the wireless network. + +The next step will be to configure the wireless connection in the file [.filename]#/etc/rc.conf#. + +To use a static address it will be necessary to execute the following command: + +[source,shell] +.... +# sysrc ifconfig_wlan0="inet 192.168.1.20 netmask 255.255.255.0" +.... + +To use a dynamic address it will be necessary to execute the following command: + +[source,shell] +.... +# ifconfig_wlan0="WPA DHCP" +.... + +Then restart the network executing the following command: + +[source,shell] +.... +# service netif restart +.... + +[NOTE] +==== +More information on how to perform more advanced methods of authentication can be obtained at crossref:advanced-networking[network-advanced-wireless,"Wireless Advanced Authentication"]. +==== + +[[authenticate-open-networks]] +==== Authenticate with Open Networks + +[TIP] +==== +It is important that the user is *very* careful when connecting to open networks without any kind of authentication. +==== + +Once the wireless network scan is done and the SSID of the wireless network is selected, execute the following command: + +[source,shell] +.... +# ifconfig wlan0 SSID +.... + +And then execute man:dhclient[8] to get the address configured: + +[source,shell] +.... +# dhclient wlan0 +.... + +=== Using Both Wired and Wireless Connections + +A wired connection provides better performance and reliability, while a wireless connection provides flexibility and mobility. +Laptop users typically want to roam seamlessly between the two types of connections. + +On FreeBSD, it is possible to combine two or even more network interfaces together in a "failover" fashion. +This type of configuration uses the most preferred and available connection from a group of network interfaces, and the operating system switches automatically when the link state changes. + +Link aggregation and failover is covered in crossref:advanced-networking[network-aggregation,"Link Aggregation and Failover"] and an example for using both wired and wireless connections is provided at crossref:advanced-networking[networking-lagg-wired-and-wireless,"Failover Mode Between Ethernet and Wireless Interfaces"]. + +[[hostname]] +== Hostname + +The hostname represents the fully qualified domain name (FQDN) of the host on the network. + +[TIP] +==== +If no hostname has been set for the host FreeBSD will assign the value `Amnesiac`. +==== + +[[get-hostname]] +=== Check The Current Hostname + +man:hostname[1] can be used to check the current hostname: + +[source,shell] +.... +$ hostname +.... + +The output should be similar to the following: + +[.programlisting] +.... +freebsdhostname +.... + +[[change-hostname]] +=== Change Hostname + +To change the hostname of the host and persist it across reboots execute the following command: + +[source,shell] +.... +# sysrc hostname="newhostname" +.... + +[[dns]] +== DNS + +The DNS could be understanded as a link:https://en.wikipedia.org/wiki/Telephone_directory[telephone directory] in which an IP is identified to a hostname and vice versa. + +There are three files who handle how a FreeBSD system interact with the DNS. +These three files are man:hosts[5], man:resolv.conf[5] and man:nsswitch.conf[5] + +Unless otherwise stated in the [.filename]#/etc/nsswitch.conf# file, FreeBSD will look at the addresses in the [.filename]#/etc/hosts# file and then the [.filename]#/etc/resolv.conf# file. + +[NOTE] +==== +The man:nsswitch.conf[5] file specifies how the nsdispatch (name-service switch dispatcher) should operate. + +By default, the hosts section of the [.filename]#/etc/nsswitch.conf# file will be as follows: + +[.programlisting] +.... +hosts: files dns +.... + +For example, in case of using the man:nscd[8] service. +The order of preference could be changed by leaving the line as follows: + +[.programlisting] +.... +hosts: files cache dns +.... +==== + +[[local-addresses]] +=== Local addresses + +The [.filename]#/etc/hosts# file is a simple text database who provide host name to IP address mappings. +Entries for local computers connected via a LAN can be added to this file for simplistic naming purposes instead of setting up a DNS server. +Additionally, [.filename]#/etc/hosts# can be used to provide a local record of Internet names, reducing the need to query external DNS servers for commonly accessed names. + +For example, in the case of having a local instance of package:www/gitlab-ce[] in a local environment, it could be added as follows to the file [.filename]#/etc/hosts#: + +[.programlisting] +.... +192.168.1.150 git.example.com git +.... + +[[configuring-nameserver]] +=== Configuring the Nameserver + +How a FreeBSD system accesses the Internet Domain Name System (DNS) is controlled by man:resolv.conf[5]. + +The most common entries to [.filename]#/etc/resolv.conf# are: + +[.informaltable] +[cols="1,1", frame="none"] +|=== + +|`nameserver` +|The IP address of a name server the resolver should query. The servers are queried in the order listed with a maximum of three. + +|`search` +|Search list for hostname lookup. This is normally determined by the domain of the local hostname. + +|`domain` +|The local domain name. +|=== + +A typical [.filename]#/etc/resolv.conf# looks like this: + +[.programlisting] +.... +search example.com +nameserver 147.11.1.11 +nameserver 147.11.100.30 +.... + +[NOTE] +==== +Only one of the `search` and `domain` options should be used. +==== + +When using DHCP, man:dhclient[8] usually rewrites [.filename]#/etc/resolv.conf# with information received from the DHCP server. + +[TIP] +==== +If the machine in which the configuration is being made is *not* a DNS server, man:local-unbound[8] can be used to improve DNS lookup performance. + +To enable it at boot time execute the following command: + +[source,shell] +.... +# sysrc local_unbound_enable="YES" +.... + +To start the man:local-unbound[8] service execute the following command: + +[source,shell] +.... +# service local_unbound start +.... +==== + +[[troubleshooting]] +== Troubleshooting + +When troubleshooting hardware and software configurations, check the simple things first. + +* Is the network cable plugged in? +* Are the network services properly configured? +* Is the firewall configured correctly? +* Is the NIC supported by FreeBSD? +* Is the router working correctly? + +[TIP] +==== +Before sending a bug report, always check the Hardware Notes in the link:https://www.freebsd.org/releases/[FreeBSD release page], update the version of FreeBSD to the latest STABLE version, check the mailing list archives, and search the Internet. +==== + +[[wired-troubleshooting]] +=== Troubleshooting in Wired Networks + +If the card works, yet performance is poor, read through man:tuning[7]. +Also, check the network configuration as incorrect network settings can cause slow connections. + +`No route to host` messages occur if the system is unable to route a packet to the destination host. +This can happen if no default route is specified or if a cable is unplugged. +Check the output of `netstat -rn` and make sure there is a valid route to the host. +If there is not, read crossref:advanced-networking[network-routing,"Gateways and Routes"]. + +`ping: sendto: Permission denied` error messages are often caused by a misconfigured firewall. +If a firewall is enabled on FreeBSD but no rules have been defined, the default policy is to deny all traffic, even man:ping[8]. +Refer to crossref:firewalls[firewalls,Firewalls] for more information. + +[[wireless-troubleshooting]] +=== Troubleshooting in Wireless Networks + +This section describes a number of steps to help troubleshoot common wireless networking problems. + +* If the access point is not listed when scanning, check that the configuration has not limited the wireless device to a limited set of channels. + +* If the device cannot associate with an access point, verify that the configuration matches the settings on the access point. This includes the authentication scheme and any security protocols. Simplify the configuration as much as possible. If using a security protocol such as WPA2 or WPA, configure the access point for open authentication and no security to see if traffic will pass. + +* Once the system can associate with the access point, diagnose the network configuration using tools like man:ping[8]. + +* There are many lower-level debugging tools. Debugging messages can be enabled in the 802.11 protocol support layer using man:wlandebug[8]. diff --git a/documentation/content/en/books/handbook/partii.adoc b/documentation/content/en/books/handbook/partii.adoc index 4d2526bb5d..342894e332 100644 --- a/documentation/content/en/books/handbook/partii.adoc +++ b/documentation/content/en/books/handbook/partii.adoc @@ -1,9 +1,9 @@ --- title: Part II. Common Tasks -prev: books/handbook/wayland +prev: books/handbook/network next: books/handbook/desktop showBookMenu: true -weight: 9 +weight: 10 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/partiii.adoc b/documentation/content/en/books/handbook/partiii.adoc index 77b0b12f0e..1064117730 100644 --- a/documentation/content/en/books/handbook/partiii.adoc +++ b/documentation/content/en/books/handbook/partiii.adoc @@ -3,7 +3,7 @@ title: Part III. System Administration prev: books/handbook/linuxemu next: books/handbook/config showBookMenu: true -weight: 16 +weight: 17 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/partiv.adoc b/documentation/content/en/books/handbook/partiv.adoc index 5ccdb202c5..cdcb6e8ddd 100644 --- a/documentation/content/en/books/handbook/partiv.adoc +++ b/documentation/content/en/books/handbook/partiv.adoc @@ -3,7 +3,7 @@ title: Part IV. Network Communication prev: books/handbook/usb-device-mode next: books/handbook/serialcomms showBookMenu: true -weight: 32 +weight: 33 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/partv.adoc b/documentation/content/en/books/handbook/partv.adoc index bc547b0e86..8b61fd57dd 100644 --- a/documentation/content/en/books/handbook/partv.adoc +++ b/documentation/content/en/books/handbook/partv.adoc @@ -3,7 +3,7 @@ title: Part V. Appendices prev: books/handbook/advanced-networking next: books/handbook/mirrors showBookMenu: true -weight: 39 +weight: 40 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/pgpkeys/_index.adoc b/documentation/content/en/books/handbook/pgpkeys/_index.adoc index d9b5bff13a..af4170370e 100644 --- a/documentation/content/en/books/handbook/pgpkeys/_index.adoc +++ b/documentation/content/en/books/handbook/pgpkeys/_index.adoc @@ -6,7 +6,7 @@ next: books/handbook/glossary description: List of OpenPGP keys of the FreeBSD officers are shown here tags: ["OpenGPG", "keys", "officers"] showBookMenu: true -weight: 43 +weight: 44 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/ports/_index.adoc b/documentation/content/en/books/handbook/ports/_index.adoc index cd0afab183..4690379e63 100644 --- a/documentation/content/en/books/handbook/ports/_index.adoc +++ b/documentation/content/en/books/handbook/ports/_index.adoc @@ -163,7 +163,7 @@ Do you want to fetch and install it not? [y/N] man:pkg[7] will intercept the command, and if you confirm that is your intention, download the man:pkg[8] tarball, install man:pkg[8] from it, bootstrap the local package database and then proceed to run the command you originally requested. -More recent versions of man:pkg[7] understand `pkg -N` as a test to see if man:pkg[8] is installed without triggering the installation, and conversely, `pkg bootstrap[-f]` to install man:pkg[8] (or force it to be reinstalled) without performing any other actions. +More recent versions of man:pkg[7] understand `pkg -N` as a test to see if man:pkg[8] is installed without triggering the installation, and conversely, pkg bootstrap[-f] to install man:pkg[8] (or force it to be reinstalled) without performing any other actions. Usage information for pkg is available in the man:pkg[8] manual page or by running `pkg` without additional arguments. Additional pkg configuration options are described in man:pkg.conf[5]. @@ -184,15 +184,15 @@ Refer to a command's help or man page for details and more examples. [[quarterly-latest-branch]] === Quarterly and Latest Ports Branches -Quarterly branches provides users with a more predictable and stable experience for port and package installation and upgrades. +The `Quarterly` branch provides users with a more predictable and stable experience for port and package installation and upgrades. This is done essentially by only allowing non-feature updates. Quarterly branches aim to receive security fixes (that may be version updates, or backports of commits), bug fixes and ports compliance or framework changes. -A quarterly is branched from `main` at the beginning of every (yearly) quarter in January, April, July, and October. +The Quarterly branch is cut from HEAD at the beginning of every (yearly) quarter in January, April, July, and October. Branches are named according to the year (YYYY) and quarter (Q1-4) they are created in. -For example, the quarterly branch created in January 2023, is named `2023Q1`. -`latest` provides the latest versions of ports. +For example, the quarterly branch created in January 2023, is named 2023Q1. +And the `Latest` branch provides the latest versions of the packages to the users. -To switch man:pkg.conf[5] from quarterly to latest -- if you do not already have a [.filename]#FreeBSD.conf# at [.filename]#/usr/local/etc/pkg/repos# -- run the following commands: +To switch man:pkg[8] from Quarterly to Latest run the following commands: [source,shell] .... @@ -200,11 +200,11 @@ To switch man:pkg.conf[5] from quarterly to latest -- if you do not already have # echo 'FreeBSD: { url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest" }' > /usr/local/etc/pkg/repos/FreeBSD.conf .... -Then run this command to update the local package repositories catalogues: +Then run this command to update the local package repositories catalogues for the Latest branch: [source,shell] .... -# pkg update +# pkg update -f .... [[pkg-configuration]] @@ -675,13 +675,13 @@ By default, the Ports Collection itself is stored as a subdirectory of `/usr/por [WARNING] ==== Before installing and using the Ports Collection, please be aware that it is generally ill-advised to use the Ports Collection in conjunction with the binary packages provided via pkg to install software. -In RELEASE versions of FreeBSD: man:pkg.conf[5] defaults to quarterly, not latest. -Dependencies could be different for a port in latest, compared to its counterpart (if any) in quarterly, and this could result in conflicts between dependencies installed by pkg and those from the Ports Collection. -If the Ports Collection and pkg must be used in conjunction, then be sure that your Ports Collection and pkg are on the same branch of the ports tree. +pkg, by default, tracks quarterly branch-releases of the ports tree and not HEAD. +Dependencies could be different for a port in HEAD compared to its counterpart in a quarterly branch release and this could result in conflicts between dependencies installed by pkg and those from the Ports Collection. +If the Ports Collection and pkg must be used in conjunction, then be sure that your Ports Collection and pkg are on the same branch release of the ports tree. ==== The Ports Collection contains directories for software categories. -Within each category are subdirectories for individual applications. +Inside each category are subdirectories for individual applications. Each application subdirectory contains a set of files that tells FreeBSD how to compile and install that program, called a _ports skeleton_. Each port skeleton includes these files and directories: @@ -727,14 +727,14 @@ If the ports tree is not available, or pkg is being used to manage packages, Git # pkg install git .... + -. Check out the `main` branch of the ports repo: +. Check out a copy of the HEAD branch of the ports tree: + [source,shell] .... # git clone https://git.FreeBSD.org/ports.git /usr/ports .... + -. Or, check out a quarterly branch: +. Or, check out a copy of a quarterly branch: + [source,shell] .... diff --git a/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc b/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc index 7025350c63..9524063158 100644 --- a/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc +++ b/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 29. PPP +title: Chapter 30. PPP part: IV. Network Communication prev: books/handbook/serialcomms next: books/handbook/mail description: FreeBSD supports the Point-to-Point (PPP) protocol which can be used to establish a network or Internet connection using a dial-up modem tags: ["PPP", "PPPoE", "PPPoA", "modem"] showBookMenu: true -weight: 34 +weight: 35 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 29 +:sectnumoffset: 30 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/printing/_index.adoc b/documentation/content/en/books/handbook/printing/_index.adoc index f07ddc02bc..d543a7e1d6 100644 --- a/documentation/content/en/books/handbook/printing/_index.adoc +++ b/documentation/content/en/books/handbook/printing/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 10. Printing +title: Chapter 11. Printing part: Part II. Common Tasks prev: books/handbook/kernelconfig next: books/handbook/linuxemu description: This chapter covers the printing system in FreeBSD tags: ["printing", "CUPS", "LPD", "PostScript", "PDLs", "HPLIP", "LPRng"] showBookMenu: true -weight: 13 +weight: 14 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 10 +:sectnumoffset: 11 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/security/_index.adoc b/documentation/content/en/books/handbook/security/_index.adoc index 3488dbd985..718a190541 100644 --- a/documentation/content/en/books/handbook/security/_index.adoc +++ b/documentation/content/en/books/handbook/security/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 15. Security +title: Chapter 16. Security part: Part III. System Administration prev: books/handbook/boot next: books/handbook/jails description: Hundreds of standard practices have been authored about how to secure systems and networks, and as a user of FreeBSD, understanding how to protect against attacks and intruders is a must tags: ["security", "one-time passwords", "TCP Wrapper", "Kerberos", "OpenSSL", "IPsec", "OpenSSH", "ACL", "advisories", "sudo", "doas", "monitoring"] showBookMenu: true -weight: 19 +weight: 20 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 15 +:sectnumoffset: 16 :partnums: :source-highlighter: rouge :experimental: @@ -120,11 +120,11 @@ Disable any accounts that do not need login access. To deny login access to accounts, two methods exist. The first is to lock the account. -This example locks the `imani` account: +This example locks the `toor` account: [source,shell] .... -# pw lock imani +# pw lock toor .... The second method is to prevent login access by changing the shell to [.filename]#/usr/sbin/nologin#. @@ -132,7 +132,7 @@ Only the superuser can change the shell for other users: [source,shell] .... -# chsh -s /usr/sbin/nologin imani +# chsh -s /usr/sbin/nologin toor .... The [.filename]#/usr/sbin/nologin# shell prevents the system from assigning a shell to the user when they attempt to login. diff --git a/documentation/content/en/books/handbook/serialcomms/_index.adoc b/documentation/content/en/books/handbook/serialcomms/_index.adoc index ea78fc896e..5d1a81fd87 100644 --- a/documentation/content/en/books/handbook/serialcomms/_index.adoc +++ b/documentation/content/en/books/handbook/serialcomms/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 28. Serial Communications +title: Chapter 29. Serial Communications part: Part IV. Network Communication prev: books/handbook/partiv next: books/handbook/ppp-and-slip description: This chapter covers some of the ways serial communications can be used on FreeBSD tags: ["serial", "communications", "terminal", "modem", "console"] showBookMenu: true -weight: 33 +weight: 34 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 28 +:sectnumoffset: 29 :partnums: :source-highlighter: rouge :experimental: 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 93c1086df6..2f06c06776 100644 --- a/documentation/content/en/books/handbook/usb-device-mode/_index.adoc +++ b/documentation/content/en/books/handbook/usb-device-mode/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 27. USB Device Mode / USB OTG +title: Chapter 28. USB Device Mode / USB OTG part: Part III. System Administration prev: books/handbook/dtrace next: books/handbook/partiv description: This chapter covers the use of USB Device Mode and USB On The Go (USB OTG) in FreeBSD tags: ["OTG", "USB"] showBookMenu: true -weight: 31 +weight: 32 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 27 +:sectnumoffset: 28 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/virtualization/_index.adoc b/documentation/content/en/books/handbook/virtualization/_index.adoc index a4540edca2..f31e6fdc0e 100644 --- a/documentation/content/en/books/handbook/virtualization/_index.adoc +++ b/documentation/content/en/books/handbook/virtualization/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 23. Virtualization +title: Chapter 24. Virtualization part: Part III. System Administration prev: books/handbook/filesystems next: books/handbook/l10n description: Virtualization software allows multiple operating systems to run simultaneously on the same computer tags: ["virtualization", "Parallels", "VMware", "VirtualBox", "bhyve", "XEN"] showBookMenu: true -weight: 27 +weight: 28 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 23 +:sectnumoffset: 24 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/wayland/_index.adoc b/documentation/content/en/books/handbook/wayland/_index.adoc index 0e7387ad5d..c27c38438a 100644 --- a/documentation/content/en/books/handbook/wayland/_index.adoc +++ b/documentation/content/en/books/handbook/wayland/_index.adoc @@ -2,7 +2,7 @@ title: Chapter 6. Wayland part: Part I. Getting Started prev: books/handbook/x11 -next: books/handbook/partii +next: books/handbook/network description: This chapter describes how to install and configure Wayland and compositors on FreeBSD, which provides a graphical user environment tags: ["Wayland", "XWayland", "KDE", "Plasma", "Xfce", "Gnome", "Intel", "AMD", "NVIDIA", "Wayfire", "Sway", "Hikari"] showBookMenu: true diff --git a/documentation/content/en/books/handbook/wine/_index.adoc b/documentation/content/en/books/handbook/wine/_index.adoc index 8d216ed495..41e55424c7 100644 --- a/documentation/content/en/books/handbook/wine/_index.adoc +++ b/documentation/content/en/books/handbook/wine/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 12. WINE +title: Chapter 13. WINE part: Part II. Common Tasks prev: books/handbook/linuxemu next: books/handbook/partiii description: This chapter will describe how to install WINE on a FreeBSD system and how to configure WINE tags: ["WINE", "emulation", "guide", "tutorial"] showBookMenu: true -weight: 15 +weight: 16 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 12 +:sectnumoffset: 13 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/zfs/_index.adoc b/documentation/content/en/books/handbook/zfs/_index.adoc index bf55c48c58..b447e318e2 100644 --- a/documentation/content/en/books/handbook/zfs/_index.adoc +++ b/documentation/content/en/books/handbook/zfs/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 21. The Z File System (ZFS) +title: Chapter 22. The Z File System (ZFS) part: Part III. System Administration prev: books/handbook/geom next: books/handbook/filesystems description: ZFS is an advanced file system designed to solve major problems found in previous storage subsystem software tags: ["ZFS", "filesystem", "administration", "zpool", "features", "terminology", "RAID-Z"] showBookMenu: true -weight: 25 +weight: 26 path: "/books/handbook/" --- @@ -18,7 +18,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 21 +:sectnumoffset: 22 :partnums: :source-highlighter: rouge :experimental: @@ -2819,7 +2819,10 @@ ZFS supports different types of quotas: the dataset quota, the <<zfs-term-refquo Quotas limit the total size of a dataset and its descendants, including snapshots of the dataset, child datasets, and the snapshots of those datasets. -Quotas cannot be set on ZFS volumes, as the `volsize` property acts as an implicit quota. +[NOTE] +==== +Volumes do not support quotas, as the `volsize` property acts as an implicit quota. +==== |[[zfs-term-refquota]]Reference Quota |A reference quota limits the amount of space a dataset can consume by enforcing a hard limit. This hard limit includes space referenced by the dataset alone and does not include space used by descendants, such as file systems or snapshots. |