Index: head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml (revision 50967) +++ head/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml (revision 50968) @@ -1,5263 +1,5263 @@ Advanced Networking Synopsis This chapter covers a number of advanced networking topics. After reading this chapter, you will know: The basics of gateways and routes. How to set up USB tethering. How to set up &ieee; 802.11 and &bluetooth; devices. How to make &os; act as a bridge. How to set up network PXE booting. How to set up IPv6 on a &os; machine. How to enable and utilize the features of the Common Address Redundancy Protocol (CARP) in &os;. How to configure multiple VLANs on &os;. Before reading this chapter, you should: Understand the basics of the /etc/rc scripts. Be familiar with basic network terminology. Know how to configure and install a new &os; kernel (). Know how to install additional third-party software (). Gateways and Routes Coranth Gryphon Contributed by routing gateway subnet 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 &os; system as a router and offers some troubleshooting tips. Routing Basics To view the routing table of a &os; system, use &man.netstat.1;: &prompt.user; netstat -r Routing tables Internet: Destination Gateway Flags Refs Use Netif Expire default outside-gw UGS 37 418 em0 localhost localhost UH 0 181 lo0 test0 0:e0:b5:36:cf:4f UHLW 5 63288 re0 77 10.20.30.255 link#1 UHLW 1 2421 example.com link#1 UC 0 0 host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0 host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 => host2.example.com link#1 UC 0 0 224 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. 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 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. &os; will automatically identify any hosts, test0 in the example, on the local Ethernet and add a route for that host over the Ethernet interface, 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 &os; 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. host The host1 line refers to the host by its Ethernet address. Since it is the sending host, &os; knows to use the loopback interface (lo0) rather than the Ethernet interface. The two host2 lines represent aliases which were created using &man.ifconfig.8;. The => symbol after the 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. summarizes some of these flags and their meanings: Commonly Seen Routing Table Flags Command Purpose U The route is active (up). H The route destination is a single host. G Send anything for this destination on to this gateway, which will figure out from there where to send it. S This route was statically configured. C Clones a new route based upon this route for machines to connect to. This type of route is normally used for local networks. W The route was auto-configured based upon a local area network (clone) route. L Route involves references to Ethernet (link) hardware.
On a &os; system, the default route can defined in /etc/rc.conf by specifying the IP address of the default gateway: defaultrouter="10.20.30.1" It is also possible to manually add the route using route: &prompt.root; 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;. Configuring a Router with Static Routes Al Hoang Contributed by dual homed hosts A &os; 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. router In order for the system to forward packets between interfaces, &os; must be configured as a router. Internet standards and good engineering practice prevent the &os; Project from enabling this feature by default, but it can be configured to start at boot by adding this line to /etc/rc.conf: 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. BGP RIP OSPF 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. For large networks, static routes quickly become unscalable. &os; 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 net/zebra package or port. Consider the following network: INTERNET | (10.0.0.1/24) Default Router to Internet | |Interface xl0 |10.0.0.10/24 +------+ | | RouterA | | (FreeBSD gateway) +------+ | Interface xl1 | 192.168.1.1/24 | +--------------------------------+ Internal Net 1 | 192.168.1.2/24 | +------+ | | RouterB | | +------+ | 192.168.2.1/24 | Internal Net 2 In this scenario, RouterA is a &os; 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: &prompt.user; netstat -nr Routing tables Internet: Destination Gateway Flags Refs Use Netif Expire default 10.0.0.1 UGS 0 49378 xl0 127.0.0.1 127.0.0.1 UH 0 6 lo0 10.0.0.0/24 link#1 UC 0 0 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: &prompt.root; 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 &os; system reboots. If a static route needs to be persistent, add it to /etc/rc.conf: # Add Internal Net 2 as a persistent static route 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. 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: static_routes="net1 net2" route_net1="-net 192.168.0.0/24 192.168.0.1" route_net2="-net 192.168.1.0/24 192.168.1.1" 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? 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. &man.traceroute.8; 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;. Multicast Considerations multicast routing kernel options MROUTING &os; natively supports both multicast applications and multicast routing. Multicast applications do not require any special configuration in order to run on &os;. Support for multicast routing requires that the following option be compiled into a custom kernel: options MROUTING The multicast routing daemon, mrouted can be installed using the net/mrouted package or port. This daemon implements the DVMRP multicast routing protocol and is configured by editing /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. DVMRP has largely been replaced by the PIM protocol in many multicast installations. Refer to &man.pim.4; for more information. Wireless Networking Loader Marc Fonvieille Murray Stokely wireless networking 802.11 wireless networking Wireless Networking Basics Most wireless networks are based on the &ieee; 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; 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; 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. &os; 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. Quick Start Connecting a computer to an existing wireless network is a very common situation. This procedure shows the steps required. Obtain the SSID (Service Set Identifier) and PSK (Pre-Shared Key) for the wireless network from the network administrator. Identify the wireless adapter. The &os; GENERIC kernel includes drivers for many common wireless adapters. If the wireless adapter is one of those models, it will be shown in the output from &man.ifconfig.8;: &prompt.user; ifconfig | grep -B3 -i wireless On &os; 11 or higher, use this command instead: &prompt.user; sysctl net.wlan.devices If a wireless adapter is not listed, an additional kernel module might be required, or it might be a model not supported by &os;. This example shows the Atheros ath0 wireless adapter. Add an entry for this network to /etc/wpa_supplicant.conf. If the file does not exist, create it. Replace myssid and mypsk with the SSID and PSK provided by the network administrator. network={ ssid="myssid" psk="mypsk" } Add entries to /etc/rc.conf to configure the network on startup: wlans_ath0="wlan0" ifconfig_wlan0="WPA SYNCDHCP" Restart the computer, or restart the network service to connect to the network: &prompt.root; service netif restart Basic Setup Kernel Configuration To use wireless networking, a wireless networking card is needed and the kernel needs to be configured with the appropriate wireless networking support. The kernel is separated into multiple modules so that only the required support needs to be configured. The most commonly used wireless devices are those that use parts made by Atheros. These devices are supported by &man.ath.4; and require the following line to be added to /boot/loader.conf: 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: if_wi_load="YES" 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 &os; Hardware Notes, available on the Release + xlink:href="https://www.FreeBSD.org/releases/index.html">Release Information page of the &os; website. If a native &os; driver for the wireless device does not exist, it may be possible to use the &windows; driver with the help of the 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 /boot/loader.conf: wlan_wep_load="YES" wlan_ccmp_load="YES" wlan_tkip_load="YES" Once this information has been added to /boot/loader.conf, reboot the &os; box. Alternately, load the modules by hand using &man.kldload.8;. For users who do not want to use modules, it is possible to compile these drivers into the kernel by adding the following lines to a custom kernel configuration file: device wlan # 802.11 support device wlan_wep # 802.11 WEP support device wlan_ccmp # 802.11 CCMP support device wlan_tkip # 802.11 TKIP support device wlan_amrr # AMRR transmit rate control algorithm device ath # Atheros pci/cardbus NIC's device ath_hal # pci/cardbus chip support options AH_SUPPORT_AR5416 # enable AR5416 tx/rx descriptors device ath_rate_sample # SampleRate tx rate control for ath With this information in the kernel configuration file, recompile the kernel and reboot the &os; machine. Information about the wireless device should appear in the boot messages, like this: ath0: <Atheros 5212> mem 0x88000000-0x8800ffff irq 11 at device 0.0 on cardbus1 ath0: [ITHREAD] ath0: AR2413 mac 7.9 RF2413 phy 4.5 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. &os; 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: &prompt.root; ifconfig wlan0 create wlandev ath0 &prompt.root; ifconfig wlan0 up scan SSID/MESH ID BSSID CHAN RATE S:N INT CAPS dlinkap 00:13:46:49:41:76 11 54M -90:96 100 EPS WPA WME freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 100 EPS WPA The interface must be 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: Station Capability Codes Capability Code Meaning E Extended Service Set (ESS). Indicates that the station is part of an infrastructure network rather than an IBSS/ad-hoc network. I IBSS/ad-hoc network. Indicates that the station is part of an ad-hoc network rather than an ESS network. P Privacy. Encryption is required for all data frames exchanged within the BSS using cryptographic means such as WEP, TKIP or AES-CCMP. S Short Preamble. Indicates that the network is using short preambles, defined in 802.11b High Rate/DSSS PHY, and utilizes a 56 bit sync field rather than the 128 bit field used in long preamble mode. s Short slot time. Indicates that the 802.11g network is using a short slot time because there are no legacy (802.11b) stations present.
One can also display the current list of known networks with: &prompt.root; ifconfig wlan0 list scan This information may be updated automatically by the adapter or manually with a 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 &os; without encryption. Once familiar with these concepts, it is strongly recommend to use WPA to set up the wireless network. There are three basic steps to configure a wireless network: select an access point, authenticate the station, and configure an IP address. The following sections discuss each step. Selecting an Access Point Most of the time, it is sufficient to let the system choose an access point using the builtin heuristics. This is the default behavior when an interface is marked as up or it is listed in /etc/rc.conf: wlans_ath0="wlan0" ifconfig_wlan0="DHCP" If there are multiple access points, a specific one can be selected by its SSID: 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: 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 parameter: 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 parameter, which locks operation to one specific frequency, and the 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 . If using an &apple; &airport; Extreme base station for an access point, shared-key authentication together with a WEP key needs to be configured. This can be configured in /etc/rc.conf or by using &man.wpa.supplicant.8;. For a single &airport; base station, access can be configured with: 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 . Getting an <acronym>IP</acronym> Address with <acronym>DHCP</acronym> 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 /etc/rc.conf and add DHCP to the configuration for the device: wlans_ath0="wlan0" ifconfig_wlan0="DHCP" The wireless interface is now ready to bring up: &prompt.root; service netif start Once the interface is running, use &man.ifconfig.8; to see the status of the interface ath0: &prompt.root; ifconfig wlan0 wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255 media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g status: associated ssid dlinkap channel 11 (2462 Mhz 11g) bssid 00:13:46:49:41:76 country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7 scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst The status: associated line means that it is connected to the wireless network. The bssid 00:13:46:49:41:76 is the MAC address of the access point and authmode OPEN indicates that the communication is not encrypted. Static <acronym>IP</acronym> 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: wlans_ath0="wlan0" ifconfig_wlan0="inet 192.168.1.100 netmask 255.255.255.0 ssid your_ssid_here" <acronym>WPA</acronym> 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. 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, /etc/wpa_supplicant.conf, to run. More information regarding this file can be found in &man.wpa.supplicant.conf.5;. <acronym>WPA-PSK</acronym> 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. Always use strong passwords that are sufficiently long and made from a rich alphabet so that they will not be easily guessed or attacked. The first step is the configuration of /etc/wpa_supplicant.conf with the SSID and the pre-shared key of the network: network={ ssid="freebsdap" psk="freebsdmall" } Then, in /etc/rc.conf, indicate that the wireless device configuration will be done with WPA and the IP address will be obtained with DHCP: wlans_ath0="wlan0" ifconfig_wlan0="WPA DHCP" Then, bring up the interface: &prompt.root; service netif start Starting wpa_supplicant. DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 5 DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 6 DHCPOFFER from 192.168.0.1 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 DHCPACK from 192.168.0.1 bound to 192.168.0.254 -- renewal in 300 seconds. wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst roaming MANUAL Or, try to configure the interface manually using the information in /etc/wpa_supplicant.conf: &prompt.root; wpa_supplicant -i wlan0 -c /etc/wpa_supplicant.conf Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz) Associated with 00:11:95:c3:0d:ac WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=CCMP GTK=CCMP] CTRL-EVENT-CONNECTED - Connection to 00:11:95:c3:0d:ac completed (auth) [id=0 id_str=] The next operation is to launch &man.dhclient.8; to get the IP address from the DHCP server: &prompt.root; dhclient wlan0 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 DHCPACK from 192.168.0.1 bound to 192.168.0.254 -- renewal in 300 seconds. &prompt.root; ifconfig wlan0 wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst roaming MANUAL If /etc/rc.conf has an ifconfig_wlan0="DHCP" entry, &man.dhclient.8; will be launched automatically after &man.wpa.supplicant.8; associates with the access point. If DHCP is not possible or desired, set a static IP address after &man.wpa.supplicant.8; has authenticated the station: &prompt.root; ifconfig wlan0 inet 192.168.0.100 netmask 255.255.255.0 &prompt.root; ifconfig wlan0 wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst roaming MANUAL When DHCP is not used, the default gateway and the nameserver also have to be manually set: &prompt.root; route add default your_default_router &prompt.root; echo "nameserver your_DNS_server" >> /etc/resolv.conf <acronym>WPA</acronym> with <acronym>EAP-TLS</acronym> 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 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 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 /etc/wpa_supplicant.conf: network={ ssid="freebsdap" proto=RSN key_mgmt=WPA-EAP eap=TLS identity="loader" ca_cert="/etc/certs/cacert.pem" client_cert="/etc/certs/clientcert.pem" private_key="/etc/certs/clientkey.pem" private_key_passwd="freebsdmallclient" } This field indicates the network name (SSID). This example uses the RSN &ieee; 802.11i protocol, also known as WPA2. The key_mgmt line refers to the key management protocol to use. In this example, it is WPA using EAP authentication. This field indicates the EAP method for the connection. The identity field contains the identity string for EAP. The ca_cert field indicates the pathname of the CA certificate file. This file is needed to verify the server certificate. The client_cert line gives the pathname to the client certificate file. This certificate is unique to each wireless client of the network. The private_key field is the pathname to the client certificate private key file. The private_key_passwd field contains the passphrase for the private key. Then, add the following lines to /etc/rc.conf: wlans_ath0="wlan0" ifconfig_wlan0="WPA DHCP" The next step is to bring up the interface: &prompt.root; service netif start Starting wpa_supplicant. DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 DHCPACK from 192.168.0.20 bound to 192.168.0.254 -- renewal in 300 seconds. wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst roaming MANUAL It is also possible to bring up the interface manually using &man.wpa.supplicant.8; and &man.ifconfig.8;. <acronym>WPA</acronym> with <acronym>EAP-TTLS</acronym> 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 /etc/wpa_supplicant.conf: network={ ssid="freebsdap" proto=RSN key_mgmt=WPA-EAP eap=TTLS identity="test" password="test" ca_cert="/etc/certs/cacert.pem" phase2="auth=MD5" } This field specifies the EAP method for the connection. The identity field contains the identity string for EAP authentication inside the encrypted TLS tunnel. The password field contains the passphrase for the EAP authentication. The ca_cert field indicates the pathname of the CA certificate file. This file is needed to verify the server certificate. This field specifies the authentication method used in the encrypted TLS tunnel. In this example, EAP with MD5-Challenge is used. The inner authentication phase is often called phase2. Next, add the following lines to /etc/rc.conf: wlans_ath0="wlan0" ifconfig_wlan0="WPA DHCP" The next step is to bring up the interface: &prompt.root; service netif start Starting wpa_supplicant. DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21 DHCPACK from 192.168.0.20 bound to 192.168.0.254 -- renewal in 300 seconds. wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst roaming MANUAL <acronym>WPA</acronym> with <acronym>EAP-PEAP</acronym> 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. 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 /etc/wpa_supplicant.conf to configure the EAP-PEAP related settings: network={ ssid="freebsdap" proto=RSN key_mgmt=WPA-EAP eap=PEAP identity="test" password="test" ca_cert="/etc/certs/cacert.pem" phase1="peaplabel=0" phase2="auth=MSCHAPV2" } This field specifies the EAP method for the connection. The identity field contains the identity string for EAP authentication inside the encrypted TLS tunnel. The password field contains the passphrase for the EAP authentication. The ca_cert field indicates the pathname of the CA certificate file. This file is needed to verify the server certificate. This field contains the parameters for the first phase of authentication, the TLS tunnel. According to the authentication server used, specify a specific label for authentication. Most of the time, the label will be client EAP encryption which is set by using peaplabel=0. More information can be found in &man.wpa.supplicant.conf.5;. This field specifies the authentication protocol used in the encrypted TLS tunnel. In the case of PEAP, it is auth=MSCHAPV2. Add the following to /etc/rc.conf: wlans_ath0="wlan0" ifconfig_wlan0="WPA DHCP" Then, bring up the interface: &prompt.root; service netif start Starting wpa_supplicant. DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21 DHCPACK from 192.168.0.20 bound to 192.168.0.254 -- renewal in 300 seconds. wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst roaming MANUAL <acronym>WEP</acronym> 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;: &prompt.root; ifconfig wlan0 create wlandev ath0 &prompt.root; ifconfig wlan0 inet 192.168.1.100 netmask 255.255.255.0 \ ssid my_net wepmode on weptxkey 3 wepkey 3:0x3456789012 The weptxkey specifies which WEP key will be used in the transmission. This example uses the third key. This must match the setting on the access point. When unsure which key is used by the access point, try 1 (the first key) for this value. The wepkey selects one of the WEP keys. It should be in the format index:key. Key 1 is used by default; the index only needs to be set when using a key other than the first key. 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 /etc/wpa_supplicant.conf: network={ ssid="my_net" key_mgmt=NONE wep_key3=3456789012 wep_tx_keyidx=3 } Then: &prompt.root; wpa_supplicant -i wlan0 -c /etc/wpa_supplicant.conf Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz) Associated with 00:13:46:49:41:76 Ad-hoc Mode 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: &prompt.root; ifconfig wlan0 create wlandev ath0 wlanmode adhoc &prompt.root; ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap &prompt.root; ifconfig wlan0 wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:11:95:c3:0d:ac inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <adhoc> status: running ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 protmode CTS wme burst The adhoc parameter indicates that the interface is running in IBSS mode. B should now be able to detect A: &prompt.root; ifconfig wlan0 create wlandev ath0 wlanmode adhoc &prompt.root; ifconfig wlan0 up scan SSID/MESH ID BSSID CHAN RATE S:N INT CAPS 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: &prompt.root; ifconfig wlan0 inet 192.168.0.2 netmask 255.255.255.0 ssid freebsdap &prompt.root; ifconfig wlan0 wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <adhoc> status: running ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 protmode CTS wme burst Both A and B are now ready to exchange information. &os; Host Access Points &os; 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 &os; machine is acting as a gateway to another network such as the Internet. Basic Settings Before configuring a &os; 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 . The NDIS driver wrapper for &windows; drivers does not currently support AP operation. Only native &os; 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: &prompt.root; ifconfig wlan0 create wlandev ath0 &prompt.root; ifconfig wlan0 list caps drivercaps=6f85edc1<STA,FF,TURBOP,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,MBSS,WPA1,WPA2,BURST,WME,WDS,BGSCAN,TXFRAG> 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. 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: &prompt.root; ifconfig wlan0 destroy then regenerated with the correct option before setting the other parameters: &prompt.root; ifconfig wlan0 create wlandev ath0 wlanmode hostap &prompt.root; ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap mode 11g channel 1 Use &man.ifconfig.8; again to see the status of the wlan0 interface: &prompt.root; ifconfig wlan0 wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:11:95:c3:0d:ac inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> status: running ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs The hostap parameter indicates the interface is running in the host-based access point mode. The interface configuration can be done automatically at boot time by adding the following lines to /etc/rc.conf: wlans_ath0="wlan0" create_args_wlan0="wlanmode hostap" ifconfig_wlan0="inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap mode 11g channel 1" 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. Once the AP is configured, initiate a scan from another wireless machine to find the AP: &prompt.root; ifconfig wlan0 create wlandev ath0 &prompt.root; ifconfig wlan0 up scan SSID/MESH ID BSSID CHAN RATE S:N INT CAPS freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME The client machine found the AP and can be associated with it: &prompt.root; ifconfig wlan0 inet 192.168.0.2 netmask 255.255.255.0 ssid freebsdap &prompt.root; ifconfig wlan0 wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g status: associated ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7 scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS wme burst <acronym>WPA2</acronym> Host-based Access Point This section focuses on setting up a &os; access point using the WPA2 security protocol. More details regarding WPA and the configuration of WPA-based wireless clients can be found in . 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 &os; machine acting as the AP. Once the AP is correctly working, &man.hostapd.8; can be automatically started at boot with this line in /etc/rc.conf: hostapd_enable="YES" Before trying to configure &man.hostapd.8;, first configure the basic settings introduced in . <acronym>WPA2-PSK</acronym> WPA2-PSK is intended for small networks where the use of a backend authentication server is not possible or desired. The configuration is done in /etc/hostapd.conf: interface=wlan0 debug=1 ctrl_interface=/var/run/hostapd ctrl_interface_group=wheel ssid=freebsdap wpa=2 wpa_passphrase=freebsdmall wpa_key_mgmt=WPA-PSK wpa_pairwise=CCMP Wireless interface used for the access point. Level of verbosity used during the execution of &man.hostapd.8;. A value of 1 represents the minimal level. Pathname of the directory used by &man.hostapd.8; to store domain socket files for communication with external programs such as &man.hostapd.cli.8;. The default value is used in this example. The group allowed to access the control interface files. The wireless network name, or SSID, that will appear in wireless scans. Enable WPA and specify which WPA authentication protocol will be required. A value of 2 configures the AP for WPA2 and is recommended. Set to 1 only if the obsolete WPA is required. ASCII passphrase for WPA authentication. Always use strong passwords that are at least 8 characters long and made from a rich alphabet so that they will not be easily guessed or attacked. The key management protocol to use. This example sets WPA-PSK. Encryption algorithms accepted by the access point. In this example, only the CCMP (AES) cipher is accepted. CCMP is an alternative to TKIP and is strongly preferred when possible. TKIP should be allowed only when there are stations incapable of using CCMP. The next step is to start &man.hostapd.8;: &prompt.root; service hostapd forcestart &prompt.root; ifconfig wlan0 wlan0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 04:f0:21:16:8e:10 inet6 fe80::6f0:21ff:fe16:8e10%wlan0 prefixlen 64 scopeid 0x9 nd6 options=21<PERFORMNUD,AUTO_LINKLOCAL> media: IEEE 802.11 Wireless Ethernet autoselect mode 11na <hostap> status: running ssid No5ignal channel 36 (5180 MHz 11a ht/40+) bssid 04:f0:21:16:8e:10 country US ecm authmode WPA2/802.11i privacy MIXED deftxkey 2 AES-CCM 2:128-bit AES-CCM 3:128-bit txpower 17 mcastrate 6 mgmtrate 6 scanvalid 60 ampdulimit 64k ampdudensity 8 shortgi wme burst dtimperiod 1 -dfs groups: wlan Once the AP is running, the clients can associate with it. See for more details. It is possible to see the stations associated with the AP using ifconfig wlan0 list sta. <acronym>WEP</acronym> Host-based Access Point It is not recommended to use WEP for setting up an AP since there is no authentication mechanism and the encryption is easily cracked. Some legacy wireless cards only support WEP and these cards will only support an AP without authentication or encryption. The wireless device can now be put into hostap mode and configured with the correct SSID and IP address: &prompt.root; ifconfig wlan0 create wlandev ath0 wlanmode hostap &prompt.root; ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 \ ssid freebsdap wepmode on weptxkey 3 wepkey 3:0x3456789012 mode 11g The weptxkey indicates which WEP key will be used in the transmission. This example uses the third key as key numbering starts with 1. This parameter must be specified in order to encrypt the data. The wepkey sets the selected WEP key. It should be in the format index:key. If the index is not given, key 1 is set. The index needs to be set when using keys other than the first key. Use &man.ifconfig.8; to see the status of the wlan0 interface: &prompt.root; ifconfig wlan0 wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:11:95:c3:0d:ac inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> status: running ssid freebsdap channel 4 (2427 Mhz 11g) bssid 00:11:95:c3:0d:ac country US ecm authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs From another wireless machine, it is now possible to initiate a scan to find the AP: &prompt.root; ifconfig wlan0 create wlandev ath0 &prompt.root; ifconfig wlan0 up scan SSID BSSID CHAN RATE S:N INT CAPS freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS In this example, the client machine found the AP and can associate with it using the correct parameters. See for more details. Using Both Wired and Wireless Connections A wired connection provides better performance and reliability, while a wireless connection provides flexibility and mobility. Laptop users typically want to roam seamlessly between the two types of connections. On &os;, 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 and an example for using both wired and wireless connections is provided at . Troubleshooting This section describes a number of steps to help troubleshoot common wireless networking problems. If the access point is not listed when scanning, check that the configuration has not limited the wireless device to a limited set of channels. If the device cannot associate with an access point, verify that the configuration matches the settings on the access point. This includes the authentication scheme and any security protocols. Simplify the configuration as much as possible. If using a security protocol such as WPA or WEP, configure the access point for open authentication and no security to see if traffic will pass. Debugging support is provided by &man.wpa.supplicant.8;. Try running this utility manually with and look at the system logs. Once the system can associate with the access point, diagnose the network configuration using tools like &man.ping.8;. There are many lower-level debugging tools. Debugging messages can be enabled in the 802.11 protocol support layer using &man.wlandebug.8;. For example, to enable console messages related to scanning for access points and the 802.11 protocol handshakes required to arrange communication: &prompt.root; wlandebug -i wlan0 +scan+auth+debug+assoc net.wlan.0.debug: 0 => 0xc80000<assoc,auth,scan> Many useful statistics are maintained by the 802.11 layer and wlanstats, found in /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. USB Tethering tether Many cellphones provide the option to share their data connection over USB (often called "tethering"). This feature uses either the RNDIS, CDC or a custom &apple; &iphone;/&ipad; protocol. &android; devices generally use the &man.urndis.4; driver. &apple; devices use the &man.ipheth.4; driver. Older devices will often use the &man.cdce.4; driver. Before attaching a device, load the appropriate driver into the kernel: &prompt.root; kldload if_urndis &prompt.root; kldload if_cdce &prompt.root; kldload if_ipheth Once the device is attached ue0 will be available for use like a normal network device. Be sure that the USB tethering option is enabled on the device. Bluetooth Pav Lucistnik Written by pav@FreeBSD.org 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. This section describes the use of a USB Bluetooth dongle on a &os; system. It then describes the various Bluetooth protocols and utilities. Loading Bluetooth Support The Bluetooth stack in &os; 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: &prompt.root; kldload ng_ubt If the Bluetooth device will be attached to the system during system startup, the system can be configured to load the module at boot time by adding the driver to /boot/loader.conf: 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 /var/log/messages: ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2 ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2 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. When starting the stack, the output should be similar to the following: &prompt.root; service bluetooth start ubt0 BD_ADDR: 00:02:72:00:d4:1a Features: 0xff 0xff 0xf 00 00 00 00 00 <3-Slot> <5-Slot> <Encryption> <Slot offset> <Timing accuracy> <Switch> <Hold mode> <Sniff mode> <Park mode> <RSSI> <Channel quality> <SCO link> <HV2 packets> <HV3 packets> <u-law log> <A-law log> <CVSD> <Paging scheme> <Power control> <Transparent SCO data> Max. ACL packet size: 192 bytes Number of ACL packets: 8 Max. SCO packet size: 64 bytes Number of SCO packets: 8 Finding Other Bluetooth Devices HCI The Host Controller Interface (HCI) provides a uniform method for accessing Bluetooth baseband capabilities. In &os;, 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. &prompt.user; hccontrol -n ubt0hci inquiry Inquiry result, num_responses=1 Inquiry result #0 BD_ADDR: 00:80:37:29:19:a4 Page Scan Rep. Mode: 0x1 Page Scan Period Mode: 00 Page Scan Mode: 00 Class: 52:02:04 Clock offset: 0x78ef 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 /etc/bluetooth/hosts. The following example shows how to obtain the human readable name that was assigned to the remote device: &prompt.user; hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4 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. 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 obtain the list of active baseband connections for the local device: &prompt.user; hccontrol -n ubt0hci read_connection_list 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. &prompt.root; hccontrol -n ubt0hci disconnect 41 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. 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. The &man.hcsecd.8; daemon is responsible for handling Bluetooth authentication requests. The default configuration file is /etc/bluetooth/hcsecd.conf. An example section for a cellular phone with the PIN code set to 1234 is shown below: device { bdaddr 00:80:37:29:19:a4; name "Pav's T39"; key nokey; pin "1234"; } The only limitation on PIN codes is length. Some devices, such as Bluetooth headsets, may have a fixed PIN code built in. The 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 hcsecd.conf. Now the computer and the remote device are paired. Alternatively, pairing can be initiated on the remote device. The following line can be added to /etc/rc.conf to configure &man.hcsecd.8; to start automatically on system start: hcsecd_enable="YES" The following is a sample of the &man.hcsecd.8; daemon output: hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4 hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4 Network Access with <acronym>PPP</acronym> Profiles A Dial-Up Networking (DUN) profile can be used to configure a cellular phone as a wireless modem for connecting to a dial-up Internet access server. It can also be used to configure a computer to receive data calls from a cellular phone. Network access with a PPP profile can be used to provide LAN access for a single Bluetooth device or multiple Bluetooth devices. It can also provide PC to PC connection using PPP networking over serial cable emulation. In &os;, these profiles are implemented with &man.ppp.8; and the &man.rfcomm.pppd.8; wrapper which converts a Bluetooth connection into something PPP can use. Before a profile can be used, a new PPP label must be created in /etc/ppp/ppp.conf. Consult &man.rfcomm.pppd.8; for examples. In this example, &man.rfcomm.pppd.8; is used to open a connection to a remote device with a BD_ADDR of 00:80:37:29:19:a4 on a DUN RFCOMM channel: &prompt.root; rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup The actual channel number will be obtained from the remote device using the SDP protocol. It is possible to specify the RFCOMM channel by hand, and in this case &man.rfcomm.pppd.8; will not perform the SDP query. Use &man.sdpcontrol.8; to find out the RFCOMM channel on the remote device. In order to provide network access with the PPP LAN service, &man.sdpd.8; must be running and a new entry for LAN clients must be created in /etc/ppp/ppp.conf. Consult &man.rfcomm.pppd.8; for examples. Finally, start the RFCOMM PPP server on a valid RFCOMM channel number. The RFCOMM PPP server will automatically register the Bluetooth LAN service with the local SDP daemon. The example below shows how to start the RFCOMM PPP server. &prompt.root; rfcomm_pppd -s -C 7 -l rfcomm-server Bluetooth Protocols This section provides an overview of the various Bluetooth protocols, their function, and associated utilities. Logical Link Control and Adaptation Protocol (<acronym>L2CAP</acronym>) L2CAP The Logical Link Control and Adaptation Protocol (L2CAP) provides connection-oriented and connectionless data services to upper layer protocols. L2CAP permits higher level protocols and applications to transmit and receive L2CAP data packets up to 64 kilobytes in length. L2CAP is based around the concept of channels. A channel is a logical connection on top of a baseband connection, where each channel is bound to a single protocol in a many-to-one fashion. Multiple channels can be bound to the same protocol, but a channel cannot be bound to multiple protocols. Each L2CAP packet received on a channel is directed to the appropriate higher level protocol. Multiple channels can share the same baseband connection. In &os;, a netgraph L2CAP node is created for each Bluetooth device. This node is normally connected to the downstream Bluetooth HCI node and upstream Bluetooth socket nodes. The default name for the L2CAP node is devicel2cap. For more details refer to &man.ng.l2cap.4;. A useful command is &man.l2ping.8;, which can be used to ping other devices. Some Bluetooth implementations might not return all of the data sent to them, so 0 bytes in the following example is normal. &prompt.root; l2ping -a 00:80:37:29:19:a4 0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0 0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0 0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0 0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0 The &man.l2control.8; utility is used to perform various operations on L2CAP nodes. This example shows how to obtain the list of logical connections (channels) and the list of baseband connections for the local device: &prompt.user; l2control -a 00:02:72:00:d4:1a read_channel_list L2CAP channels: Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State 00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN &prompt.user; l2control -a 00:02:72:00:d4:1a read_connection_list L2CAP connections: Remote BD_ADDR Handle Flags Pending State 00:07:e0:00:0b:ca 41 O 0 OPEN Another diagnostic tool is &man.btsockstat.1;. It is similar to &man.netstat.1;, but for Bluetooth network-related data structures. The example below shows the same logical connection as &man.l2control.8; above. &prompt.user; btsockstat Active L2CAP sockets PCB Recv-Q Send-Q Local address/PSM Foreign address CID State c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN Active RFCOMM sessions L2PCB PCB Flag MTU Out-Q DLCs State c2afe900 c2b53380 1 127 0 Yes OPEN Active RFCOMM sockets PCB Recv-Q Send-Q Local address Foreign address Chan DLCI State c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN Radio Frequency Communication (<acronym>RFCOMM</acronym>) The RFCOMM protocol provides emulation of serial ports over the L2CAP protocol. RFCOMM is a simple transport protocol, with additional provisions for emulating the 9 circuits of RS-232 (EIATIA-232-E) serial ports. It supports up to 60 simultaneous connections (RFCOMM channels) between two Bluetooth devices. For the purposes of RFCOMM, a complete communication path involves two applications running on the communication endpoints with a communication segment between them. RFCOMM is intended to cover applications that make use of the serial ports of the devices in which they reside. The communication segment is a direct connect Bluetooth link from one device to another. RFCOMM is only concerned with the connection between the devices in the direct connect case, or between the device and a modem in the network case. RFCOMM can support other configurations, such as modules that communicate via Bluetooth wireless technology on one side and provide a wired interface on the other side. In &os;, RFCOMM is implemented at the Bluetooth sockets layer. Service Discovery Protocol (<acronym>SDP</acronym>) SDP The Service Discovery Protocol (SDP) provides the means for client applications to discover the existence of services provided by server applications as well as the attributes of those services. The attributes of a service include the type or class of service offered and the mechanism or protocol information needed to utilize the service. SDP involves communication between a SDP server and a SDP client. The server maintains a list of service records that describe the characteristics of services associated with the server. Each service record contains information about a single service. A client may retrieve information from a service record maintained by the SDP server by issuing a SDP request. If the client, or an application associated with the client, decides to use a service, it must open a separate connection to the service provider in order to utilize the service. SDP provides a mechanism for discovering services and their attributes, but it does not provide a mechanism for utilizing those services. Normally, a SDP client searches for services based on some desired characteristics of the services. However, there are times when it is desirable to discover which types of services are described by an SDP server's service records without any prior information about the services. This process of looking for any offered services is called browsing. The Bluetooth SDP server, &man.sdpd.8;, and command line client, &man.sdpcontrol.8;, are included in the standard &os; installation. The following example shows how to perform a SDP browse query. &prompt.user; sdpcontrol -a 00:01:03:fc:6e:ec browse Record Handle: 00000000 Service Class ID List: Service Discovery Server (0x1000) Protocol Descriptor List: L2CAP (0x0100) Protocol specific parameter #1: u/int/uuid16 1 Protocol specific parameter #2: u/int/uuid16 1 Record Handle: 0x00000001 Service Class ID List: Browse Group Descriptor (0x1001) Record Handle: 0x00000002 Service Class ID List: LAN Access Using PPP (0x1102) Protocol Descriptor List: L2CAP (0x0100) RFCOMM (0x0003) Protocol specific parameter #1: u/int8/bool 1 Bluetooth Profile Descriptor List: LAN Access Using PPP (0x1102) ver. 1.0 Note that each service has a list of attributes, such as the RFCOMM channel. Depending on the service, the user might need to make note of some of the attributes. Some Bluetooth implementations do not support service browsing and may return an empty list. In this case, it is possible to search for the specific service. The example below shows how to search for the OBEX Object Push (OPUSH) service: &prompt.user; sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH Offering services on &os; to Bluetooth clients is done with the &man.sdpd.8; server. The following line can be added to /etc/rc.conf: sdpd_enable="YES" Then the &man.sdpd.8; daemon can be started with: &prompt.root; service sdpd start The local server application that wants to provide a Bluetooth service to remote clients will register the service with the local SDP daemon. An example of such an application is &man.rfcomm.pppd.8;. Once started, it will register the Bluetooth LAN service with the local SDP daemon. The list of services registered with the local SDP server can be obtained by issuing a SDP browse query via the local control channel: &prompt.root; sdpcontrol -l browse <acronym>OBEX</acronym> Object Push (<acronym>OPUSH</acronym>) OBEX Object Exchange (OBEX) is a widely used protocol for simple file transfers between mobile devices. Its main use is in infrared communication, where it is used for generic file transfers between notebooks or PDAs, and for sending business cards or calendar entries between cellular phones and other devices with Personal Information Manager (PIM) applications. The OBEX server and client are implemented by obexapp, which can be installed using the comms/obexapp package or port. The OBEX client is used to push and/or pull objects from the OBEX server. An example object is a business card or an appointment. The OBEX client can obtain the RFCOMM channel number from the remote device via SDP. This can be done by specifying the service name instead of the RFCOMM channel number. Supported service names are: IrMC, FTRN, and OPUSH. It is also possible to specify the RFCOMM channel as a number. Below is an example of an OBEX session where the device information object is pulled from the cellular phone, and a new object, the business card, is pushed into the phone's directory. &prompt.user; obexapp -a 00:80:37:29:19:a4 -C IrMC obex> get telecom/devinfo.txt devinfo-t39.txt Success, response: OK, Success (0x20) obex> put new.vcf Success, response: OK, Success (0x20) obex> di Success, response: OK, Success (0x20) In order to provide the OPUSH service, &man.sdpd.8; must be running and a root folder, where all incoming objects will be stored, must be created. The default path to the root folder is /var/spool/obex. Finally, start the OBEX server on a valid RFCOMM channel number. The OBEX server will automatically register the OPUSH service with the local SDP daemon. The example below shows how to start the OBEX server. &prompt.root; obexapp -s -C 10 Serial Port Profile (<acronym>SPP</acronym>) The Serial Port Profile (SPP) allows Bluetooth devices to perform serial cable emulation. This profile allows legacy applications to use Bluetooth as a cable replacement, through a virtual serial port abstraction. In &os;, &man.rfcomm.sppd.1; implements SPP and a pseudo tty is used as a virtual serial port abstraction. The example below shows how to connect to a remote device's serial port service. A RFCOMM channel does not have to be specified as &man.rfcomm.sppd.1; can obtain it from the remote device via SDP. To override this, specify a RFCOMM channel on the command line. &prompt.root; rfcomm_sppd -a 00:07:E0:00:0B:CA -t rfcomm_sppd[94692]: Starting on /dev/pts/6... /dev/pts/6 Once connected, the pseudo tty can be used as serial port: &prompt.root; cu -l /dev/pts/6 The pseudo tty is printed on stdout and can be read by wrapper scripts: PTS=`rfcomm_sppd -a 00:07:E0:00:0B:CA -t` cu -l $PTS Troubleshooting By default, when &os; is accepting a new connection, it tries to perform a role switch and become master. Some older Bluetooth devices which do not support role switching will not be able to connect. Since role switching is performed when a new connection is being established, it is not possible to ask the remote device if it supports role switching. However, there is a HCI option to disable role switching on the local side: &prompt.root; hccontrol -n ubt0hci write_node_role_switch 0 To display Bluetooth packets, use the third-party package hcidump, which can be installed using the comms/hcidump package or port. This utility is similar to &man.tcpdump.1; and can be used to display the contents of Bluetooth packets on the terminal and to dump the Bluetooth packets to a file. Bridging Andrew Thompson Written by IP subnet bridge It is sometimes useful to divide a network, such as an Ethernet segment, into network segments without having to create IP subnets and use a router to connect the segments together. A device that connects two networks together in this fashion is called a bridge. A bridge works by learning the MAC addresses of the devices on each of its network interfaces. It forwards traffic between networks only when the source and destination MAC addresses are on different networks. In many respects, a bridge is like an Ethernet switch with very few ports. A &os; system with multiple network interfaces can be configured to act as a bridge. Bridging can be useful in the following situations: Connecting Networks The basic operation of a bridge is to join two or more network segments. There are many reasons to use a host-based bridge instead of networking equipment, such as cabling constraints or firewalling. A bridge can also connect a wireless interface running in hostap mode to a wired network and act as an access point. Filtering/Traffic Shaping Firewall A bridge can be used when firewall functionality is needed without routing or Network Address Translation (NAT). An example is a small company that is connected via DSL or ISDN to an ISP. There are thirteen public IP addresses from the ISP and ten computers on the network. In this situation, using a router-based firewall is difficult because of subnetting issues. A bridge-based firewall can be configured without any IP addressing issues. Network Tap A bridge can join two network segments in order to inspect all Ethernet frames that pass between them using &man.bpf.4; and &man.tcpdump.1; on the bridge interface or by sending a copy of all frames out an additional interface known as a span port. Layer 2 VPN Two Ethernet networks can be joined across an IP link by bridging the networks to an EtherIP tunnel or a &man.tap.4; based solution such as OpenVPN. Layer 2 Redundancy A network can be connected together with multiple links and use the Spanning Tree Protocol (STP) to block redundant paths. This section describes how to configure a &os; system as a bridge using &man.if.bridge.4;. A netgraph bridging driver is also available, and is described in &man.ng.bridge.4;. Packet filtering can be used with any firewall package that hooks into the &man.pfil.9; framework. The bridge can be used as a traffic shaper with &man.altq.4; or &man.dummynet.4;. Enabling the Bridge In &os;, &man.if.bridge.4; is a kernel module which is automatically loaded by &man.ifconfig.8; when creating a bridge interface. It is also possible to compile bridge support into a custom kernel by adding device if_bridge to the custom kernel configuration file. The bridge is created using interface cloning. To create the bridge interface: &prompt.root; ifconfig bridge create bridge0 &prompt.root; ifconfig bridge0 bridge0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 96:3d:4b:f1:79:7a id 00:00:00:00:00:00 priority 32768 hellotime 2 fwddelay 15 maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 root id 00:00:00:00:00:00 priority 0 ifcost 0 port 0 When a bridge interface is created, it is automatically assigned a randomly generated Ethernet address. The maxaddr and timeout parameters control how many MAC addresses the bridge will keep in its forwarding table and how many seconds before each entry is removed after it is last seen. The other parameters control how STP operates. Next, specify which network interfaces to add as members of the bridge. For the bridge to forward packets, all member interfaces and the bridge need to be up: &prompt.root; ifconfig bridge0 addm fxp0 addm fxp1 up &prompt.root; ifconfig fxp0 up &prompt.root; ifconfig fxp1 up The bridge can now forward Ethernet frames between fxp0 and fxp1. Add the following lines to /etc/rc.conf so the bridge is created at startup: cloned_interfaces="bridge0" ifconfig_bridge0="addm fxp0 addm fxp1 up" ifconfig_fxp0="up" ifconfig_fxp1="up" If the bridge host needs an IP address, set it on the bridge interface, not on the member interfaces. The address can be set statically or via DHCP. This example sets a static IP address: &prompt.root; ifconfig bridge0 inet 192.168.0.1/24 It is also possible to assign an IPv6 address to a bridge interface. To make the changes permanent, add the addressing information to /etc/rc.conf. When packet filtering is enabled, bridged packets will pass through the filter inbound on the originating interface on the bridge interface, and outbound on the appropriate interfaces. Either stage can be disabled. When direction of the packet flow is important, it is best to firewall on the member interfaces rather than the bridge itself. The bridge has several configurable settings for passing non-IP and IP packets, and layer2 firewalling with &man.ipfw.8;. See &man.if.bridge.4; for more information. Enabling Spanning Tree For an Ethernet network to function properly, only one active path can exist between two devices. The STP protocol detects loops and puts redundant links into a blocked state. Should one of the active links fail, STP calculates a different tree and enables one of the blocked paths to restore connectivity to all points in the network. The Rapid Spanning Tree Protocol (RSTP or 802.1w) provides backwards compatibility with legacy STP. RSTP provides faster convergence and exchanges information with neighboring switches to quickly transition to forwarding mode without creating loops. &os; supports RSTP and STP as operating modes, with RSTP being the default mode. STP can be enabled on member interfaces using &man.ifconfig.8;. For a bridge with fxp0 and fxp1 as the current interfaces, enable STP with: &prompt.root; ifconfig bridge0 stp fxp0 stp fxp1 bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether d6:cf:d5:a0:94:6d id 00:01:02:4b:d4:50 priority 32768 hellotime 2 fwddelay 15 maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 root id 00:01:02:4b:d4:50 priority 32768 ifcost 0 port 0 member: fxp0 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> port 3 priority 128 path cost 200000 proto rstp role designated state forwarding member: fxp1 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> port 4 priority 128 path cost 200000 proto rstp role designated state forwarding This bridge has a spanning tree ID of 00:01:02:4b:d4:50 and a priority of 32768. As the root id is the same, it indicates that this is the root bridge for the tree. Another bridge on the network also has STP enabled: bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 96:3d:4b:f1:79:7a id 00:13:d4:9a:06:7a priority 32768 hellotime 2 fwddelay 15 maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 root id 00:01:02:4b:d4:50 priority 32768 ifcost 400000 port 4 member: fxp0 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> port 4 priority 128 path cost 200000 proto rstp role root state forwarding member: fxp1 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> port 5 priority 128 path cost 200000 proto rstp role designated state forwarding The line root id 00:01:02:4b:d4:50 priority 32768 ifcost 400000 port 4 shows that the root bridge is 00:01:02:4b:d4:50 and has a path cost of 400000 from this bridge. The path to the root bridge is via port 4 which is fxp0. Bridge Interface Parameters Several ifconfig parameters are unique to bridge interfaces. This section summarizes some common uses for these parameters. The complete list of available parameters is described in &man.ifconfig.8;. private A private interface does not forward any traffic to any other port that is also designated as a private interface. The traffic is blocked unconditionally so no Ethernet frames will be forwarded, including ARP packets. If traffic needs to be selectively blocked, a firewall should be used instead. span A span port transmits a copy of every Ethernet frame received by the bridge. The number of span ports configured on a bridge is unlimited, but if an interface is designated as a span port, it cannot also be used as a regular bridge port. This is most useful for snooping a bridged network passively on another host connected to one of the span ports of the bridge. For example, to send a copy of all frames out the interface named fxp4: &prompt.root; ifconfig bridge0 span fxp4 sticky If a bridge member interface is marked as sticky, dynamically learned address entries are treated as static entries in the forwarding cache. Sticky entries are never aged out of the cache or replaced, even if the address is seen on a different interface. This gives the benefit of static address entries without the need to pre-populate the forwarding table. Clients learned on a particular segment of the bridge cannot roam to another segment. An example of using sticky addresses is to combine the bridge with VLANs in order to isolate customer networks without wasting IP address space. Consider that CustomerA is on vlan100, CustomerB is on vlan101, and the bridge has the address 192.168.0.1: &prompt.root; ifconfig bridge0 addm vlan100 sticky vlan100 addm vlan101 sticky vlan101 &prompt.root; ifconfig bridge0 inet 192.168.0.1/24 In this example, both clients see 192.168.0.1 as their default gateway. Since the bridge cache is sticky, one host cannot spoof the MAC address of the other customer in order to intercept their traffic. Any communication between the VLANs can be blocked using a firewall or, as seen in this example, private interfaces: &prompt.root; ifconfig bridge0 private vlan100 private vlan101 The customers are completely isolated from each other and the full /24 address range can be allocated without subnetting. The number of unique source MAC addresses behind an interface can be limited. Once the limit is reached, packets with unknown source addresses are dropped until an existing host cache entry expires or is removed. The following example sets the maximum number of Ethernet devices for CustomerA on vlan100 to 10: &prompt.root; ifconfig bridge0 ifmaxaddr vlan100 10 Bridge interfaces also support monitor mode, where the packets are discarded after &man.bpf.4; processing and are not processed or forwarded further. This can be used to multiplex the input of two or more interfaces into a single &man.bpf.4; stream. This is useful for reconstructing the traffic for network taps that transmit the RX/TX signals out through two separate interfaces. For example, to read the input from four network interfaces as one stream: &prompt.root; ifconfig bridge0 addm fxp0 addm fxp1 addm fxp2 addm fxp3 monitor up &prompt.root; tcpdump -i bridge0 <acronym>SNMP</acronym> Monitoring The bridge interface and STP parameters can be monitored via &man.bsnmpd.1; which is included in the &os; base system. The exported bridge MIBs conform to IETF standards so any SNMP client or monitoring package can be used to retrieve the data. To enable monitoring on the bridge, uncomment this line in /etc/snmpd.config by removing the beginning # symbol: begemotSnmpdModulePath."bridge" = "/usr/lib/snmp_bridge.so" Other configuration settings, such as community names and access lists, may need to be modified in this file. See &man.bsnmpd.1; and &man.snmp.bridge.3; for more information. Once these edits are saved, add this line to /etc/rc.conf: bsnmpd_enable="YES" Then, start &man.bsnmpd.1;: &prompt.root; service bsnmpd start The following examples use the Net-SNMP software (net-mgmt/net-snmp) to query a bridge from a client system. The net-mgmt/bsnmptools port can also be used. From the SNMP client which is running Net-SNMP, add the following lines to $HOME/.snmp/snmp.conf in order to import the bridge MIB definitions: mibdirs +/usr/share/snmp/mibs mibs +BRIDGE-MIB:RSTP-MIB:BEGEMOT-MIB:BEGEMOT-BRIDGE-MIB To monitor a single bridge using the IETF BRIDGE-MIB (RFC4188): &prompt.user; snmpwalk -v 2c -c public bridge1.example.com mib-2.dot1dBridge BRIDGE-MIB::dot1dBaseBridgeAddress.0 = STRING: 66:fb:9b:6e:5c:44 BRIDGE-MIB::dot1dBaseNumPorts.0 = INTEGER: 1 ports BRIDGE-MIB::dot1dStpTimeSinceTopologyChange.0 = Timeticks: (189959) 0:31:39.59 centi-seconds BRIDGE-MIB::dot1dStpTopChanges.0 = Counter32: 2 BRIDGE-MIB::dot1dStpDesignatedRoot.0 = Hex-STRING: 80 00 00 01 02 4B D4 50 ... BRIDGE-MIB::dot1dStpPortState.3 = INTEGER: forwarding(5) BRIDGE-MIB::dot1dStpPortEnable.3 = INTEGER: enabled(1) BRIDGE-MIB::dot1dStpPortPathCost.3 = INTEGER: 200000 BRIDGE-MIB::dot1dStpPortDesignatedRoot.3 = Hex-STRING: 80 00 00 01 02 4B D4 50 BRIDGE-MIB::dot1dStpPortDesignatedCost.3 = INTEGER: 0 BRIDGE-MIB::dot1dStpPortDesignatedBridge.3 = Hex-STRING: 80 00 00 01 02 4B D4 50 BRIDGE-MIB::dot1dStpPortDesignatedPort.3 = Hex-STRING: 03 80 BRIDGE-MIB::dot1dStpPortForwardTransitions.3 = Counter32: 1 RSTP-MIB::dot1dStpVersion.0 = INTEGER: rstp(2) The dot1dStpTopChanges.0 value is two, indicating that the STP bridge topology has changed twice. A topology change means that one or more links in the network have changed or failed and a new tree has been calculated. The dot1dStpTimeSinceTopologyChange.0 value will show when this happened. To monitor multiple bridge interfaces, the private BEGEMOT-BRIDGE-MIB can be used: &prompt.user; snmpwalk -v 2c -c public bridge1.example.com enterprises.fokus.begemot.begemotBridge BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge0" = STRING: bridge0 BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge2" = STRING: bridge2 BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge0" = STRING: e:ce:3b:5a:9e:13 BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge2" = STRING: 12:5e:4d:74:d:fc BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge0" = INTEGER: 1 BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge2" = INTEGER: 1 ... BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge0" = Timeticks: (116927) 0:19:29.27 centi-seconds BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge2" = Timeticks: (82773) 0:13:47.73 centi-seconds BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge0" = Counter32: 1 BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge2" = Counter32: 1 BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge0" = Hex-STRING: 80 00 00 40 95 30 5E 31 BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge2" = Hex-STRING: 80 00 00 50 8B B8 C6 A9 To change the bridge interface being monitored via the mib-2.dot1dBridge subtree: &prompt.user; snmpset -v 2c -c private bridge1.example.com BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2 Link Aggregation and Failover Andrew Thompson Written by lagg failover FEC LACP loadbalance roundrobin &os; provides the &man.lagg.4; interface which can be used to aggregate multiple network interfaces into one virtual interface in order to provide failover and link aggregation. Failover allows traffic to continue to flow as long as at least one aggregated network interface has an established link. Link aggregation works best on switches which support LACP, as this protocol distributes traffic bi-directionally while responding to the failure of individual links. The aggregation protocols supported by the lagg interface determine which ports are used for outgoing traffic and whether or not a specific port accepts incoming traffic. The following protocols are supported by &man.lagg.4;: failover This mode sends and receives traffic only through the master port. If the master port becomes unavailable, the next active port is used. The first interface added to the virtual interface is the master port and all subsequently added interfaces are used as failover devices. If failover to a non-master port occurs, the original port becomes master once it becomes available again. fec / loadbalance &cisco; Fast ðerchannel; (FEC) is found on older &cisco; switches. It provides a static setup and does not negotiate aggregation with the peer or exchange frames to monitor the link. If the switch supports LACP, that should be used instead. lacp The &ieee; 802.3ad Link Aggregation Control Protocol (LACP) negotiates a set of aggregable links with the peer into one or more Link Aggregated Groups (LAGs). Each LAG is composed of ports of the same speed, set to full-duplex operation, and traffic is balanced across the ports in the LAG with the greatest total speed. Typically, there is only one LAG which contains all the ports. In the event of changes in physical connectivity, LACP will quickly converge to a new configuration. LACP balances outgoing traffic across the active ports based on hashed protocol header information and accepts incoming traffic from any active port. The hash includes the Ethernet source and destination address and, if available, the VLAN tag, and the IPv4 or IPv6 source and destination address. roundrobin This mode distributes outgoing traffic using a round-robin scheduler through all active ports and accepts incoming traffic from any active port. Since this mode violates Ethernet frame ordering, it should be used with caution. Configuration Examples This section demonstrates how to configure a &cisco; switch and a &os; system for LACP load balancing. It then shows how to configure two Ethernet interfaces in failover mode as well as how to configure failover mode between an Ethernet and a wireless interface. <acronym>LACP</acronym> Aggregation with a &cisco; Switch This example connects two &man.fxp.4; Ethernet interfaces on a &os; machine to the first two Ethernet ports on a &cisco; switch as a single load balanced and fault tolerant link. More interfaces can be added to increase throughput and fault tolerance. Replace the names of the &cisco; ports, Ethernet devices, channel group number, and IP address shown in the example to match the local configuration. Frame ordering is mandatory on Ethernet links and any traffic between two stations always flows over the same physical link, limiting the maximum speed to that of one interface. The transmit algorithm attempts to use as much information as it can to distinguish different traffic flows and balance the flows across the available interfaces. On the &cisco; switch, add the FastEthernet0/1 and FastEthernet0/2 interfaces to channel group 1: interface FastEthernet0/1 channel-group 1 mode active channel-protocol lacp ! interface FastEthernet0/2 channel-group 1 mode active channel-protocol lacp On the &os; system, create the &man.lagg.4; interface using the physical interfaces fxp0 and fxp1 and bring the interfaces up with an IP address of 10.0.0.3/24: &prompt.root; ifconfig fxp0 up &prompt.root; ifconfig fxp1 up &prompt.root; ifconfig lagg0 create &prompt.root; ifconfig lagg0 up laggproto lacp laggport fxp0 laggport fxp1 10.0.0.3/24 Next, verify the status of the virtual interface: &prompt.root; ifconfig lagg0 lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 options=8<VLAN_MTU> ether 00:05:5d:71:8d:b8 media: Ethernet autoselect status: active laggproto lacp laggport: fxp1 flags=1c<ACTIVE,COLLECTING,DISTRIBUTING> laggport: fxp0 flags=1c<ACTIVE,COLLECTING,DISTRIBUTING> Ports marked as ACTIVE are part of the LAG that has been negotiated with the remote switch. Traffic will be transmitted and received through these active ports. Add to the above command to view the LAG identifiers. To see the port status on the &cisco; switch: switch# show lacp neighbor Flags: S - Device is requesting Slow LACPDUs F - Device is requesting Fast LACPDUs A - Device is in Active mode P - Device is in Passive mode Channel group 1 neighbors Partner's information: LACP port Oper Port Port Port Flags Priority Dev ID Age Key Number State Fa0/1 SA 32768 0005.5d71.8db8 29s 0x146 0x3 0x3D Fa0/2 SA 32768 0005.5d71.8db8 29s 0x146 0x4 0x3D For more detail, type show lacp neighbor detail. To retain this configuration across reboots, add the following entries to /etc/rc.conf on the &os; system: ifconfig_fxp0="up" ifconfig_fxp1="up" cloned_interfaces="lagg0" ifconfig_lagg0="laggproto lacp laggport fxp0 laggport fxp1 10.0.0.3/24" Failover Mode Failover mode can be used to switch over to a secondary interface if the link is lost on the master interface. To configure failover, make sure that the underlying physical interfaces are up, then create the &man.lagg.4; interface. In this example, fxp0 is the master interface, fxp1 is the secondary interface, and the virtual interface is assigned an IP address of 10.0.0.15/24: &prompt.root; ifconfig fxp0 up &prompt.root; ifconfig fxp1 up &prompt.root; ifconfig lagg0 create &prompt.root; ifconfig lagg0 up laggproto failover laggport fxp0 laggport fxp1 10.0.0.15/24 The virtual interface should look something like this: &prompt.root; ifconfig lagg0 lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 options=8<VLAN_MTU> ether 00:05:5d:71:8d:b8 inet 10.0.0.15 netmask 0xffffff00 broadcast 10.0.0.255 media: Ethernet autoselect status: active laggproto failover laggport: fxp1 flags=0<> laggport: fxp0 flags=5<MASTER,ACTIVE> Traffic will be transmitted and received on fxp0. If the link is lost on fxp0, fxp1 will become the active link. If the link is restored on the master interface, it will once again become the active link. To retain this configuration across reboots, add the following entries to /etc/rc.conf: ifconfig_fxp0="up" ifconfig_fxp1="up" cloned_interfaces="lagg0" ifconfig_lagg0="laggproto failover laggport fxp0 laggport fxp1 10.0.0.15/24" Failover Mode Between Ethernet and Wireless Interfaces For laptop users, it is usually desirable to configure the wireless device as a secondary which is only used when the Ethernet connection is not available. With &man.lagg.4;, it is possible to configure a failover which prefers the Ethernet connection for both performance and security reasons, while maintaining the ability to transfer data over the wireless connection. This is achieved by overriding the physical wireless interface's MAC address with that of the Ethernet interface. In this example, the Ethernet interface, bge0, is the master and the wireless interface, wlan0, is the failover. The wlan0 device was created from iwn0 wireless interface, which will be configured with the MAC address of the Ethernet interface. First, determine the MAC address of the Ethernet interface: &prompt.root; ifconfig bge0 bge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 options=19b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,TSO4> ether 00:21:70:da:ae:37 inet6 fe80::221:70ff:feda:ae37%bge0 prefixlen 64 scopeid 0x2 nd6 options=29<PERFORMNUD,IFDISABLED,AUTO_LINKLOCAL> media: Ethernet autoselect (1000baseT <full-duplex>) status: active Replace bge0 to match the system's Ethernet interface name. The ether line will contain the MAC address of the specified interface. Now, change the MAC address of the underlying wireless interface: &prompt.root; ifconfig iwn0 ether 00:21:70:da:ae:37 Bring the wireless interface up, but do not set an IP address: &prompt.root; ifconfig wlan0 create wlandev iwn0 ssid my_router up Make sure the bge0 interface is up, then create the &man.lagg.4; interface with bge0 as master with failover to wlan0: &prompt.root; ifconfig bge0 up &prompt.root; ifconfig lagg0 create &prompt.root; ifconfig lagg0 up laggproto failover laggport bge0 laggport wlan0 The virtual interface should look something like this: &prompt.root; ifconfig lagg0 lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 options=8<VLAN_MTU> ether 00:21:70:da:ae:37 media: Ethernet autoselect status: active laggproto failover laggport: wlan0 flags=0<> laggport: bge0 flags=5<MASTER,ACTIVE> Then, start the DHCP client to obtain an IP address: &prompt.root; dhclient lagg0 To retain this configuration across reboots, add the following entries to /etc/rc.conf: ifconfig_bge0="up" wlans_iwn0="wlan0" ifconfig_wlan0="WPA" create_args_wlan0="wlanaddr 00:21:70:da:ae:37" cloned_interfaces="lagg0" ifconfig_lagg0="up laggproto failover laggport bge0 laggport wlan0 DHCP" Diskless Operation with <acronym>PXE</acronym> Jean-François Dockès Updated by Alex Dupre Reorganized and enhanced by diskless workstation diskless operation The &intel; Preboot eXecution Environment (PXE) allows an operating system to boot over the network. For example, a &os; system can boot over the network and operate without a local disk, using file systems mounted from an NFS server. PXE support is usually available in the BIOS. To use PXE when the machine starts, select the Boot from network option in the BIOS setup or type a function key during system initialization. In order to provide the files needed for an operating system to boot over the network, a PXE setup also requires properly configured DHCP, TFTP, and NFS servers, where: Initial parameters, such as an IP address, executable boot filename and location, server name, and root path are obtained from the DHCP server. The operating system loader file is booted using TFTP. The file systems are loaded using NFS. When a computer PXE boots, it receives information over DHCP about where to obtain the initial boot loader file. After the host computer receives this information, it downloads the boot loader via TFTP and then executes the boot loader. In &os;, the boot loader file is /boot/pxeboot. After /boot/pxeboot executes, the &os; kernel is loaded and the rest of the &os; bootup sequence proceeds, as described in . This section describes how to configure these services on a &os; system so that other systems can PXE boot into &os;. Refer to &man.diskless.8; for more information. As described, the system providing these services is insecure. It should live in a protected area of a network and be untrusted by other hosts. Setting Up the <acronym>PXE</acronym> Environment Craig Rodrigues
rodrigc@FreeBSD.org
 Written by The steps shown in this section configure the built-in NFS and TFTP servers. The next section demonstrates how to install and configure the DHCP server. In this example, the directory which will contain the files used by PXE users is /b/tftpboot/FreeBSD/install. It is important that this directory exists and that the same directory name is set in both /etc/inetd.conf and /usr/local/etc/dhcpd.conf. Create the root directory which will contain a &os; installation to be NFS mounted: &prompt.root; export NFSROOTDIR=/b/tftpboot/FreeBSD/install &prompt.root; mkdir -p ${NFSROOTDIR} Enable the NFS server by adding this line to /etc/rc.conf: nfs_server_enable="YES" Export the diskless root directory via NFS by adding the following to /etc/exports: /b -ro -alldirs Start the NFS server: &prompt.root; service nfsd start Enable &man.inetd.8; by adding the following line to /etc/rc.conf: inetd_enable="YES" Uncomment the following line in /etc/inetd.conf by making sure it does not start with a # symbol: tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /b/tftpboot Some PXE versions require the TCP version of TFTP. In this case, uncomment the second tftp line which contains stream tcp. Start &man.inetd.8;: &prompt.root; service inetd start Rebuild the &os; kernel and userland (refer to for more detailed instructions): &prompt.root; cd /usr/src &prompt.root; make buildworld &prompt.root; make buildkernel Install &os; into the directory mounted over NFS: &prompt.root; make installworld DESTDIR=${NFSROOTDIR} &prompt.root; make installkernel DESTDIR=${NFSROOTDIR} &prompt.root; make distribution DESTDIR=${NFSROOTDIR} Test that the TFTP server works and can download the boot loader which will be obtained via PXE: &prompt.root; tftp localhost tftp> get FreeBSD/install/boot/pxeboot Received 264951 bytes in 0.1 seconds Edit ${NFSROOTDIR}/etc/fstab and create an entry to mount the root file system over NFS: # Device Mountpoint FSType Options Dump Pass myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro 0 0 Replace myhost.example.com with the hostname or IP address of the NFS server. In this example, the root file system is mounted read-only in order to prevent NFS clients from potentially deleting the contents of the root file system. Set the root password in the PXE environment for client machines which are PXE booting : &prompt.root; chroot ${NFSROOTDIR} &prompt.root; passwd If needed, enable &man.ssh.1; root logins for client machines which are PXE booting by editing ${NFSROOTDIR}/etc/ssh/sshd_config and enabling PermitRootLogin. This option is documented in &man.sshd.config.5;. Perform any other needed customizations of the PXE environment in ${NFSROOTDIR}. These customizations could include things like installing packages or editing the password file with &man.vipw.8;. When booting from an NFS root volume, /etc/rc detects the NFS boot and runs /etc/rc.initdiskless. In this case, /etc and /var need to be memory backed file systems so that these directories are writable but the NFS root directory is read-only: &prompt.root; chroot ${NFSROOTDIR} &prompt.root; mkdir -p conf/base &prompt.root; tar -c -v -f conf/base/etc.cpio.gz --format cpio --gzip etc &prompt.root; tar -c -v -f conf/base/var.cpio.gz --format cpio --gzip var When the system boots, memory file systems for /etc and /var will be created and mounted and the contents of the cpio.gz files will be copied into them. Configuring the <acronym>DHCP</acronym> Server DHCP diskless operation The DHCP server does not need to be the same machine as the TFTP and NFS server, but it needs to be accessible in the network. DHCP is not part of the &os; base system but can be installed using the net/isc-dhcp43-server port or package. Once installed, edit the configuration file, /usr/local/etc/dhcpd.conf. Configure the next-server, filename, and root-path settings as seen in this example: subnet 192.168.0.0 netmask 255.255.255.0 { range 192.168.0.2 192.168.0.3 ; option subnet-mask 255.255.255.0 ; option routers 192.168.0.1 ; option broadcast-address 192.168.0.255 ; option domain-name-servers 192.168.35.35, 192.168.35.36 ; option domain-name "example.com"; # IP address of TFTP server next-server 192.168.0.1 ; # path of boot loader obtained via tftp filename "FreeBSD/install/boot/pxeboot" ; # pxeboot boot loader will try to NFS mount this directory for root FS option root-path "192.168.0.1:/b/tftpboot/FreeBSD/install/" ; } The next-server directive is used to specify the IP address of the TFTP server. The filename directive defines the path to /boot/pxeboot. A relative filename is used, meaning that /b/tftpboot is not included in the path. The root-path option defines the path to the NFS root file system. Once the edits are saved, enable DHCP at boot time by adding the following line to /etc/rc.conf: dhcpd_enable="YES" Then start the DHCP service: &prompt.root; service isc-dhcpd start Debugging <acronym>PXE</acronym> Problems Once all of the services are configured and started, PXE clients should be able to automatically load &os; over the network. If a particular client is unable to connect, when that client machine boots up, enter the BIOS configuration menu and confirm that it is set to boot from the network. This section describes some troubleshooting tips for isolating the source of the configuration problem should no clients be able to PXE boot. Use the net/wireshark package or port to debug the network traffic involved during the PXE booting process, which is illustrated in the diagram below.
