diff --git a/documentation/content/en/books/handbook/network/_index.adoc b/documentation/content/en/books/handbook/network/_index.adoc new file mode 100644 --- /dev/null +++ b/documentation/content/en/books/handbook/network/_index.adoc @@ -0,0 +1,578 @@ +--- +title: Chapter 7. Network +part: Part III. System Administration +prev: books/handbook/partiii +next: books/handbook/boot +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", "virtual hosts"] +showBookMenu: true +weight: 7 +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. +* Insights into network performance tuning, enabling readers to optimize network throughput and minimize latency. +* An understanding of various network services and protocols supported by FreeBSD, with configuration instructions for DNS, DHCP and more. +* The ability to troubleshoot common network issues in FreeBSD, utilizing diagnostic tools and analyzing network logs. + +[[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 = network +.... + +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] execute the following command: + +[source,shell] +.... +# kldload if_alc_load +.... + +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]] +== Configuring the Wired Network Connection + +Once the right driver is loaded the network adapter needs to be configured. +FreeBSD uses the driver name followed by a number representing the order in which the card is detected at boot to name the network interface card (NIC). +For example, `em0` is the first network interface card (NIC) on the system using the man:em[4] driver. + +To display the network interface card (NIC) configuration, enter the following command: + +[source,shell] +.... +% ifconfig +.... + +The output should be similar to the following: + +[.programlisting] +.... +em0: flags=8863 metric 0 mtu 1500 + options=481249b + 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 ) + status: active + nd6 options=23 +lo0: flags=8049 metric 0 mtu 16384 + options=680003 + inet6 ::1 prefixlen 128 + inet6 fe80::1%lo0 prefixlen 64 scopeid 0x2 + inet 127.0.0.1 netmask 0xff000000 + groups: lo + nd6 options=21 +.... + +In this example, the following devices were displayed: + +* `em0`: The Ethernet interface. +* `lo0`: The loopback device. + +The example shows that `em0` is up and running. + +The key indicators are: + +. `UP` means that the card is configured and ready. +. The card has an IPv4 Internet (`inet`) address, `192.168.1.19`. +. The card 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 card (`ether`) is `00:1f:16:0f:27:5a`. +. The physical media selection is on autoselection mode (`media: Ethernet autoselect (1000baseT )`). +. 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 card. + +If the man:ifconfig[8] output had shown something similar to the next output it would indicate the card has not been configured: + +[.programlisting] +.... +em0: flags=8822 metric 0 mtu 1500 + options=481249b + ether 00:1f:16:0f:27:5a + media: Ethernet autoselect + status: no carrier + nd6 options=29 +.... + +[[config-static-ip-v4]] +=== Configuring Static IPv4 Address + +// TODO: Add an introduction + +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 netmask 255.255.255.0 +.... + +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" +.... + +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 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="DHCP" +.... + +[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 metric 0 mtu 1500 + options=481249b + 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 ) + status: active + nd6 options=23 +.... + +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]] +.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]. + +[[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 and enable the router solicitation daemon, man:rtsol[8]. + +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" +# sysrc rtsold_enable="YES" +.... + +To assign a default router, specify its address executing the following command: + +[source,shell] +.... +# sysrc ipv6_defaultrouter="2001:db8:4672:6565::1" +.... + +[[network-wireless]] +== Configuring the Wireless Network Connection + +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. + +[[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 stepp will be the restart `netif` service executing the following command: + +[source,shell] +.... +# service netif restart +.... + +[[scan-wireless-networks]] +=== Scan Wireless networks + +// TODO + +// TODO - Rest of the wireless section + +[[hostname]] +== Hostname + +// TODO + +[[dns]] +== DNS + +// TODO + +[[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: + +[source,shell] +.... +# sysrc 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 `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: + +[source,shell] +.... +# 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" +.... + +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] +.... +# sysrc ifconfig_fxp0_aliases="inet 10.1.1.1-5/24 inet 202.0.75.17-20/28" +.... + +[[network-activity]] +== Network activity + +// TODO