Date: Sun, 6 Jun 2021 09:16:07 GMT From: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: a8c5c8965c - main - Use One Sentence Per Line in the Handbook Message-ID: <202106060916.1569G7Bf034082@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=a8c5c8965cd534ff9634d95e6d84edb321c273d5 commit a8c5c8965cd534ff9634d95e6d84edb321c273d5 Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2021-06-06 09:15:27 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2021-06-06 09:15:55 +0000 Use One Sentence Per Line in the Handbook --- .../content/en/books/handbook/_index.adoc | 13 +- .../books/handbook/advanced-networking/_index.adoc | 916 ++++++++++++++------ .../content/en/books/handbook/audit/_index.adoc | 103 ++- .../content/en/books/handbook/basics/_index.adoc | 685 +++++++++++---- .../en/books/handbook/bibliography/_index.adoc | 3 +- documentation/content/en/books/handbook/book.adoc | 13 +- .../content/en/books/handbook/boot/_index.adoc | 151 +++- .../en/books/handbook/bsdinstall/_index.adoc | 459 +++++++--- .../content/en/books/handbook/config/_index.adoc | 851 +++++++++++++----- .../en/books/handbook/cutting-edge/_index.adoc | 15 +- .../content/en/books/handbook/desktop/_index.adoc | 127 ++- .../content/en/books/handbook/disks/_index.adoc | 739 +++++++++++----- .../content/en/books/handbook/dtrace/_index.adoc | 81 +- .../en/books/handbook/eresources/_index.adoc | 260 ++++-- .../en/books/handbook/filesystems/_index.adoc | 30 +- .../en/books/handbook/firewalls/_index.adoc | 950 +++++++++++++++------ .../content/en/books/handbook/geom/_index.adoc | 376 +++++--- .../en/books/handbook/introduction/_index.adoc | 101 ++- .../content/en/books/handbook/jails/_index.adoc | 289 +++++-- .../en/books/handbook/kernelconfig/_index.adoc | 114 ++- .../content/en/books/handbook/l10n/_index.adoc | 124 ++- .../content/en/books/handbook/linuxemu/_index.adoc | 80 +- .../content/en/books/handbook/mac/_index.adoc | 324 +++++-- .../content/en/books/handbook/mail/_index.adoc | 385 ++++++--- .../content/en/books/handbook/mirrors/_index.adoc | 51 +- .../en/books/handbook/multimedia/_index.adoc | 321 +++++-- .../en/books/handbook/network-servers/_index.adoc | 939 ++++++++++++++------ documentation/content/en/books/handbook/parti.adoc | 3 +- .../content/en/books/handbook/partii.adoc | 3 +- .../content/en/books/handbook/partiii.adoc | 7 +- .../content/en/books/handbook/partiv.adoc | 6 +- .../content/en/books/handbook/pgpkeys/_index.adoc | 5 +- .../content/en/books/handbook/ports/_index.adoc | 347 +++++--- .../en/books/handbook/ppp-and-slip/_index.adoc | 246 ++++-- .../content/en/books/handbook/preface/_index.adoc | 48 +- .../content/en/books/handbook/printing/_index.adoc | 252 ++++-- .../content/en/books/handbook/security/_index.adoc | 883 ++++++++++++++----- .../en/books/handbook/serialcomms/_index.adoc | 433 +++++++--- .../en/books/handbook/usb-device-mode/_index.adoc | 91 +- .../en/books/handbook/virtualization/_index.adoc | 342 ++++++-- .../content/en/books/handbook/wine/_index.adoc | 259 ++++-- .../content/en/books/handbook/x11/_index.adoc | 419 ++++++--- .../content/en/books/handbook/zfs/_index.adoc | 762 +++++++++++++---- 43 files changed, 9320 insertions(+), 3286 deletions(-) diff --git a/documentation/content/en/books/handbook/_index.adoc b/documentation/content/en/books/handbook/_index.adoc index 6551efc869..af69a1236e 100644 --- a/documentation/content/en/books/handbook/_index.adoc +++ b/documentation/content/en/books/handbook/_index.adoc @@ -26,9 +26,16 @@ include::shared/en/mailing-lists.adoc[] [.abstract-title] Abstract -Welcome to FreeBSD! This handbook covers the installation and day to day use of _FreeBSD {rel130-current}-RELEASE_, _FreeBSD {rel122-current}-RELEASE_ and _FreeBSD {rel114-current}-RELEASE_. This book is the result of ongoing work by many individuals. Some sections might be outdated. Those interested in helping to update and expand this document should send email to the {freebsd-doc}. - -The latest version of this book is available from the https://www.FreeBSD.org/[FreeBSD web site]. Previous versions can be obtained from https://docs.FreeBSD.org/doc/[https://docs.FreeBSD.org/doc/]. The book can be downloaded in a variety of formats and compression options from the https://download.freebsd.org/ftp/doc/[FreeBSD FTP server] or one of the numerous link:./mirrors#mirrors-ftp[mirror sites]. Printed copies can be purchased at the https://www.freebsdmall.com/[FreeBSD Mall]. Searches can be performed on the handbook and other documents on the link:https://www.FreeBSD.org/search/[search page]. +Welcome to FreeBSD! This handbook covers the installation and day to day use of _FreeBSD {rel130-current}-RELEASE_, _FreeBSD {rel122-current}-RELEASE_ and _FreeBSD {rel114-current}-RELEASE_. +This book is the result of ongoing work by many individuals. +Some sections might be outdated. +Those interested in helping to update and expand this document should send email to the {freebsd-doc}. + +The latest version of this book is available from the https://www.FreeBSD.org/[FreeBSD web site]. +Previous versions can be obtained from https://docs.FreeBSD.org/doc/[https://docs.FreeBSD.org/doc/]. +The book can be downloaded in a variety of formats and compression options from the https://download.freebsd.org/ftp/doc/[FreeBSD FTP server] or one of the numerous link:./mirrors#mirrors-ftp[mirror sites]. +Printed copies can be purchased at the https://www.freebsdmall.com/[FreeBSD Mall]. +Searches can be performed on the handbook and other documents on the link:https://www.FreeBSD.org/search/[search page]. ''' diff --git a/documentation/content/en/books/handbook/advanced-networking/_index.adoc b/documentation/content/en/books/handbook/advanced-networking/_index.adoc index 73e766a724..a64a5e8fa5 100644 --- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc +++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc @@ -70,9 +70,16 @@ Before reading this chapter, you should: [[network-routing]] == Gateways and Routes -_Routing_ is the mechanism that allows a system to find the network path to another system. A _route_ is a defined pair of addresses which represent the "destination" and a "gateway". The route indicates that when trying to get to the specified destination, send the packets through the specified gateway. There are three types of destinations: individual hosts, subnets, and "default". The "default route" is used if no other routes apply. There are also three types of gateways: individual hosts, interfaces, also called links, and Ethernet hardware (MAC) addresses. Known routes are stored in a routing table. +_Routing_ is the mechanism that allows a system to find the network path to another system. +A _route_ is a defined pair of addresses which represent the "destination" and a "gateway". +The route indicates that when trying to get to the specified destination, send the packets through the specified gateway. +There are three types of destinations: individual hosts, subnets, and "default". +The "default route" is used if no other routes apply. +There are also three types of gateways: individual hosts, interfaces, also called links, and Ethernet hardware (MAC) addresses. +Known routes are stored in a routing table. -This section provides an overview of routing basics. It then demonstrates how to configure a FreeBSD system as a router and offers some troubleshooting tips. +This section provides an overview of routing basics. +It then demonstrates how to configure a FreeBSD system as a router and offers some troubleshooting tips. [[network-routing-default]] === Routing Basics @@ -100,32 +107,49 @@ host2.example.com link#1 UC 0 0 The entries in this example are as follows: default:: -The first route in this table specifies the `default` route. When the local system needs to make a connection to a remote host, it checks the routing table to determine if a known path exists. If the remote host matches an entry in the table, the system checks to see if it can connect using the interface specified in that entry. +The first route in this table specifies the `default` route. +When the local system needs to make a connection to a remote host, it checks the routing table to determine if a known path exists. +If the remote host matches an entry in the table, the system checks to see if it can connect using the interface specified in that entry. + -If the destination does not match an entry, or if all known paths fail, the system uses the entry for the default route. For hosts on a local area network, the `Gateway` field in the default route is set to the system which has a direct connection to the Internet. When reading this entry, verify that the `Flags` column indicates that the gateway is usable (`UG`). +If the destination does not match an entry, or if all known paths fail, the system uses the entry for the default route. +For hosts on a local area network, the `Gateway` field in the default route is set to the system which has a direct connection to the Internet. +When reading this entry, verify that the `Flags` column indicates that the gateway is usable (`UG`). + The default route for a machine which itself is functioning as the gateway to the outside world will be the gateway machine at the Internet Service Provider (ISP). localhost:: -The second route is the `localhost` route. The interface specified in the `Netif` column for `localhost` is [.filename]#lo0#, also known as the loopback device. This indicates that all traffic for this destination should be internal, rather than sending it out over the network. +The second route is the `localhost` route. +The interface specified in the `Netif` column for `localhost` is [.filename]#lo0#, also known as the loopback device. +This indicates that all traffic for this destination should be internal, rather than sending it out over the network. MAC address:: -The addresses beginning with `0:e0:` are MAC addresses. FreeBSD will automatically identify any hosts, `test0` in the example, on the local Ethernet and add a route for that host over the Ethernet interface, [.filename]#re0#. This type of route has a timeout, seen in the `Expire` column, which is used if the host does not respond in a specific amount of time. When this happens, the route to this host will be automatically deleted. These hosts are identified using the Routing Information Protocol (RIP), which calculates routes to local hosts based upon a shortest path determination. +The addresses beginning with `0:e0:` are MAC addresses. +FreeBSD will automatically identify any hosts, `test0` in the example, on the local Ethernet and add a route for that host over the Ethernet interface, [.filename]#re0#. +This type of route has a timeout, seen in the `Expire` column, which is used if the host does not respond in a specific amount of time. +When this happens, the route to this host will be automatically deleted. +These hosts are identified using the Routing Information Protocol (RIP), which calculates routes to local hosts based upon a shortest path determination. subnet:: -FreeBSD will automatically add subnet routes for the local subnet. In this example, `10.20.30.255` is the broadcast address for the subnet `10.20.30` and `example.com` is the domain name associated with that subnet. The designation `link#1` refers to the first Ethernet card in the machine. +FreeBSD will automatically add subnet routes for the local subnet. +In this example, `10.20.30.255` is the broadcast address for the subnet `10.20.30` and `example.com` is the domain name associated with that subnet. +The designation `link#1` refers to the first Ethernet card in the machine. + -Local network hosts and local subnets have their routes automatically configured by a daemon called man:routed[8]. If it is not running, only routes which are statically defined by the administrator will exist. +Local network hosts and local subnets have their routes automatically configured by a daemon called man:routed[8]. +If it is not running, only routes which are statically defined by the administrator will exist. host:: -The `host1` line refers to the host by its Ethernet address. Since it is the sending host, FreeBSD knows to use the loopback interface ([.filename]#lo0#) rather than the Ethernet interface. +The `host1` line refers to the host by its Ethernet address. +Since it is the sending host, FreeBSD knows to use the loopback interface ([.filename]#lo0#) rather than the Ethernet interface. + -The two `host2` lines represent aliases which were created using man:ifconfig[8]. The `=>` symbol after the [.filename]#lo0# interface says that an alias has been set in addition to the loopback address. Such routes only show up on the host that supports the alias and all other hosts on the local network will have a `link#1` line for such routes. +The two `host2` lines represent aliases which were created using man:ifconfig[8]. +The `=>` symbol after the [.filename]#lo0# interface says that an alias has been set in addition to the loopback address. +Such routes only show up on the host that supports the alias and all other hosts on the local network will have a `link#1` line for such routes. 224:: The final line (destination subnet `224`) deals with multicasting. -Various attributes of each route can be seen in the `Flags` column. <<routeflags>> summarizes some of these flags and their meanings: +Various attributes of each route can be seen in the `Flags` column. +<<routeflags>> summarizes some of these flags and their meanings: [[routeflags]] .Commonly Seen Routing Table Flags @@ -170,34 +194,45 @@ It is also possible to manually add the route using `route`: # route add default 10.20.30.1 .... -Note that manually added routes will not survive a reboot. For more information on manual manipulation of network routing tables, refer to man:route[8]. +Note that manually added routes will not survive a reboot. +For more information on manual manipulation of network routing tables, refer to man:route[8]. [[network-static-routes]] === Configuring a Router with Static Routes -A FreeBSD system can be configured as the default gateway, or router, for a network if it is a dual-homed system. A dual-homed system is a host which resides on at least two different networks. Typically, each network is connected to a separate network interface, though IP aliasing can be used to bind multiple addresses, each on a different subnet, to one physical interface. +A FreeBSD system can be configured as the default gateway, or router, for a network if it is a dual-homed system. +A dual-homed system is a host which resides on at least two different networks. +Typically, each network is connected to a separate network interface, though IP aliasing can be used to bind multiple addresses, each on a different subnet, to one physical interface. -In order for the system to forward packets between interfaces, FreeBSD must be configured as a router. Internet standards and good engineering practice prevent the FreeBSD Project from enabling this feature by default, but it can be configured to start at boot by adding this line to [.filename]#/etc/rc.conf#: +In order for the system to forward packets between interfaces, FreeBSD must be configured as a router. +Internet standards and good engineering practice prevent the FreeBSD Project from enabling this feature by default, but it can be configured to start at boot by adding this line to [.filename]#/etc/rc.conf#: [.programlisting] .... gateway_enable="YES" # Set to YES if this host will be a gateway .... -To enable routing now, set the man:sysctl[8] variable `net.inet.ip.forwarding` to `1`. To stop routing, reset this variable to `0`. +To enable routing now, set the man:sysctl[8] variable `net.inet.ip.forwarding` to `1`. +To stop routing, reset this variable to `0`. -The routing table of a router needs additional routes so it knows how to reach other networks. Routes can be either added manually using static routes or routes can be automatically learned using a routing protocol. Static routes are appropriate for small networks and this section describes how to add a static routing entry for a small network. +The routing table of a router needs additional routes so it knows how to reach other networks. +Routes can be either added manually using static routes or routes can be automatically learned using a routing protocol. +Static routes are appropriate for small networks and this section describes how to add a static routing entry for a small network. [NOTE] ==== -For large networks, static routes quickly become unscalable. FreeBSD comes with the standard BSD routing daemon man:routed[8], which provides the routing protocols RIP, versions 1 and 2, and IRDP. Support for the BGP and OSPF routing protocols can be installed using the package:net/zebra[] package or port. +For large networks, static routes quickly become unscalable. +FreeBSD comes with the standard BSD routing daemon man:routed[8], which provides the routing protocols RIP, versions 1 and 2, and IRDP. +Support for the BGP and OSPF routing protocols can be installed using the package:net/zebra[] package or port. ==== Consider the following network: image::static-routes.png[] -In this scenario, `RouterA` is a FreeBSD machine that is acting as a router to the rest of the Internet. It has a default route set to `10.0.0.1` which allows it to connect with the outside world. `RouterB` is already configured to use `192.168.1.1` as its default gateway. +In this scenario, `RouterA` is a FreeBSD machine that is acting as a router to the rest of the Internet. +It has a default route set to `10.0.0.1` which allows it to connect with the outside world. +`RouterB` is already configured to use `192.168.1.1` as its default gateway. Before adding any static routes, the routing table on `RouterA` looks like this: @@ -214,14 +249,17 @@ default 10.0.0.1 UGS 0 49378 xl0 192.168.1.0/24 link#2 UC 0 0 xl1 .... -With the current routing table, `RouterA` does not have a route to the `192.168.2.0/24` network. The following command adds the `Internal Net 2` network to ``RouterA``'s routing table using `192.168.1.2` as the next hop: +With the current routing table, `RouterA` does not have a route to the `192.168.2.0/24` network. +The following command adds the `Internal Net 2` network to ``RouterA``'s routing table using `192.168.1.2` as the next hop: [source,shell] .... # route add -net 192.168.2.0/24 192.168.1.2 .... -Now, `RouterA` can reach any host on the `192.168.2.0/24` network. However, the routing information will not persist if the FreeBSD system reboots. If a static route needs to be persistent, add it to [.filename]#/etc/rc.conf#: +Now, `RouterA` can reach any host on the `192.168.2.0/24` network. +However, the routing information will not persist if the FreeBSD system reboots. +If a static route needs to be persistent, add it to [.filename]#/etc/rc.conf#: [.programlisting] .... @@ -230,9 +268,11 @@ static_routes="internalnet2" route_internalnet2="-net 192.168.2.0/24 192.168.1.2" .... -The `static_routes` configuration variable is a list of strings separated by a space, where each string references a route name. The variable `route_internalnet2` contains the static route for that route name. +The `static_routes` configuration variable is a list of strings separated by a space, where each string references a route name. +The variable `route_internalnet2` contains the static route for that route name. -Using more than one string in `static_routes` creates multiple static routes. The following shows an example of adding static routes for the `192.168.0.0/24` and `192.168.1.0/24` networks: +Using more than one string in `static_routes` creates multiple static routes. +The following shows an example of adding static routes for the `192.168.0.0/24` and `192.168.1.0/24` networks: [.programlisting] .... @@ -244,31 +284,44 @@ route_net2="-net 192.168.1.0/24 192.168.1.1" [[network-routing-troubleshooting]] === Troubleshooting -When an address space is assigned to a network, the service provider configures their routing tables so that all traffic for the network will be sent to the link for the site. But how do external sites know to send their packets to the network's ISP? +When an address space is assigned to a network, the service provider configures their routing tables so that all traffic for the network will be sent to the link for the site. +But how do external sites know to send their packets to the network's ISP? -There is a system that keeps track of all assigned address spaces and defines their point of connection to the Internet backbone, or the main trunk lines that carry Internet traffic across the country and around the world. Each backbone machine has a copy of a master set of tables, which direct traffic for a particular network to a specific backbone carrier, and from there down the chain of service providers until it reaches a particular network. +There is a system that keeps track of all assigned address spaces and defines their point of connection to the Internet backbone, or the main trunk lines that carry Internet traffic across the country and around the world. +Each backbone machine has a copy of a master set of tables, which direct traffic for a particular network to a specific backbone carrier, and from there down the chain of service providers until it reaches a particular network. -It is the task of the service provider to advertise to the backbone sites that they are the point of connection, and thus the path inward, for a site. This is known as route propagation. +It is the task of the service provider to advertise to the backbone sites that they are the point of connection, and thus the path inward, for a site. +This is known as route propagation. -Sometimes, there is a problem with route propagation and some sites are unable to connect. Perhaps the most useful command for trying to figure out where routing is breaking down is `traceroute`. It is useful when `ping` fails. +Sometimes, there is a problem with route propagation and some sites are unable to connect. +Perhaps the most useful command for trying to figure out where routing is breaking down is `traceroute`. +It is useful when `ping` fails. -When using `traceroute`, include the address of the remote host to connect to. The output will show the gateway hosts along the path of the attempt, eventually either reaching the target host, or terminating because of a lack of connection. For more information, refer to man:traceroute[8]. +When using `traceroute`, include the address of the remote host to connect to. +The output will show the gateway hosts along the path of the attempt, eventually either reaching the target host, or terminating because of a lack of connection. +For more information, refer to man:traceroute[8]. [[network-routing-multicast]] === Multicast Considerations -FreeBSD natively supports both multicast applications and multicast routing. Multicast applications do not require any special configuration in order to run on FreeBSD. Support for multicast routing requires that the following option be compiled into a custom kernel: +FreeBSD natively supports both multicast applications and multicast routing. +Multicast applications do not require any special configuration in order to run on FreeBSD. +Support for multicast routing requires that the following option be compiled into a custom kernel: [.programlisting] .... options MROUTING .... -The multicast routing daemon, mrouted can be installed using the package:net/mrouted[] package or port. This daemon implements the DVMRP multicast routing protocol and is configured by editing [.filename]#/usr/local/etc/mrouted.conf# in order to set up the tunnels and DVMRP. The installation of mrouted also installs map-mbone and mrinfo, as well as their associated man pages. Refer to these for configuration examples. +The multicast routing daemon, mrouted can be installed using the package:net/mrouted[] package or port. +This daemon implements the DVMRP multicast routing protocol and is configured by editing [.filename]#/usr/local/etc/mrouted.conf# in order to set up the tunnels and DVMRP. +The installation of mrouted also installs map-mbone and mrinfo, as well as their associated man pages. +Refer to these for configuration examples. [NOTE] ==== -DVMRP has largely been replaced by the PIM protocol in many multicast installations. Refer to man:pim[4] for more information. +DVMRP has largely been replaced by the PIM protocol in many multicast installations. +Refer to man:pim[4] for more information. ==== [[network-wireless]] @@ -276,22 +329,46 @@ DVMRP has largely been replaced by the PIM protocol in many multicast installati === Wireless Networking Basics -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 r equirements 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. +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. +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. @@ -342,16 +419,21 @@ ifconfig_wlan0="WPA SYNCDHCP" ==== 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. +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#: +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: +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] .... @@ -360,10 +442,17 @@ 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. +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#: +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] .... @@ -372,7 +461,8 @@ 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]. +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] ==== @@ -407,7 +497,8 @@ ath0: AR2413 mac 7.9 RF2413 phy 4.5 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`: +The available region definitions can be found in [.filename]#/etc/regdomain.xml#. +To set the data at runtime, use `ifconfig`: [source,shell] .... @@ -423,13 +514,18 @@ To persist the settings, add it to [.filename]#/etc/rc.conf#: === 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. +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: +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] .... @@ -442,10 +538,13 @@ 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 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: +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: .Station Capability Codes [cols="1,1", frame="none", options="header"] @@ -476,17 +575,21 @@ One can also display the current list of known networks with: # 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. +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. +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. +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#: +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] .... @@ -502,7 +605,8 @@ 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: +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] .... @@ -510,7 +614,9 @@ 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: +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] .... @@ -518,15 +624,25 @@ 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]. +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>>. +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: +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] .... @@ -534,12 +650,16 @@ 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>>. +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: +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] .... @@ -570,11 +690,14 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 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. +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: +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] .... @@ -585,20 +708,33 @@ 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. +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. -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. +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]. +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. +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. ==== @@ -710,11 +846,17 @@ When DHCP is not used, the default gateway and the nameserver also have to be ma [[network-wireless-wpa-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. Authentication in WPA Enterprise is based on the Extensible Authentication Protocol (EAP). +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. +Authentication in WPA Enterprise is based on the Extensible Authentication Protocol (EAP). -EAP does not come with an encryption method. Instead, EAP is embedded inside an encrypted tunnel. There are many EAP authentication methods, but EAP-TLS, EAP-TTLS, and EAP-PEAP are the most common. +EAP does not come with an encryption method. +Instead, EAP is embedded inside an encrypted tunnel. +There are many EAP authentication methods, but EAP-TLS, EAP-TTLS, and EAP-PEAP are the most common. -EAP with Transport Layer Security (EAP-TLS) is a well-supported wireless authentication protocol since it was the first EAP method to be certified by the http://www.wi-fi.org/[Wi-Fi Alliance]. EAP-TLS requires three certificates to run: the certificate of the Certificate Authority (CA) installed on all machines, the server certificate for the authentication server, and one client certificate for each wireless client. In this EAP method, both the authentication server and wireless client authenticate each other by presenting their respective certificates, and then verify that these certificates were signed by the organization's CA. +EAP with Transport Layer Security (EAP-TLS) is a well-supported wireless authentication protocol since it was the first EAP method to be certified by the http://www.wi-fi.org/[Wi-Fi Alliance]. +EAP-TLS requires three certificates to run: the certificate of the Certificate Authority (CA) installed on all machines, the server certificate for the authentication server, and one client certificate for each wireless client. +In this EAP method, both the authentication server and wireless client authenticate each other by presenting their respective certificates, and then verify that these certificates were signed by the organization's CA. As previously, the configuration is done via [.filename]#/etc/wpa_supplicant.conf#: @@ -778,7 +920,10 @@ It is also possible to bring up the interface manually using man:wpa_supplicant[ [[network-wireless-wpa-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. This method is similar to a web server which creates a secure SSL tunnel even if visitors do not have client-side certificates. EAP-TTLS uses an encrypted TLS tunnel for safe transport of the authentication data. +With EAP-TLS, both the authentication server and the client need a certificate. +With EAP-TTLS, a client certificate is optional. +This method is similar to a web server which creates a secure SSL tunnel even if visitors do not have client-side certificates. +EAP-TTLS uses an encrypted TLS tunnel for safe transport of the authentication data. The required configuration can be added to [.filename]#/etc/wpa_supplicant.conf#: @@ -838,12 +983,16 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 [NOTE] ==== -PEAPv0/EAP-MSCHAPv2 is the most common PEAP method. In this chapter, the term PEAP is used to refer to that method. +PEAPv0/EAP-MSCHAPv2 is the most common PEAP method. +In this chapter, the term PEAP is used to refer to that method. ==== -Protected EAP (PEAP) is designed as an alternative to EAP-TTLS and is the most used EAP standard after EAP-TLS. In a network with mixed operating systems, PEAP should be the most supported standard after EAP-TLS. +Protected EAP (PEAP) is designed as an alternative to EAP-TTLS and is the most used EAP standard after EAP-TLS. +In a network with mixed operating systems, PEAP should be the most supported standard after EAP-TLS. -PEAP is similar to EAP-TTLS as it uses a server-side certificate to authenticate clients by creating an encrypted TLS tunnel between the client and the authentication server, which protects the ensuing exchange of authentication information. PEAP authentication differs from EAP-TTLS as it broadcasts the username in the clear and only the password is sent in the encrypted TLS tunnel. EAP-TTLS will use the TLS tunnel for both the username and password. +PEAP is similar to EAP-TTLS as it uses a server-side certificate to authenticate clients by creating an encrypted TLS tunnel between the client and the authentication server, which protects the ensuing exchange of authentication information. +PEAP authentication differs from EAP-TTLS as it broadcasts the username in the clear and only the password is sent in the encrypted TLS tunnel. +EAP-TTLS will use the TLS tunnel for both the username and password. Add the following lines to [.filename]#/etc/wpa_supplicant.conf# to configure the EAP-PEAP related settings: @@ -903,7 +1052,8 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 [[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. +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]: @@ -924,7 +1074,8 @@ 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#: +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] .... @@ -947,7 +1098,8 @@ Associated with 00:13:46:49:41:76 === 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. +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. On `A`: @@ -978,7 +1130,8 @@ The `adhoc` parameter indicates that the interface is running in IBSS mode. freebsdap 02:11:95:c3:0d:ac 2 54M -64:-96 100 IS WME .... -The `I` in the output confirms that `A` is in ad-hoc mode. Now, configure `B` with a different IP address: +The `I` in the output confirms that `A` is in ad-hoc mode. +Now, configure `B` with a different IP address: [source,shell] .... @@ -999,16 +1152,19 @@ Both `A` and `B` are now ready to exchange information. [[network-wireless-ap]] === FreeBSD Host Access Points -FreeBSD can act as an Access Point (AP) which eliminates the need to buy a hardware AP or run an ad-hoc network. This can be particularly useful when a FreeBSD machine is acting as a gateway to another network such as the Internet. +FreeBSD can act as an Access Point (AP) which eliminates the need to buy a hardware AP or run an ad-hoc network. +This can be particularly useful when a FreeBSD machine is acting as a gateway to another network such as the Internet. [[network-wireless-ap-basic]] ==== Basic Settings -Before configuring a FreeBSD machine as an AP, the kernel must be configured with the appropriate networking support for the wireless card as well as the security protocols being used. For more details, see <<network-wireless-basic>>. +Before configuring a FreeBSD machine as an AP, the kernel must be configured with the appropriate networking support for the wireless card as well as the security protocols being used. +For more details, see <<network-wireless-basic>>. [NOTE] ==== -The NDIS driver wrapper for Windows(R) drivers does not currently support AP operation. Only native FreeBSD wireless drivers support AP mode. +The NDIS driver wrapper for Windows(R) drivers does not currently support AP operation. +Only native FreeBSD wireless drivers support AP mode. ==== Once wireless networking support is loaded, check if the wireless device supports the host-based access point mode, also known as hostap mode: @@ -1021,7 +1177,10 @@ drivercaps=6f85edc1<STA,FF,TURBOP,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MO cryptocaps=1f<WEP,TKIP,AES,AES_CCM,TKIPMIC> .... -This output displays the card's capabilities. The `HOSTAP` word confirms that this wireless card can act as an AP. Various supported ciphers are also listed: WEP, TKIP, and AES. This information indicates which security protocols can be used on the AP. +This output displays the card's capabilities. +The `HOSTAP` word confirms that this wireless card can act as an AP. +Various supported ciphers are also listed: WEP, TKIP, and AES. +This information indicates which security protocols can be used on the AP. The wireless device can only be put into hostap mode during the creation of the network pseudo-device, so a previously created device must be destroyed first: @@ -1066,7 +1225,8 @@ ifconfig_wlan0="inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap mode 11g c ==== Host-based Access Point Without Authentication or Encryption -Although it is not recommended to run an AP without any authentication or encryption, this is a simple way to check if the AP is working. This configuration is also important for debugging client issues. +Although it is not recommended to run an AP without any authentication or encryption, this is a simple way to check if the AP is working. +This configuration is also important for debugging client issues. Once the AP is configured, initiate a scan from another wireless machine to find the AP: @@ -1098,11 +1258,13 @@ The client machine found the AP and can be associated with it: [[network-wireless-ap-wpa]] ==== WPA2 Host-based Access Point -This section focuses on setting up a FreeBSD access point using the WPA2 security protocol. More details regarding WPA and the configuration of WPA-based wireless clients can be found in <<network-wireless-wpa>>. +This section focuses on setting up a FreeBSD access point using the WPA2 security protocol. +More details regarding WPA and the configuration of WPA-based wireless clients can be found in <<network-wireless-wpa>>. The man:hostapd[8] daemon is used to deal with client authentication and key management on the WPA2-enabled AP. -The following configuration operations are performed on the FreeBSD machine acting as the AP. Once the AP is correctly working, man:hostapd[8] can be automatically started at boot with this line in [.filename]#/etc/rc.conf#: +The following configuration operations are performed on the FreeBSD machine acting as the AP. +Once the AP is correctly working, man:hostapd[8] can be automatically started at boot with this line in [.filename]#/etc/rc.conf#: [.programlisting] .... @@ -1164,11 +1326,14 @@ wlan0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> metric 0 mtu 1 groups: wlan .... -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`. +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. +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: @@ -1207,13 +1372,16 @@ 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. +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. +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. +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>>. @@ -1234,14 +1402,18 @@ Debugging support is provided by man:wpa_supplicant[8]. Try running this utility net.wlan.0.debug: 0 => 0xc80000<assoc,auth,scan> .... + -Many useful statistics are maintained by the 802.11 layer and `wlanstats`, found in [.filename]#/usr/src/tools/tools/net80211#, will dump this information. These statistics should display all errors identified by the 802.11 layer. However, some errors are identified in the device drivers that lie below the 802.11 layer so they may not show up. To diagnose device-specific problems, refer to the drivers' documentation. +Many useful statistics are maintained by the 802.11 layer and `wlanstats`, found in [.filename]#/usr/src/tools/tools/net80211#, will dump this information. +These statistics should display all errors identified by the 802.11 layer. +However, some errors are identified in the device drivers that lie below the 802.11 layer so they may not show up. +To diagnose device-specific problems, refer to the drivers' documentation. 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 -Many cellphones provide the option to share their data connection over USB (often called "tethering"). This feature uses one of RNDIS, CDC, or a custom Apple(R) iPhone(R)/iPad(R) protocol. +Many cellphones provide the option to share their data connection over USB (often called "tethering"). +This feature uses one of RNDIS, CDC, or a custom Apple(R) iPhone(R)/iPad(R) protocol. * Android(TM) devices generally use the man:urndis[4] driver. * Apple(R) devices use the man:ipheth[4] driver. @@ -1256,7 +1428,8 @@ Before attaching a device, load the appropriate driver into the kernel: # kldload if_ipheth .... -Once the device is attached ``ue``_0_ will be available for use like a normal network device. Be sure that the "USB tethering" option is enabled on the device. +Once the device is attached ``ue``_0_ will be available for use like a normal network device. +Be sure that the "USB tethering" option is enabled on the device. To make this change permanent and load the driver as a module at boot time, place the appropriate line of the following in [.filename]#/boot/loader.conf#: @@ -1270,15 +1443,23 @@ if_ipheth_load="YES" [[network-bluetooth]] == Bluetooth -Bluetooth is a wireless technology for creating personal networks operating in the 2.4 GHz unlicensed band, with a range of 10 meters. Networks are usually formed ad-hoc from portable devices such as cellular phones, handhelds, and laptops. Unlike Wi-Fi wireless technology, Bluetooth offers higher level service profiles, such as FTP-like file servers, file pushing, voice transport, serial line emulation, and more. +Bluetooth is a wireless technology for creating personal networks operating in the 2.4 GHz unlicensed band, with a range of 10 meters. +Networks are usually formed ad-hoc from portable devices such as cellular phones, handhelds, and laptops. +Unlike Wi-Fi wireless technology, Bluetooth offers higher level service profiles, such as FTP-like file servers, file pushing, voice transport, serial line emulation, and more. -This section describes the use of a USB Bluetooth dongle on a FreeBSD system. It then describes the various Bluetooth protocols and utilities. +This section describes the use of a USB Bluetooth dongle on a FreeBSD system. +It then describes the various Bluetooth protocols and utilities. === Loading Bluetooth Support -The Bluetooth stack in FreeBSD is implemented using the man:netgraph[4] framework. A broad variety of Bluetooth USB dongles is supported by man:ng_ubt[4]. Broadcom BCM2033 based Bluetooth devices are supported by the man:ubtbcmfw[4] and man:ng_ubt[4] drivers. The 3Com Bluetooth PC Card 3CRWB60-A is supported by the man:ng_bt3c[4] driver. Serial and UART based Bluetooth devices are supported by man:sio[4], man:ng_h4[4], and man:hcseriald[8]. +The Bluetooth stack in FreeBSD is implemented using the man:netgraph[4] framework. +A broad variety of Bluetooth USB dongles is supported by man:ng_ubt[4]. +Broadcom BCM2033 based Bluetooth devices are supported by the man:ubtbcmfw[4] and man:ng_ubt[4] drivers. +The 3Com Bluetooth PC Card 3CRWB60-A is supported by the man:ng_bt3c[4] driver. +Serial and UART based Bluetooth devices are supported by man:sio[4], man:ng_h4[4], and man:hcseriald[8]. -Before attaching a device, determine which of the above drivers it uses, then load the driver. For example, if the device uses the man:ng_ubt[4] driver: +Before attaching a device, determine which of the above drivers it uses, then load the driver. +For example, if the device uses the man:ng_ubt[4] driver: [source,shell] .... @@ -1292,7 +1473,8 @@ If the Bluetooth device will be attached to the system during system startup, th ng_ubt_load="YES" .... -Once the driver is loaded, plug in the USB dongle. If the driver load was successful, output similar to the following should appear on the console and in [.filename]#/var/log/messages#: +Once the driver is loaded, plug in the USB dongle. +If the driver load was successful, output similar to the following should appear on the console and in [.filename]#/var/log/messages#: [source,shell] .... @@ -1302,7 +1484,9 @@ ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3, wMaxPacketSize=49, nframes=6, buffer size=294 .... -To start and stop the Bluetooth stack, use its startup script. It is a good idea to stop the stack before unplugging the device. Starting the bluetooth stack might require man:hcsecd[8] to be started. When starting the stack, the output should be similar to the following: +To start and stop the Bluetooth stack, use its startup script. It is a good idea to stop the stack before unplugging the device. +Starting the bluetooth stack might require man:hcsecd[8] to be started. +When starting the stack, the output should be similar to the following: [source,shell] .... @@ -1322,9 +1506,16 @@ Number of SCO packets: 8 === Finding Other Bluetooth Devices -The Host Controller Interface (HCI) provides a uniform method for accessing Bluetooth baseband capabilities. In FreeBSD, a netgraph HCI node is created for each Bluetooth device. For more details, refer to man:ng_hci[4]. +The Host Controller Interface (HCI) provides a uniform method for accessing Bluetooth baseband capabilities. +In FreeBSD, a netgraph HCI node is created for each Bluetooth device. +For more details, refer to man:ng_hci[4]. -One of the most common tasks is discovery of Bluetooth devices within RF proximity. This operation is called _inquiry_. Inquiry and other HCI related operations are done using man:hccontrol[8]. The example below shows how to find out which Bluetooth devices are in range. The list of devices should be displayed in a few seconds. Note that a remote device will only answer the inquiry if it is set to _discoverable_ mode. +One of the most common tasks is discovery of Bluetooth devices within RF proximity. +This operation is called _inquiry_. +Inquiry and other HCI related operations are done using man:hccontrol[8]. +The example below shows how to find out which Bluetooth devices are in range. +The list of devices should be displayed in a few seconds. +Note that a remote device will only answer the inquiry if it is set to _discoverable_ mode. [source,shell] .... @@ -1340,7 +1531,10 @@ Inquiry result #0 Inquiry complete. Status: No error [00] .... -The `BD_ADDR` is the unique address of a Bluetooth device, similar to the MAC address of a network card. This address is needed for further communication with a device and it is possible to assign a human readable name to a `BD_ADDR`. Information regarding the known Bluetooth hosts is contained in [.filename]#/etc/bluetooth/hosts#. The following example shows how to obtain the human readable name that was assigned to the remote device: +The `BD_ADDR` is the unique address of a Bluetooth device, similar to the MAC address of a network card. +This address is needed for further communication with a device and it is possible to assign a human readable name to a `BD_ADDR`. +Information regarding the known Bluetooth hosts is contained in [.filename]#/etc/bluetooth/hosts#. +The following example shows how to obtain the human readable name that was assigned to the remote device: [source,shell] .... @@ -1349,11 +1543,14 @@ BD_ADDR: 00:80:37:29:19:a4 Name: Pav's T39 .... -If an inquiry is performed on a remote Bluetooth device, it will find the computer as "your.host.name (ubt0)". The name assigned to the local device can be changed at any time. +If an inquiry is performed on a remote Bluetooth device, it will find the computer as "your.host.name (ubt0)". +The name assigned to the local device can be changed at any time. -Remote devices can be assigned aliases in [.filename]#/etc/bluetooth/hosts#. More information about [.filename]#/etc/bluetooth/hosts# file might be found in man:bluetooth.hosts[5]. +Remote devices can be assigned aliases in [.filename]#/etc/bluetooth/hosts#. +More information about [.filename]#/etc/bluetooth/hosts# file might be found in man:bluetooth.hosts[5]. -The Bluetooth system provides a point-to-point connection between two Bluetooth units, or a point-to-multipoint connection which is shared among several Bluetooth devices. The following example shows how to create a connection to a remote device: +The Bluetooth system provides a point-to-point connection between two Bluetooth units, or a point-to-multipoint connection which is shared among several Bluetooth devices. +The following example shows how to create a connection to a remote device: [source,shell] .... @@ -1371,7 +1568,8 @@ Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State 00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN .... -A _connection handle_ is useful when termination of the baseband connection is required, though it is normally not required to do this by hand. The stack will automatically terminate inactive baseband connections. +A _connection handle_ is useful when termination of the baseband connection is required, though it is normally not required to do this by hand. +The stack will automatically terminate inactive baseband connections. [source,shell] .... @@ -1380,13 +1578,24 @@ Connection handle: 41 Reason: Connection terminated by local host [0x16] .... -Type `hccontrol help` for a complete listing of available HCI commands. Most of the HCI commands do not require superuser privileges. +Type `hccontrol help` for a complete listing of available HCI commands. +Most of the HCI commands do not require superuser privileges. === Device Pairing -By default, Bluetooth communication is not authenticated, and any device can talk to any other device. A Bluetooth device, such as a cellular phone, may choose to require authentication to provide a particular service. Bluetooth authentication is normally done with a _PIN code_, an ASCII string up to 16 characters in length. The user is required to enter the same PIN code on both devices. Once the user has entered the PIN code, both devices will generate a _link key_. After that, the link key can be stored either in the devices or in a persistent storage. Next time, both devices will use the previously generated link key. This procedure is called _pairing_. Note that if the link key is lost by either device, the pairing must be repeated. +By default, Bluetooth communication is not authenticated, and any device can talk to any other device. +A Bluetooth device, such as a cellular phone, may choose to require authentication to provide a particular service. +Bluetooth authentication is normally done with a _PIN code_, an ASCII string up to 16 characters in length. +The user is required to enter the same PIN code on both devices. +Once the user has entered the PIN code, both devices will generate a _link key_. +After that, the link key can be stored either in the devices or in a persistent storage. +Next time, both devices will use the previously generated link key. +This procedure is called _pairing_. +Note that if the link key is lost by either device, the pairing must be repeated. -The man:hcsecd[8] daemon is responsible for handling Bluetooth authentication requests. The default configuration file is [.filename]#/etc/bluetooth/hcsecd.conf#. An example section for a cellular phone with the PIN code set to `1234` is shown below: +The man:hcsecd[8] daemon is responsible for handling Bluetooth authentication requests. +The default configuration file is [.filename]#/etc/bluetooth/hcsecd.conf#. +An example section for a cellular phone with the PIN code set to `1234` is shown below: [.programlisting] .... @@ -1398,7 +1607,14 @@ device { } .... -The only limitation on PIN codes is length. Some devices, such as Bluetooth headsets, may have a fixed PIN code built in. The `-d` switch forces man:hcsecd[8] to stay in the foreground, so it is easy to see what is happening. Set the remote device to receive pairing and initiate the Bluetooth connection to the remote device. The remote device should indicate that pairing was accepted and request the PIN code. Enter the same PIN code listed in [.filename]#hcsecd.conf#. Now the computer and the remote device are paired. Alternatively, pairing can be initiated on the remote device. +The only limitation on PIN codes is length. +Some devices, such as Bluetooth headsets, may have a fixed PIN code built in. +The `-d` switch forces man:hcsecd[8] to stay in the foreground, so it is easy to see what is happening. +Set the remote device to receive pairing and initiate the Bluetooth connection to the remote device. +The remote device should indicate that pairing was accepted and request the PIN code. +Enter the same PIN code listed in [.filename]#hcsecd.conf#. +Now the computer and the remote device are paired. +Alternatively, pairing can be initiated on the remote device. *** 26075 LINES SKIPPED ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202106060916.1569G7Bf034082>