<acronym>PXE</acronym> Booting Process with <acronym>NFS</acronym> Root Mount Client broadcasts a DHCPDISCOVER message. The DHCP server responds with the IP address, next-server, filename, and root-path values. The client sends a TFTP request to next-server, asking to retrieve filename. The TFTP server responds and sends filename to client. The client executes filename, which is &man.pxeboot.8;, which then loads the kernel. When the kernel executes, the root file system specified by root-path is mounted over NFS.
On the TFTP server, read /var/log/xferlog to ensure that pxeboot is being retrieved from the correct location. To test this example configuration: &prompt.root; tftp 192.168.0.1 tftp> get FreeBSD/install/boot/pxeboot Received 264951 bytes in 0.1 seconds The BUGS sections in &man.tftpd.8; and &man.tftp.1; document some limitations with TFTP. Make sure that the root file system can be mounted via NFS. To test this example configuration: &prompt.root; mount -t nfs 192.168.0.1:/b/tftpboot/FreeBSD/install /mnt <acronym>IPv6</acronym> Aaron Kaplan Originally Written by Tom Rhodes Restructured and Added by Brad Davis Extended by 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 (RFC2462). Mandatory multicast addresses. Built-in IPsec (IP security). Simplified header structure. Support for mobile IP. IPv6-to-IPv4 transition mechanisms. &os; includes the http://www.kame.net/ IPv6 reference implementation and comes with everything needed to use IPv6. This section focuses on getting IPv6 configured and running. Background on <acronym>IPv6</acronym> Addresses There are three different types of IPv6 addresses: Unicast A packet sent to a unicast address arrives at the interface belonging to the address. Anycast These addresses are syntactically indistinguishable from unicast addresses but they address a group of interfaces. The packet destined for an anycast address will arrive at the nearest router interface. Anycast addresses are only used by routers. Multicast These addresses identify a group of interfaces. A packet destined for a multicast address will arrive at all interfaces belonging to the multicast group. The IPv4 broadcast address, usually xxx.xxx.xxx.255, is expressed by multicast addresses in IPv6. When reading an IPv6 address, the canonical form is represented as x:x:x:x:x:x:x:x, where each x represents a 16 bit hex value. An example is FEBC:A574:382B:23C1:AA49:4592:4EFE:9982. Often, an address will have long substrings of all zeros. A :: (double colon) can be used to replace one substring per address. Also, up to three leading 0s 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 &os; system's IPv6 address, use &man.ifconfig.8;: &prompt.root; ifconfig rl0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500 inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255 inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1 ether 00:00:21:03:08:e1 media: Ethernet autoselect (100baseTX ) status: active In this example, the rl0 interface is using fe80::200:21ff:fe03:8e1%rl0, an auto-configured link-local address which was automatically generated from the MAC address. Some IPv6 addresses are reserved. A summary of these reserved addresses is seen in : Reserved <acronym>IPv6</acronym> Addresses 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 RFC3513. Configuring <acronym>IPv6</acronym> To configure a &os; system as an IPv6 client, add these two lines to rc.conf: ifconfig_rl0_ipv6="inet6 accept_rtadv" rtsold_enable="YES" The first line enables the specified interface to receive router solicitation messages. The second line enables the router solicitation daemon, &man.rtsol.8;. If the interface needs a statically assigned IPv6 address, add an entry to specify the static address and associated prefix length: ifconfig_rl0_ipv6="inet6 2001:db8:4672:6565:2026:5043:2d42:5344 prefixlen 64" To assign a default router, specify its address: ipv6_defaultrouter="2001:db8:4672:6565::1" Connecting to a Provider In order to connect to other IPv6 networks, one must have a provider or a tunnel that supports IPv6: Contact an Internet Service Provider to see if they offer IPv6. Hurricane Electric offers tunnels with end-points all around the globe. Install the net/freenet6 package or port for a dial-up connection. This section demonstrates how to take the directions from a tunnel provider and convert them into /etc/rc.conf settings that will persist through reboots. The first /etc/rc.conf entry creates the generic tunneling interface gif0: cloned_interfaces="gif0" Next, configure that interface with the IPv4 addresses of the local and remote endpoints. Replace MY_IPv4_ADDR and REMOTE_IPv4_ADDR with the actual IPv4 addresses: create_args_gif0="tunnel MY_IPv4_ADDR REMOTE_IPv4_ADDR" To apply the IPv6 address that has been assigned for use as the IPv6 tunnel endpoint, add this line, replacing MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR with the assigned address: ifconfig_gif0_ipv6="inet6 MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR" Then, set the default route for the other side of the IPv6 tunnel. Replace MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR with the default gateway address assigned by the provider: ipv6_defaultrouter="MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR" If the &os; system will route IPv6 packets between the rest of the network and the world, enable the gateway using this line: ipv6_gateway_enable="YES" Router Advertisement and Host Auto Configuration This section demonstrates how to setup &man.rtadvd.8; to advertise the IPv6 default route. To enable &man.rtadvd.8;, add the following to /etc/rc.conf: rtadvd_enable="YES" It is important to specify the interface on which to do IPv6 router solicitation. For example, to tell &man.rtadvd.8; to use rl0: rtadvd_interfaces="rl0" Next, create the configuration file, /etc/rtadvd.conf as seen in this example: rl0:\ :addrs#1:addr="2001:db8:1f11:246::":prefixlen#64:tc=ether: Replace rl0 with the interface to be used and 2001:db8:1f11:246:: with the prefix of the allocation. For a dedicated /64 subnet, nothing else needs to be changed. Otherwise, change the prefixlen# to the correct value. <acronym>IPv6</acronym> and <acronym>IPv6</acronym> Address Mapping When IPv6 is enabled on a server, there may be a need to enable IPv4 mapped IPv6 address communication. This compatibility option allows for IPv4 addresses to be represented as IPv6 addresses. Permitting IPv6 applications to communicate with IPv4 and vice versa may be a security issue. This option may not be required in most cases and is available only for compatibility. This option will allow IPv6-only applications to work with IPv4 in a dual stack environment. This is most useful for third party applications which may not support an IPv6-only environment. To enable this feature, add the following to /etc/rc.conf: ipv6_ipv4mapping="YES" Reviewing the information in RFC 3493, section 3.6 and 3.7 as well as RFC 4038 section 4.2 may be useful to some administrators. Common Address Redundancy Protocol (<acronym>CARP</acronym>) Tom Rhodes Contributed by Allan Jude Updated by CARP Common Address Redundancy Protocol The Common Address Redundancy Protocol (CARP) allows multiple hosts to share the same IP address and Virtual Host ID (VHID) in order to provide high availability for one or more services. This means that one or more hosts can fail, and the other hosts will transparently take over so that users do not see a service failure. In addition to the shared IP address, each host has its own IP address for management and configuration. All of the machines that share an IP address have the same VHID. The VHID for each virtual IP address must be unique across the broadcast domain of the network interface. High availability using CARP is built into &os;, though the steps to configure it vary slightly depending upon the &os; version. This section provides the same example configuration for versions before and equal to or after &os; 10. This example configures failover support with three hosts, all with unique IP addresses, but providing the same web content. It has two different masters named hosta.example.org and hostb.example.org, with a shared backup named hostc.example.org. These machines are load balanced with a Round Robin DNS configuration. The master and backup machines are configured identically except for their hostnames and management IP addresses. These servers must have the same configuration and run the same services. When the failover occurs, requests to the service on the shared IP address can only be answered correctly if the backup server has access to the same content. The backup machine has two additional CARP interfaces, one for each of the master content server's IP addresses. When a failure occurs, the backup server will pick up the failed master machine's IP address. Using <acronym>CARP</acronym> on &os; 10 and Later Enable boot-time support for CARP by adding an entry for the carp.ko kernel module in /boot/loader.conf: carp_load="YES" To load the module now without rebooting: &prompt.root; kldload carp For users who prefer to use a custom kernel, include the following line in the custom kernel configuration file and compile the kernel as described in : device carp The hostname, management IP address and subnet mask, shared IP address, and VHID are all set by adding entries to /etc/rc.conf. This example is for hosta.example.org: hostname="hosta.example.org" ifconfig_em0="inet 192.168.1.3 netmask 255.255.255.0" ifconfig_em0_alias0="inet vhid 1 pass testpass alias 192.168.1.50/32" The next set of entries are for hostb.example.org. Since it represents a second master, it uses a different shared IP address and VHID. However, the passwords specified with must be identical as CARP will only listen to and accept advertisements from machines with the correct password. hostname="hostb.example.org" ifconfig_em0="inet 192.168.1.4 netmask 255.255.255.0" ifconfig_em0_alias0="inet vhid 2 pass testpass alias 192.168.1.51/32" The third machine, hostc.example.org, is configured to handle failover from either master. This machine is configured with two CARP VHIDs, one to handle the virtual IP address for each of the master hosts. The CARP advertising skew, , is set to ensure that the backup host advertises later than the master, since controls the order of precedence when there are multiple backup servers. hostname="hostc.example.org" ifconfig_em0="inet 192.168.1.5 netmask 255.255.255.0" ifconfig_em0_alias0="inet vhid 1 advskew 100 pass testpass alias 192.168.1.50/32" ifconfig_em0_alias1="inet vhid 2 advskew 100 pass testpass alias 192.168.1.51/32" Having two CARP VHIDs configured means that hostc.example.org will notice if either of the master servers becomes unavailable. If a master fails to advertise before the backup server, the backup server will pick up the shared IP address until the master becomes available again. Preemption is disabled by default. If preemption has been enabled, hostc.example.org might not release the virtual IP address back to the original master server. The administrator can force the backup server to return the IP address to the master with the command: &prompt.root; ifconfig em0 vhid 1 state backup Once the configuration is complete, either restart networking or reboot each system. High availability is now enabled. CARP functionality can be controlled via several &man.sysctl.8; variables documented in the &man.carp.4; manual pages. Other actions can be triggered from CARP events by using &man.devd.8;. Using <acronym>CARP</acronym> on &os; 9 and Earlier The configuration for these versions of &os; is similar to the one described in the previous section, except that a CARP device must first be created and referred to in the configuration. Enable boot-time support for CARP by loading the if_carp.ko kernel module in /boot/loader.conf: if_carp_load="YES" To load the module now without rebooting: &prompt.root; kldload carp For users who prefer to use a custom kernel, include the following line in the custom kernel configuration file and compile the kernel as described in : device carp Next, on each host, create a CARP device: &prompt.root; ifconfig carp0 create Set the hostname, management IP address, the shared IP address, and VHID by adding the required lines to /etc/rc.conf. Since a virtual CARP device is used instead of an alias, the actual subnet mask of /24 is used instead of /32. Here are the entries for hosta.example.org: hostname="hosta.example.org" ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0" cloned_interfaces="carp0" ifconfig_carp0="vhid 1 pass testpass 192.168.1.50/24" On hostb.example.org: hostname="hostb.example.org" ifconfig_fxp0="inet 192.168.1.4 netmask 255.255.255.0" cloned_interfaces="carp0" ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24" The third machine, hostc.example.org, is configured to handle failover from either of the master hosts: hostname="hostc.example.org" ifconfig_fxp0="inet 192.168.1.5 netmask 255.255.255.0" cloned_interfaces="carp0 carp1" ifconfig_carp0="vhid 1 advskew 100 pass testpass 192.168.1.50/24" ifconfig_carp1="vhid 2 advskew 100 pass testpass 192.168.1.51/24" Preemption is disabled in the GENERIC &os; kernel. If preemption has been enabled with a custom kernel, hostc.example.org may not release the IP address back to the original content server. The administrator can force the backup server to return the IP address to the master with the command: &prompt.root; ifconfig carp0 down && ifconfig carp0 up This should be done on the carp interface which corresponds to the correct host. Once the configuration is complete, either restart networking or reboot each system. High availability is now enabled. VLANs VLANs Virtual LANs VLANs are a way of virtually dividing up a network into many different subnetworks. Each will have its own broadcast domain and be isolated from the rest of the VLANs. On &os;, VLANs must be supported by the network card driver. To see which drivers support vlans, refer to the &man.vlan.4; manual page. When configuring a VLAN, a couple pieces of information must be known. First, which network interface? Second, what is the VLAN tag? To configure VLANs at run time, with a NIC of em0 and a VLAN tag of 5. The command would look like this: &prompt.root; ifconfig em0.5 create vlan 5 vlandev em0 inet 192.168.20.20/24 See how the interface name includes the NIC driver name and the VLAN tag, separated by a period? This is a best practice to make maintaining the VLAN configuration easy when many VLANs are present on a machine. To configure VLANs at boot time, /etc/rc.conf must be updated. To duplicate the configuration above, the following will need to be added: vlans_em0="5" ifconfig_em0_5="inet 192.168.20.20/24" Additional VLANs may be added, by simply adding the tag to the vlans_em0 field and adding an additional line configuring the network on that VLAN tag's interface. Index: head/en_US.ISO8859-1/books/handbook/desktop/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/handbook/desktop/chapter.xml (revision 50967) +++ head/en_US.ISO8859-1/books/handbook/desktop/chapter.xml (revision 50968) @@ -1,1141 +1,1141 @@ Desktop Applications Synopsis While &os; is popular as a server for its performance and stability, it is also suited for day-to-day use as a desktop. With over &os.numports; applications available as &os; packages or ports, it is easy to build a customized desktop that runs a wide variety of desktop applications. This chapter demonstrates how to install numerous desktop applications, including web browsers, productivity software, document viewers, and financial software. Users who prefer to install a pre-built desktop version of FreeBSD rather than configuring one from scratch should refer to the trueos.org website. Readers of this chapter should know how to: Install additional software using packages or ports as described in . Install X and a window manager as described in . For information on how to configure a multimedia environment, refer to . Browsers browsers web &os; does not come with a pre-installed web browser. Instead, the www + xlink:href="https://www.FreeBSD.org/ports/www.html">www category of the Ports Collection contains many browsers which can be installed as a package or compiled from the Ports Collection. The KDE and GNOME desktop environments include their own HTML browser. Refer to for more information on how to set up these complete desktops. Some lightweight browsers include www/dillo2, www/links, and www/w3m. This section demonstrates how to install the following popular web browsers and indicates if the application is resource-heavy, takes time to compile from ports, or has any major dependencies. Application Name Resources Needed Installation from Ports Notes Firefox medium heavy &os;, &linux;, and localized versions are available Opera light light &os; and &linux; versions are available Konqueror medium heavy Requires KDE libraries Chromium medium heavy Requires Gtk+ Firefox Firefox Firefox is an open source browser that is fully ported to &os;. It features a standards-compliant HTML display engine, tabbed browsing, popup blocking, extensions, improved security, and more. Firefox is based on the Mozilla codebase. To install the package of the latest release version of Firefox, type: &prompt.root; pkg install firefox To instead install Firefox Extended Support Release (ESR) version, use: &prompt.root; pkg install firefox-esr Localized versions are available in www/firefox-i18n and www/firefox-esr-i18n. The Ports Collection can instead be used to compile the desired version of Firefox from source code. This example builds www/firefox, where firefox can be replaced with the ESR or localized version to install. &prompt.root; cd /usr/ports/www/firefox &prompt.root; make install clean Firefox and &java; Plugin The installation of Firefox does not include &java; support. However, java/icedtea-web provides a free software web browser plugin for running Java applets. It can be installed as a package by running: &prompt.root; pkg install icedtea-web Alternatively, to compile from the Ports Collection: &prompt.root; cd /usr/ports/java/icedtea-web &prompt.root; make install clean Keep the default configuration options when compiling the port. Once installed, start Firefox, enter about:plugins in the location bar and press Enter. A page listing the installed plugins will be displayed. The &java; plugin should be listed. If the browser is unable to find the plugin, each user will have to run the following command and relaunch the browser: &prompt.user; ln -s /usr/local/lib/IcedTeaPlugin.so \ $HOME/.mozilla/plugins/ Firefox and &adobe; &flash; Plugin Flash A native &adobe; &flash; plugin is not available for &os;. However, a software wrapper for running the &linux; version of the plugin is available. This wrapper also provides support for other browser plugins such as &realplayer;. To install and enable this plugin, perform these steps: Install www/nspluginwrapper from the port. Due to licensing restrictions, a package is not available. This port requires emulators/linux_base-c6. Install www/linux-flashplayer from the port. Due to licensing restrictions, a package is not available. Before the plugin is first used, each user must run: &prompt.user; nspluginwrapper -v -a -i When the plugin port has been updated and reinstalled, each user must run: &prompt.user; nspluginwrapper -v -a -u Start the browser, enter about:plugins in the location bar and press Enter. A list of all the currently available plugins will be shown. Firefox and Swfdec &flash; Plugin Swfdec is a decoder and renderer for &flash; animations. Swfdec-Mozilla is a plugin for Firefox browsers that uses the Swfdec library for playing SWF files. To install the package: &prompt.root; pkg install swfdec-plugin If the package is not available, compile and install it from the Ports Collection: &prompt.root; cd /usr/ports/www/swfdec-plugin &prompt.root; make install clean Restart the browser to activate this plugin. Opera Opera Opera is a full-featured and standards-compliant browser which is still lightweight and fast. It comes with a built-in mail and news reader, an IRC client, an RSS/Atom feeds reader, and more. It is available as a native &os; version and as a version that runs under &linux; emulation. This command installs the package of the &os; version of Opera. Replace opera with linux-opera to instead install the &linux; version. &prompt.root; pkg install opera Alternately, install either version through the Ports Collection. This example compiles the native version: &prompt.root; cd /usr/ports/www/opera &prompt.root; make install clean To install the &linux; version, substitute linux-opera in place of opera. To install &adobe; &flash; plugin support, first compile the www/linux-c6-flashplugin11 port. Licensing restrictions prevent making a package available. Then install www/opera-linuxplugins. This example compiles both applications from ports: &prompt.root; cd /usr/ports/www/linux-c6-flashplugin11 &prompt.root; make install clean &prompt.root; cd /usr/ports/www/opera-linuxplugins &prompt.root; make install clean Once installed, check the presence of the plugin by starting the browser, entering opera:plugins in the location bar and pressing Enter. A list should appear with all the currently available plugins. To add the &java; plugin, follow the instructions in . Konqueror Konqueror Konqueror is more than a web browser as it is also a file manager and a multimedia viewer. It is included in the x11/kde4-baseapps package or port. Konqueror supports WebKit as well as its own KHTML. WebKit is a rendering engine used by many modern browsers including Chromium. To use WebKit with Konqueror on &os;, install the www/kwebkitpart package or port. This example installs the package: &prompt.root; pkg install kwebkitpart To install from the Ports Collection: &prompt.root; cd /usr/ports/www/kwebkitpart &prompt.root; make install clean To enable WebKit within Konqueror, click Settings, Configure Konqueror. In the General settings page, click the drop-down menu next to Default web browser engine and change KHTML to WebKit. Konqueror also supports &flash;. A How To guide for getting &flash; support on Konqueror is available at http://freebsd.kde.org/howtos/konqueror-flash.php. Chromium Chromium Chromium is an open source browser project that aims to build a safer, faster, and more stable web browsing experience. Chromium features tabbed browsing, popup blocking, extensions, and much more. Chromium is the open source project upon which the Google Chrome web browser is based. Chromium can be installed as a package by typing: &prompt.root; pkg install chromium Alternatively, Chromium can be compiled from source using the Ports Collection: &prompt.root; cd /usr/ports/www/chromium &prompt.root; make install clean The executable for Chromium is /usr/local/bin/chrome, not /usr/local/bin/chromium. Chromium and &java; Plugin The installation of Chromium does not include &java; support. To install &java; plugin support, follow the instructions in . Once &java; support is installed, start Chromium and enter about:plugins in the address bar. IcedTea-Web should be listed as one of the installed plugins. If Chromium does not display the IcedTea-Web plugin, run the following commands and restart the web browser: &prompt.root; mkdir -p /usr/local/share/chromium/plugins &prompt.root; ln -s /usr/local/lib/IcedTeaPlugin.so \ /usr/local/share/chromium/plugins/ Chromium and &adobe; &flash; Plugin Configuring Chromium and &adobe; &flash; is similar to the instructions in . No additional configuration should be necessary, since Chromium is able to use some plugins from other browsers. Productivity When it comes to productivity, new users often look for an office suite or an easy-to-use word processor. While some desktop environments like KDE provide an office suite, there is no default productivity package. Several office suites and graphical word processors are available for &os;, regardless of the installed window manager. This section demonstrates how to install the following popular productivity software and indicates if the application is resource-heavy, takes time to compile from ports, or has any major dependencies. Application Name Resources Needed Installation from Ports Major Dependencies Calligra light heavy KDE AbiWord light light Gtk+ or GNOME The Gimp light heavy Gtk+ Apache OpenOffice heavy huge &jdk; and Mozilla LibreOffice somewhat heavy huge Gtk+, or KDE/ GNOME, or &jdk; Calligra Calligra office suite Calligra The KDE desktop environment includes an office suite which can be installed separately from KDE. Calligra includes standard components that can be found in other office suites. Words is the word processor, Sheets is the spreadsheet program, Stage manages slide presentations, and Karbon is used to draw graphical documents. In &os;, editors/calligra can be installed as a package or a port. To install the package: &prompt.root; pkg install calligra If the package is not available, use the Ports Collection instead: &prompt.root; cd /usr/ports/editors/calligra &prompt.root; make install clean AbiWord AbiWord AbiWord is a free word processing program similar in look and feel to µsoft; Word. It is fast, contains many features, and is user-friendly. AbiWord can import or export many file formats, including some proprietary ones like µsoft; .rtf. To install the AbiWord package: &prompt.root; pkg install abiword If the package is not available, it can be compiled from the Ports Collection: &prompt.root; cd /usr/ports/editors/abiword &prompt.root; make install clean The GIMP The GIMP For image authoring or picture retouching, The GIMP provides a sophisticated image manipulation program. It can be used as a simple paint program or as a quality photo retouching suite. It supports a large number of plugins and features a scripting interface. The GIMP can read and write a wide range of file formats and supports interfaces with scanners and tablets. To install the package: &prompt.root; pkg install gimp Alternately, use the Ports Collection: &prompt.root; cd /usr/ports/graphics/gimp &prompt.root; make install clean The graphics category (freebsd.org/ports/graphics.html) + xlink:href="https://www.FreeBSD.org/ports/graphics.html">freebsd.org/ports/graphics.html) of the Ports Collection contains several GIMP-related plugins, help files, and user manuals. Apache OpenOffice Apache OpenOffice office suite Apache OpenOffice Apache OpenOffice is an open source office suite which is developed under the wing of the Apache Software Foundation's Incubator. It includes all of the applications found in a complete office productivity suite: a word processor, spreadsheet, presentation manager, and drawing program. Its user interface is similar to other office suites, and it can import and export in various popular file formats. It is available in a number of different languages and internationalization has been extended to interfaces, spell checkers, and dictionaries. The word processor of Apache OpenOffice uses a native XML file format for increased portability and flexibility. The spreadsheet program features a macro language which can be interfaced with external databases. Apache OpenOffice is stable and runs natively on &windows;, &solaris;, &linux;, &os;, and &macos; X. More information about Apache OpenOffice can be found at openoffice.org. For &os; specific information refer to porting.openoffice.org/freebsd/. To install the Apache OpenOffice package: &prompt.root; pkg install apache-openoffice Once the package is installed, type the following command to launch Apache OpenOffice: &prompt.user; openoffice-X.Y.Z where X.Y.Z is the version number of the installed version of Apache OpenOffice. The first time Apache OpenOffice launches, some questions will be asked and a .openoffice.org folder will be created in the user's home directory. If the desired Apache OpenOffice package is not available, compiling the port is still an option. However, this requires a lot of disk space and a fairly long time to compile: &prompt.root; cd /usr/ports/editors/openoffice-4 &prompt.root; make install clean To build a localized version, replace the previous command with: &prompt.root; make LOCALIZED_LANG=your_language install clean Replace your_language with the correct language ISO-code. A list of supported language codes is available in files/Makefile.localized, located in the port's directory. LibreOffice LibreOffice office suite LibreOffice LibreOffice is a free software office suite developed by documentfoundation.org. It is compatible with other major office suites and available on a variety of platforms. It is a rebranded fork of Apache OpenOffice and includes applications found in a complete office productivity suite: a word processor, spreadsheet, presentation manager, drawing program, database management program, and a tool for creating and editing mathematical formulæ. It is available in a number of different languages and internationalization has been extended to interfaces, spell checkers, and dictionaries. The word processor of LibreOffice uses a native XML file format for increased portability and flexibility. The spreadsheet program features a macro language which can be interfaced with external databases. LibreOffice is stable and runs natively on &windows;, &linux;, &os;, and &macos; X. More information about LibreOffice can be found at libreoffice.org. To install the English version of the LibreOffice package: &prompt.root; pkg install libreoffice The editors category (freebsd.org/ports/editors.html) + xlink:href="https://www.FreeBSD.org/ports/editors.html">freebsd.org/ports/editors.html) of the Ports Collection contains several localizations for LibreOffice. When installing a localized package, replace libreoffice with the name of the localized package. Once the package is installed, type the following command to run LibreOffice: &prompt.user; libreoffice During the first launch, some questions will be asked and a .libreoffice folder will be created in the user's home directory. If the desired LibreOffice package is not available, compiling the port is still an option. However, this requires a lot of disk space and a fairly long time to compile. This example compiles the English version: &prompt.root; cd /usr/ports/editors/libreoffice &prompt.root; make install clean To build a localized version, cd into the port directory of the desired language. Supported languages can be found in the editors category (freebsd.org/ports/editors.html) + xlink:href="https://www.FreeBSD.org/ports/editors.html">freebsd.org/ports/editors.html) of the Ports Collection. Document Viewers Some new document formats have gained popularity since the advent of &unix; and the viewers they require may not be available in the base system. This section demonstrates how to install the following document viewers: Application Name Resources Needed Installation from Ports Major Dependencies Xpdf light light FreeType gv light light Xaw3d Geeqie light light Gtk+ or GNOME ePDFView light light Gtk+ Okular light heavy KDE Xpdf Xpdf PDF viewing For users that prefer a small &os; PDF viewer, Xpdf provides a light-weight and efficient viewer which requires few resources. It uses the standard X fonts and does not require any additional toolkits. To install the Xpdf package: &prompt.root; pkg install xpdf If the package is not available, use the Ports Collection: &prompt.root; cd /usr/ports/graphics/xpdf &prompt.root; make install clean Once the installation is complete, launch xpdf and use the right mouse button to activate the menu. <application>gv</application> gv PDF viewing PostScript viewing gv is a &postscript; and PDF viewer. It is based on ghostview, but has a nicer look as it is based on the Xaw3d widget toolkit. gv has many configurable features, such as orientation, paper size, scale, and anti-aliasing. Almost any operation can be performed with either the keyboard or the mouse. To install gv as a package: &prompt.root; pkg install gv If a package is unavailable, use the Ports Collection: &prompt.root; cd /usr/ports/print/gv &prompt.root; make install clean Geeqie Geeqie Geeqie is a fork from the unmaintained GQView project, in an effort to move development forward and integrate the existing patches. Geeqie is an image manager which supports viewing a file with a single click, launching an external editor, and thumbnail previews. It also features a slideshow mode and some basic file operations, making it easy to manage image collections and to find duplicate files. Geeqie supports full screen viewing and internationalization. To install the Geeqie package: &prompt.root; pkg install geeqie If the package is not available, use the Ports Collection: &prompt.root; cd /usr/ports/graphics/geeqie &prompt.root; make install clean ePDFView ePDFView PDF viewing ePDFView is a lightweight PDF document viewer that only uses the Gtk+ and Poppler libraries. It is currently under development, but already opens most PDF files (even encrypted), save copies of documents, and has support for printing using CUPS. To install ePDFView as a package: &prompt.root; pkg install epdfview If a package is unavailable, use the Ports Collection: &prompt.root; cd /usr/ports/graphics/epdfview &prompt.root; make install clean Okular Okular PDF viewing Okular is a universal document viewer based on KPDF for KDE. It can open many document formats, including PDF, &postscript;, DjVu, CHM, XPS, and ePub. To install Okular as a package: &prompt.root; pkg install okular If a package is unavailable, use the Ports Collection: &prompt.root; cd /usr/ports/graphics/okular &prompt.root; make install clean Finance For managing personal finances on a &os; desktop, some powerful and easy-to-use applications can be installed. Some are compatible with widespread file formats, such as the formats used by Quicken and Excel. This section covers these programs: Application Name Resources Needed Installation from Ports Major Dependencies GnuCash light heavy GNOME Gnumeric light heavy GNOME KMyMoney light heavy KDE GnuCash GnuCash GnuCash is part of the GNOME effort to provide user-friendly, yet powerful, applications to end-users. GnuCash can be used to keep track of income and expenses, bank accounts, and stocks. It features an intuitive interface while remaining professional. GnuCash provides a smart register, a hierarchical system of accounts, and many keyboard accelerators and auto-completion methods. It can split a single transaction into several more detailed pieces. GnuCash can import and merge Quicken QIF files. It also handles most international date and currency formats. To install the GnuCash package: &prompt.root; pkg install gnucash If the package is not available, use the Ports Collection: &prompt.root; cd /usr/ports/finance/gnucash &prompt.root; make install clean Gnumeric Gnumeric spreadsheet Gnumeric Gnumeric is a spreadsheet program developed by the GNOME community. It features convenient automatic guessing of user input according to the cell format with an autofill system for many sequences. It can import files in a number of popular formats, including Excel, Lotus 1-2-3, and Quattro Pro. It has a large number of built-in functions and allows all of the usual cell formats such as number, currency, date, time, and much more. To install Gnumeric as a package: &prompt.root; pkg install gnumeric If the package is not available, use the Ports Collection: &prompt.root; cd /usr/ports/math/gnumeric &prompt.root; make install clean KMyMoney KMyMoney spreadsheet KMyMoney KMyMoney is a personal finance application created by the KDE community. KMyMoney aims to provide the important features found in commercial personal finance manager applications. It also highlights ease-of-use and proper double-entry accounting among its features. KMyMoney imports from standard Quicken QIF files, tracks investments, handles multiple currencies, and provides a wealth of reports. To install KMyMoney as a package: &prompt.root; pkg install kmymoney-kde4 If the package is not available, use the Ports Collection: &prompt.root; cd /usr/ports/finance/kmymoney-kde4 &prompt.root; make install clean Index: head/en_US.ISO8859-1/books/handbook/introduction/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/handbook/introduction/chapter.xml (revision 50967) +++ head/en_US.ISO8859-1/books/handbook/introduction/chapter.xml (revision 50968) @@ -1,1311 +1,1311 @@ Introduction Jim Mock Restructured, reorganized, and parts rewritten by Synopsis Thank you for your interest in &os;! The following chapter covers various aspects of the &os; Project, such as its history, goals, development model, and so on. After reading this chapter, you will know: How &os; relates to other computer operating systems. The history of the &os; Project. The goals of the &os; Project. The basics of the &os; open-source development model. And of course: where the name &os; comes from. Welcome to &os;! 4.4BSD-Lite &os; is a 4.4BSD-Lite based operating system for Intel (x86 and &itanium;), AMD64, &arm;, and Sun &ultrasparc; computers. Ports to other architectures are also under way. You can also read about the history of &os;, or the current release. If you are interested in contributing something to the Project (code, hardware, funding), see the Contributing to &os; article. What Can &os; Do? &os; has many noteworthy features. Some of these are: Preemptive multitasking preemptive multitasking with dynamic priority adjustment to ensure smooth and fair sharing of the computer between applications and users, even under the heaviest of loads. Multi-user facilities multi-user facilities which allow many people to use a &os; system simultaneously for a variety of things. This means, for example, that system peripherals such as printers and tape drives are properly shared between all users on the system or the network and that individual resource limits can be placed on users or groups of users, protecting critical system resources from over-use. Strong TCP/IP networking TCP/IP networking with support for industry standards such as SCTP, DHCP, NFS, NIS, PPP, SLIP, IPsec, and IPv6. This means that your &os; machine can interoperate easily with other systems as well as act as an enterprise server, providing vital functions such as NFS (remote file access) and email services or putting your organization on the Internet with WWW, FTP, routing and firewall (security) services. Memory protection memory protection ensures that applications (or users) cannot interfere with each other. One application crashing will not affect others in any way. The industry standard X Window System X Window System (X11R7) can provide a graphical user interface (GUI) on any machine and comes with full sources. binary compatibility Linux binary compatibility SCO binary compatibility SVR4 binary compatibility BSD/OS binary compatibility NetBSD Binary compatibility with many programs built for Linux, SCO, SVR4, BSDI and NetBSD. Thousands of ready-to-run applications are available from the &os; ports and packages collection. Why search the net when you can find it all right here? Thousands of additional and easy-to-port applications are available on the Internet. &os; is source code compatible with most popular commercial &unix; systems and thus most applications require few, if any, changes to compile. Demand paged virtual memory virtual memory and merged VM/buffer cache design efficiently satisfies applications with large appetites for memory while still maintaining interactive response to other users. SMP Symmetric Multi-Processing (SMP) support for machines with multiple CPUs. compilers C compilers C++ A full complement of C and C++ development tools. Many additional languages for advanced research and development are also available in the ports and packages collection. Source code source code for the entire system means you have the greatest degree of control over your environment. Why be locked into a proprietary solution at the mercy of your vendor when you can have a truly open system? Extensive online documentation. And many more! &os; is based on the 4.4BSD-Lite 4.4BSD-Lite release from Computer Systems Research Group (CSRG) Computer Systems Research Group (CSRG) at the University of California at Berkeley, and carries on the distinguished tradition of BSD systems development. In addition to the fine work provided by CSRG, the &os; Project has put in many thousands of hours in fine tuning the system for maximum performance and reliability in real-life load situations. &os; offers performance and reliability on par with commercial offerings, combined with many cutting-edge features not available anywhere else. The applications to which &os; can be put are truly limited only by your own imagination. From software development to factory automation, inventory control to azimuth correction of remote satellite antennae; if it can be done with a commercial &unix; product then it is more than likely that you can do it with &os; too! &os; also benefits significantly from literally thousands of high quality applications developed by research centers and universities around the world, often available at little to no cost. Commercial applications are also available and appearing in greater numbers every day. Because the source code for &os; itself is generally available, the system can also be customized to an almost unheard of degree for special applications or projects, and in ways not generally possible with operating systems from most major commercial vendors. Here is just a sampling of some of the applications in which people are currently using &os;: Internet Services: The robust TCP/IP networking built into &os; makes it an ideal platform for a variety of Internet services such as: World Wide Web servers web servers (standard or secure [SSL]) IPv4 and IPv6 routing Firewalls firewall and NAT NAT (IP masquerading) gateways FTP servers FTP servers electronic mail email email Electronic Mail servers And more... Education: Are you a student of computer science or a related engineering field? There is no better way of learning about operating systems, computer architecture and networking than the hands on, under the hood experience that &os; can provide. A number of freely available CAD, mathematical and graphic design packages also make it highly useful to those whose primary interest in a computer is to get other work done! Research: With source code for the entire system available, &os; is an excellent platform for research in operating systems as well as other branches of computer science. &os;'s freely available nature also makes it possible for remote groups to collaborate on ideas or shared development without having to worry about special licensing agreements or limitations on what may be discussed in open forums. Networking: Need a new router? router A name server (DNS)? DNS Server A firewall to keep people out of your internal network? &os; can easily turn that unused PC sitting in the corner into an advanced router with sophisticated packet-filtering capabilities. Embedded: &os; makes an excellent platform to build embedded systems upon. embedded With support for the &arm;, &mips; and &powerpc; platforms, coupled with a robust network stack, cutting edge features and the permissive BSD license &os; makes an excellent foundation for building embedded routers, firewalls, and other devices. X Window System GNOME KDE Desktop: &os; makes a fine choice for an inexpensive desktop solution using the freely available X11 server. &os; offers a choice from many open-source desktop environments, including the standard GNOME and KDE graphical user interfaces. &os; can even boot diskless from a central server, making individual workstations even cheaper and easier to administer. Software Development: The basic &os; system comes with a full complement of development tools including a full C/C++ Compiler compiler and debugger suite. Support for many other languages are also available through the ports and packages collection. &os; is available to download free of charge, or can be obtained on either CD-ROM or DVD. Please see for more information about obtaining &os;. Who Uses &os;? users large sites running &os; &os;'s advanced features, proven security, predictable release cycle, and permissive license have led to its use as a platform for building many commercial and open source appliances, devices, and products. Many of the world's largest IT companies use &os;: Apache Apache - The Apache Software Foundation runs most of its public facing infrastructure, including possibly one of the largest SVN repositories in the world with over 1.4 million commits, on &os;. Apple Apple - OS X borrows heavily from &os; for the network stack, virtual file system, and many userland components. Apple iOS also contains elements borrowed from &os;. Cisco Cisco - IronPort network security and anti-spam appliances run a modified &os; kernel. Citrix Citrix - The NetScaler line of security appliances provide layer 4-7 load balancing, content caching, application firewall, secure VPN, and mobile cloud network access, along with the power of a &os; shell. Dell KACE Dell KACE - The KACE system management appliances run &os; because of its reliability, scalability, and the community that supports its continued development. Experts Exchange Experts Exchange - All public facing web servers are powered by &os; and they make extensive use of jails to isolate development and testing environments without the overhead of virtualization. Isilon Isilon - Isilon's enterprise storage appliances are based on &os;. The extremely liberal &os; license allowed Isilon to integrate their intellectual property throughout the kernel and focus on building their product instead of an operating system. iXsystems iXsystems - The TrueNAS line of unified storage appliances is based on &os;. In addition to their commercial products, iXsystems also manages development of the open source projects TrueOS and FreeNAS. Juniper Juniper - The JunOS operating system that powers all Juniper networking gear (including routers, switches, security, and networking appliances) is based on &os;. Juniper is one of many vendors that showcases the symbiotic relationship between the project and vendors of commercial products. Improvements generated at Juniper are upstreamed into &os; to reduce the complexity of integrating new features from &os; back into JunOS in the future. McAfee McAfee - SecurOS, the basis of McAfee enterprise firewall products including Sidewinder is based on &os;. NetApp NetApp - The Data ONTAP GX line of storage appliances are based on &os;. In addition, NetApp has contributed back many features, including the new BSD licensed hypervisor, bhyve. Netflix Netflix - The OpenConnect appliance that Netflix uses to stream movies to its customers is based on &os;. Netflix has made extensive contributions to the codebase and works to maintain a zero delta from mainline &os;. Netflix OpenConnect appliances are responsible for delivering more than 32% of all Internet traffic in North America. Sandvine Sandvine - Sandvine uses &os; as the basis of their high performance real-time network processing platforms that make up their intelligent network policy control products. Sony Sony - The PlayStation 4 gaming console runs a modified version of &os;. Sophos Sophos - The Sophos Email Appliance product is based on a hardened &os; and scans inbound mail for spam and viruses, while also monitoring outbound mail for malware as well as the accidental loss of sensitive information. Spectra Logic Spectra Logic - The nTier line of archive grade storage appliances run &os; and OpenZFS. Stormshield Stormshield - Stormshield Network Security appliances are based on a hardened version of &os;. The BSD license allows them to integrate their own intellectual property with the system while returning a great deal of interesting development to the community. The Weather Channel The Weather Channel - The IntelliStar appliance that is installed at each local cable provider's headend and is responsible for injecting local weather forecasts into the cable TV network's programming runs &os;. Verisign Verisign - Verisign is responsible for operating the .com and .net root domain registries as well as the accompanying DNS infrastructure. They rely on a number of different network operating systems including &os; to ensure there is no common point of failure in their infrastructure. Voxer Voxer - Voxer powers their mobile voice messaging platform with ZFS on &os;. Voxer switched from a Solaris derivative to &os; because of its superior documentation, larger and more active community, and more developer friendly environment. In addition to critical features like ZFS and DTrace, &os; also offers TRIM support for ZFS. WhatsApp WhatsApp - When WhatsApp needed a platform that would be able to handle more than 1 million concurrent TCP connections per server, they chose &os;. They then proceeded to scale past 2.5 million connections per server. Wheel Systems Wheel Systems - The FUDO security appliance allows enterprises to monitor, control, record, and audit contractors and administrators who work on their systems. Based on all of the best security features of &os; including ZFS, GELI, Capsicum, HAST, and auditdistd. &os; has also spawned a number of related open source projects: BSD Router BSD Router - A &os; based replacement for large enterprise routers designed to run on standard PC hardware. FreeNAS FreeNAS - A customized &os; designed to be used as a network file server appliance. Provides a python based web interface to simplify the management of both the UFS and ZFS file systems. Includes support for NFS, SMB/CIFS, AFP, FTP, and iSCSI. Includes an extensible plugin system based on &os; jails. GhostBSD GhostBSD - A desktop oriented distribution of &os; bundled with the Gnome desktop environment. mfsBSD mfsBSD - A toolkit for building a &os; system image that runs entirely from memory. NAS4Free NAS4Free - A file server distribution based on &os; with a PHP powered web interface. OPNSense OPNsense - OPNsense is an open source, easy-to-use and easy-to-build FreeBSD based firewall and routing platform. OPNsense includes most of the features available in expensive commercial firewalls, and more in many cases. It brings the rich feature set of commercial offerings with the benefits of open and verifiable sources. TrueOS TrueOS - A customized version of &os; geared towards desktop users with graphical utilities to exposing the power of &os; to all users. Designed to ease the transition of Windows and OS X users. pfSense pfSense - A firewall distribution based on &os; with a huge array of features and extensive IPv6 support. ZRouter ZRouter - An open source alternative firmware for embedded devices based on &os;. Designed to replace the proprietary firmware on off-the-shelf routers. &os; is also used to power some of the biggest sites on the Internet, including: Yahoo! Yahoo! Yandex Yandex Rambler Rambler Sina Sina Pair Networks Pair Networks Sony Japan Sony Japan Netcraft Netcraft Netflix Netflix NetEase NetEase Weathernews Weathernews TELEHOUSE America TELEHOUSE America and many more. Wikipedia also maintains a list of products based on &os;. About the &os; Project The following section provides some background information on the project, including a brief history, project goals, and the development model of the project. A Brief History of &os; 386BSD Patchkit Hubbard, Jordan Williams, Nate Grimes, Rod FreeBSD Project history The &os; Project had its genesis in the early part of 1993, partially as an outgrowth of the Unofficial 386BSDPatchkit by the patchkit's last 3 coordinators: Nate Williams, Rod Grimes and Jordan Hubbard. 386BSD The original goal was to produce an intermediate snapshot of 386BSD in order to fix a number of problems with it that the patchkit mechanism just was not capable of solving. The early working title for the project was 386BSD 0.5 or 386BSD Interim in reference of that fact. Jolitz, Bill 386BSD was Bill Jolitz's operating system, which had been up to that point suffering rather severely from almost a year's worth of neglect. As the patchkit swelled ever more uncomfortably with each passing day, they decided to assist Bill by providing this interim cleanup snapshot. Those plans came to a rude halt when Bill Jolitz suddenly decided to withdraw his sanction from the project without any clear indication of what would be done instead. Greenman, David Walnut Creek CDROM The trio thought that the goal remained worthwhile, even without Bill's support, and so they adopted the name "&os;" coined by David Greenman. The initial objectives were set after consulting with the system's current users and, once it became clear that the project was on the road to perhaps even becoming a reality, Jordan contacted Walnut Creek CDROM with an eye toward improving &os;'s distribution channels for those many unfortunates without easy access to the Internet. Walnut Creek CDROM not only supported the idea of distributing &os; on CD but also went so far as to provide the project with a machine to work on and a fast Internet connection. Without Walnut Creek CDROM's almost unprecedented degree of faith in what was, at the time, a completely unknown project, it is quite unlikely that &os; would have gotten as far, as fast, as it has today. 4.3BSD-Lite Net/2 U.C. Berkeley 386BSD Free Software Foundation The first CD-ROM (and general net-wide) distribution was &os; 1.0, released in December of 1993. This was based on the 4.3BSD-Lite (Net/2) tape from U.C. Berkeley, with many components also provided by 386BSD and the Free Software Foundation. It was a fairly reasonable success for a first offering, and they followed it with the highly successful &os; 1.1 release in May of 1994. Novell U.C. Berkeley Net/2 AT&T Around this time, some rather unexpected storm clouds formed on the horizon as Novell and U.C. Berkeley settled their long-running lawsuit over the legal status of the Berkeley Net/2 tape. A condition of that settlement was U.C. Berkeley's concession that large parts of Net/2 were encumbered code and the property of Novell, who had in turn acquired it from AT&T some time previously. What Berkeley got in return was Novell's blessing that the 4.4BSD-Lite release, when it was finally released, would be declared unencumbered and all existing Net/2 users would be strongly encouraged to switch. This included &os;, and the project was given until the end of July 1994 to stop shipping its own Net/2 based product. Under the terms of that agreement, the project was allowed one last release before the deadline, that release being &os; 1.1.5.1. &os; then set about the arduous task of literally re-inventing itself from a completely new and rather incomplete set of 4.4BSD-Lite bits. The Lite releases were light in part because Berkeley's CSRG had removed large chunks of code required for actually constructing a bootable running system (due to various legal requirements) and the fact that the Intel port of 4.4 was highly incomplete. It took the project until November of 1994 to make this transition, and in December it released &os; 2.0 to the world. Despite being still more than a little rough around the edges, the release was a significant success and was followed by the more robust and easier to install &os; 2.0.5 release in June of 1995. Since that time, &os; has made a series of releases each time improving the stability, speed, and feature set of the previous version. For now, long-term development projects continue to take place in the 10.X-CURRENT (trunk) branch, and snapshot releases of 10.X are continually made available from the snapshot server as work progresses. &os; Project Goals Jordan Hubbard Contributed by FreeBSD Project goals The goals of the &os; Project are to provide software that may be used for any purpose and without strings attached. Many of us have a significant investment in the code (and project) and would certainly not mind a little financial compensation now and then, but we are definitely not prepared to insist on it. We believe that our first and foremost mission is to provide code to any and all comers, and for whatever purpose, so that the code gets the widest possible use and provides the widest possible benefit. This is, I believe, one of the most fundamental goals of Free Software and one that we enthusiastically support. GNU General Public License (GPL) GNU Lesser General Public License (LGPL) BSD Copyright That code in our source tree which falls under the GNU General Public License (GPL) or Library General Public License (LGPL) comes with slightly more strings attached, though at least on the side of enforced access rather than the usual opposite. Due to the additional complexities that can evolve in the commercial use of GPL software we do, however, prefer software submitted under the more relaxed BSD copyright when it is a reasonable option to do so. The &os; Development Model Satoshi Asami Contributed by FreeBSD Project development model The development of &os; is a very open and flexible process, being literally built from the contributions of thousands of people around the world, as can be seen from our list of contributors. &os;'s development infrastructure allow these thousands of contributors to collaborate over the Internet. We are constantly on the lookout for new developers and ideas, and those interested in becoming more closely involved with the project need simply contact us at the &a.hackers;. The &a.announce; is also available to those wishing to make other &os; users aware of major areas of work. Useful things to know about the &os; Project and its development process, whether working independently or in close cooperation: The SVN repositories CVS CVS Repository Concurrent Versions System CVS Subversion Subversion Repository SVN Subversion For several years, the central source tree for &os; was maintained by CVS (Concurrent Versions System), a freely available source code control tool. In June 2008, the Project switched to using SVN (Subversion). The switch was deemed necessary, as the technical limitations imposed by CVS were becoming obvious due to the rapid expansion of the source tree and the amount of history already stored. The Documentation Project and Ports Collection repositories also moved from CVS to SVN in May 2012 and July 2012, respectively. Please refer to the Synchronizing your source tree section for more information on obtaining the &os; src/ repository and Using the Ports Collection for details on obtaining the &os; Ports Collection. The committers list The committers committers are the people who have write access to the Subversion tree, and are authorized to make modifications to the &os; source (the term committer comes from commit, the source control command which is used to bring new changes into the repository). Anyone can submit a bug to the Bug Database. Before submitting a bug report, the &os; mailing lists, IRC channels, or forums can be used to help verify that an issue is actually a bug. The FreeBSD core team The &os; core team core team would be equivalent to the board of directors if the &os; Project were a company. The primary task of the core team is to make sure the project, as a whole, is in good shape and is heading in the right directions. Inviting dedicated and responsible developers to join our group of committers is one of the functions of the core team, as is the recruitment of new core team members as others move on. The current core team was elected from a pool of committer candidates in July 2014. Elections are held every 2 years. Like most developers, most members of the core team are also volunteers when it comes to &os; development and do not benefit from the project financially, so commitment should also not be misconstrued as meaning guaranteed support. The board of directors analogy above is not very accurate, and it may be more suitable to say that these are the people who gave up their lives in favor of &os; against their better judgement! Outside contributors Last, but definitely not least, the largest group of developers are the users themselves who provide feedback and bug fixes to us on an almost constant basis. The primary way of keeping in touch with &os;'s more non-centralized development is to subscribe to the &a.hackers; where such things are discussed. See for more information about the various &os; mailing lists. The &os; Contributors List contributors is a long and growing one, so why not join it by contributing something back to &os; today? Providing code is not the only way of contributing to the project; for a more complete list of things that need doing, please refer to the &os; Project web site. In summary, our development model is organized as a loose set of concentric circles. The centralized model is designed for the convenience of the users of &os;, who are provided with an easy way of tracking one central code base, not to keep potential contributors out! Our desire is to present a stable operating system with a large set of coherent application programs that the users can easily install and use — this model works very well in accomplishing that. All we ask of those who would join us as &os; developers is some of the same dedication its current people have to its continued success! Third Party Programs In addition to the base distributions, &os; offers a ported software collection with thousands of commonly sought-after programs. At the time of this writing, there were over &os.numports; ports! The list of ports ranges from http servers, to games, languages, editors, and almost everything in between. The entire Ports Collection requires approximately &ports.size;. To compile a port, you simply change to the directory of the program you wish to install, type make install, and let the system do the rest. The full original distribution for each port you build is retrieved dynamically so you need only enough disk space to build the ports you want. Almost every port is also provided as a pre-compiled package, which can be installed with a simple command (pkg install) by those who do not wish to compile their own ports from source. More information on packages and ports can be found in . Additional Documentation All recent &os; versions provide an option in the installer (either &man.sysinstall.8; or &man.bsdinstall.8;) to install additional documentation under /usr/local/share/doc/freebsd during the initial system setup. Documentation may also be installed at any later time using packages as described in . You may view the locally installed manuals with any HTML capable browser using the following URLs: The FreeBSD Handbook /usr/local/share/doc/freebsd/handbook/index.html The FreeBSD FAQ /usr/local/share/doc/freebsd/faq/index.html You can also view the master (and most frequently updated) copies at http://www.FreeBSD.org/. + xlink:href="https://www.FreeBSD.org/">https://www.FreeBSD.org/. Index: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml (revision 50967) +++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml (revision 50968) @@ -1,1735 +1,1735 @@ Installing Applications: Packages and Ports Synopsis ports packages &os; is bundled with a rich collection of system tools as part of the base system. In addition, &os; provides two complementary technologies for installing third-party software: the &os; Ports Collection, for installing from source, and packages, for installing from pre-built binaries. Either method may be used to install software from local media or from the network. After reading this chapter, you will know: The difference between binary packages and ports. How to find third-party software that has been ported to &os;. How to manage binary packages using pkg. How to build third-party software from source using the Ports Collection. How to find the files installed with the application for post-installation configuration. What to do if a software installation fails. Overview of Software Installation The typical steps for installing third-party software on a &unix; system include: Find and download the software, which might be distributed in source code format or as a binary. Unpack the software from its distribution format. This is typically a tarball compressed with a program such as &man.compress.1;, &man.gzip.1;, &man.bzip2.1; or &man.xz.1;. Locate the documentation in INSTALL, README or some file in a doc/ subdirectory and read up on how to install the software. If the software was distributed in source format, compile it. This may involve editing a Makefile or running a configure script. Test and install the software. A &os; port is a collection of files designed to automate the process of compiling an application from source code. The files that comprise a port contain all the necessary information to automatically download, extract, patch, compile, and install the application. If the software has not already been adapted and tested on &os;, the source code might need editing in order for it to install and run properly. However, over &os.numports; third-party applications have already been ported to &os;. When feasible, these applications are made available for download as pre-compiled packages. Packages can be manipulated with the &os; package management commands. Both packages and ports understand dependencies. If a package or port is used to install an application and a dependent library is not already installed, the library will automatically be installed first. A &os; package contains pre-compiled copies of all the commands for an application, as well as any configuration files and documentation. A package can be manipulated with the &man.pkg.8; commands, such as pkg install. While the two technologies are similar, packages and ports each have their own strengths. Select the technology that meets your requirements for installing a particular application. Package Benefits A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application. Packages do not require compilation time. For large applications, such as Mozilla, KDE, or GNOME, this can be important on a slow system. Packages do not require any understanding of the process involved in compiling software on &os;. Port Benefits Packages are normally compiled with conservative options because they have to run on the maximum number of systems. By compiling from the port, one can change the compilation options. Some applications have compile-time options relating to which features are installed. For example, Apache can be configured with a wide variety of different built-in options. In some cases, multiple packages will exist for the same application to specify certain settings. For example, Ghostscript is available as a ghostscript package and a ghostscript-nox11 package, depending on whether or not Xorg is installed. Creating multiple packages rapidly becomes impossible if an application has more than one or two different compile-time options. The licensing conditions of some software forbid binary distribution. Such software must be distributed as source code which must be compiled by the end-user. Some people do not trust binary distributions or prefer to read through source code in order to look for potential problems. Source code is needed in order to apply custom patches. To keep track of updated ports, subscribe to the &a.ports; and the &a.ports-bugs;. Before installing any application, check for security issues related to the application or type pkg audit -F to check all installed applications for known vulnerabilities. The remainder of this chapter explains how to use packages and ports to install and manage third-party software on &os;. Finding Software &os;'s list of available applications is growing all the time. There are a number of ways to find software to install: The &os; web site maintains an up-to-date searchable list of all the available applications, at http://www.FreeBSD.org/ports/. + xlink:href="&url.base;/ports/index.html">https://www.FreeBSD.org/ports/. The ports can be searched by application name or by software category. FreshPorts Dan Langille maintains FreshPorts.org which provides a comprehensive search utility and also tracks changes to the applications in the Ports Collection. Registered users can create a customized watch list in order to receive an automated email when their watched ports are updated. SourceForge If finding a particular application becomes challenging, try searching a site like SourceForge.net or GitHub.com then check back at the &os; site to see if the application has been ported. pkg search To search the binary package repository for an application: &prompt.root; pkg search subversion git-subversion-1.9.2 java-subversion-1.8.8_2 p5-subversion-1.8.8_2 py27-hgsubversion-1.6 py27-subversion-1.8.8_2 ruby-subversion-1.8.8_2 subversion-1.8.8_2 subversion-book-4515 subversion-static-1.8.8_2 subversion16-1.6.23_4 subversion17-1.7.16_2 Package names include the version number and, in the case of ports based on python, the version number of the version of python the package was built with. Some ports also have multiple versions available. In the case of Subversion, there are different versions available, as well as different compile options. In this case, the statically linked version of Subversion. When indicating which package to install, it is best to specify the application by the port origin, which is the path in the ports tree. Repeat the pkg search with to list the origin of each package: &prompt.root; pkg search -o subversion devel/git-subversion java/java-subversion devel/p5-subversion devel/py-hgsubversion devel/py-subversion devel/ruby-subversion devel/subversion16 devel/subversion17 devel/subversion devel/subversion-book devel/subversion-static Searching by shell globs, regular expressions, exact match, by description, or any other field in the repository database is also supported by pkg search. After installing ports-mgmt/pkg or ports-mgmt/pkg-devel, see &man.pkg-search.8; for more details. If the Ports Collection is already installed, there are several methods to query the local version of the ports tree. To find out which category a port is in, type whereis file, where file is the program to be installed: &prompt.root; whereis lsof lsof: /usr/ports/sysutils/lsof Alternately, an &man.echo.1; statement can be used: &prompt.root; echo /usr/ports/*/*lsof* /usr/ports/sysutils/lsof Note that this will also return any matched files downloaded into the /usr/ports/distfiles directory. Another way to find software is by using the Ports Collection's built-in search mechanism. To use the search feature, cd to /usr/ports then run make search name=program-name where program-name is the name of the software. For example, to search for lsof: &prompt.root; cd /usr/ports &prompt.root; make search name=lsof Port: lsof-4.88.d,8 Path: /usr/ports/sysutils/lsof Info: Lists information about open files (similar to fstat(1)) Maint: ler@lerctr.org Index: sysutils B-deps: R-deps: The built-in search mechanism uses a file of index information. If a message indicates that the INDEX is required, run make fetchindex to download the current index file. With the INDEX present, make search will be able to perform the requested search. The Path: line indicates where to find the port. To receive less information, use the quicksearch feature: &prompt.root; cd /usr/ports &prompt.root; make quicksearch name=lsof Port: lsof-4.88.d,8 Path: /usr/ports/sysutils/lsof Info: Lists information about open files (similar to fstat(1)) For more in-depth searching, use make search key=string or make quicksearch key=string, where string is some text to search for. The text can be in comments, descriptions, or dependencies in order to find ports which relate to a particular subject when the name of the program is unknown. When using search or quicksearch, the search string is case-insensitive. Searching for LSOF will yield the same results as searching for lsof. Using <application>pkg</application> for Binary Package Management pkg is the next generation replacement for the traditional &os; package management tools, offering many features that make dealing with binary packages faster and easier. For sites wishing to only use prebuilt binary packages from the &os; mirrors, managing packages with pkg can be sufficient. However, for those sites building from source or using their own repositories, a separate port management tool will be needed. Since pkg only works with binary packages, it is not a replacement for such tools. Those tools can be used to install software from both binary packages and the Ports Collection, while pkg installs only binary packages. Getting Started with <application>pkg</application> &os; includes a bootstrap utility which can be used to download and install pkg and its manual pages. This utility is designed to work with versions of &os; starting with 10.X. Not all &os; versions and architectures support this bootstrap process. The current list is at . For other cases, pkg must instead be installed from the Ports Collection or as a binary package. To bootstrap the system, run: &prompt.root; /usr/sbin/pkg You must have a working Internet connection for the bootstrap process to succeed. Otherwise, to install the port, run: &prompt.root; cd /usr/ports/ports-mgmt/pkg &prompt.root; make &prompt.root; make install clean When upgrading an existing system that originally used the older pkg_* tools, the database must be converted to the new format, so that the new tools are aware of the already installed packages. Once pkg has been installed, the package database must be converted from the traditional format to the new format by running this command: &prompt.root; pkg2ng This step is not required for new installations that do not yet have any third-party software installed. This step is not reversible. Once the package database has been converted to the pkg format, the traditional pkg_* tools should no longer be used. The package database conversion may emit errors as the contents are converted to the new version. Generally, these errors can be safely ignored. However, a list of software that was not successfully converted is shown after pkg2ng finishes. These applications must be manually reinstalled. To ensure that the Ports Collection registers new software with pkg instead of the traditional packages database, &os; versions earlier than 10.X require this line in /etc/make.conf: WITH_PKGNG= yes By default, pkg uses the binary packages from the &os; package mirrors (the repository). For information about building a custom package repository, see . Additional pkg configuration options are described in &man.pkg.conf.5;. Usage information for pkg is available in the &man.pkg.8; manual page or by running pkg without additional arguments. Each pkg command argument is documented in a command-specific manual page. To read the manual page for pkg install, for example, run either of these commands: &prompt.root; pkg help install &prompt.root; man pkg-install The rest of this section demonstrates common binary package management tasks which can be performed using pkg. Each demonstrated command provides many switches to customize its use. Refer to a command's help or man page for details and more examples. Obtaining Information About Installed Packages Information about the packages installed on a system can be viewed by running pkg info which, when run without any switches, will list the package version for either all installed packages or the specified package. For example, to see which version of pkg is installed, run: &prompt.root; pkg info pkg pkg-1.1.4_1 Installing and Removing Packages To install a binary package use the following command, where packagename is the name of the package to install: &prompt.root; pkg install packagename This command uses repository data to determine which version of the software to install and if it has any uninstalled dependencies. For example, to install curl: &prompt.root; pkg install curl Updating repository catalogue /usr/local/tmp/All/curl-7.31.0_1.txz 100% of 1181 kB 1380 kBps 00m01s /usr/local/tmp/All/ca_root_nss-3.15.1_1.txz 100% of 288 kB 1700 kBps 00m00s Updating repository catalogue The following 2 packages will be installed: Installing ca_root_nss: 3.15.1_1 Installing curl: 7.31.0_1 The installation will require 3 MB more space 0 B to be downloaded Proceed with installing packages [y/N]: y Checking integrity... done [1/2] Installing ca_root_nss-3.15.1_1... done [2/2] Installing curl-7.31.0_1... done Cleaning up cache files...Done The new package and any additional packages that were installed as dependencies can be seen in the installed packages list: &prompt.root; pkg info ca_root_nss-3.15.1_1 The root certificate bundle from the Mozilla Project curl-7.31.0_1 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers pkg-1.1.4_6 New generation package manager Packages that are no longer needed can be removed with pkg delete. For example: &prompt.root; pkg delete curl The following packages will be deleted: curl-7.31.0_1 The deletion will free 3 MB Proceed with deleting packages [y/N]: y [1/1] Deleting curl-7.31.0_1... done Upgrading Installed Packages Installed packages can be upgraded to their latest versions by running: &prompt.root; pkg upgrade This command will compare the installed versions with those available in the repository catalogue and upgrade them from the repository. Auditing Installed Packages Software vulnerabilities are regularly discovered in third-party applications. To address this, pkg includes a built-in auditing mechanism. To determine if there are any known vulnerabilities for the software installed on the system, run: &prompt.root; pkg audit -F Automatically Removing Leaf Dependencies Removing a package may leave behind dependencies which are no longer required. Unneeded packages that were installed as dependencies can be automatically detected and removed using: &prompt.root; pkg autoremove Packages to be autoremoved: ca_root_nss-3.15.1_1 The autoremoval will free 723 kB Proceed with autoremoval of packages [y/N]: y Deinstalling ca_root_nss-3.15.1_1... done Restoring the Package Database Unlike the traditional package management system, pkg includes its own package database backup mechanism. This functionality is enabled by default. To disable the periodic script from backing up the package database, set daily_backup_pkgdb_enable="NO" in &man.periodic.conf.5;. To restore the contents of a previous package database backup, run the following command replacing /path/to/pkg.sql with the location of the backup: &prompt.root; pkg backup -r /path/to/pkg.sql If restoring a backup taken by the periodic script, it must be decompressed prior to being restored. To run a manual backup of the pkg database, run the following command, replacing /path/to/pkg.sql with a suitable file name and location: &prompt.root; pkg backup -d /path/to/pkg.sql Removing Stale Packages By default, pkg stores binary packages in a cache directory defined by PKG_CACHEDIR in &man.pkg.conf.5;. Only copies of the latest installed packages are kept. Older versions of pkg kept all previous packages. To remove these outdated binary packages, run: &prompt.root; pkg clean The entire cache may be cleared by running: &prompt.root; pkg clean -a Modifying Package Metadata Software within the &os; Ports Collection can undergo major version number changes. To address this, pkg has a built-in command to update package origins. This can be useful, for example, if lang/php5 is renamed to lang/php53 so that lang/php5 can now represent version 5.4. To change the package origin for the above example, run: &prompt.root; pkg set -o lang/php5:lang/php53 As another example, to update lang/ruby18 to lang/ruby19, run: &prompt.root; pkg set -o lang/ruby18:lang/ruby19 As a final example, to change the origin of the libglut shared libraries from graphics/libglut to graphics/freeglut, run: &prompt.root; pkg set -o graphics/libglut:graphics/freeglut When changing package origins, it is important to reinstall packages that are dependent on the package with the modified origin. To force a reinstallation of dependent packages, run: &prompt.root; pkg install -Rf graphics/freeglut Using the Ports Collection The Ports Collection is a set of Makefiles, patches, and description files. Each set of these files is used to compile and install an individual application on &os;, and is called a port. By default, the Ports Collection itself is stored as a subdirectory of /usr/ports. Before an application can be compiled using a port, the Ports Collection must first be installed. If it was not installed during the installation of &os;, use one of the following methods to install it: Portsnap Method The base system of &os; includes Portsnap. This is a fast and user-friendly tool for retrieving the Ports Collection and is the recommended choice for most users. This utility connects to a &os; site, verifies the secure key, and downloads a new copy of the Ports Collection. The key is used to verify the integrity of all downloaded files. To download a compressed snapshot of the Ports Collection into /var/db/portsnap: &prompt.root; portsnap fetch When running Portsnap for the first time, extract the snapshot into /usr/ports: &prompt.root; portsnap extract After the first use of Portsnap has been completed as shown above, /usr/ports can be updated as needed by running: &prompt.root; portsnap fetch &prompt.root; portsnap update When using fetch, the extract or the update operation may be run consecutively, like so: &prompt.root; portsnap fetch update Subversion Method If more control over the ports tree is needed or if local changes need to be maintained, Subversion can be used to obtain the Ports Collection. Refer to the Subversion Primer for a detailed description of Subversion. Subversion must be installed before it can be used to check out the ports tree. If a copy of the ports tree is already present, install Subversion like this: &prompt.root; cd /usr/ports/devel/subversion &prompt.root; make install clean If the ports tree is not available, or pkg is being used to manage packages, Subversion can be installed as a package: &prompt.root; pkg install subversion Check out a copy of the ports tree: &prompt.root; svn checkout https://svn.FreeBSD.org/ports/head /usr/ports As needed, update /usr/ports after the initial Subversion checkout: &prompt.root; svn update /usr/ports The Ports Collection contains directories for software categories. Inside each category are subdirectories for individual applications. Each application subdirectory contains a set of files that tells &os; how to compile and install that program, called a ports skeleton. Each port skeleton includes these files and directories: Makefile: contains statements that specify how the application should be compiled and where its components should be installed. distinfo: contains the names and checksums of the files that must be downloaded to build the port. files/: this directory contains any patches needed for the program to compile and install on &os;. This directory may also contain other files used to build the port. pkg-descr: provides a more detailed description of the program. pkg-plist: a list of all the files that will be installed by the port. It also tells the ports system which files to remove upon deinstallation. Some ports include pkg-message or other files to handle special situations. For more details on these files, and on ports in general, refer to the &os; Porter's Handbook. The port does not include the actual source code, also known as a distfile. The extract portion of building a port will automatically save the downloaded source to /usr/ports/distfiles. Installing Ports ports installing This section provides basic instructions on using the Ports Collection to install or remove software. The detailed description of available make targets and environment variables is available in &man.ports.7;. Before compiling any port, be sure to update the Ports Collection as described in the previous section. Since the installation of any third-party software can introduce security vulnerabilities, it is recommended to first check for known security issues related to the port. Alternately, run pkg audit -F before installing a new port. This command can be configured to automatically perform a security audit and an update of the vulnerability database during the daily security system check. For more information, refer to &man.pkg-audit.8; and &man.periodic.8;. Using the Ports Collection assumes a working Internet connection. It also requires superuser privilege. To compile and install the port, change to the directory of the port to be installed, then type make install at the prompt. Messages will indicate the progress: &prompt.root; cd /usr/ports/sysutils/lsof &prompt.root; make install >> lsof_4.88D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/. >> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/. ===> Extracting for lsof-4.88 ... [extraction output snipped] ... >> Checksum OK for lsof_4.88D.freebsd.tar.gz. ===> Patching for lsof-4.88.d,8 ===> Applying FreeBSD patches for lsof-4.88.d,8 ===> Configuring for lsof-4.88.d,8 ... [configure output snipped] ... ===> Building for lsof-4.88.d,8 ... [compilation output snipped] ... ===> Installing for lsof-4.88.d,8 ... [installation output snipped] ... ===> Generating temporary packing list ===> Compressing manual pages for lsof-4.88.d,8 ===> Registering installation for lsof-4.88.d,8 ===> SECURITY NOTE: This port has installed the following binaries which execute with increased privileges. /usr/local/sbin/lsof &prompt.root; Since lsof is a program that runs with increased privileges, a security warning is displayed as it is installed. Once the installation is complete, the prompt will be returned. Some shells keep a cache of the commands that are available in the directories listed in the PATH environment variable, to speed up lookup operations for the executable file of these commands. Users of the tcsh shell should type rehash so that a newly installed command can be used without specifying its full path. Use hash -r instead for the sh shell. Refer to the documentation for the shell for more information. During installation, a working subdirectory is created which contains all the temporary files used during compilation. Removing this directory saves disk space and minimizes the chance of problems later when upgrading to the newer version of the port: &prompt.root; make clean ===> Cleaning for lsof-88.d,8 &prompt.root; To save this extra step, instead use make install clean when compiling the port. Customizing Ports Installation Some ports provide build options which can be used to enable or disable application components, provide security options, or allow for other customizations. Examples include www/firefox, security/gpgme, and mail/sylpheed-claws. If the port depends upon other ports which have configurable options, it may pause several times for user interaction as the default behavior is to prompt the user to select options from a menu. To avoid this and do all of the configuration in one batch, run make config-recursive within the port skeleton. Then, run make install [clean] to compile and install the port. When using config-recursive, the list of ports to configure are gathered by the all-depends-list target. It is recommended to run make config-recursive until all dependent ports options have been defined, and ports options screens no longer appear, to be certain that all dependency options have been configured. There are several ways to revisit a port's build options menu in order to add, remove, or change these options after a port has been built. One method is to cd into the directory containing the port and type make config. Another option is to use make showconfig. Another option is to execute make rmconfig which will remove all selected options and allow you to start over. All of these options, and others, are explained in great detail in &man.ports.7;. The ports system uses &man.fetch.1; to download the source files, which supports various environment variables. The FTP_PASSIVE_MODE, FTP_PROXY, and FTP_PASSWORD variables may need to be set if the &os; system is behind a firewall or FTP/HTTP proxy. See &man.fetch.3; for the complete list of supported variables. For users who cannot be connected to the Internet all the time, make fetch can be run within /usr/ports, to fetch all distfiles, or within a category, such as /usr/ports/net, or within the specific port skeleton. Note that if a port has any dependencies, running this command in a category or ports skeleton will not fetch the distfiles of ports from another category. Instead, use make fetch-recursive to also fetch the distfiles for all the dependencies of a port. In rare cases, such as when an organization has a local distfiles repository, the MASTER_SITES variable can be used to override the download locations specified in the Makefile. When using, specify the alternate location: &prompt.root; cd /usr/ports/directory &prompt.root; make MASTER_SITE_OVERRIDE= \ ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/ fetch The WRKDIRPREFIX and PREFIX variables can override the default working and target directories. For example: &prompt.root; make WRKDIRPREFIX=/usr/home/example/ports install will compile the port in /usr/home/example/ports and install everything under /usr/local. &prompt.root; make PREFIX=/usr/home/example/local install will compile the port in /usr/ports and install it in /usr/home/example/local. And: &prompt.root; make WRKDIRPREFIX=../ports PREFIX=../local install will combine the two. These can also be set as environmental variables. Refer to the manual page for your shell for instructions on how to set an environmental variable. Removing Installed Ports ports removing Installed ports can be uninstalled using pkg delete. Examples for using this command can be found in the &man.pkg-delete.8; manual page. Alternately, make deinstall can be run in the port's directory: &prompt.root; cd /usr/ports/sysutils/lsof make deinstall ===> Deinstalling for sysutils/lsof ===> Deinstalling Deinstallation has been requested for the following 1 packages: lsof-4.88.d,8 The deinstallation will free 229 kB [1/1] Deleting lsof-4.88.d,8... done It is recommended to read the messages as the port is uninstalled. If the port has any applications that depend upon it, this information will be displayed but the uninstallation will proceed. In such cases, it may be better to reinstall the application in order to prevent broken dependencies. Upgrading Ports ports upgrading Over time, newer versions of software become available in the Ports Collection. This section describes how to determine which software can be upgraded and how to perform the upgrade. To determine if newer versions of installed ports are available, ensure that the latest version of the ports tree is installed, using the updating command described in either or . On &os; 10 and later, or if the system has been converted to pkg, the following command will list the installed ports which are out of date: &prompt.root; pkg version -l "<" For &os; 9.X and lower, the following command will list the installed ports that are out of date: &prompt.root; pkg_version -l "<" Before attempting an upgrade, read /usr/ports/UPDATING from the top of the file to the date closest to the last time ports were upgraded or the system was installed. This file describes various issues and additional steps users may encounter and need to perform when updating a port, including such things as file format changes, changes in locations of configuration files, or any incompatibilities with previous versions. Make note of any instructions which match any of the ports that need upgrading and follow these instructions when performing the upgrade. Tools To Upgrade And Manage Ports ports upgrading-tools The Ports Collection contains several utilities to perform the actual upgrade. Each has its strengths and weaknesses. Historically, most installations used either Portmaster or Portupgrade. Synth is a newer alternative. The choice of which tool is best for a particular system is up to the system administrator. It is recommended practice to back up your data before using any of these tools. Upgrading Ports Using <application>Portmaster</application> portmaster ports-mgmt/portmaster is a very small utility for upgrading installed ports. It is designed to use the tools installed with the &os; base system without depending on other ports or databases. To install this utility as a port: &prompt.root; cd /usr/ports/ports-mgmt/portmaster &prompt.root; make install clean Portmaster defines four categories of ports: Root port: has no dependencies and is not a dependency of any other ports. Trunk port: has no dependencies, but other ports depend upon it. Branch port: has dependencies and other ports depend upon it. Leaf port: has dependencies but no other ports depend upon it. To list these categories and search for updates: &prompt.root; portmaster -L ===>>> Root ports (No dependencies, not depended on) ===>>> ispell-3.2.06_18 ===>>> screen-4.0.3 ===>>> New version available: screen-4.0.3_1 ===>>> tcpflow-0.21_1 ===>>> 7 root ports ... ===>>> Branch ports (Have dependencies, are depended on) ===>>> apache22-2.2.3 ===>>> New version available: apache22-2.2.8 ... ===>>> Leaf ports (Have dependencies, not depended on) ===>>> automake-1.9.6_2 ===>>> bash-3.1.17 ===>>> New version available: bash-3.2.33 ... ===>>> 32 leaf ports ===>>> 137 total installed ports ===>>> 83 have new versions available This command is used to upgrade all outdated ports: &prompt.root; portmaster -a By default, Portmaster makes a backup package before deleting the existing port. If the installation of the new version is successful, Portmaster deletes the backup. Using instructs Portmaster not to automatically delete the backup. Adding starts Portmaster in interactive mode, prompting for confirmation before upgrading each port. Many other options are available. Read through the manual page for &man.portmaster.8; for details regarding their usage. If errors are encountered during the upgrade process, add to upgrade and rebuild all ports: &prompt.root; portmaster -af Portmaster can also be used to install new ports on the system, upgrading all dependencies before building and installing the new port. To use this function, specify the location of the port in the Ports Collection: &prompt.root; portmaster shells/bash More information about ports-mgmt/portmaster may be found in its pkg-descr. Upgrading Ports Using Portupgrade portupgrade ports-mgmt/portupgrade is another utility that can be used to upgrade ports. It installs a suite of applications which can be used to manage ports. However, it is dependent upon Ruby. To install the port: &prompt.root; cd /usr/ports/ports-mgmt/portupgrade &prompt.root; make install clean Before performing an upgrade using this utility, it is recommended to scan the list of installed ports using pkgdb -F and to fix all the inconsistencies it reports. To upgrade all the outdated ports installed on the system, use portupgrade -a. Alternately, include to be asked for confirmation of every individual upgrade: &prompt.root; portupgrade -ai To upgrade only a specified application instead of all available ports, use portupgrade pkgname. It is very important to include to first upgrade all the ports required by the given application: &prompt.root; portupgrade -R firefox If is included, Portupgrade searches for available packages in the local directories listed in PKG_PATH. If none are available locally, it then fetches packages from a remote site. If packages can not be found locally or fetched remotely, Portupgrade will use ports. To avoid using ports entirely, specify . This last set of options tells Portupgrade to abort if no packages are available: &prompt.root; portupgrade -PP gnome3 To just fetch the port distfiles, or packages, if is specified, without building or installing anything, use . For further information on all of the available switches, refer to the manual page for portupgrade. More information about ports-mgmt/portupgrade may be found in its pkg-descr. Ports and Disk Space ports disk-space Using the Ports Collection will use up disk space over time. After building and installing a port, running make clean within the ports skeleton will clean up the temporary work directory. If Portmaster is used to install a port, it will automatically remove this directory unless is specified. If Portupgrade is installed, this command will remove all work directories found within the local copy of the Ports Collection: &prompt.root; portsclean -C In addition, outdated source distribution files accumulate in /usr/ports/distfiles over time. To use Portupgrade to delete all the distfiles that are no longer referenced by any ports: &prompt.root; portsclean -D Portupgrade can remove all distfiles not referenced by any port currently installed on the system: &prompt.root; portsclean -DD If Portmaster is installed, use: &prompt.root; portmaster --clean-distfiles By default, this command is interactive and prompts the user to confirm if a distfile should be deleted. In addition to these commands, ports-mgmt/pkg_cutleaves automates the task of removing installed ports that are no longer needed. Building Packages with <application>Poudriere</application> Poudriere is a BSD-licensed utility for creating and testing &os; packages. It uses &os; jails to set up isolated compilation environments. These jails can be used to build packages for versions of &os; that are different from the system on which it is installed, and also to build packages for i386 if the host is an &arch.amd64; system. Once the packages are built, they are in a layout identical to the official mirrors. These packages are usable by &man.pkg.8; and other package management tools. Poudriere is installed using the ports-mgmt/poudriere package or port. The installation includes a sample configuration file /usr/local/etc/poudriere.conf.sample. Copy this file to /usr/local/etc/poudriere.conf. Edit the copied file to suit the local configuration. While ZFS is not required on the system running poudriere, it is beneficial. When ZFS is used, ZPOOL must be specified in /usr/local/etc/poudriere.conf and FREEBSD_HOST should be set to a nearby mirror. Defining CCACHE_DIR enables the use of devel/ccache to cache compilation and reduce build times for frequently-compiled code. It may be convenient to put poudriere datasets in an isolated tree mounted at /poudriere. Defaults for the other configuration values are adequate. The number of processor cores detected is used to define how many builds will run in parallel. Supply enough virtual memory, either with RAM or swap space. If virtual memory runs out, the compilation jails will stop and be torn down, resulting in weird error messages. Initialize Jails and Port Trees After configuration, initialize poudriere so that it installs a jail with the required &os; tree and a ports tree. Specify a name for the jail using and the &os; version with . On systems running &os;/&arch.amd64;, the architecture can be set with to either i386 or amd64. The default is the architecture shown by uname. &prompt.root; poudriere jail -c -j 10amd64 -v 10.0-RELEASE ====>> Creating 10amd64 fs... done ====>> Fetching base.txz for FreeBSD 10.0-RELEASE amd64 /poudriere/jails/10amd64/fromftp/base.txz 100% of 59 MB 1470 kBps 00m42s ====>> Extracting base.txz... done ====>> Fetching src.txz for FreeBSD 10.0-RELEASE amd64 /poudriere/jails/10amd64/fromftp/src.txz 100% of 107 MB 1476 kBps 01m14s ====>> Extracting src.txz... done ====>> Fetching games.txz for FreeBSD 10.0-RELEASE amd64 /poudriere/jails/10amd64/fromftp/games.txz 100% of 865 kB 734 kBps 00m01s ====>> Extracting games.txz... done ====>> Fetching lib32.txz for FreeBSD 10.0-RELEASE amd64 /poudriere/jails/10amd64/fromftp/lib32.txz 100% of 14 MB 1316 kBps 00m12s ====>> Extracting lib32.txz... done ====>> Cleaning up... done ====>> Jail 10amd64 10.0-RELEASE amd64 is ready to be used &prompt.root; poudriere ports -c -p local ====>> Creating local fs... done ====>> Extracting portstree "local"... Looking up portsnap.FreeBSD.org mirrors... 7 mirrors found. Fetching public key from ec2-eu-west-1.portsnap.freebsd.org... done. Fetching snapshot tag from ec2-eu-west-1.portsnap.freebsd.org... done. Fetching snapshot metadata... done. Fetching snapshot generated at Tue Feb 11 01:07:15 CET 2014: 94a3431f0ce567f6452ffde4fd3d7d3c6e1da143efec76100% of 69 MB 1246 kBps 00m57s Extracting snapshot... done. Verifying snapshot integrity... done. Fetching snapshot tag from ec2-eu-west-1.portsnap.freebsd.org... done. Fetching snapshot metadata... done. Updating from Tue Feb 11 01:07:15 CET 2014 to Tue Feb 11 16:05:20 CET 2014. Fetching 4 metadata patches... done. Applying metadata patches... done. Fetching 0 metadata files... done. Fetching 48 patches. (48/48) 100.00% done. done. Applying patches... done. Fetching 1 new ports or files... done. /poudriere/ports/tester/CHANGES /poudriere/ports/tester/COPYRIGHT [...] Building new INDEX files... done. On a single computer, poudriere can build ports with multiple configurations, in multiple jails, and from different port trees. Custom configurations for these combinations are called sets. See the CUSTOMIZATION section of &man.poudriere.8; for details after ports-mgmt/poudriere or ports-mgmt/poudriere-devel is installed. The basic configuration shown here puts a single jail-, port-, and set-specific make.conf in /usr/local/etc/poudriere.d. The filename in this example is created by combining the jail name, port name, and set name: 10amd64-local-workstation-make.conf. The system make.conf and this new file are combined at build time to create the make.conf used by the build jail. Packages to be built are entered in 10amd64-local-workstation-pkglist: editors/emacs devel/git ports-mgmt/pkg ... Options and dependencies for the specified ports are configured: &prompt.root; poudriere options -j 10amd64 -p local -z workstation -f 10amd64-local-workstation-pkglist Finally, packages are built and a package repository is created: &prompt.root; poudriere bulk -j 10amd64 -p local -z workstation -f 10amd64-local-workstation-pkglist While running, pressing Ctrlt displays the current state of the build. Poudriere also builds files in /poudriere/logs/bulk/jailname that can be used with a web server to display build information. After completion, the new packages are now available for installation from the poudriere repository. For more information on using poudriere, see &man.poudriere.8; and the main web site, . Configuring pkg Clients to Use a Poudriere Repository While it is possible to use both a custom repository along side of the official repository, sometimes it is useful to disable the official repository. This is done by creating a configuration file that overrides and disables the official configuration file. Create /usr/local/etc/pkg/repos/FreeBSD.conf that contains the following: FreeBSD: { enabled: no } Usually it is easiest to serve a poudriere repository to the client machines via HTTP. Set up a webserver to serve up the package directory, for instance: /usr/local/poudriere/data/packages/10amd64, where 10amd64 is the name of the build. If the URL to the package repository is: http://pkg.example.com/10amd64, then the repository configuration file in /usr/local/etc/pkg/repos/custom.conf would look like: custom: { url: "http://pkg.example.com/10amd64", enabled: yes, } Post-Installation Considerations Regardless of whether the software was installed from a binary package or port, most third-party applications require some level of configuration after installation. The following commands and locations can be used to help determine what was installed with the application. Most applications install at least one default configuration file in /usr/local/etc. In cases where an application has a large number of configuration files, a subdirectory will be created to hold them. Often, sample configuration files are installed which end with a suffix such as .sample. The configuration files should be reviewed and possibly edited to meet the system's needs. To edit a sample file, first copy it without the .sample extension. Applications which provide documentation will install it into /usr/local/share/doc and many applications also install manual pages. This documentation should be consulted before continuing. Some applications run services which must be added to /etc/rc.conf before starting the application. These applications usually install a startup script in /usr/local/etc/rc.d. See Starting Services for more information. By design, applications do not run their startup script upon installation, nor do they run their stop script upon deinstallation or upgrade. This decision is left to the individual system administrator. Users of &man.csh.1; should run rehash to rebuild the known binary list in the shells PATH. Use pkg info to determine which files, man pages, and binaries were installed with the application. Dealing with Broken Ports When a port does not build or install, try the following: Search to see if there is a fix pending for the port in the Problem Report database. If so, implementing the proposed fix may fix the issue. Ask the maintainer of the port for help. Type make maintainer in the ports skeleton or read the port's Makefile to find the maintainer's email address. Remember to include the $FreeBSD: line from the port's Makefile and the output leading up to the error in the email to the maintainer. Some ports are not maintained by an individual but instead by a group maintainer represented by a mailing list. Many, but not all, of these addresses look like freebsd-listname@FreeBSD.org. Please take this into account when sending an email. In particular, ports maintained by ports@FreeBSD.org are not maintained by a specific individual. Instead, any fixes and support come from the general community who subscribe to that mailing list. More volunteers are always needed! If there is no response to the email, use Bugzilla to submit a bug report using the instructions in Writing &os; Problem Reports. Fix it! The Porter's Handbook includes detailed information on the ports infrastructure so that you can fix the occasional broken port or even submit your own! Install the package instead of the port using the instructions in . Index: head/en_US.ISO8859-1/books/handbook/security/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/handbook/security/chapter.xml (revision 50967) +++ head/en_US.ISO8859-1/books/handbook/security/chapter.xml (revision 50968) @@ -1,4147 +1,4147 @@ Security Tom Rhodes Rewritten by security Synopsis Security, whether physical or virtual, is a topic so broad that an entire industry has evolved around it. Hundreds of standard practices have been authored about how to secure systems and networks, and as a user of &os;, understanding how to protect against attacks and intruders is a must. In this chapter, several fundamentals and techniques will be discussed. The &os; system comes with multiple layers of security, and many more third party utilities may be added to enhance security. After reading this chapter, you will know: Basic &os; system security concepts. The various crypt mechanisms available in &os;. How to set up one-time password authentication. How to configure TCP Wrapper for use with &man.inetd.8;. How to set up Kerberos on &os;. How to configure IPsec and create a VPN. How to configure and use OpenSSH on &os;. How to use file system ACLs. How to use pkg to audit third party software packages installed from the Ports Collection. How to utilize &os; security advisories. What Process Accounting is and how to enable it on &os;. How to control user resources using login classes or the resource limits database. Before reading this chapter, you should: Understand basic &os; and Internet concepts. Additional security topics are covered elsewhere in this Handbook. For example, Mandatory Access Control is discussed in and Internet firewalls are discussed in . Introduction Security is everyone's responsibility. A weak entry point in any system could allow intruders to gain access to critical information and cause havoc on an entire network. One of the core principles of information security is the CIA triad, which stands for the Confidentiality, Integrity, and Availability of information systems. The CIA triad is a bedrock concept of computer security as customers and users expect their data to be protected. For example, a customer expects that their credit card information is securely stored (confidentiality), that their orders are not changed behind the scenes (integrity), and that they have access to their order information at all times (availablility). To provide CIA, security professionals apply a defense in depth strategy. The idea of defense in depth is to add several layers of security to prevent one single layer failing and the entire security system collapsing. For example, a system administrator cannot simply turn on a firewall and consider the network or system secure. One must also audit accounts, check the integrity of binaries, and ensure malicious tools are not installed. To implement an effective security strategy, one must understand threats and how to defend against them. What is a threat as it pertains to computer security? Threats are not limited to remote attackers who attempt to access a system without permission from a remote location. Threats also include employees, malicious software, unauthorized network devices, natural disasters, security vulnerabilities, and even competing corporations. Systems and networks can be accessed without permission, sometimes by accident, or by remote attackers, and in some cases, via corporate espionage or former employees. As a user, it is important to prepare for and admit when a mistake has led to a security breach and report possible issues to the security team. As an administrator, it is important to know of the threats and be prepared to mitigate them. When applying security to systems, it is recommended to start by securing the basic accounts and system configuration, and then to secure the network layer so that it adheres to the system policy and the organization's security procedures. Many organizations already have a security policy that covers the configuration of technology devices. The policy should include the security configuration of workstations, desktops, mobile devices, phones, production servers, and development servers. In many cases, standard operating procedures (SOPs) already exist. When in doubt, ask the security team. The rest of this introduction describes how some of these basic security configurations are performed on a &os; system. The rest of this chapter describes some specific tools which can be used when implementing a security policy on a &os; system. Preventing Logins In securing a system, a good starting point is an audit of accounts. Ensure that root has a strong password and that this password is not shared. Disable any accounts that do not need login access. To deny login access to accounts, two methods exist. The first is to lock the account. This example locks the toor account: &prompt.root; pw lock toor The second method is to prevent login access by changing the shell to /sbin/nologin. Only the superuser can change the shell for other users: &prompt.root; chsh -s /usr/sbin/nologin toor The /usr/sbin/nologin shell prevents the system from assigning a shell to the user when they attempt to login. Permitted Account Escalation In some cases, system administration needs to be shared with other users. &os; has two methods to handle this. The first one, which is not recommended, is a shared root password used by members of the wheel group. With this method, a user types su and enters the password for wheel whenever superuser access is needed. The user should then type exit to leave privileged access after finishing the commands that required administrative access. To add a user to this group, edit /etc/group and add the user to the end of the wheel entry. The user must be separated by a comma character with no space. The second, and recommended, method to permit privilege escalation is to install the security/sudo package or port. This software provides additional auditing, more fine-grained user control, and can be configured to lock users into running only the specified privileged commands. After installation, use visudo to edit /usr/local/etc/sudoers. This example creates a new webadmin group, adds the trhodes account to that group, and configures that group access to restart apache24: &prompt.root; pw groupadd webadmin -M trhodes -g 6000 &prompt.root; visudo %webadmin ALL=(ALL) /usr/sbin/service apache24 * Password Hashes Passwords are a necessary evil of technology. When they must be used, they should be complex and a powerful hash mechanism should be used to encrypt the version that is stored in the password database. &os; supports the DES, MD5, SHA256, SHA512, and Blowfish hash algorithms in its crypt() library. The default of SHA512 should not be changed to a less secure hashing algorithm, but can be changed to the more secure Blowfish algorithm. Blowfish is not part of AES and is not considered compliant with any Federal Information Processing Standards (FIPS). Its use may not be permitted in some environments. To determine which hash algorithm is used to encrypt a user's password, the superuser can view the hash for the user in the &os; password database. Each hash starts with a symbol which indicates the type of hash mechanism used to encrypt the password. If DES is used, there is no beginning symbol. For MD5, the symbol is $. For SHA256 and SHA512, the symbol is $6$. For Blowfish, the symbol is $2a$. In this example, the password for dru is hashed using the default SHA512 algorithm as the hash starts with $6$. Note that the encrypted hash, not the password itself, is stored in the password database: &prompt.root; grep dru /etc/master.passwd dru:$6$pzIjSvCAn.PBYQBA$PXpSeWPx3g5kscj3IMiM7tUEUSPmGexxta.8Lt9TGSi2lNQqYGKszsBPuGME0:1001:1001::0:0:dru:/usr/home/dru:/bin/csh The hash mechanism is set in the user's login class. For this example, the user is in the default login class and the hash algorithm is set with this line in /etc/login.conf: :passwd_format=sha512:\ To change the algorithm to Blowfish, modify that line to look like this: :passwd_format=blf:\ Then run cap_mkdb /etc/login.conf as described in . Note that this change will not affect any existing password hashes. This means that all passwords should be re-hashed by asking users to run passwd in order to change their password. For remote logins, two-factor authentication should be used. An example of two-factor authentication is something you have, such as a key, and something you know, such as the passphrase for that key. Since OpenSSH is part of the &os; base system, all network logins should be over an encrypted connection and use key-based authentication instead of passwords. For more information, refer to . Kerberos users may need to make additional changes to implement OpenSSH in their network. These changes are described in . Password Policy Enforcement Enforcing a strong password policy for local accounts is a fundamental aspect of system security. In &os;, password length, password strength, and password complexity can be implemented using built-in Pluggable Authentication Modules (PAM). This section demonstrates how to configure the minimum and maximum password length and the enforcement of mixed characters using the pam_passwdqc.so module. This module is enforced when a user changes their password. To configure this module, become the superuser and uncomment the line containing pam_passwdqc.so in /etc/pam.d/passwd. Then, edit that line to match the password policy: password requisite pam_passwdqc.so min=disabled,disabled,disabled,12,10 similar=deny retry=3 enforce=users This example sets several requirements for new passwords. The min setting controls the minimum password length. It has five values because this module defines five different types of passwords based on their complexity. Complexity is defined by the type of characters that must exist in a password, such as letters, numbers, symbols, and case. The types of passwords are described in &man.pam.passwdqc.8;. In this example, the first three types of passwords are disabled, meaning that passwords that meet those complexity requirements will not be accepted, regardless of their length. The 12 sets a minimum password policy of at least twelve characters, if the password also contains characters with three types of complexity. The 10 sets the password policy to also allow passwords of at least ten characters, if the password contains characters with four types of complexity. The similar setting denies passwords that are similar to the user's previous password. The retry setting provides a user with three opportunities to enter a new password. Once this file is saved, a user changing their password will see a message similar to the following: &prompt.user; passwd Changing local password for trhodes Old Password: You can now choose the new password. A valid password should be a mix of upper and lower case letters, digits and other characters. You can use a 12 character long password with characters from at least 3 of these 4 classes, or a 10 character long password containing characters from all the classes. Characters that form a common pattern are discarded by the check. Alternatively, if noone else can see your terminal now, you can pick this as your password: "trait-useful&knob". Enter new password: If a password that does not match the policy is entered, it will be rejected with a warning and the user will have an opportunity to try again, up to the configured number of retries. Most password policies require passwords to expire after so many days. To set a password age time in &os;, set for the user's login class in /etc/login.conf. The default login class contains an example: # :passwordtime=90d:\ So, to set an expiry of 90 days for this login class, remove the comment symbol (#), save the edit, and run cap_mkdb /etc/login.conf. To set the expiration on individual users, pass an expiration date or the number of days to expiry and a username to pw: &prompt.root; pw usermod -p 30-apr-2015 -n trhodes As seen here, an expiration date is set in the form of day, month, and year. For more information, see &man.pw.8;. Detecting Rootkits A rootkit is any unauthorized software that attempts to gain root access to a system. Once installed, this malicious software will normally open up another avenue of entry for an attacker. Realistically, once a system has been compromised by a rootkit and an investigation has been performed, the system should be reinstalled from scratch. There is tremendous risk that even the most prudent security or systems engineer will miss something an attacker left behind. A rootkit does do one thing useful for administrators: once detected, it is a sign that a compromise happened at some point. But, these types of applications tend to be very well hidden. This section demonstrates a tool that can be used to detect rootkits, security/rkhunter. After installation of this package or port, the system may be checked using the following command. It will produce a lot of information and will require some manual pressing of ENTER: &prompt.root; rkhunter -c After the process completes, a status message will be printed to the screen. This message will include the amount of files checked, suspect files, possible rootkits, and more. During the check, some generic security warnings may be produced about hidden files, the OpenSSH protocol selection, and known vulnerable versions of installed software. These can be handled now or after a more detailed analysis has been performed. Every administrator should know what is running on the systems they are responsible for. Third-party tools like rkhunter and sysutils/lsof, and native commands such as netstat and ps, can show a great deal of information on the system. Take notes on what is normal, ask questions when something seems out of place, and be paranoid. While preventing a compromise is ideal, detecting a compromise is a must. Binary Verification Verification of system files and binaries is important because it provides the system administration and security teams information about system changes. A software application that monitors the system for changes is called an Intrusion Detection System (IDS). &os; provides native support for a basic IDS system. While the nightly security emails will notify an administrator of changes, the information is stored locally and there is a chance that a malicious user could modify this information in order to hide their changes to the system. As such, it is recommended to create a separate set of binary signatures and store them on a read-only, root-owned directory or, preferably, on a removable USB disk or remote rsync server. The built-in mtree utility can be used to generate a specification of the contents of a directory. A seed, or a numeric constant, is used to generate the specification and is required to check that the specification has not changed. This makes it possible to determine if a file or binary has been modified. Since the seed value is unknown by an attacker, faking or checking the checksum values of files will be difficult to impossible. The following example generates a set of SHA256 hashes, one for each system binary in /bin, and saves those values to a hidden file in root's home directory, /root/.bin_chksum_mtree: &prompt.root; mtree -s 3483151339707503 -c -K cksum,sha256digest -p /bin > /root/.bin_chksum_mtree &prompt.root; mtree: /bin checksum: 3427012225 The 3483151339707503 represents the seed. This value should be remembered, but not shared. Viewing /root/.bin_cksum_mtree should yield output similar to the following: # user: root # machine: dreadnaught # tree: /bin # date: Mon Feb 3 10:19:53 2014 # . /set type=file uid=0 gid=0 mode=0555 nlink=1 flags=none . type=dir mode=0755 nlink=2 size=1024 \ time=1380277977.000000000 \133 nlink=2 size=11704 time=1380277977.000000000 \ cksum=484492447 \ sha256digest=6207490fbdb5ed1904441fbfa941279055c3e24d3a4049aeb45094596400662a cat size=12096 time=1380277975.000000000 cksum=3909216944 \ sha256digest=65ea347b9418760b247ab10244f47a7ca2a569c9836d77f074e7a306900c1e69 chflags size=8168 time=1380277975.000000000 cksum=3949425175 \ sha256digest=c99eb6fc1c92cac335c08be004a0a5b4c24a0c0ef3712017b12c89a978b2dac3 chio size=18520 time=1380277975.000000000 cksum=2208263309 \ sha256digest=ddf7c8cb92a58750a675328345560d8cc7fe14fb3ccd3690c34954cbe69fc964 chmod size=8640 time=1380277975.000000000 cksum=2214429708 \ sha256digest=a435972263bf814ad8df082c0752aa2a7bdd8b74ff01431ccbd52ed1e490bbe7 The machine's hostname, the date and time the specification was created, and the name of the user who created the specification are included in this report. There is a checksum, size, time, and SHA256 digest for each binary in the directory. To verify that the binary signatures have not changed, compare the current contents of the directory to the previously generated specification, and save the results to a file. This command requires the seed that was used to generate the original specification: &prompt.root; mtree -s 3483151339707503 -p /bin < /root/.bin_chksum_mtree >> /root/.bin_chksum_output &prompt.root; mtree: /bin checksum: 3427012225 This should produce the same checksum for /bin that was produced when the specification was created. If no changes have occurred to the binaries in this directory, the /root/.bin_chksum_output output file will be empty. To simulate a change, change the date on /bin/cat using touch and run the verification command again: &prompt.root; touch /bin/cat &prompt.root; mtree -s 3483151339707503 -p /bin < /root/.bin_chksum_mtree >> /root/.bin_chksum_output &prompt.root; more /root/.bin_chksum_output cat changed modification time expected Fri Sep 27 06:32:55 2013 found Mon Feb 3 10:28:43 2014 It is recommended to create specifications for the directories which contain binaries and configuration files, as well as any directories containing sensitive data. Typically, specifications are created for /bin, /sbin, /usr/bin, /usr/sbin, /usr/local/bin, /etc, and /usr/local/etc. More advanced IDS systems exist, such as security/aide. In most cases, mtree provides the functionality administrators need. It is important to keep the seed value and the checksum output hidden from malicious users. More information about mtree can be found in &man.mtree.8;. System Tuning for Security In &os;, many system features can be tuned using sysctl. A few of the security features which can be tuned to prevent Denial of Service (DoS) attacks will be covered in this section. More information about using sysctl, including how to temporarily change values and how to make the changes permanent after testing, can be found in . Any time a setting is changed with sysctl, the chance to cause undesired harm is increased, affecting the availability of the system. All changes should be monitored and, if possible, tried on a testing system before being used on a production system. By default, the &os; kernel boots with a security level of -1. This is called insecure mode because immutable file flags may be turned off and all devices may be read from or written to. The security level will remain at -1 unless it is altered through sysctl or by a setting in the startup scripts. The security level may be increased during system startup by setting kern_securelevel_enable to YES in /etc/rc.conf, and the value of kern_securelevel to the desired security level. See &man.security.7; and &man.init.8; for more information on these settings and the available security levels. Increasing the securelevel can break Xorg and cause other issues. Be prepared to do some debugging. The net.inet.tcp.blackhole and net.inet.udp.blackhole settings can be used to drop incoming SYN packets on closed ports without sending a return RST response. The default behavior is to return an RST to show a port is closed. Changing the default provides some level of protection against ports scans, which are used to determine which applications are running on a system. Set net.inet.tcp.blackhole to 2 and net.inet.udp.blackhole to 1. Refer to &man.blackhole.4; for more information about these settings. The net.inet.icmp.drop_redirect and net.inet.ip.redirect settings help prevent against redirect attacks. A redirect attack is a type of DoS which sends mass numbers of ICMP type 5 packets. Since these packets are not required, set net.inet.icmp.drop_redirect to 1 and set net.inet.ip.redirect to 0. Source routing is a method for detecting and accessing non-routable addresses on the internal network. This should be disabled as non-routable addresses are normally not routable on purpose. To disable this feature, set net.inet.ip.sourceroute and net.inet.ip.accept_sourceroute to 0. When a machine on the network needs to send messages to all hosts on a subnet, an ICMP echo request message is sent to the broadcast address. However, there is no reason for an external host to perform such an action. To reject all external broadcast requests, set net.inet.icmp.bmcastecho to 0. Some additional settings are documented in &man.security.7;. One-time Passwords one-time passwords security one-time passwords By default, &os; includes support for One-time Passwords In Everything (OPIE). OPIE is designed to prevent replay attacks, in which an attacker discovers a user's password and uses it to access a system. Since a password is only used once in OPIE, a discovered password is of little use to an attacker. OPIE uses a secure hash and a challenge/response system to manage passwords. The &os; implementation uses the MD5 hash by default. OPIE uses three different types of passwords. The first is the usual &unix; or Kerberos password. The second is the one-time password which is generated by opiekey. The third type of password is the secret password which is used to generate one-time passwords. The secret password has nothing to do with, and should be different from, the &unix; password. There are two other pieces of data that are important to OPIE. One is the seed or key, consisting of two letters and five digits. The other is the iteration count, a number between 1 and 100. OPIE creates the one-time password by concatenating the seed and the secret password, applying the MD5 hash as many times as specified by the iteration count, and turning the result into six short English words which represent the one-time password. The authentication system keeps track of the last one-time password used, and the user is authenticated if the hash of the user-provided password is equal to the previous password. Because a one-way hash is used, it is impossible to generate future one-time passwords if a successfully used password is captured. The iteration count is decremented after each successful login to keep the user and the login program in sync. When the iteration count gets down to 1, OPIE must be reinitialized. There are a few programs involved in this process. A one-time password, or a consecutive list of one-time passwords, is generated by passing an iteration count, a seed, and a secret password to &man.opiekey.1;. In addition to initializing OPIE, &man.opiepasswd.1; is used to change passwords, iteration counts, or seeds. The relevant credential files in /etc/opiekeys are examined by &man.opieinfo.1; which prints out the invoking user's current iteration count and seed. This section describes four different sorts of operations. The first is how to set up one-time-passwords for the first time over a secure connection. The second is how to use opiepasswd over an insecure connection. The third is how to log in over an insecure connection. The fourth is how to generate a number of keys which can be written down or printed out to use at insecure locations. Initializing <acronym>OPIE</acronym> To initialize OPIE for the first time, run this command from a secure location: &prompt.user; opiepasswd -c Adding unfurl: Only use this method from the console; NEVER from remote. If you are using telnet, xterm, or a dial-in, type ^C now or exit with no password. Then run opiepasswd without the -c parameter. Using MD5 to compute responses. Enter new secret pass phrase: Again new secret pass phrase: ID unfurl OTP key is 499 to4268 MOS MALL GOAT ARM AVID COED The sets console mode which assumes that the command is being run from a secure location, such as a computer under the user's control or a SSH session to a computer under the user's control. When prompted, enter the secret password which will be used to generate the one-time login keys. This password should be difficult to guess and should be different than the password which is associated with the user's login account. It must be between 10 and 127 characters long. Remember this password. The ID line lists the login name (unfurl), default iteration count (499), and default seed (to4268). When logging in, the system will remember these parameters and display them, meaning that they do not have to be memorized. The last line lists the generated one-time password which corresponds to those parameters and the secret password. At the next login, use this one-time password. Insecure Connection Initialization To initialize or change the secret password on an insecure system, a secure connection is needed to some place where opiekey can be run. This might be a shell prompt on a trusted machine. An iteration count is needed, where 100 is probably a good value, and the seed can either be specified or the randomly-generated one used. On the insecure connection, the machine being initialized, use &man.opiepasswd.1;: &prompt.user; opiepasswd Updating unfurl: You need the response from an OTP generator. Old secret pass phrase: otp-md5 498 to4268 ext Response: GAME GAG WELT OUT DOWN CHAT New secret pass phrase: otp-md5 499 to4269 Response: LINE PAP MILK NELL BUOY TROY ID mark OTP key is 499 gr4269 LINE PAP MILK NELL BUOY TROY To accept the default seed, press Return. Before entering an access password, move over to the secure connection and give it the same parameters: &prompt.user; opiekey 498 to4268 Using the MD5 algorithm to compute response. Reminder: Do not use opiekey from telnet or dial-in sessions. Enter secret pass phrase: GAME GAG WELT OUT DOWN CHAT Switch back over to the insecure connection, and copy the generated one-time password over to the relevant program. Generating a Single One-time Password After initializing OPIE and logging in, a prompt like this will be displayed: &prompt.user; telnet example.com Trying 10.0.0.1... Connected to example.com Escape character is '^]'. FreeBSD/i386 (example.com) (ttypa) login: <username> otp-md5 498 gr4269 ext Password: The OPIE prompts provides a useful feature. If Return is pressed at the password prompt, the prompt will turn echo on and display what is typed. This can be useful when attempting to type in a password by hand from a printout. MS-DOS Windows MacOS At this point, generate the one-time password to answer this login prompt. This must be done on a trusted system where it is safe to run &man.opiekey.1;. There are versions of this command for &windows;, &macos; and &os;. This command needs the iteration count and the seed as command line options. Use cut-and-paste from the login prompt on the machine being logged in to. On the trusted system: &prompt.user; opiekey 498 to4268 Using the MD5 algorithm to compute response. Reminder: Do not use opiekey from telnet or dial-in sessions. Enter secret pass phrase: GAME GAG WELT OUT DOWN CHAT Once the one-time password is generated, continue to log in. Generating Multiple One-time Passwords Sometimes there is no access to a trusted machine or secure connection. In this case, it is possible to use &man.opiekey.1; to generate a number of one-time passwords beforehand. For example: &prompt.user; opiekey -n 5 30 zz99999 Using the MD5 algorithm to compute response. Reminder: Do not use opiekey from telnet or dial-in sessions. Enter secret pass phrase: <secret password> 26: JOAN BORE FOSS DES NAY QUIT 27: LATE BIAS SLAY FOLK MUCH TRIG 28: SALT TIN ANTI LOON NEAL USE 29: RIO ODIN GO BYE FURY TIC 30: GREW JIVE SAN GIRD BOIL PHI The requests five keys in sequence, and specifies what the last iteration number should be. Note that these are printed out in reverse order of use. The really paranoid might want to write the results down by hand; otherwise, print the list. Each line shows both the iteration count and the one-time password. Scratch off the passwords as they are used. Restricting Use of &unix; Passwords OPIE can restrict the use of &unix; passwords based on the IP address of a login session. The relevant file is /etc/opieaccess, which is present by default. Refer to &man.opieaccess.5; for more information on this file and which security considerations to be aware of when using it. Here is a sample opieaccess: permit 192.168.0.0 255.255.0.0 This line allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use &unix; passwords at any time. If no rules in opieaccess are matched, the default is to deny non-OPIE logins. TCP Wrapper TomRhodesWritten by TCP Wrapper TCP Wrapper is a host-based access control system which extends the abilities of . It can be configured to provide logging support, return messages, and connection restrictions for the server daemons under the control of inetd. Refer to &man.tcpd.8; for more information about TCP Wrapper and its features. TCP Wrapper should not be considered a replacement for a properly configured firewall. Instead, TCP Wrapper should be used in conjunction with a firewall and other security enhancements in order to provide another layer of protection in the implementation of a security policy. Initial Configuration To enable TCP Wrapper in &os;, add the following lines to /etc/rc.conf: inetd_enable="YES" inetd_flags="-Ww" Then, properly configure /etc/hosts.allow. Unlike other implementations of TCP Wrapper, the use of hosts.deny is deprecated in &os;. All configuration options should be placed in /etc/hosts.allow. In the simplest configuration, daemon connection policies are set to either permit or block, depending on the options in /etc/hosts.allow. The default configuration in &os; is to allow all connections to the daemons started with inetd. Basic configuration usually takes the form of daemon : address : action, where daemon is the daemon which inetd started, address is a valid hostname, IP address, or an IPv6 address enclosed in brackets ([ ]), and action is either allow or deny. TCP Wrapper uses a first rule match semantic, meaning that the configuration file is scanned from the beginning for a matching rule. When a match is found, the rule is applied and the search process stops. For example, to allow POP3 connections via the mail/qpopper daemon, the following lines should be appended to hosts.allow: # This line is required for POP3 connections: qpopper : ALL : allow Whenever this file is edited, restart inetd: &prompt.root; service inetd restart Advanced Configuration TCP Wrapper provides advanced options to allow more control over the way connections are handled. In some cases, it may be appropriate to return a comment to certain hosts or daemon connections. In other cases, a log entry should be recorded or an email sent to the administrator. Other situations may require the use of a service for local connections only. This is all possible through the use of configuration options known as wildcards, expansion characters, and external command execution. Suppose that a situation occurs where a connection should be denied yet a reason should be sent to the host who attempted to establish that connection. That action is possible with . When a connection attempt is made, executes a shell command or script. An example exists in hosts.allow: # The rest of the daemons are protected. ALL : ALL \ : severity auth.info \ : twist /bin/echo "You are not welcome to use %d from %h." In this example, the message You are not allowed to use daemon name from hostname. will be returned for any daemon not configured in hosts.allow. This is useful for sending a reply back to the connection initiator right after the established connection is dropped. Any message returned must be wrapped in quote (") characters. It may be possible to launch a denial of service attack on the server if an attacker floods these daemons with connection requests. Another possibility is to use . Like , implicitly denies the connection and may be used to run external shell commands or scripts. Unlike , will not send a reply back to the host who established the connection. For example, consider the following configuration: # We do not allow connections from example.com: ALL : .example.com \ : spawn (/bin/echo %a from %h attempted to access %d >> \ /var/log/connections.log) \ : deny This will deny all connection attempts from *.example.com and log the hostname, IP address, and the daemon to which access was attempted to /var/log/connections.log. This example uses the substitution characters %a and %h. Refer to &man.hosts.access.5; for the complete list. To match every instance of a daemon, domain, or IP address, use ALL. Another wildcard is PARANOID which may be used to match any host which provides an IP address that may be forged because the IP address differs from its resolved hostname. In this example, all connection requests to Sendmail which have an IP address that varies from its hostname will be denied: # Block possibly spoofed requests to sendmail: sendmail : PARANOID : deny Using the PARANOID wildcard will result in denied connections if the client or server has a broken DNS setup. To learn more about wildcards and their associated functionality, refer to &man.hosts.access.5;. When adding new configuration lines, make sure that any unneeded entries for that daemon are commented out in hosts.allow. <application>Kerberos</application> Tillman Hodgson Contributed by Mark Murray Based on a contribution by Kerberos is a network authentication protocol which was originally created by the Massachusetts Institute of Technology (MIT) as a way to securely provide authentication across a potentially hostile network. The Kerberos protocol uses strong cryptography so that both a client and server can prove their identity without sending any unencrypted secrets over the network. Kerberos can be described as an identity-verifying proxy system and as a trusted third-party authentication system. After a user authenticates with Kerberos, their communications can be encrypted to assure privacy and data integrity. The only function of Kerberos is to provide the secure authentication of users and servers on the network. It does not provide authorization or auditing functions. It is recommended that Kerberos be used with other security methods which provide authorization and audit services. The current version of the protocol is version 5, described in RFC 4120. Several free implementations of this protocol are available, covering a wide range of operating systems. MIT continues to develop their Kerberos package. It is commonly used in the US as a cryptography product, and has historically been subject to US export regulations. In &os;, MIT Kerberos is available as the security/krb5 package or port. The Heimdal Kerberos implementation was explicitly developed outside of the US to avoid export regulations. The Heimdal Kerberos distribution is included in the base &os; installation, and another distribution with more configurable options is available as security/heimdal in the Ports Collection. In Kerberos users and services are identified as principals which are contained within an administrative grouping, called a realm. A typical user principal would be of the form user@REALM (realms are traditionally uppercase). This section provides a guide on how to set up Kerberos using the Heimdal distribution included in &os;. For purposes of demonstrating a Kerberos installation, the name spaces will be as follows: The DNS domain (zone) will be example.org. The Kerberos realm will be EXAMPLE.ORG. Use real domain names when setting up Kerberos, even if it will run internally. This avoids DNS problems and assures inter-operation with other Kerberos realms. Setting up a Heimdal <acronym>KDC</acronym> Kerberos5 Key Distribution Center The Key Distribution Center (KDC) is the centralized authentication service that Kerberos provides, the trusted third party of the system. It is the computer that issues Kerberos tickets, which are used for clients to authenticate to servers. Because the KDC is considered trusted by all other computers in the Kerberos realm, it has heightened security concerns. Direct access to the KDC should be limited. While running a KDC requires few computing resources, a dedicated machine acting only as a KDC is recommended for security reasons. To begin setting up a KDC, add these lines to /etc/rc.conf: kdc_enable="YES" kadmind_enable="YES" Next, edit /etc/krb5.conf as follows: [libdefaults] default_realm = EXAMPLE.ORG [realms] EXAMPLE.ORG = { kdc = kerberos.example.org admin_server = kerberos.example.org } [domain_realm] .example.org = EXAMPLE.ORG In this example, the KDC will use the fully-qualified hostname kerberos.example.org. The hostname of the KDC must be resolvable in the DNS. Kerberos can also use the DNS to locate KDCs, instead of a [realms] section in /etc/krb5.conf. For large organizations that have their own DNS servers, the above example could be trimmed to: [libdefaults] default_realm = EXAMPLE.ORG [domain_realm] .example.org = EXAMPLE.ORG With the following lines being included in the example.org zone file: _kerberos._udp IN SRV 01 00 88 kerberos.example.org. _kerberos._tcp IN SRV 01 00 88 kerberos.example.org. _kpasswd._udp IN SRV 01 00 464 kerberos.example.org. _kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org. _kerberos IN TXT EXAMPLE.ORG In order for clients to be able to find the Kerberos services, they must have either a fully configured /etc/krb5.conf or a minimally configured /etc/krb5.conf and a properly configured DNS server. Next, create the Kerberos database which contains the keys of all principals (users and hosts) encrypted with a master password. It is not required to remember this password as it will be stored in /var/heimdal/m-key; it would be reasonable to use a 45-character random password for this purpose. To create the master key, run kstash and enter a password: &prompt.root; kstash Master key: xxxxxxxxxxxxxxxxxxxxxxx Verifying password - Master key: xxxxxxxxxxxxxxxxxxxxxxx Once the master key has been created, the database should be initialized. The Kerberos administrative tool &man.kadmin.8; can be used on the KDC in a mode that operates directly on the database, without using the &man.kadmind.8; network service, as kadmin -l. This resolves the chicken-and-egg problem of trying to connect to the database before it is created. At the kadmin prompt, use init to create the realm's initial database: &prompt.root; kadmin -l kadmin> init EXAMPLE.ORG Realm max ticket life [unlimited]: Lastly, while still in kadmin, create the first principal using add. Stick to the default options for the principal for now, as these can be changed later with modify. Type ? at the prompt to see the available options. kadmin> add tillman Max ticket life [unlimited]: Max renewable life [unlimited]: Attributes []: Password: xxxxxxxx Verifying password - Password: xxxxxxxx Next, start the KDC services by running service kdc start and service kadmind start. While there will not be any kerberized daemons running at this point, it is possible to confirm that the KDC is functioning by obtaining a ticket for the principal that was just created: &prompt.user; kinit tillman tillman@EXAMPLE.ORG's Password: Confirm that a ticket was successfully obtained using klist: &prompt.user; klist Credentials cache: FILE:/tmp/krb5cc_1001 Principal: tillman@EXAMPLE.ORG Issued Expires Principal Aug 27 15:37:58 2013 Aug 28 01:37:58 2013 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG The temporary ticket can be destroyed when the test is finished: &prompt.user; kdestroy Configuring a Server to Use <application>Kerberos</application> Kerberos5 enabling services The first step in configuring a server to use Kerberos authentication is to ensure that it has the correct configuration in /etc/krb5.conf. The version from the KDC can be used as-is, or it can be regenerated on the new system. Next, create /etc/krb5.keytab on the server. This is the main part of Kerberizing a service — it corresponds to generating a secret shared between the service and the KDC. The secret is a cryptographic key, stored in a keytab. The keytab contains the server's host key, which allows it and the KDC to verify each others' identity. It must be transmitted to the server in a secure fashion, as the security of the server can be broken if the key is made public. Typically, the keytab is generated on an administrator's trusted machine using kadmin, then securely transferred to the server, e.g., with &man.scp.1;; it can also be created directly on the server if that is consistent with the desired security policy. It is very important that the keytab is transmitted to the server in a secure fashion: if the key is known by some other party, that party can impersonate any user to the server! Using kadmin on the server directly is convenient, because the entry for the host principal in the KDC database is also created using kadmin. Of course, kadmin is a kerberized service; a Kerberos ticket is needed to authenticate to the network service, but to ensure that the user running kadmin is actually present (and their session has not been hijacked), kadmin will prompt for the password to get a fresh ticket. The principal authenticating to the kadmin service must be permitted to use the kadmin interface, as specified in kadmind.acl. See the section titled Remote administration in info heimdal for details on designing access control lists. Instead of enabling remote kadmin access, the administrator could securely connect to the KDC via the local console or &man.ssh.1;, and perform administration locally using kadmin -l. After installing /etc/krb5.conf, use add --random-key in kadmin. This adds the server's host principal to the database, but does not extract a copy of the host principal key to a keytab. To generate the keytab, use ext to extract the server's host principal key to its own keytab: &prompt.root; kadmin kadmin> add --random-key host/myserver.example.org Max ticket life [unlimited]: Max renewable life [unlimited]: Principal expiration time [never]: Password expiration time [never]: Attributes []: kadmin> ext_keytab host/myserver.example.org kadmin> exit Note that ext_keytab stores the extracted key in /etc/krb5.keytab by default. This is good when being run on the server being kerberized, but the --keytab path/to/file argument should be used when the keytab is being extracted elsewhere: &prompt.root; kadmin kadmin> ext_keytab --keytab=/tmp/example.keytab host/myserver.example.org kadmin> exit The keytab can then be securely copied to the server using &man.scp.1; or a removable media. Be sure to specify a non-default keytab name to avoid inserting unneeded keys into the system's keytab. At this point, the server can read encrypted messages from the KDC using its shared key, stored in krb5.keytab. It is now ready for the Kerberos-using services to be enabled. One of the most common such services is &man.sshd.8;, which supports Kerberos via the GSS-API. In /etc/ssh/sshd_config, add the line: GSSAPIAuthentication yes After making this change, &man.sshd.8; must be restarted for the new configuration to take effect: service sshd restart. Configuring a Client to Use <application>Kerberos</application> Kerberos5 configure clients As it was for the server, the client requires configuration in /etc/krb5.conf. Copy the file in place (securely) or re-enter it as needed. Test the client by using kinit, klist, and kdestroy from the client to obtain, show, and then delete a ticket for an existing principal. Kerberos applications should also be able to connect to Kerberos enabled servers. If that does not work but obtaining a ticket does, the problem is likely with the server and not with the client or the KDC. In the case of kerberized &man.ssh.1;, GSS-API is disabled by default, so test using ssh -o GSSAPIAuthentication=yes hostname. When testing a Kerberized application, try using a packet sniffer such as tcpdump to confirm that no sensitive information is sent in the clear. Various Kerberos client applications are available. With the advent of a bridge so that applications using SASL for authentication can use GSS-API mechanisms as well, large classes of client applications can use Kerberos for authentication, from Jabber clients to IMAP clients. .k5login .k5users Users within a realm typically have their Kerberos principal mapped to a local user account. Occasionally, one needs to grant access to a local user account to someone who does not have a matching Kerberos principal. For example, tillman@EXAMPLE.ORG may need access to the local user account webdevelopers. Other principals may also need access to that local account. The .k5login and .k5users files, placed in a user's home directory, can be used to solve this problem. For example, if the following .k5login is placed in the home directory of webdevelopers, both principals listed will have access to that account without requiring a shared password: tillman@example.org jdoe@example.org Refer to &man.ksu.1; for more information about .k5users. <acronym>MIT</acronym> Differences The major difference between the MIT and Heimdal implementations is that kadmin has a different, but equivalent, set of commands and uses a different protocol. If the KDC is MIT, the Heimdal version of kadmin cannot be used to administer the KDC remotely, and vice versa. Client applications may also use slightly different command line options to accomplish the same tasks. Following the instructions at http://web.mit.edu/Kerberos/www/ is recommended. Be careful of path issues: the MIT port installs into /usr/local/ by default, and the &os; system applications run instead of the MIT versions if PATH lists the system directories first. When using MIT Kerberos as a KDC on &os;, the following edits should also be made to rc.conf: kerberos5_server="/usr/local/sbin/krb5kdc" kadmind5_server="/usr/local/sbin/kadmind" kerberos5_server_flags="" kerberos5_server_enable="YES" kadmind5_server_enable="YES" <application>Kerberos</application> Tips, Tricks, and Troubleshooting When configuring and troubleshooting Kerberos, keep the following points in mind: When using either Heimdal or MIT Kerberos from ports, ensure that the PATH lists the port's versions of the client applications before the system versions. If all the computers in the realm do not have synchronized time settings, authentication may fail. describes how to synchronize clocks using NTP. If the hostname is changed, the host/ principal must be changed and the keytab updated. This also applies to special keytab entries like the HTTP/ principal used for Apache's www/mod_auth_kerb. All hosts in the realm must be both forward and reverse resolvable in DNS or, at a minimum, exist in /etc/hosts. CNAMEs will work, but the A and PTR records must be correct and in place. The error message for unresolvable hosts is not intuitive: Kerberos5 refuses authentication because Read req failed: Key table entry not found. Some operating systems that act as clients to the KDC do not set the permissions for ksu to be setuid root. This means that ksu does not work. This is a permissions problem, not a KDC error. With MIT Kerberos, to allow a principal to have a ticket life longer than the default lifetime of ten hours, use modify_principal at the &man.kadmin.8; prompt to change the maxlife of both the principal in question and the krbtgt principal. The principal can then use kinit -l to request a ticket with a longer lifetime. When running a packet sniffer on the KDC to aid in troubleshooting while running kinit from a workstation, the Ticket Granting Ticket (TGT) is sent immediately, even before the password is typed. This is because the Kerberos server freely transmits a TGT to any unauthorized request. However, every TGT is encrypted in a key derived from the user's password. When a user types their password, it is not sent to the KDC, it is instead used to decrypt the TGT that kinit already obtained. If the decryption process results in a valid ticket with a valid time stamp, the user has valid Kerberos credentials. These credentials include a session key for establishing secure communications with the Kerberos server in the future, as well as the actual TGT, which is encrypted with the Kerberos server's own key. This second layer of encryption allows the Kerberos server to verify the authenticity of each TGT. Host principals can have a longer ticket lifetime. If the user principal has a lifetime of a week but the host being connected to has a lifetime of nine hours, the user cache will have an expired host principal and the ticket cache will not work as expected. When setting up krb5.dict to prevent specific bad passwords from being used as described in &man.kadmind.8;, remember that it only applies to principals that have a password policy assigned to them. The format used in krb5.dict is one string per line. Creating a symbolic link to /usr/share/dict/words might be useful. Mitigating <application>Kerberos</application> Limitations Kerberos5 limitations and shortcomings Since Kerberos is an all or nothing approach, every service enabled on the network must either be modified to work with Kerberos or be otherwise secured against network attacks. This is to prevent user credentials from being stolen and re-used. An example is when Kerberos is enabled on all remote shells but the non-Kerberized POP3 mail server sends passwords in plain text. The KDC is a single point of failure. By design, the KDC must be as secure as its master password database. The KDC should have absolutely no other services running on it and should be physically secure. The danger is high because Kerberos stores all passwords encrypted with the same master key which is stored as a file on the KDC. A compromised master key is not quite as bad as one might fear. The master key is only used to encrypt the Kerberos database and as a seed for the random number generator. As long as access to the KDC is secure, an attacker cannot do much with the master key. If the KDC is unavailable, network services are unusable as authentication cannot be performed. This can be alleviated with a single master KDC and one or more slaves, and with careful implementation of secondary or fall-back authentication using PAM. Kerberos allows users, hosts and services to authenticate between themselves. It does not have a mechanism to authenticate the KDC to the users, hosts, or services. This means that a trojanned kinit could record all user names and passwords. File system integrity checking tools like security/tripwire can alleviate this. Resources and Further Information Kerberos5 external resources The Kerberos FAQ Designing an Authentication System: a Dialog in Four Scenes RFC 4120, The Kerberos Network Authentication Service (V5) MIT Kerberos home page Heimdal Kerberos home page OpenSSL TomRhodesWritten by security OpenSSL OpenSSL is an open source implementation of the SSL and TLS protocols. It provides an encryption transport layer on top of the normal communications layer, allowing it to be intertwined with many network applications and services. The version of OpenSSL included in &os; supports the Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1 (TLSv1) network security protocols and can be used as a general cryptographic library. OpenSSL is often used to encrypt authentication of mail clients and to secure web based transactions such as credit card payments. Some ports, such as www/apache24 and databases/postgresql91-server, include a compile option for building with OpenSSL. &os; provides two versions of OpenSSL: one in the base system and one in the Ports Collection. Users can choose which version to use by default for other ports using the following knobs: WITH_OPENSSL_PORT: when set, the port will use OpenSSL from the security/openssl port, even if the version in the base system is up to date or newer. WITH_OPENSSL_BASE: when set, the port will compile against OpenSSL provided by the base system. Another common use of OpenSSL is to provide certificates for use with software applications. Certificates can be used to verify the credentials of a company or individual. If a certificate has not been signed by an external Certificate Authority (CA), such as http://www.verisign.com, the application that uses the certificate will produce a warning. There is a cost associated with obtaining a signed certificate and using a signed certificate is not mandatory as certificates can be self-signed. However, using an external authority will prevent warnings and can put users at ease. This section demonstrates how to create and use certificates on a &os; system. Refer to for an example of how to create a CA for signing one's own certificates. For more information about SSL, read the free OpenSSL Cookbook. Generating Certificates OpenSSL certificate generation To generate a certificate that will be signed by an external CA, issue the following command and input the information requested at the prompts. This input information will be written to the certificate. At the Common Name prompt, input the fully qualified name for the system that will use the certificate. If this name does not match the server, the application verifying the certificate will issue a warning to the user, rendering the verification provided by the certificate as useless. &prompt.root; openssl req -new -nodes -out req.pem -keyout cert.key -sha256 -newkey rsa:2048 Generating a 2048 bit RSA private key ..................+++ .............................................................+++ writing new private key to 'cert.key' ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:PA Locality Name (eg, city) []:Pittsburgh Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Company Organizational Unit Name (eg, section) []:Systems Administrator Common Name (eg, YOUR name) []:localhost.example.org Email Address []:trhodes@FreeBSD.org Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: An optional company name []:Another Name Other options, such as the expire time and alternate encryption algorithms, are available when creating a certificate. A complete list of options is described in &man.openssl.1;. This command will create two files in the current directory. The certificate request, req.pem, can be sent to a CA who will validate the entered credentials, sign the request, and return the signed certificate. The second file, cert.key, is the private key for the certificate and should be stored in a secure location. If this falls in the hands of others, it can be used to impersonate the user or the server. Alternately, if a signature from a CA is not required, a self-signed certificate can be created. First, generate the RSA key: &prompt.root; openssl genrsa -rand -genkey -out cert.key 2048 0 semi-random bytes loaded Generating RSA private key, 2048 bit long modulus .............................................+++ .................................................................................................................+++ e is 65537 (0x10001) Use this key to create a self-signed certificate. Follow the usual prompts for creating a certificate: &prompt.root; openssl req -new -x509 -days 365 -key cert.key -out cert.crt -sha256 You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:PA Locality Name (eg, city) []:Pittsburgh Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Company Organizational Unit Name (eg, section) []:Systems Administrator Common Name (e.g. server FQDN or YOUR name) []:localhost.example.org Email Address []:trhodes@FreeBSD.org This will create two new files in the current directory: a private key file cert.key, and the certificate itself, cert.crt. These should be placed in a directory, preferably under /etc/ssl/, which is readable only by root. Permissions of 0700 are appropriate for these files and can be set using chmod. Using Certificates One use for a certificate is to encrypt connections to the Sendmail mail server in order to prevent the use of clear text authentication. Some mail clients will display an error if the user has not installed a local copy of the certificate. Refer to the documentation included with the software for more information on certificate installation. In &os; 10.0-RELEASE and above, it is possible to create a self-signed certificate for Sendmail automatically. To enable this, add the following lines to /etc/rc.conf: sendmail_enable="YES" sendmail_cert_create="YES" sendmail_cert_cn="localhost.example.org" This will automatically create a self-signed certificate, /etc/mail/certs/host.cert, a signing key, /etc/mail/certs/host.key, and a CA certificate, /etc/mail/certs/cacert.pem. The certificate will use the Common Name specified in . After saving the edits, restart Sendmail: &prompt.root; service sendmail restart If all went well, there will be no error messages in /var/log/maillog. For a simple test, connect to the mail server's listening port using telnet: &prompt.root; telnet example.com 25 Trying 192.0.34.166... Connected to example.com. Escape character is '^]'. 220 example.com ESMTP Sendmail 8.14.7/8.14.7; Fri, 18 Apr 2014 11:50:32 -0400 (EDT) ehlo example.com 250-example.com Hello example.com [192.0.34.166], pleased to meet you 250-ENHANCEDSTATUSCODES 250-PIPELINING 250-8BITMIME 250-SIZE 250-DSN 250-ETRN 250-AUTH LOGIN PLAIN 250-STARTTLS 250-DELIVERBY 250 HELP quit 221 2.0.0 example.com closing connection Connection closed by foreign host. If the STARTTLS line appears in the output, everything is working correctly. <acronym>VPN</acronym> over <acronym>IPsec</acronym> Nik Clayton
nik@FreeBSD.org
Written by Hiten M. Pandya
hmp@FreeBSD.org
Written by IPsec Internet Protocol Security (IPsec) is a set of protocols which sit on top of the Internet Protocol (IP) layer. It allows two or more hosts to communicate in a secure manner by authenticating and encrypting each IP packet of a communication session. The &os; IPsec network stack is based on the http://www.kame.net/ implementation and supports both IPv4 and IPv6 sessions. IPsec ESP IPsec AH IPsec is comprised of the following sub-protocols: Encapsulated Security Payload (ESP): this protocol protects the IP packet data from third party interference by encrypting the contents using symmetric cryptography algorithms such as Blowfish and 3DES. Authentication Header (AH): this protocol protects the IP packet header from third party interference and spoofing by computing a cryptographic checksum and hashing the IP packet header fields with a secure hashing function. This is then followed by an additional header that contains the hash, to allow the information in the packet to be authenticated. IP Payload Compression Protocol (IPComp): this protocol tries to increase communication performance by compressing the IP payload in order to reduce the amount of data sent. These protocols can either be used together or separately, depending on the environment. VPN virtual private network VPN IPsec supports two modes of operation. The first mode, Transport Mode, protects communications between two hosts. The second mode, Tunnel Mode, is used to build virtual tunnels, commonly known as Virtual Private Networks (VPNs). Consult &man.ipsec.4; for detailed information on the IPsec subsystem in &os;. IPsec support is enabled by default on &os; 11 and later. For previous versions of &os;, add these options to a custom kernel configuration file and rebuild the kernel using the instructions in : kernel options IPSEC options IPSEC #IP security device crypto kernel options IPSEC_DEBUG If IPsec debugging support is desired, the following kernel option should also be added: options IPSEC_DEBUG #debug for IP security This rest of this chapter demonstrates the process of setting up an IPsec VPN between a home network and a corporate network. In the example scenario: Both sites are connected to the Internet through a gateway that is running &os;. The gateway on each network has at least one external IP address. In this example, the corporate LAN's external IP address is 172.16.5.4 and the home LAN's external IP address is 192.168.1.12. The internal addresses of the two networks can be either public or private IP addresses. However, the address space must not collide. For example, both networks cannot use 192.168.1.x. In this example, the corporate LAN's internal IP address is 10.246.38.1 and the home LAN's internal IP address is 10.0.0.5. Configuring a <acronym>VPN</acronym> on &os; Tom Rhodes
trhodes@FreeBSD.org
Written by To begin, security/ipsec-tools must be installed from the Ports Collection. This software provides a number of applications which support the configuration. The next requirement is to create two &man.gif.4; pseudo-devices which will be used to tunnel packets and allow both networks to communicate properly. As root, run the following commands, replacing internal and external with the real IP addresses of the internal and external interfaces of the two gateways: &prompt.root; ifconfig gif0 create &prompt.root; ifconfig gif0 internal1 internal2 &prompt.root; ifconfig gif0 tunnel external1 external2 Verify the setup on each gateway, using ifconfig. Here is the output from Gateway 1: gif0: flags=8051 mtu 1280 tunnel inet 172.16.5.4 --> 192.168.1.12 inet6 fe80::2e0:81ff:fe02:5881%gif0 prefixlen 64 scopeid 0x6 inet 10.246.38.1 --> 10.0.0.5 netmask 0xffffff00 Here is the output from Gateway 2: gif0: flags=8051 mtu 1280 tunnel inet 192.168.1.12 --> 172.16.5.4 inet 10.0.0.5 --> 10.246.38.1 netmask 0xffffff00 inet6 fe80::250:bfff:fe3a:c1f%gif0 prefixlen 64 scopeid 0x4 Once complete, both internal IP addresses should be reachable using &man.ping.8;: priv-net# ping 10.0.0.5 PING 10.0.0.5 (10.0.0.5): 56 data bytes 64 bytes from 10.0.0.5: icmp_seq=0 ttl=64 time=42.786 ms 64 bytes from 10.0.0.5: icmp_seq=1 ttl=64 time=19.255 ms 64 bytes from 10.0.0.5: icmp_seq=2 ttl=64 time=20.440 ms 64 bytes from 10.0.0.5: icmp_seq=3 ttl=64 time=21.036 ms --- 10.0.0.5 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max/stddev = 19.255/25.879/42.786/9.782 ms corp-net# ping 10.246.38.1 PING 10.246.38.1 (10.246.38.1): 56 data bytes 64 bytes from 10.246.38.1: icmp_seq=0 ttl=64 time=28.106 ms 64 bytes from 10.246.38.1: icmp_seq=1 ttl=64 time=42.917 ms 64 bytes from 10.246.38.1: icmp_seq=2 ttl=64 time=127.525 ms 64 bytes from 10.246.38.1: icmp_seq=3 ttl=64 time=119.896 ms 64 bytes from 10.246.38.1: icmp_seq=4 ttl=64 time=154.524 ms --- 10.246.38.1 ping statistics --- 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 28.106/94.594/154.524/49.814 ms As expected, both sides have the ability to send and receive ICMP packets from the privately configured addresses. Next, both gateways must be told how to route packets in order to correctly send traffic from either network. The following commands will achieve this goal: corp-net&prompt.root; route add 10.0.0.0 10.0.0.5 255.255.255.0 corp-net&prompt.root; route add net 10.0.0.0: gateway 10.0.0.5 priv-net&prompt.root; route add 10.246.38.0 10.246.38.1 255.255.255.0 priv-net&prompt.root; route add host 10.246.38.0: gateway 10.246.38.1 At this point, internal machines should be reachable from each gateway as well as from machines behind the gateways. Again, use &man.ping.8; to confirm: corp-net# ping 10.0.0.8 PING 10.0.0.8 (10.0.0.8): 56 data bytes 64 bytes from 10.0.0.8: icmp_seq=0 ttl=63 time=92.391 ms 64 bytes from 10.0.0.8: icmp_seq=1 ttl=63 time=21.870 ms 64 bytes from 10.0.0.8: icmp_seq=2 ttl=63 time=198.022 ms 64 bytes from 10.0.0.8: icmp_seq=3 ttl=63 time=22.241 ms 64 bytes from 10.0.0.8: icmp_seq=4 ttl=63 time=174.705 ms --- 10.0.0.8 ping statistics --- 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 21.870/101.846/198.022/74.001 ms priv-net# ping 10.246.38.107 PING 10.246.38.1 (10.246.38.107): 56 data bytes 64 bytes from 10.246.38.107: icmp_seq=0 ttl=64 time=53.491 ms 64 bytes from 10.246.38.107: icmp_seq=1 ttl=64 time=23.395 ms 64 bytes from 10.246.38.107: icmp_seq=2 ttl=64 time=23.865 ms 64 bytes from 10.246.38.107: icmp_seq=3 ttl=64 time=21.145 ms 64 bytes from 10.246.38.107: icmp_seq=4 ttl=64 time=36.708 ms --- 10.246.38.107 ping statistics --- 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 21.145/31.721/53.491/12.179 ms Setting up the tunnels is the easy part. Configuring a secure link is a more in depth process. The following configuration uses pre-shared (PSK) RSA keys. Other than the IP addresses, the /usr/local/etc/racoon/racoon.conf on both gateways will be identical and look similar to: path pre_shared_key "/usr/local/etc/racoon/psk.txt"; #location of pre-shared key file log debug; #log verbosity setting: set to 'notify' when testing and debugging is complete padding # options are not to be changed { maximum_length 20; randomize off; strict_check off; exclusive_tail off; } timer # timing options. change as needed { counter 5; interval 20 sec; persend 1; # natt_keepalive 15 sec; phase1 30 sec; phase2 15 sec; } listen # address [port] that racoon will listen on { isakmp 172.16.5.4 [500]; isakmp_natt 172.16.5.4 [4500]; } remote 192.168.1.12 [500] { exchange_mode main,aggressive; doi ipsec_doi; situation identity_only; my_identifier address 172.16.5.4; peers_identifier address 192.168.1.12; lifetime time 8 hour; passive off; proposal_check obey; # nat_traversal off; generate_policy off; proposal { encryption_algorithm blowfish; hash_algorithm md5; authentication_method pre_shared_key; lifetime time 30 sec; dh_group 1; } } sainfo (address 10.246.38.0/24 any address 10.0.0.0/24 any) # address $network/$netmask $type address $network/$netmask $type ( $type being any or esp) { # $network must be the two internal networks you are joining. pfs_group 1; lifetime time 36000 sec; encryption_algorithm blowfish,3des; authentication_algorithm hmac_md5,hmac_sha1; compression_algorithm deflate; } For descriptions of each available option, refer to the manual page for racoon.conf. The Security Policy Database (SPD) needs to be configured so that &os; and racoon are able to encrypt and decrypt network traffic between the hosts. This can be achieved with a shell script, similar to the following, on the corporate gateway. This file will be used during system initialization and should be saved as /usr/local/etc/racoon/setkey.conf. flush; spdflush; # To the home network spdadd 10.246.38.0/24 10.0.0.0/24 any -P out ipsec esp/tunnel/172.16.5.4-192.168.1.12/use; spdadd 10.0.0.0/24 10.246.38.0/24 any -P in ipsec esp/tunnel/192.168.1.12-172.16.5.4/use; Once in place, racoon may be started on both gateways using the following command: &prompt.root; /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf -l /var/log/racoon.log The output should be similar to the following: corp-net# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf Foreground mode. 2006-01-30 01:35:47: INFO: begin Identity Protection mode. 2006-01-30 01:35:48: INFO: received Vendor ID: KAME/racoon 2006-01-30 01:35:55: INFO: received Vendor ID: KAME/racoon 2006-01-30 01:36:04: INFO: ISAKMP-SA established 172.16.5.4[500]-192.168.1.12[500] spi:623b9b3bd2492452:7deab82d54ff704a 2006-01-30 01:36:05: INFO: initiate new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0] 2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=28496098(0x1b2d0e2) 2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=47784998(0x2d92426) 2006-01-30 01:36:13: INFO: respond new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0] 2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=124397467(0x76a279b) 2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=175852902(0xa7b4d66) To ensure the tunnel is working properly, switch to another console and use &man.tcpdump.1; to view network traffic using the following command. Replace em0 with the network interface card as required: &prompt.root; tcpdump -i em0 host 172.16.5.4 and dst 192.168.1.12 Data similar to the following should appear on the console. If not, there is an issue and debugging the returned data will be required. 01:47:32.021683 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xa) 01:47:33.022442 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xb) 01:47:34.024218 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xc) At this point, both networks should be available and seem to be part of the same network. Most likely both networks are protected by a firewall. To allow traffic to flow between them, rules need to be added to pass packets. For the &man.ipfw.8; firewall, add the following lines to the firewall configuration file: ipfw add 00201 allow log esp from any to any ipfw add 00202 allow log ah from any to any ipfw add 00203 allow log ipencap from any to any ipfw add 00204 allow log udp from any 500 to any The rule numbers may need to be altered depending on the current host configuration. For users of &man.pf.4; or &man.ipf.8;, the following rules should do the trick: pass in quick proto esp from any to any pass in quick proto ah from any to any pass in quick proto ipencap from any to any pass in quick proto udp from any port = 500 to any port = 500 pass in quick on gif0 from any to any pass out quick proto esp from any to any pass out quick proto ah from any to any pass out quick proto ipencap from any to any pass out quick proto udp from any port = 500 to any port = 500 pass out quick on gif0 from any to any Finally, to allow the machine to start support for the VPN during system initialization, add the following lines to /etc/rc.conf: ipsec_enable="YES" ipsec_program="/usr/local/sbin/setkey" ipsec_file="/usr/local/etc/racoon/setkey.conf" # allows setting up spd policies on boot racoon_enable="yes" OpenSSH ChernLeeContributed by OpenSSH security OpenSSH OpenSSH is a set of network connectivity tools used to provide secure access to remote machines. Additionally, TCP/IP connections can be tunneled or forwarded securely through SSH connections. OpenSSH encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and other network-level attacks. OpenSSH is maintained by the OpenBSD project and is installed by default in &os;. It is compatible with both SSH version 1 and 2 protocols. When data is sent over the network in an unencrypted form, network sniffers anywhere in between the client and server can steal user/password information or data transferred during the session. OpenSSH offers a variety of authentication and encryption methods to prevent this from happening. More information about OpenSSH is available from http://www.openssh.com/. This section provides an overview of the built-in client utilities to securely access other systems and securely transfer files from a &os; system. It then describes how to configure a SSH server on a &os; system. More information is available in the man pages mentioned in this chapter. Using the SSH Client Utilities OpenSSH client To log into a SSH server, use ssh and specify a username that exists on that server and the IP address or hostname of the server. If this is the first time a connection has been made to the specified server, the user will be prompted to first verify the server's fingerprint: &prompt.root; ssh user@example.com The authenticity of host 'example.com (10.0.0.1)' can't be established. ECDSA key fingerprint is 25:cc:73:b5:b3:96:75:3d:56:19:49:d2:5c:1f:91:3b. Are you sure you want to continue connecting (yes/no)? yes Permanently added 'example.com' (ECDSA) to the list of known hosts. Password for user@example.com: user_password SSH utilizes a key fingerprint system to verify the authenticity of the server when the client connects. When the user accepts the key's fingerprint by typing yes when connecting for the first time, a copy of the key is saved to .ssh/known_hosts in the user's home directory. Future attempts to login are verified against the saved key and ssh will display an alert if the server's key does not match the saved key. If this occurs, the user should first verify why the key has changed before continuing with the connection. By default, recent versions of OpenSSH only accept SSHv2 connections. By default, the client will use version 2 if possible and will fall back to version 1 if the server does not support version 2. To force ssh to only use the specified protocol, include or . Additional options are described in &man.ssh.1;. OpenSSH secure copy &man.scp.1; Use &man.scp.1; to securely copy a file to or from a remote machine. This example copies COPYRIGHT on the remote system to a file of the same name in the current directory of the local system: &prompt.root; scp user@example.com:/COPYRIGHT COPYRIGHT Password for user@example.com: ******* COPYRIGHT 100% |*****************************| 4735 00:00 &prompt.root; Since the fingerprint was already verified for this host, the server's key is automatically checked before prompting for the user's password. The arguments passed to scp are similar to cp. The file or files to copy is the first argument and the destination to copy to is the second. Since the file is fetched over the network, one or more of the file arguments takes the form . Be aware when copying directories recursively that scp uses , whereas cp uses . To open an interactive session for copying files, use sftp. Refer to &man.sftp.1; for a list of available commands while in an sftp session. Key-based Authentication Instead of using passwords, a client can be configured to connect to the remote machine using keys. To generate RSA authentication keys, use ssh-keygen. To generate a public and private key pair, specify the type of key and follow the prompts. It is recommended to protect the keys with a memorable, but hard to guess passphrase. &prompt.user; ssh-keygen -t rsa Generating public/private rsa key pair. Enter file in which to save the key (/home/user/.ssh/id_rsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/user/.ssh/id_rsa. Your public key has been saved in /home/user/.ssh/id_rsa.pub. The key fingerprint is: SHA256:54Xm9Uvtv6H4NOo6yjP/YCfODryvUU7yWHzMqeXwhq8 user@host.example.com The key's randomart image is: +---[RSA 2048]----+ | | | | | | | . o.. | | .S*+*o | | . O=Oo . . | | = Oo= oo..| | .oB.* +.oo.| | =OE**.o..=| +----[SHA256]-----+ Type a passphrase here. It can contain spaces and symbols. Retype the passphrase to verify it. The private key is stored in ~/.ssh/id_rsa and the public key is stored in ~/.ssh/id_rsa.pub. The public key must be copied to ~/.ssh/authorized_keys on the remote machine for key-based authentication to work. Many users believe that keys are secure by design and will use a key without a passphrase. This is dangerous behavior. An administrator can verify that a key pair is protected by a passphrase by viewing the private key manually. If the private key file contains the word ENCRYPTED, the key owner is using a passphrase. In addition, to better secure end users, from may be placed in the public key file. For example, adding from="192.168.10.5" in front of the ssh-rsa prefix will only allow that specific user to log in from that IP address. The options and files vary with different versions of OpenSSH. To avoid problems, consult &man.ssh-keygen.1;. If a passphrase is used, the user is prompted for the passphrase each time a connection is made to the server. To load SSH keys into memory and remove the need to type the passphrase each time, use &man.ssh-agent.1; and &man.ssh-add.1;. Authentication is handled by ssh-agent, using the private keys that are loaded into it. ssh-agent can be used to launch another application like a shell or a window manager. To use ssh-agent in a shell, start it with a shell as an argument. Add the identity by running ssh-add and entering the passphrase for the private key. The user will then be able to ssh to any host that has the corresponding public key installed. For example: &prompt.user; ssh-agent csh &prompt.user; ssh-add Enter passphrase for key '/usr/home/user/.ssh/id_rsa': Identity added: /usr/home/user/.ssh/id_rsa (/usr/home/user/.ssh/id_rsa) &prompt.user; Enter the passphrase for the key. To use ssh-agent in &xorg;, add an entry for it in ~/.xinitrc. This provides the ssh-agent services to all programs launched in &xorg;. An example ~/.xinitrc might look like this: exec ssh-agent startxfce4 This launches ssh-agent, which in turn launches XFCE, every time &xorg; starts. Once &xorg; has been restarted so that the changes can take effect, run ssh-add to load all of the SSH keys. <acronym>SSH</acronym> Tunneling OpenSSH tunneling OpenSSH has the ability to create a tunnel to encapsulate another protocol in an encrypted session. The following command tells ssh to create a tunnel for telnet: &prompt.user; ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com &prompt.user; This example uses the following options: Forces ssh to use version 2 to connect to the server. Indicates no command, or tunnel only. If omitted, ssh initiates a normal session. Forces ssh to run in the background. Indicates a local tunnel in localport:remotehost:remoteport format. The login name to use on the specified remote SSH server. An SSH tunnel works by creating a listen socket on localhost on the specified localport. It then forwards any connections received on localport via the SSH connection to the specified remotehost:remoteport. In the example, port 5023 on the client is forwarded to port 23 on the remote machine. Since port 23 is used by telnet, this creates an encrypted telnet session through an SSH tunnel. This method can be used to wrap any number of insecure TCP protocols such as SMTP, POP3, and FTP, as seen in the following examples. Create a Secure Tunnel for <acronym>SMTP</acronym> &prompt.user; ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com user@mailserver.example.com's password: ***** &prompt.user; telnet localhost 5025 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. 220 mailserver.example.com ESMTP This can be used in conjunction with ssh-keygen and additional user accounts to create a more seamless SSH tunneling environment. Keys can be used in place of typing a password, and the tunnels can be run as a separate user. Secure Access of a <acronym>POP3</acronym> Server In this example, there is an SSH server that accepts connections from the outside. On the same network resides a mail server running a POP3 server. To check email in a secure manner, create an SSH connection to the SSH server and tunnel through to the mail server: &prompt.user; ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com user@ssh-server.example.com's password: ****** Once the tunnel is up and running, point the email client to send POP3 requests to localhost on port 2110. This connection will be forwarded securely across the tunnel to mail.example.com. Bypassing a Firewall Some firewalls filter both incoming and outgoing connections. For example, a firewall might limit access from remote machines to ports 22 and 80 to only allow SSH and web surfing. This prevents access to any other service which uses a port other than 22 or 80. The solution is to create an SSH connection to a machine outside of the network's firewall and use it to tunnel to the desired service: &prompt.user; ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org user@unfirewalled-system.example.org's password: ******* In this example, a streaming Ogg Vorbis client can now be pointed to localhost port 8888, which will be forwarded over to music.example.com on port 8000, successfully bypassing the firewall. Enabling the SSH Server OpenSSH enabling In addition to providing built-in SSH client utilities, a &os; system can be configured as an SSH server, accepting connections from other SSH clients. To see if sshd is operating, use the &man.service.8; command: &prompt.root; service sshd status If the service is not running, add the following line to /etc/rc.conf. sshd_enable="YES" This will start sshd, the daemon program for OpenSSH, the next time the system boots. To start it now: &prompt.root; service sshd start The first time sshd starts on a &os; system, the system's host keys will be automatically created and the fingerprint will be displayed on the console. Provide users with the fingerprint so that they can verify it the first time they connect to the server. Refer to &man.sshd.8; for the list of available options when starting sshd and a more complete discussion about authentication, the login process, and the various configuration files. At this point, the sshd should be available to all users with a username and password on the system. SSH Server Security While sshd is the most widely used remote administration facility for &os;, brute force and drive by attacks are common to any system exposed to public networks. Several additional parameters are available to prevent the success of these attacks and will be described in this section. It is a good idea to limit which users can log into the SSH server and from where using the AllowUsers keyword in the OpenSSH server configuration file. For example, to only allow root to log in from 192.168.1.32, add this line to /etc/ssh/sshd_config: AllowUsers root@192.168.1.32 To allow admin to log in from anywhere, list that user without specifying an IP address: AllowUsers admin Multiple users should be listed on the same line, like so: AllowUsers root@192.168.1.32 admin After making changes to /etc/ssh/sshd_config, tell sshd to reload its configuration file by running: &prompt.root; service sshd reload When this keyword is used, it is important to list each user that needs to log into this machine. Any user that is not specified in that line will be locked out. Also, the keywords used in the OpenSSH server configuration file are case-sensitive. If the keyword is not spelled correctly, including its case, it will be ignored. Always test changes to this file to make sure that the edits are working as expected. Refer to &man.sshd.config.5; to verify the spelling and use of the available keywords. In addition, users may be forced to use two factor authentication via the use of a public and private key. When required, the user may generate a key pair through the use of &man.ssh-keygen.1; and send the administrator the public key. This key file will be placed in the authorized_keys as described above in the client section. To force the users to use keys only, the following option may be configured: AuthenticationMethods publickey Do not confuse /etc/ssh/sshd_config with /etc/ssh/ssh_config (note the extra d in the first filename). The first file configures the server and the second file configures the client. Refer to &man.ssh.config.5; for a listing of the available client settings. Access Control Lists TomRhodesContributed by ACL Access Control Lists (ACLs) extend the standard &unix; permission model in a &posix;.1e compatible way. This permits an administrator to take advantage of a more fine-grained permissions model. The &os; GENERIC kernel provides ACL support for UFS file systems. Users who prefer to compile a custom kernel must include the following option in their custom kernel configuration file: options UFS_ACL If this option is not compiled in, a warning message will be displayed when attempting to mount a file system with ACL support. ACLs rely on extended attributes which are natively supported in UFS2. This chapter describes how to enable ACL support and provides some usage examples. Enabling <acronym>ACL</acronym> Support ACLs are enabled by the mount-time administrative flag, , which may be added to /etc/fstab. The mount-time flag can also be automatically set in a persistent manner using &man.tunefs.8; to modify a superblock ACLs flag in the file system header. In general, it is preferred to use the superblock flag for several reasons: The superblock flag cannot be changed by a remount using as it requires a complete umount and fresh mount. This means that ACLs cannot be enabled on the root file system after boot. It also means that ACL support on a file system cannot be changed while the system is in use. Setting the superblock flag causes the file system to always be mounted with ACLs enabled, even if there is not an fstab entry or if the devices re-order. This prevents accidental mounting of the file system without ACL support. It is desirable to discourage accidental mounting without ACLs enabled because nasty things can happen if ACLs are enabled, then disabled, then re-enabled without flushing the extended attributes. In general, once ACLs are enabled on a file system, they should not be disabled, as the resulting file protections may not be compatible with those intended by the users of the system, and re-enabling ACLs may re-attach the previous ACLs to files that have since had their permissions changed, resulting in unpredictable behavior. File systems with ACLs enabled will show a plus (+) sign in their permission settings: drwx------ 2 robert robert 512 Dec 27 11:54 private drwxrwx---+ 2 robert robert 512 Dec 23 10:57 directory1 drwxrwx---+ 2 robert robert 512 Dec 22 10:20 directory2 drwxrwx---+ 2 robert robert 512 Dec 27 11:57 directory3 drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html In this example, directory1, directory2, and directory3 are all taking advantage of ACLs, whereas public_html is not. Using <acronym>ACL</acronym>s File system ACLs can be viewed using getfacl. For instance, to view the ACL settings on test: &prompt.user; getfacl test #file:test #owner:1001 #group:1001 user::rw- group::r-- other::r-- To change the ACL settings on this file, use setfacl. To remove all of the currently defined ACLs from a file or file system, include . However, the preferred method is to use as it leaves the basic fields required for ACLs to work. &prompt.user; setfacl -k test To modify the default ACL entries, use : &prompt.user; setfacl -m u:trhodes:rwx,group:web:r--,o::--- test In this example, there were no pre-defined entries, as they were removed by the previous command. This command restores the default options and assigns the options listed. If a user or group is added which does not exist on the system, an Invalid argument error will be displayed. Refer to &man.getfacl.1; and &man.setfacl.1; for more information about the options available for these commands. Monitoring Third Party Security Issues TomRhodesContributed by pkg In recent years, the security world has made many improvements to how vulnerability assessment is handled. The threat of system intrusion increases as third party utilities are installed and configured for virtually any operating system available today. Vulnerability assessment is a key factor in security. While &os; releases advisories for the base system, doing so for every third party utility is beyond the &os; Project's capability. There is a way to mitigate third party vulnerabilities and warn administrators of known security issues. A &os; add on utility known as pkg includes options explicitly for this purpose. pkg polls a database for security issues. The database is updated and maintained by the &os; Security Team and ports developers. Please refer to instructions for installing pkg. Installation provides &man.periodic.8; configuration files for maintaining the pkg audit database, and provides a programmatic method of keeping it updated. This functionality is enabled if daily_status_security_pkgaudit_enable is set to YES in &man.periodic.conf.5;. Ensure that daily security run emails, which are sent to root's email account, are being read. After installation, and to audit third party utilities as part of the Ports Collection at any time, an administrator may choose to update the database and view known vulnerabilities of installed packages by invoking: &prompt.root; pkg audit -F pkg displays messages any published vulnerabilities in installed packages: Affected package: cups-base-1.1.22.0_1 Type of problem: cups-base -- HPGL buffer overflow vulnerability. -Reference: <http://www.FreeBSD.org/ports/portaudit/40a3bca2-6809-11d9-a9e7-0001020eed82.html> +Reference: <https://www.FreeBSD.org/ports/portaudit/40a3bca2-6809-11d9-a9e7-0001020eed82.html> 1 problem(s) in your installed packages found. You are advised to update or deinstall the affected package(s) immediately. By pointing a web browser to the displayed URL, an administrator may obtain more information about the vulnerability. This will include the versions affected, by &os; port version, along with other web sites which may contain security advisories. pkg is a powerful utility and is extremely useful when coupled with ports-mgmt/portmaster. &os; Security Advisories TomRhodesContributed by &os; Security Advisories Like many producers of quality operating systems, the &os; Project has a security team which is responsible for determining the End-of-Life (EoL) date for each &os; release and to provide security updates for supported releases which have not yet reached their EoL. More information about the &os; security team and the supported releases is available on the &os; security page. One task of the security team is to respond to reported security vulnerabilities in the &os; operating system. Once a vulnerability is confirmed, the security team verifies the steps necessary to fix the vulnerability and updates the source code with the fix. It then publishes the details as a Security Advisory. Security advisories are published on the &os; website and mailed to the &a.security-notifications.name;, &a.security.name;, and &a.announce.name; mailing lists. This section describes the format of a &os; security advisory. Format of a Security Advisory Here is an example of a &os; security advisory: ============================================================================= -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 ============================================================================= FreeBSD-SA-14:04.bind Security Advisory The FreeBSD Project Topic: BIND remote denial of service vulnerability Category: contrib Module: bind Announced: 2014-01-14 Credits: ISC Affects: FreeBSD 8.x and FreeBSD 9.x Corrected: 2014-01-14 19:38:37 UTC (stable/9, 9.2-STABLE) 2014-01-14 19:42:28 UTC (releng/9.2, 9.2-RELEASE-p3) 2014-01-14 19:42:28 UTC (releng/9.1, 9.1-RELEASE-p10) 2014-01-14 19:38:37 UTC (stable/8, 8.4-STABLE) 2014-01-14 19:42:28 UTC (releng/8.4, 8.4-RELEASE-p7) 2014-01-14 19:42:28 UTC (releng/8.3, 8.3-RELEASE-p14) CVE Name: CVE-2014-0591 For general information regarding FreeBSD Security Advisories, including descriptions of the fields above, security branches, and the following sections, please visit <URL:http://security.FreeBSD.org/>. I. Background BIND 9 is an implementation of the Domain Name System (DNS) protocols. The named(8) daemon is an Internet Domain Name Server. II. Problem Description Because of a defect in handling queries for NSEC3-signed zones, BIND can crash with an "INSIST" failure in name.c when processing queries possessing certain properties. This issue only affects authoritative nameservers with at least one NSEC3-signed zone. Recursive-only servers are not at risk. III. Impact An attacker who can send a specially crafted query could cause named(8) to crash, resulting in a denial of service. IV. Workaround No workaround is available, but systems not running authoritative DNS service with at least one NSEC3-signed zone using named(8) are not vulnerable. V. Solution Perform one of the following: 1) Upgrade your vulnerable system to a supported FreeBSD stable or release / security branch (releng) dated after the correction date. 2) To update your vulnerable system via a source code patch: The following patches have been verified to apply to the applicable FreeBSD release branches. a) Download the relevant patch from the location below, and verify the detached PGP signature using your PGP utility. [FreeBSD 8.3, 8.4, 9.1, 9.2-RELEASE and 8.4-STABLE] # fetch http://security.FreeBSD.org/patches/SA-14:04/bind-release.patch # fetch http://security.FreeBSD.org/patches/SA-14:04/bind-release.patch.asc # gpg --verify bind-release.patch.asc [FreeBSD 9.2-STABLE] # fetch http://security.FreeBSD.org/patches/SA-14:04/bind-stable-9.patch # fetch http://security.FreeBSD.org/patches/SA-14:04/bind-stable-9.patch.asc # gpg --verify bind-stable-9.patch.asc b) Execute the following commands as root: # cd /usr/src # patch < /path/to/patch Recompile the operating system using buildworld and installworld as -described in <URL:http://www.FreeBSD.org/handbook/makeworld.html>. +described in <URL:https://www.FreeBSD.org/handbook/makeworld.html>. Restart the applicable daemons, or reboot the system. 3) To update your vulnerable system via a binary patch: Systems running a RELEASE version of FreeBSD on the i386 or amd64 platforms can be updated via the freebsd-update(8) utility: # freebsd-update fetch # freebsd-update install VI. Correction details The following list contains the correction revision numbers for each affected branch. Branch/path Revision - ------------------------------------------------------------------------- stable/8/ r260646 releng/8.3/ r260647 releng/8.4/ r260647 stable/9/ r260646 releng/9.1/ r260647 releng/9.2/ r260647 - ------------------------------------------------------------------------- To see which files were modified by a particular revision, run the following command, replacing NNNNNN with the revision number, on a machine with Subversion installed: # svn diff -cNNNNNN --summarize svn://svn.freebsd.org/base Or visit the following URL, replacing NNNNNN with the revision number: <URL:http://svnweb.freebsd.org/base?view=revision&revision=NNNNNN> VII. References <URL:https://kb.isc.org/article/AA-01078> <URL:http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-0591> The latest revision of this advisory is available at <URL:http://security.FreeBSD.org/advisories/FreeBSD-SA-14:04.bind.asc> -----BEGIN PGP SIGNATURE----- iQIcBAEBCgAGBQJS1ZTYAAoJEO1n7NZdz2rnOvQP/2/68/s9Cu35PmqNtSZVVxVG ZSQP5EGWx/lramNf9566iKxOrLRMq/h3XWcC4goVd+gZFrvITJSVOWSa7ntDQ7TO XcinfRZ/iyiJbs/Rg2wLHc/t5oVSyeouyccqODYFbOwOlk35JjOTMUG1YcX+Zasg ax8RV+7Zt1QSBkMlOz/myBLXUjlTZ3Xg2FXVsfFQW5/g2CjuHpRSFx1bVNX6ysoG 9DT58EQcYxIS8WfkHRbbXKh9I1nSfZ7/Hky/kTafRdRMrjAgbqFgHkYTYsBZeav5 fYWKGQRJulYfeZQ90yMTvlpF42DjCC3uJYamJnwDIu8OhS1WRBI8fQfr9DRzmRua OK3BK9hUiScDZOJB6OqeVzUTfe7MAA4/UwrDtTYQ+PqAenv1PK8DZqwXyxA9ThHb zKO3OwuKOVHJnKvpOcr+eNwo7jbnHlis0oBksj/mrq2P9m2ueF9gzCiq5Ri5Syag Wssb1HUoMGwqU0roS8+pRpNC8YgsWpsttvUWSZ8u6Vj/FLeHpiV3mYXPVMaKRhVm 067BA2uj4Th1JKtGleox+Em0R7OFbCc/9aWC67wiqI6KRyit9pYiF3npph+7D5Eq 7zPsUdDd+qc+UTiLp3liCRp5w6484wWdhZO6wRtmUgxGjNkxFoNnX8CitzF8AaqO UWWemqWuz3lAZuORQ9KX =OQzQ -----END PGP SIGNATURE----- Every security advisory uses the following format: Each security advisory is signed by the PGP key of the Security Officer. The public key for the Security Officer can be verified at . The name of the security advisory always begins with FreeBSD-SA- (for FreeBSD Security Advisory), followed by the year in two digit format (14:), followed by the advisory number for that year (04.), followed by the name of the affected application or subsystem (bind). The advisory shown here is the fourth advisory for 2014 and it affects BIND. The Topic field summarizes the vulnerability. The Category refers to the affected part of the system which may be one of core, contrib, or ports. The core category means that the vulnerability affects a core component of the &os; operating system. The contrib category means that the vulnerability affects software included with &os;, such as BIND. The ports category indicates that the vulnerability affects software available through the Ports Collection. The Module field refers to the component location. In this example, the bind module is affected; therefore, this vulnerability affects an application installed with the operating system. The Announced field reflects the date the security advisory was published. This means that the security team has verified that the problem exists and that a patch has been committed to the &os; source code repository. The Credits field gives credit to the individual or organization who noticed the vulnerability and reported it. The Affects field explains which releases of &os; are affected by this vulnerability. The Corrected field indicates the date, time, time offset, and releases that were corrected. The section in parentheses shows each branch for which the fix has been merged, and the version number of the corresponding release from that branch. The release identifier itself includes the version number and, if appropriate, the patch level. The patch level is the letter p followed by a number, indicating the sequence number of the patch, allowing users to track which patches have already been applied to the system. The CVE Name field lists the advisory number, if one exists, in the public cve.mitre.org security vulnerabilities database. The Background field provides a description of the affected module. The Problem Description field explains the vulnerability. This can include information about the flawed code and how the utility could be maliciously used. The Impact field describes what type of impact the problem could have on a system. The Workaround field indicates if a workaround is available to system administrators who cannot immediately patch the system . The Solution field provides the instructions for patching the affected system. This is a step by step tested and verified method for getting a system patched and working securely. The Correction Details field displays each affected Subversion branch with the revision number that contains the corrected code. The References field offers sources of additional information regarding the vulnerability. Process Accounting TomRhodesContributed by Process Accounting Process accounting is a security method in which an administrator may keep track of system resources used and their allocation among users, provide for system monitoring, and minimally track a user's commands. Process accounting has both positive and negative points. One of the positives is that an intrusion may be narrowed down to the point of entry. A negative is the amount of logs generated by process accounting, and the disk space they may require. This section walks an administrator through the basics of process accounting. If more fine-grained accounting is needed, refer to . Enabling and Utilizing Process Accounting Before using process accounting, it must be enabled using the following commands: &prompt.root; touch /var/account/acct &prompt.root; chmod 600 /var/account/acct &prompt.root; accton /var/account/acct &prompt.root; echo 'accounting_enable="YES"' >> /etc/rc.conf Once enabled, accounting will begin to track information such as CPU statistics and executed commands. All accounting logs are in a non-human readable format which can be viewed using sa. If issued without any options, sa prints information relating to the number of per-user calls, the total elapsed time in minutes, total CPU and user time in minutes, and the average number of I/O operations. Refer to &man.sa.8; for the list of available options which control the output. To display the commands issued by users, use lastcomm. For example, this command prints out all usage of ls by trhodes on the ttyp1 terminal: &prompt.root; lastcomm ls trhodes ttyp1 Many other useful options exist and are explained in &man.lastcomm.1;, &man.acct.5;, and &man.sa.8;. Resource Limits TomRhodesContributed by Resource limits &os; provides several methods for an administrator to limit the amount of system resources an individual may use. Disk quotas limit the amount of disk space available to users. Quotas are discussed in . quotas limiting users quotas disk quotas Limits to other resources, such as CPU and memory, can be set using either a flat file or a command to configure a resource limits database. The traditional method defines login classes by editing /etc/login.conf. While this method is still supported, any changes require a multi-step process of editing this file, rebuilding the resource database, making necessary changes to /etc/master.passwd, and rebuilding the password database. This can become time consuming, depending upon the number of users to configure. Beginning with &os; 9.0-RELEASE, rctl can be used to provide a more fine-grained method for controlling resource limits. This command supports more than user limits as it can also be used to set resource constraints on processes and jails. This section demonstrates both methods for controlling resources, beginning with the traditional method. Configuring Login Classes limiting users accounts limiting /etc/login.conf In the traditional method, login classes and the resource limits to apply to a login class are defined in /etc/login.conf. Each user account can be assigned to a login class, where default is the default login class. Each login class has a set of login capabilities associated with it. A login capability is a name=value pair, where name is a well-known identifier and value is an arbitrary string which is processed accordingly depending on the name. Whenever /etc/login.conf is edited, the /etc/login.conf.db must be updated by executing the following command: &prompt.root; cap_mkdb /etc/login.conf Resource limits differ from the default login capabilities in two ways. First, for every limit, there is a soft and hard limit. A soft limit may be adjusted by the user or application, but may not be set higher than the hard limit. The hard limit may be lowered by the user, but can only be raised by the superuser. Second, most resource limits apply per process to a specific user. lists the most commonly used resource limits. All of the available resource limits and capabilities are described in detail in &man.login.conf.5;. limiting users coredumpsize limiting users cputime limiting users filesize limiting users maxproc limiting users memorylocked limiting users memoryuse limiting users openfiles limiting users sbsize limiting users stacksize Login Class Resource Limits Resource Limit Description coredumpsize The limit on the size of a core file generated by a program is subordinate to other limits on disk usage, such as filesize or disk quotas. This limit is often used as a less severe method of controlling disk space consumption. Since users do not generate core files and often do not delete them, this setting may save them from running out of disk space should a large program crash. cputime The maximum amount of CPU time a user's process may consume. Offending processes will be killed by the kernel. This is a limit on CPU time consumed, not the percentage of the CPU as displayed in some of the fields generated by top and ps. filesize The maximum size of a file the user may own. Unlike disk quotas (), this limit is enforced on individual files, not the set of all files a user owns. maxproc The maximum number of foreground and background processes a user can run. This limit may not be larger than the system limit specified by kern.maxproc. Setting this limit too small may hinder a user's productivity as some tasks, such as compiling a large program, start lots of processes. memorylocked The maximum amount of memory a process may request to be locked into main memory using &man.mlock.2;. Some system-critical programs, such as &man.amd.8;, lock into main memory so that if the system begins to swap, they do not contribute to disk thrashing. memoryuse The maximum amount of memory a process may consume at any given time. It includes both core memory and swap usage. This is not a catch-all limit for restricting memory consumption, but is a good start. openfiles The maximum number of files a process may have open. In &os;, files are used to represent sockets and IPC channels, so be careful not to set this too low. The system-wide limit for this is defined by kern.maxfiles. sbsize The limit on the amount of network memory a user may consume. This can be generally used to limit network communications. stacksize The maximum size of a process stack. This alone is not sufficient to limit the amount of memory a program may use, so it should be used in conjunction with other limits.
There are a few other things to remember when setting resource limits: Processes started at system startup by /etc/rc are assigned to the daemon login class. Although the default /etc/login.conf is a good source of reasonable values for most limits, they may not be appropriate for every system. Setting a limit too high may open the system up to abuse, while setting it too low may put a strain on productivity. &xorg; takes a lot of resources and encourages users to run more programs simultaneously. Many limits apply to individual processes, not the user as a whole. For example, setting openfiles to 50 means that each process the user runs may open up to 50 files. The total amount of files a user may open is the value of openfiles multiplied by the value of maxproc. This also applies to memory consumption. For further information on resource limits and login classes and capabilities in general, refer to &man.cap.mkdb.1;, &man.getrlimit.2;, and &man.login.conf.5;. Enabling and Configuring Resource Limits As of &os; 10.2, rctl support is built into the kernel. Previous supported releases will need to be recompiled using the instructions in . Add these lines to either GENERIC or a custom kernel configuration file, then rebuild the kernel: options RACCT options RCTL Once the system has rebooted into the new kernel, rctl may be used to set rules for the system. Rule syntax is controlled through the use of a subject, subject-id, resource, and action, as seen in this example rule: user:trhodes:maxproc:deny=10/user In this rule, the subject is user, the subject-id is trhodes, the resource, maxproc, is the maximum number of processes, and the action is deny, which blocks any new processes from being created. This means that the user, trhodes, will be constrained to no greater than 10 processes. Other possible actions include logging to the console, passing a notification to &man.devd.8;, or sending a sigterm to the process. Some care must be taken when adding rules. Since this user is constrained to 10 processes, this example will prevent the user from performing other tasks after logging in and executing a screen session. Once a resource limit has been hit, an error will be printed, as in this example: &prompt.user; man test /usr/bin/man: Cannot fork: Resource temporarily unavailable eval: Cannot fork: Resource temporarily unavailable As another example, a jail can be prevented from exceeding a memory limit. This rule could be written as: &prompt.root; rctl -a jail:httpd:memoryuse:deny=2G/jail Rules will persist across reboots if they have been added to /etc/rctl.conf. The format is a rule, without the preceding command. For example, the previous rule could be added as: # Block jail from using more than 2G memory: jail:httpd:memoryuse:deny=2G/jail To remove a rule, use rctl to remove it from the list: &prompt.root; rctl -r user:trhodes:maxproc:deny=10/user A method for removing all rules is documented in &man.rctl.8;. However, if removing all rules for a single user is required, this command may be issued: &prompt.root; rctl -r user:trhodes Many other resources exist which can be used to exert additional control over various subjects. See &man.rctl.8; to learn about them. Shared Administration with Sudo TomRhodesContributed by Security Sudo System administrators often need the ability to grant enhanced permissions to users so they may perform privileged tasks. The idea that team members are provided access to a &os; system to perform their specific tasks opens up unique challenges to every administrator. These team members only need a subset of access beyond normal end user levels; however, they almost always tell management they are unable to perform their tasks without superuser access. Thankfully, there is no reason to provide such access to end users because tools exist to manage this exact requirement. Up to this point, the security chapter has covered permitting access to authorized users and attempting to prevent unauthorized access. Another problem arises once authorized users have access to the system resources. In many cases, some users may need access to application startup scripts, or a team of administrators need to maintain the system. Traditionally, the standard users and groups, file permissions, and even the &man.su.1; command would manage this access. And as applications required more access, as more users needed to use system resources, a better solution was required. The most used application is currently Sudo. Sudo allows administrators to configure more rigid access to system commands and provide for some advanced logging features. As a tool, it is available from the Ports Collection as security/sudo or by use of the &man.pkg.8; utility. To use the &man.pkg.8; tool: &prompt.root; pkg install sudo After the installation is complete, the installed visudo will open the configuration file with a text editor. Using visudo is highly recommended as it comes with a built in syntax checker to verify there are no errors before the file is saved. The configuration file is made up of several small sections which allow for extensive configuration. In the following example, web application maintainer, user1, needs to start, stop, and restart the web application known as webservice. To grant this user permission to perform these tasks, add this line to the end of /usr/local/etc/sudoers: user1 ALL=(ALL) /usr/sbin/service webservice * The user may now start webservice using this command: &prompt.user; sudo /usr/sbin/service webservice start While this configuration allows a single user access to the webservice service; however, in most organizations, there is an entire web team in charge of managing the service. A single line can also give access to an entire group. These steps will create a web group, add a user to this group, and allow all members of the group to manage the service: &prompt.root; pw groupadd -g 6001 -n webteam Using the same &man.pw.8; command, the user is added to the webteam group: &prompt.root; pw groupmod -m user1 -n webteam Finally, this line in /usr/local/etc/sudoers allows any member of the webteam group to manage webservice: %webteam ALL=(ALL) /usr/sbin/service webservice * Unlike &man.su.1;, Sudo only requires the end user password. This adds an advantage where users will not need shared passwords, a finding in most security audits and just bad all the way around. Users permitted to run applications with Sudo only enter their own passwords. This is more secure and gives better control than &man.su.1;, where the root password is entered and the user acquires all root permissions. Most organizations are moving or have moved toward a two factor authentication model. In these cases, the user may not have a password to enter. Sudo provides for these cases with the NOPASSWD variable. Adding it to the configuration above will allow all members of the webteam group to manage the service without the password requirement: %webteam ALL=(ALL) NOPASSWD: /usr/sbin/service webservice * Logging Output An advantage to implementing Sudo is the ability to enable session logging. Using the built in log mechanisms and the included sudoreplay command, all commands initiated through Sudo are logged for later verification. To enable this feature, add a default log directory entry, this example uses a user variable. Several other log filename conventions exist, consult the manual page for sudoreplay for additional information. Defaults iolog_dir=/var/log/sudo-io/%{user} This directory will be created automatically after the logging is configured. It is best to let the system create directory with default permissions just to be safe. In addition, this entry will also log administrators who use the sudoreplay command. To change this behavior, read and uncomment the logging options inside sudoers. Once this directive has been added to the sudoers file, any user configuration can be updated with the request to log access. In the example shown, the updated webteam entry would have the following additional changes: %webteam ALL=(ALL) NOPASSWD: LOG_INPUT: LOG_OUTPUT: /usr/sbin/service webservice * From this point on, all webteam members altering the status of the webservice application will be logged. The list of previous and current sessions can be displayed with: &prompt.root; sudoreplay -l In the output, to replay a specific session, search for the TSID= entry, and pass that to sudoreplay with no other options to replay the session at normal speed. For example: &prompt.root; sudoreplay user1/00/00/02 While sessions are logged, any administrator is able to remove sessions and leave only a question of why they had done so. It is worthwhile to add a daily check through an intrusion detection system (IDS) or similar software so that other administrators are alerted to manual alterations. The sudoreplay is extremely extendable. Consult the documentation for more information. Index: head/en_US.ISO8859-1/books/handbook/x11/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/handbook/x11/chapter.xml (revision 50967) +++ head/en_US.ISO8859-1/books/handbook/x11/chapter.xml (revision 50968) @@ -1,2170 +1,2170 @@ The X Window System Synopsis An installation of &os; using bsdinstall does not automatically install a graphical user interface. This chapter describes how to install and configure &xorg;, which provides the open source X Window System used to provide a graphical environment. It then describes how to find and install a desktop environment or window manager. Users who prefer an installation method that automatically configures the &xorg; and offers a choice of window managers during installation should refer to the website. For more information on the video hardware that &xorg; supports, refer to the x.org website. After reading this chapter, you will know: The various components of the X Window System, and how they interoperate. How to install and configure &xorg;. How to install and configure several window managers and desktop environments. How to use &truetype; fonts in &xorg;. How to set up your system for graphical logins (XDM). Before reading this chapter, you should: Know how to install additional third-party software as described in . Terminology While it is not necessary to understand all of the details of the various components in the X Window System and how they interact, some basic knowledge of these components can be useful. X server X was designed from the beginning to be network-centric, and adopts a client-server model. In this model, the X server runs on the computer that has the keyboard, monitor, and mouse attached. The server's responsibility includes tasks such as managing the display, handling input from the keyboard and mouse, and handling input or output from other devices such as a tablet or a video projector. This confuses some people, because the X terminology is exactly backward to what they expect. They expect the X server to be the big powerful machine down the hall, and the X client to be the machine on their desk. X client Each X application, such as XTerm or Firefox, is a client. A client sends messages to the server such as Please draw a window at these coordinates, and the server sends back messages such as The user just clicked on the OK button. In a home or small office environment, the X server and the X clients commonly run on the same computer. It is also possible to run the X server on a less powerful computer and to run the X applications on a more powerful system. In this scenario, the communication between the X client and server takes place over the network. window manager X does not dictate what windows should look like on-screen, how to move them around with the mouse, which keystrokes should be used to move between windows, what the title bars on each window should look like, whether or not they have close buttons on them, and so on. Instead, X delegates this responsibility to a separate window manager application. There are dozens of window managers available. Each window manager provides a different look and feel: some support virtual desktops, some allow customized keystrokes to manage the desktop, some have a Start button, and some are themeable, allowing a complete change of the desktop's look-and-feel. Window managers are available in the x11-wm category of the Ports Collection. Each window manager uses a different configuration mechanism. Some expect configuration file written by hand while others provide graphical tools for most configuration tasks. desktop environment KDE and GNOME are considered to be desktop environments as they include an entire suite of applications for performing common desktop tasks. These may include office suites, web browsers, and games. focus policy The window manager is responsible for the mouse focus policy. This policy provides some means for choosing which window is actively receiving keystrokes and it should also visibly indicate which window is currently active. One focus policy is called click-to-focus. In this model, a window becomes active upon receiving a mouse click. In the focus-follows-mouse policy, the window that is under the mouse pointer has focus and the focus is changed by pointing at another window. If the mouse is over the root window, then this window is focused. In the sloppy-focus model, if the mouse is moved over the root window, the most recently used window still has the focus. With sloppy-focus, focus is only changed when the cursor enters a new window, and not when exiting the current window. In the click-to-focus policy, the active window is selected by mouse click. The window may then be raised and appear in front of all other windows. All keystrokes will now be directed to this window, even if the cursor is moved to another window. Different window managers support different focus models. All of them support click-to-focus, and the majority of them also support other policies. Consult the documentation for the window manager to determine which focus models are available. widgets Widget is a term for all of the items in the user interface that can be clicked or manipulated in some way. This includes buttons, check boxes, radio buttons, icons, and lists. A widget toolkit is a set of widgets used to create graphical applications. There are several popular widget toolkits, including Qt, used by KDE, and GTK+, used by GNOME. As a result, applications will have a different look and feel, depending upon which widget toolkit was used to create the application. Installing <application>&xorg;</application> On &os;, &xorg; can be installed as a package or port. The binary package can be installed quickly but with fewer options for customization: &prompt.root; pkg install xorg To build and install from the Ports Collection: &prompt.root; cd /usr/ports/x11/xorg &prompt.root; make install clean Either of these installations results in the complete &xorg; system being installed. Binary packages are the best option for most users. A smaller version of the X system suitable for experienced users is available in x11/xorg-minimal. Most of the documents, libraries, and applications will not be installed. Some applications require these additional components to function. <application>&xorg;</application> Configuration Warren Block Originally contributed by &xorg; &xorg; Quick Start &xorg; supports most common video cards, keyboards, and pointing devices. Video cards, monitors, and input devices are automatically detected and do not require any manual configuration. Do not create xorg.conf or run a step unless automatic configuration fails. If &xorg; has been used on this computer before, move or remove any existing configuration files: &prompt.root; mv /etc/X11/xorg.conf ~/xorg.conf.etc &prompt.root; mv /usr/local/etc/X11/xorg.conf ~/xorg.conf.localetc Add the user who will run &xorg; to the video or wheel group to enable 3D acceleration when available. To add user jru to whichever group is available: &prompt.root; pw groupmod video -m jru || pw groupmod wheel -m jru The TWM window manager is included by default. It is started when &xorg; starts: &prompt.user; startx On some older versions of &os;, the system console must be set to &man.vt.4; before switching back to the text console will work properly. See . User Group for Accelerated Video Access to /dev/dri is needed to allow 3D acceleration on video cards. It is usually simplest to add the user who will be running X to either the video or wheel group. Here, &man.pw.8; is used to add user slurms to the video group, or to the wheel group if there is no video group: &prompt.root; pw groupmod video -m slurms || pw groupmod wheel -m slurms Kernel Mode Setting (<acronym>KMS</acronym>) When the computer switches from displaying the console to a higher screen resolution for X, it must set the video output mode. Recent versions of &xorg; use a system inside the kernel to do these mode changes more efficiently. Older versions of &os; use &man.sc.4;, which is not aware of the KMS system. The end result is that after closing X, the system console is blank, even though it is still working. The newer &man.vt.4; console avoids this problem. Add this line to /boot/loader.conf to enable &man.vt.4;: kern.vty=vt Configuration Files Manual configuration is usually not necessary. Please do not manually create configuration files unless autoconfiguration does not work. Directory &xorg; looks in several directories for configuration files. /usr/local/etc/X11/ is the recommended directory for these files on &os;. Using this directory helps keep application files separate from operating system files. Storing configuration files in the legacy /etc/X11/ still works. However, this mixes application files with the base &os; files and is not recommended. Single or Multiple Files It is easier to use multiple files that each configure a specific setting than the traditional single xorg.conf. These files are stored in the xorg.conf.d/ subdirectory of the main configuration file directory. The full path is typically /usr/local/etc/X11/xorg.conf.d/. Examples of these files are shown later in this section. The traditional single xorg.conf still works, but is neither as clear nor as flexible as multiple files in the xorg.conf.d/ subdirectory. Video Cards &intel; 3D acceleration is supported on most &intel; graphics up to Ivy Bridge (HD Graphics 2500, 4000, and P4000), including Iron Lake (HD Graphics) and Sandy Bridge (HD Graphics 2000). Driver name: intel For reference, see . &amd; Radeon 2D and 3D acceleration is supported on Radeon cards up to and including the HD6000 series. Driver name: radeon For reference, see . NVIDIA Several NVIDIA drivers are available in the x11 category of the Ports Collection. Install the driver that matches the video card. For reference, see . Hybrid Combination Graphics Some notebook computers add additional graphics processing units to those built into the chipset or processor. Optimus combines &intel; and NVIDIA hardware. Switchable Graphics or Hybrid Graphics are a combination of an &intel; or &amd; processor and an &amd; Radeon GPU. Implementations of these hybrid graphics systems vary, and &xorg; on &os; is not able to drive all versions of them. Some computers provide a BIOS option to disable one of the graphics adapters or select a discrete mode which can be used with one of the standard video card drivers. For example, it is sometimes possible to disable the NVIDIA GPU in an Optimus system. The &intel; video can then be used with an &intel; driver. BIOS settings depend on the model of computer. In some situations, both GPUs can be left enabled, but creating a configuration file that only uses the main GPU in the Device section is enough to make such a system functional. Other Video Cards Drivers for some less-common video cards can be found in the x11-drivers directory of the Ports Collection. Cards that are not supported by a specific driver might still be usable with the x11-drivers/xf86-video-vesa driver. This driver is installed by x11/xorg. It can also be installed manually as x11-drivers/xf86-video-vesa. &xorg; attempts to use this driver when a specific driver is not found for the video card. x11-drivers/xf86-video-scfb is a similar nonspecialized video driver that works on many UEFI and &arm; computers. Setting the Video Driver in a File To set the &intel; driver in a configuration file: Select &intel; Video Driver in a File /usr/local/etc/X11/xorg.conf.d/driver-intel.conf Section "Device" Identifier "Card0" Driver "intel" # BusID "PCI:1:0:0" EndSection If more than one video card is present, the BusID identifier can be uncommented and set to select the desired card. A list of video card bus IDs can be displayed with pciconf -lv | grep -B3 display. To set the Radeon driver in a configuration file: Select Radeon Video Driver in a File /usr/local/etc/X11/xorg.conf.d/driver-radeon.conf Section "Device" Identifier "Card0" Driver "radeon" EndSection To set the VESA driver in a configuration file: Select <acronym>VESA</acronym> Video Driver in a File /usr/local/etc/X11/xorg.conf.d/driver-vesa.conf Section "Device" Identifier "Card0" Driver "vesa" EndSection To set the scfb driver for use with a UEFI or &arm; computer: Select <literal>scfb</literal> Video Driver in a File /usr/local/etc/X11/xorg.conf.d/driver-scfb.conf Section "Device" Identifier "Card0" Driver "scfb" EndSection Monitors Almost all monitors support the Extended Display Identification Data standard (EDID). &xorg; uses EDID to communicate with the monitor and detect the supported resolutions and refresh rates. Then it selects the most appropriate combination of settings to use with that monitor. Other resolutions supported by the monitor can be chosen by setting the desired resolution in configuration files, or after the X server has been started with &man.xrandr.1;. Using &man.xrandr.1; Run &man.xrandr.1; without any parameters to see a list of video outputs and detected monitor modes: &prompt.user; xrandr Screen 0: minimum 320 x 200, current 3000 x 1920, maximum 8192 x 8192 DVI-0 connected primary 1920x1200+1080+0 (normal left inverted right x axis y axis) 495mm x 310mm 1920x1200 59.95*+ 1600x1200 60.00 1280x1024 85.02 75.02 60.02 1280x960 60.00 1152x864 75.00 1024x768 85.00 75.08 70.07 60.00 832x624 74.55 800x600 75.00 60.32 640x480 75.00 60.00 720x400 70.08 DisplayPort-0 disconnected (normal left inverted right x axis y axis) HDMI-0 disconnected (normal left inverted right x axis y axis) This shows that the DVI-0 output is being used to display a screen resolution of 1920x1200 pixels at a refresh rate of about 60 Hz. Monitors are not attached to the DisplayPort-0 and HDMI-0 connectors. Any of the other display modes can be selected with &man.xrandr.1;. For example, to switch to 1280x1024 at 60 Hz: &prompt.user; xrandr --mode 1280x1024 --rate 60 A common task is using the external video output on a notebook computer for a video projector. The type and quantity of output connectors varies between devices, and the name given to each output varies from driver to driver. What one driver calls HDMI-1, another might call HDMI1. So the first step is to run &man.xrandr.1; to list all the available outputs: &prompt.user; xrandr Screen 0: minimum 320 x 200, current 1366 x 768, maximum 8192 x 8192 LVDS1 connected 1366x768+0+0 (normal left inverted right x axis y axis) 344mm x 193mm 1366x768 60.04*+ 1024x768 60.00 800x600 60.32 56.25 640x480 59.94 VGA1 connected (normal left inverted right x axis y axis) 1280x1024 60.02 + 75.02 1280x960 60.00 1152x864 75.00 1024x768 75.08 70.07 60.00 832x624 74.55 800x600 72.19 75.00 60.32 56.25 640x480 75.00 72.81 66.67 60.00 720x400 70.08 HDMI1 disconnected (normal left inverted right x axis y axis) DP1 disconnected (normal left inverted right x axis y axis) Four outputs were found: the built-in panel LVDS1, and external VGA1, HDMI1, and DP1 connectors. The projector has been connected to the VGA1 output. &man.xrandr.1; is now used to set that output to the native resolution of the projector and add the additional space to the right side of the desktop: &prompt.user; xrandr --output VGA1 --auto --right-of LVDS1 --auto chooses the resolution and refresh rate detected by EDID. If the resolution is not correctly detected, a fixed value can be given with --mode instead of the --auto statement. For example, most projectors can be used with a 1024x768 resolution, which is set with --mode 1024x768. &man.xrandr.1; is often run from .xinitrc to set the appropriate mode when X starts. Setting Monitor Resolution in a File To set a screen resolution of 1024x768 in a configuration file: Set Screen Resolution in a File /usr/local/etc/X11/xorg.conf.d/screen-resolution.conf Section "Screen" Identifier "Screen0" Device "Card0" SubSection "Display" Modes "1024x768" EndSubSection EndSection The few monitors that do not have EDID can be configured by setting HorizSync and VertRefresh to the range of frequencies supported by the monitor. Manually Setting Monitor Frequencies /usr/local/etc/X11/xorg.conf.d/monitor0-freq.conf Section "Monitor" Identifier "Monitor0" HorizSync 30-83 # kHz VertRefresh 50-76 # Hz EndSection Input Devices Keyboards Keyboard Layout The standardized location of keys on a keyboard is called a layout. Layouts and other adjustable parameters are listed in &man.xkeyboard-config.7;. A United States layout is the default. To select an alternate layout, set the XkbLayout and XkbVariant options in an InputClass. This will be applied to all input devices that match the class. This example selects a French keyboard layout with the oss variant. Setting a Keyboard Layout /usr/local/etc/X11/xorg.conf.d/keyboard-fr-oss.conf Section "InputClass" Identifier "KeyboardDefaults" Driver "keyboard" MatchIsKeyboard "on" Option "XkbLayout" "fr" Option "XkbVariant" "oss" EndSection Setting Multiple Keyboard Layouts Set United States, Spanish, and Ukrainian keyboard layouts. Cycle through these layouts by pressing Alt Shift . x11/xxkb or x11/sbxkb can be used for improved layout switching control and current layout indicators. /usr/local/etc/X11/xorg.conf.d/kbd-layout-multi.conf Section "InputClass" Identifier "All Keyboards" MatchIsKeyboard "yes" Option "XkbLayout" "us, es, ua" EndSection Closing &xorg; From the Keyboard X can be closed with a combination of keys. By default, that key combination is not set because it conflicts with keyboard commands for some applications. Enabling this option requires changes to the keyboard InputDevice section: Enabling Keyboard Exit from X /usr/local/etc/X11/xorg.conf.d/keyboard-zap.conf Section "InputClass" Identifier "KeyboardDefaults" Driver "keyboard" MatchIsKeyboard "on" Option "XkbOptions" "terminate:ctrl_alt_bksp" EndSection Mice and Pointing Devices Many mouse parameters can be adjusted with configuration options. See &man.mousedrv.4x; for a full list. Mouse Buttons The number of buttons on a mouse can be set in the mouse InputDevice section of xorg.conf. To set the number of buttons to 7: Setting the Number of Mouse Buttons /usr/local/etc/X11/xorg.conf.d/mouse0-buttons.conf Section "InputDevice" Identifier "Mouse0" Option "Buttons" "7" EndSection Manual Configuration In some cases, &xorg; autoconfiguration does not work with particular hardware, or a different configuration is desired. For these cases, a custom configuration file can be created. Do not create manual configuration files unless required. Unnecessary manual configuration can prevent proper operation. A configuration file can be generated by &xorg; based on the detected hardware. This file is often a useful starting point for custom configurations. Generating an xorg.conf: &prompt.root; Xorg -configure The configuration file is saved to /root/xorg.conf.new. Make any changes desired, then test that file with: &prompt.root; Xorg -config /root/xorg.conf.new After the new configuration has been adjusted and tested, it can be split into smaller files in the normal location, /usr/local/etc/X11/xorg.conf.d/. Using Fonts in <application>&xorg;</application> Type1 Fonts The default fonts that ship with &xorg; are less than ideal for typical desktop publishing applications. Large presentation fonts show up jagged and unprofessional looking, and small fonts are almost completely unintelligible. However, there are several free, high quality Type1 (&postscript;) fonts available which can be readily used with &xorg;. For instance, the URW font collection (x11-fonts/urwfonts) includes high quality versions of standard type1 fonts (Times Roman, Helvetica, Palatino and others). The Freefonts collection (x11-fonts/freefonts) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts. In addition, &xorg; can be configured to use &truetype; fonts with a minimum of effort. For more details on this, see the &man.X.7; manual page or . To install the above Type1 font collections from binary packages, run the following commands: &prompt.root; pkg install urwfonts Alternatively, to build from the Ports Collection, run the following commands: &prompt.root; cd /usr/ports/x11-fonts/urwfonts &prompt.root; make install clean And likewise with the freefont or other collections. To have the X server detect these fonts, add an appropriate line to the X server configuration file (/etc/X11/xorg.conf), which reads: FontPath "/usr/local/share/fonts/urwfonts/" Alternatively, at the command line in the X session run: &prompt.user; xset fp+ /usr/local/share/fonts/urwfonts &prompt.user; xset fp rehash This will work but will be lost when the X session is closed, unless it is added to the startup file (~/.xinitrc for a normal startx session, or ~/.xsession when logging in through a graphical login manager like XDM). A third way is to use the new /usr/local/etc/fonts/local.conf as demonstrated in . &truetype; Fonts TrueType Fonts fonts TrueType &xorg; has built in support for rendering &truetype; fonts. There are two different modules that can enable this functionality. The freetype module is used in this example because it is more consistent with the other font rendering back-ends. To enable the freetype module just add the following line to the "Module" section of /etc/X11/xorg.conf. Load "freetype" Now make a directory for the &truetype; fonts (for example, /usr/local/share/fonts/TrueType) and copy all of the &truetype; fonts into this directory. Keep in mind that &truetype; fonts cannot be directly taken from an &apple; &mac;; they must be in &unix;/&ms-dos;/&windows; format for use by &xorg;. Once the files have been copied into this directory, use mkfontdir to create a fonts.dir, so that the X font renderer knows that these new files have been installed. mkfontdir can be installed as a package: &prompt.root; pkg install mkfontdir Then create an index of X font files in a directory: &prompt.root; cd /usr/local/share/fonts/TrueType &prompt.root; mkfontdir Now add the &truetype; directory to the font path. This is just the same as described in : &prompt.user; xset fp+ /usr/local/share/fonts/TrueType &prompt.user; xset fp rehash or add a FontPath line to xorg.conf. Now Gimp, Apache OpenOffice, and all of the other X applications should now recognize the installed &truetype; fonts. Extremely small fonts (as with text in a high resolution display on a web page) and extremely large fonts (within &staroffice;) will look much better now. Anti-Aliased Fonts anti-aliased fonts fonts anti-aliased All fonts in &xorg; that are found in /usr/local/share/fonts/ and ~/.fonts/ are automatically made available for anti-aliasing to Xft-aware applications. Most recent applications are Xft-aware, including KDE, GNOME, and Firefox. To control which fonts are anti-aliased, or to configure anti-aliasing properties, create (or edit, if it already exists) the file /usr/local/etc/fonts/local.conf. Several advanced features of the Xft font system can be tuned using this file; this section describes only some simple possibilities. For more details, please see &man.fonts-conf.5;. XML This file must be in XML format. Pay careful attention to case, and make sure all tags are properly closed. The file begins with the usual XML header followed by a DOCTYPE definition, and then the <fontconfig> tag: <?xml version="1.0"?> <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> <fontconfig> As previously stated, all fonts in /usr/local/share/fonts/ as well as ~/.fonts/ are already made available to Xft-aware applications. To add another directory outside of these two directory trees, add a line like this to /usr/local/etc/fonts/local.conf: <dir>/path/to/my/fonts</dir> After adding new fonts, and especially new font directories, rebuild the font caches: &prompt.root; fc-cache -f Anti-aliasing makes borders slightly fuzzy, which makes very small text more readable and removes staircases from large text, but can cause eyestrain if applied to normal text. To exclude font sizes smaller than 14 point from anti-aliasing, include these lines: <match target="font"> <test name="size" compare="less"> <double>14</double> </test> <edit name="antialias" mode="assign"> <bool>false</bool> </edit> </match> <match target="font"> <test name="pixelsize" compare="less" qual="any"> <double>14</double> </test> <edit mode="assign" name="antialias"> <bool>false</bool> </edit> </match> fonts spacing Spacing for some monospaced fonts might also be inappropriate with anti-aliasing. This seems to be an issue with KDE, in particular. One possible fix is to force the spacing for such fonts to be 100. Add these lines: <match target="pattern" name="family"> <test qual="any" name="family"> <string>fixed</string> </test> <edit name="family" mode="assign"> <string>mono</string> </edit> </match> <match target="pattern" name="family"> <test qual="any" name="family"> <string>console</string> </test> <edit name="family" mode="assign"> <string>mono</string> </edit> </match> (this aliases the other common names for fixed fonts as "mono"), and then add: <match target="pattern" name="family"> <test qual="any" name="family"> <string>mono</string> </test> <edit name="spacing" mode="assign"> <int>100</int> </edit> </match> Certain fonts, such as Helvetica, may have a problem when anti-aliased. Usually this manifests itself as a font that seems cut in half vertically. At worst, it may cause applications to crash. To avoid this, consider adding the following to local.conf: <match target="pattern" name="family"> <test qual="any" name="family"> <string>Helvetica</string> </test> <edit name="family" mode="assign"> <string>sans-serif</string> </edit> </match> After editing local.conf, make certain to end the file with the </fontconfig> tag. Not doing this will cause changes to be ignored. Users can add personalized settings by creating their own ~/.config/fontconfig/fonts.conf. This file uses the same XML format described above. LCD screen Fonts LCD screen One last point: with an LCD screen, sub-pixel sampling may be desired. This basically treats the (horizontally separated) red, green and blue components separately to improve the horizontal resolution; the results can be dramatic. To enable this, add the line somewhere in local.conf: <match target="font"> <test qual="all" name="rgba"> <const>unknown</const> </test> <edit name="rgba" mode="assign"> <const>rgb</const> </edit> </match> Depending on the sort of display, rgb may need to be changed to bgr, vrgb or vbgr: experiment and see which works best. The X Display Manager Seth Kingsley Contributed by X Display Manager &xorg; provides an X Display Manager, XDM, which can be used for login session management. XDM provides a graphical interface for choosing which display server to connect to and for entering authorization information such as a login and password combination. This section demonstrates how to configure the X Display Manager on &os;. Some desktop environments provide their own graphical login manager. Refer to for instructions on how to configure the GNOME Display Manager and for instructions on how to configure the KDE Display Manager. Configuring <application>XDM</application> To install XDM, use the x11/xdm package or port. Once installed, XDM can be configured to run when the machine boots up by editing this entry in /etc/ttys: ttyv8 "/usr/local/bin/xdm -nodaemon" xterm off secure Change the off to on and save the edit. The ttyv8 in this entry indicates that XDM will run on the ninth virtual terminal. The XDM configuration directory is located in /usr/local/lib/X11/xdm. This directory contains several files used to change the behavior and appearance of XDM, as well as a few scripts and programs used to set up the desktop when XDM is running. summarizes the function of each of these files. The exact syntax and usage of these files is described in &man.xdm.1;. XDM Configuration Files File Description Xaccess The protocol for connecting to XDM is called the X Display Manager Connection Protocol (XDMCP) This file is a client authorization ruleset for controlling XDMCP connections from remote machines. By default, this file does not allow any remote clients to connect. Xresources This file controls the look and feel of the XDM display chooser and login screens. The default configuration is a simple rectangular login window with the hostname of the machine displayed at the top in a large font and Login: and Password: prompts below. The format of this file is identical to the app-defaults file described in the &xorg; documentation. Xservers The list of local and remote displays the chooser should provide as login choices. Xsession Default session script for logins which is run by XDM after a user has logged in. Normally each user will have a customized session script in ~/.xsession that overrides this script Xsetup_* Script to automatically launch applications before displaying the chooser or login interfaces. There is a script for each display being used, named Xsetup_*, where * is the local display number. Typically these scripts run one or two programs in the background such as xconsole. xdm-config Global configuration for all displays running on this machine. xdm-errors Contains errors generated by the server program. If a display that XDM is trying to start hangs, look at this file for error messages. These messages are also written to the user's ~/.xsession-errors on a per-session basis. xdm-pid The running process ID of XDM.
Configuring Remote Access By default, only users on the same system can login using XDM. To enable users on other systems to connect to the display server, edit the access control rules and enable the connection listener. To configure XDM to listen for any remote connection, comment out the DisplayManager.requestPort line in /usr/local/lib/X11/xdm/xdm-config by putting a ! in front of it: ! SECURITY: do not listen for XDMCP or Chooser requests ! Comment out this line if you want to manage X terminals with xdm DisplayManager.requestPort: 0 Save the edits and restart XDM. To restrict remote access, look at the example entries in /usr/local/lib/X11/xdm/Xaccess and refer to &man.xdm.1; for further information. Desktop Environments Valentino Vaschetto Contributed by This section describes how to install three popular desktop environments on a &os; system. A desktop environment can range from a simple window manager to a complete suite of desktop applications. Over a hundred desktop environments are available in the x11-wm category of the Ports Collection. GNOME GNOME GNOME is a user-friendly desktop environment. It includes a panel for starting applications and displaying status, a desktop, a set of tools and applications, and a set of conventions that make it easy for applications to cooperate and be consistent with each other. More information regarding GNOME on &os; can be found at http://www.FreeBSD.org/gnome. + xlink:href="https://www.FreeBSD.org/gnome">https://www.FreeBSD.org/gnome. That web site contains additional documentation about installing, configuring, and managing GNOME on &os;. This desktop environment can be installed from a package: &prompt.root; pkg install gnome3 To instead build GNOME from ports, use the following command. GNOME is a large application and will take some time to compile, even on a fast computer. &prompt.root; cd /usr/ports/x11/gnome3 &prompt.root; make install clean GNOME requires /proc to be mounted. Add this line to /etc/fstab to mount this file system automatically during system startup: proc /proc procfs rw 0 0 GNOME uses D-Bus and HAL for a message bus and hardware abstraction. These applications are automatically installed as dependencies of GNOME. Enable them in /etc/rc.conf so they will be started when the system boots: dbus_enable="YES" hald_enable="YES" After installation, configure &xorg; to start GNOME. The easiest way to do this is to enable the GNOME Display Manager, GDM, which is installed as part of the GNOME package or port. It can be enabled by adding this line to /etc/rc.conf: gdm_enable="YES" It is often desirable to also start all GNOME services. To achieve this, add a second line to /etc/rc.conf: gnome_enable="YES" GDM will start automatically when the system boots. A second method for starting GNOME is to type startx from the command-line after configuring ~/.xinitrc. If this file already exists, replace the line that starts the current window manager with one that starts /usr/local/bin/gnome-session. If this file does not exist, create it with this command: &prompt.user; echo "exec /usr/local/bin/gnome-session" > ~/.xinitrc A third method is to use XDM as the display manager. In this case, create an executable ~/.xsession: &prompt.user; echo "#!/bin/sh" > ~/.xsession &prompt.user; echo "exec /usr/local/bin/gnome-session" >> ~/.xsession &prompt.user; chmod +x ~/.xsession KDE KDE KDE is another easy-to-use desktop environment. This desktop provides a suite of applications with a consistent look and feel, a standardized menu and toolbars, keybindings, color-schemes, internationalization, and a centralized, dialog-driven desktop configuration. More information on KDE can be found at http://www.kde.org/. For &os;-specific information, consult http://freebsd.kde.org. To install the KDE package, type: &prompt.root; pkg install x11/kde4 To instead build the KDE port, use the following command. Installing the port will provide a menu for selecting which components to install. KDE is a large application and will take some time to compile, even on a fast computer. &prompt.root; cd /usr/ports/x11/kde4 &prompt.root; make install clean KDE display manager KDE requires /proc to be mounted. Add this line to /etc/fstab to mount this file system automatically during system startup: proc /proc procfs rw 0 0 KDE uses D-Bus and HAL for a message bus and hardware abstraction. These applications are automatically installed as dependencies of KDE. Enable them in /etc/rc.conf so they will be started when the system boots: dbus_enable="YES" hald_enable="YES" The installation of KDE includes the KDE Display Manager, KDM. To enable this display manager, add this line to /etc/rc.conf: kdm4_enable="YES" A second method for launching KDE is to type startx from the command line. For this to work, the following line is needed in ~/.xinitrc: exec /usr/local/bin/startkde A third method for starting KDE is through XDM. To do so, create an executable ~/.xsession as follows: &prompt.user; echo "#!/bin/sh" > ~/.xsession &prompt.user; echo "exec /usr/local/bin/startkde" >> ~/.xsession &prompt.user; chmod +x ~/.xsession Once KDE is started, refer to its built-in help system for more information on how to use its various menus and applications. Xfce Xfce is a desktop environment based on the GTK+ toolkit used by GNOME. However, it is more lightweight and provides a simple, efficient, easy-to-use desktop. It is fully configurable, has a main panel with menus, applets, and application launchers, provides a file manager and sound manager, and is themeable. Since it is fast, light, and efficient, it is ideal for older or slower machines with memory limitations. More information on Xfce can be found at http://www.xfce.org. To install the Xfce package: &prompt.root; pkg install xfce Alternatively, to build the port: &prompt.root; cd /usr/ports/x11-wm/xfce4 &prompt.root; make install clean Unlike GNOME or KDE, Xfce does not provide its own login manager. In order to start Xfce from the command line by typing startx, first add its entry to ~/.xinitrc: &prompt.user; echo "exec /usr/local/bin/startxfce4 --with-ck-launch" > ~/.xinitrc An alternate method is to use XDM. To configure this method, create an executable ~/.xsession: &prompt.user; echo "#!/bin/sh" > ~/.xsession &prompt.user; echo "exec /usr/local/bin/startxfce4 --with-ck-launch" >> ~/.xsession &prompt.user; chmod +x ~/.xsession Installing Compiz Fusion One way to make using a desktop computer more pleasant is with nice 3D effects. Installing the Compiz Fusion package is easy, but configuring it requires a few steps that are not described in the port's documentation. Setting up the &os; nVidia Driver Desktop effects can cause quite a load on the graphics card. For an nVidia-based graphics card, the proprietary driver is required for good performance. Users of other graphics cards can skip this section and continue with the xorg.conf configuration. To determine which nVidia driver is needed see the FAQ question on the subject. Having determined the correct driver to use for your card, installation is as simple as installing any other package. For example, to install the latest driver: &prompt.root; pkg install x11/nvidia-driver The driver will create a kernel module, which needs to be loaded at system startup. Add the following line to /boot/loader.conf: nvidia_load="YES" To immediately load the kernel module into the running kernel by issuing a command like kldload nvidia, however it has been noted that the some versions of &xorg; will not function properly if the driver is not loaded at boot time. After editing /boot/loader.conf, a reboot is recommended. With the kernel module loaded, you normally only need to change a single line in xorg.conf to enable the proprietary driver: Find the following line in /etc/X11/xorg.conf: Driver "nv" and change it to: Driver "nvidia" Start the GUI as usual, and you should be greeted by the nVidia splash. Everything should work as usual. Configuring xorg.conf for Desktop Effects To enable Compiz Fusion, /etc/X11/xorg.conf needs to be modified: Add the following section to enable composite effects: Section "Extensions" Option "Composite" "Enable" EndSection Locate the Screen section which should look similar to the one below: Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" ... and add the following two lines (after Monitor will do): DefaultDepth 24 Option "AddARGBGLXVisuals" "True" Locate the Subsection that refers to the screen resolution that you wish to use. For example, if you wish to use 1280x1024, locate the section that follows. If the desired resolution does not appear in any subsection, you may add the relevant entry by hand: SubSection "Display" Viewport 0 0 Modes "1280x1024" EndSubSection A color depth of 24 bits is needed for desktop composition, change the above subsection to: SubSection "Display" Viewport 0 0 Depth 24 Modes "1280x1024" EndSubSection Finally, confirm that the glx and extmod modules are loaded in the Module section: Section "Module" Load "extmod" Load "glx" ... The preceding can be done automatically with x11/nvidia-xconfig by running (as root): &prompt.root; nvidia-xconfig --add-argb-glx-visuals &prompt.root; nvidia-xconfig --composite &prompt.root; nvidia-xconfig --depth=24 Installing and Configuring Compiz Fusion Installing Compiz Fusion is as simple as any other package: &prompt.root; pkg install x11-wm/compiz-fusion When the installation is finished, start your graphic desktop and at a terminal, enter the following commands (as a normal user): &prompt.user; compiz --replace --sm-disable --ignore-desktop-hints ccp & &prompt.user; emerald --replace & Your screen will flicker for a few seconds, as your window manager (e.g. Metacity if you are using GNOME) is replaced by Compiz Fusion. Emerald takes care of the window decorations (i.e. close, minimize, maximize buttons, title bars and so on). You may convert this to a trivial script and have it run at startup automatically (e.g. by adding to Sessions in a GNOME desktop): #! /bin/sh compiz --replace --sm-disable --ignore-desktop-hints ccp & emerald --replace & Save this in your home directory as, for example, start-compiz and make it executable: &prompt.user; chmod +x ~/start-compiz Then use the GUI to add it to Startup Programs (located in System, Preferences, Sessions on a GNOME desktop). To actually select all the desired effects and their settings, execute (again as a normal user) the Compiz Config Settings Manager: &prompt.user; ccsm In GNOME, this can also be found in the System, Preferences menu. If you have selected gconf support during the build, you will also be able to view these settings using gconf-editor under apps/compiz. Troubleshooting If the mouse does not work, you will need to first configure it before proceeding. In recent Xorg versions, the InputDevice sections in xorg.conf are ignored in favor of the autodetected devices. To restore the old behavior, add the following line to the ServerLayout or ServerFlags section of this file: Option "AutoAddDevices" "false" Input devices may then be configured as in previous versions, along with any other options needed (e.g., keyboard layout switching). As previously explained the hald daemon will, by default, automatically detect your keyboard. There are chances that your keyboard layout or model will not be correct, desktop environments like GNOME, KDE or Xfce provide tools to configure the keyboard. However, it is possible to set the keyboard properties directly either with the help of the &man.setxkbmap.1; utility or with a hald's configuration rule. For example if, one wants to use a PC 102 keys keyboard coming with a french layout, we have to create a keyboard configuration file for hald called x11-input.fdi and saved in the /usr/local/etc/hal/fdi/policy directory. This file should contain the following lines: <?xml version="1.0" encoding="iso-8859-1"?> <deviceinfo version="0.2"> <device> <match key="info.capabilities" contains="input.keyboard"> <merge key="input.x11_options.XkbModel" type="string">pc102</merge> <merge key="input.x11_options.XkbLayout" type="string">fr</merge> </match> </device> </deviceinfo> If this file already exists, just copy and add to your file the lines regarding the keyboard configuration. You will have to reboot your machine to force hald to read this file. It is possible to do the same configuration from an X terminal or a script with this command line: &prompt.user; setxkbmap -model pc102 -layout fr /usr/local/share/X11/xkb/rules/base.lst lists the various keyboard, layouts and options available. &xorg; tuning The xorg.conf.new configuration file may now be tuned to taste. Open the file in a text editor such as &man.emacs.1; or &man.ee.1;. If the monitor is an older or unusual model that does not support autodetection of sync frequencies, those settings can be added to xorg.conf.new under the "Monitor" section: Section "Monitor" Identifier "Monitor0" VendorName "Monitor Vendor" ModelName "Monitor Model" HorizSync 30-107 VertRefresh 48-120 EndSection Most monitors support sync frequency autodetection, making manual entry of these values unnecessary. For the few monitors that do not support autodetection, avoid potential damage by only entering values provided by the manufacturer. X allows DPMS (Energy Star) features to be used with capable monitors. The &man.xset.1; program controls the time-outs and can force standby, suspend, or off modes. If you wish to enable DPMS features for your monitor, you must add the following line to the monitor section: Option "DPMS" xorg.conf While the xorg.conf.new configuration file is still open in an editor, select the default resolution and color depth desired. This is defined in the "Screen" section: Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" DefaultDepth 24 SubSection "Display" Viewport 0 0 Depth 24 Modes "1024x768" EndSubSection EndSection The DefaultDepth keyword describes the color depth to run at by default. This can be overridden with the command line switch to &man.Xorg.1;. The Modes keyword describes the resolution to run at for the given color depth. Note that only VESA standard modes are supported as defined by the target system's graphics hardware. In the example above, the default color depth is twenty-four bits per pixel. At this color depth, the accepted resolution is 1024 by 768 pixels. Finally, write the configuration file and test it using the test mode given above. One of the tools available to assist you during troubleshooting process are the &xorg; log files, which contain information on each device that the &xorg; server attaches to. &xorg; log file names are in the format of /var/log/Xorg.0.log. The exact name of the log can vary from Xorg.0.log to Xorg.8.log and so forth. If all is well, the configuration file needs to be installed in a common location where &man.Xorg.1; can find it. This is typically /etc/X11/xorg.conf or /usr/local/etc/X11/xorg.conf. &prompt.root; cp xorg.conf.new /etc/X11/xorg.conf The &xorg; configuration process is now complete. &xorg; may be now started with the &man.startx.1; utility. The &xorg; server may also be started with the use of &man.xdm.1;. Configuration with &intel; <literal>i810</literal> Graphics Chipsets Intel i810 graphic chipset Configuration with &intel; i810 integrated chipsets requires the agpgart AGP programming interface for &xorg; to drive the card. See the &man.agp.4; driver manual page for more information. This will allow configuration of the hardware as any other graphics board. Note on systems without the &man.agp.4; driver compiled in the kernel, trying to load the module with &man.kldload.8; will not work. This driver has to be in the kernel at boot time through being compiled in or using /boot/loader.conf. Adding a Widescreen Flatpanel to the Mix widescreen flatpanel configuration This section assumes a bit of advanced configuration knowledge. If attempts to use the standard configuration tools above have not resulted in a working configuration, there is information enough in the log files to be of use in getting the setup working. Use of a text editor will be necessary. Current widescreen (WSXGA, WSXGA+, WUXGA, WXGA, WXGA+, et.al.) formats support 16:10 and 10:9 formats or aspect ratios that can be problematic. Examples of some common screen resolutions for 16:10 aspect ratios are: 2560x1600 1920x1200 1680x1050 1440x900 1280x800 At some point, it will be as easy as adding one of these resolutions as a possible Mode in the Section "Screen" as such: Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" DefaultDepth 24 SubSection "Display" Viewport 0 0 Depth 24 Modes "1680x1050" EndSubSection EndSection &xorg; is smart enough to pull the resolution information from the widescreen via I2C/DDC information so it knows what the monitor can handle as far as frequencies and resolutions. If those ModeLines do not exist in the drivers, one might need to give &xorg; a little hint. Using /var/log/Xorg.0.log one can extract enough information to manually create a ModeLine that will work. Simply look for information resembling this: (II) MGA(0): Supported additional Video Mode: (II) MGA(0): clock: 146.2 MHz Image Size: 433 x 271 mm (II) MGA(0): h_active: 1680 h_sync: 1784 h_sync_end 1960 h_blank_end 2240 h_border: 0 (II) MGA(0): v_active: 1050 v_sync: 1053 v_sync_end 1059 v_blanking: 1089 v_border: 0 (II) MGA(0): Ranges: V min: 48 V max: 85 Hz, H min: 30 H max: 94 kHz, PixClock max 170 MHz This information is called EDID information. Creating a ModeLine from this is just a matter of putting the numbers in the correct order: ModeLine <name> <clock> <4 horiz. timings> <4 vert. timings> So that the ModeLine in Section "Monitor" for this example would look like this: Section "Monitor" Identifier "Monitor1" VendorName "Bigname" ModelName "BestModel" ModeLine "1680x1050" 146.2 1680 1784 1960 2240 1050 1053 1059 1089 Option "DPMS" EndSection Now having completed these simple editing steps, X should start on your new widescreen monitor. Troubleshooting Compiz Fusion I have installed Compiz Fusion, and after running the commands you mention, my windows are left without title bars and buttons. What is wrong? You are probably missing a setting in /etc/X11/xorg.conf. Review this file carefully and check especially the DefaultDepth and AddARGBGLXVisuals directives. When I run the command to start Compiz Fusion, the X server crashes and I am back at the console. What is wrong? If you check /var/log/Xorg.0.log, you will probably find error messages during the X startup. The most common would be: (EE) NVIDIA(0): Failed to initialize the GLX module; please check in your X (EE) NVIDIA(0): log file that the GLX module has been loaded in your X (EE) NVIDIA(0): server, and that the module is the NVIDIA GLX module. If (EE) NVIDIA(0): you continue to encounter problems, Please try (EE) NVIDIA(0): reinstalling the NVIDIA driver. This is usually the case when you upgrade &xorg;. You will need to reinstall the x11/nvidia-driver package so glx is built again.