diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml index c58b946933..7c6c8ba7b8 100644 --- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml @@ -1,4174 +1,4183 @@ Advanced Networking Synopsis This chapter will cover a number of advanced networking topics. After reading this chapter, you will know: The basics of gateways and routes. How to set up IEEE 802.11 and &bluetooth; devices. How to make FreeBSD act as a bridge. How to set up network booting on a diskless machine. How to set up network address translation. How to connect two computers via PLIP. How to set up IPv6 on a FreeBSD machine. How to configure ATM under &os; 5.X. 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 FreeBSD kernel (). Know how to install additional third-party software (). Coranth Gryphon Contributed by Gateways and Routes routing gateway subnet For one machine to be able to find another over a network, there must be a mechanism in place to describe how to get from one to the other. This is called routing. A route is a defined pair of addresses: a destination and a gateway. The pair indicates that if you are trying to get to this destination, communicate through this gateway. There are three types of destinations: individual hosts, subnets, and default. The default route is used if none of the other routes apply. We will talk a little bit more about default routes later on. There are also three types of gateways: individual hosts, interfaces (also called links), and Ethernet hardware addresses (MAC addresses). An Example To illustrate different aspects of routing, we will use the following example from netstat: &prompt.user; netstat -r Routing tables Destination Gateway Flags Refs Use Netif Expire default outside-gw UGSc 37 418 ppp0 localhost localhost UH 0 181 lo0 test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 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 default route The first two lines specify the default route (which we will cover in the next section) and the localhost route. loopback device The interface (Netif column) that this routing table specifies to use for localhost is lo0, also known as the loopback device. This says to keep all traffic for this destination internal, rather than sending it out over the LAN, since it will only end up back where it started. Ethernet MAC address The next thing that stands out are the addresses beginning with 0:e0:. These are Ethernet hardware addresses, which are also known as MAC addresses. FreeBSD will automatically identify any hosts (test0 in the example) on the local Ethernet and add a route for that host, directly to it over the Ethernet interface, ed0. There is also a timeout (Expire column) associated with this type of route, which is used if we fail to hear from the host in a specific amount of time. When this happens, the route to this host will be automatically deleted. These hosts are identified using a mechanism known as RIP (Routing Information Protocol), which figures out routes to local hosts based upon a shortest path determination. subnet FreeBSD will also add subnet routes for the local subnet (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. You will notice no additional interface is specified for those. Both of these groups (local network hosts and local subnets) have their routes automatically configured by a daemon called routed. If this is not run, then only routes which are statically defined (i.e. entered explicitly) will exist. The host1 line refers to our host, which it knows by Ethernet address. Since we are the sending host, FreeBSD knows to use the loopback interface (lo0) rather than sending it out over the Ethernet interface. The two host2 lines are an example of what happens when we use an &man.ifconfig.8; alias (see the section on Ethernet for reasons why we would do this). The => symbol after the lo0 interface says that not only are we using the loopback (since this address also refers to the local host), but specifically it is an alias. Such routes only show up on the host that supports the alias; all other hosts on the local network will simply have a link#1 line for such routes. The final line (destination subnet 224) deals with multicasting, which will be covered in another section. Finally, various attributes of each route can be seen in the Flags column. Below is a short table of some of these flags and their meanings: U Up: The route is active. H Host: The route destination is a single host. G Gateway: Send anything for this destination on to this remote system, which will figure out from there where to send it. S Static: This route was configured manually, not automatically generated by the system. C Clone: Generates a new route based upon this route for machines we connect to. This type of route is normally used for local networks. W WasCloned: Indicated a route that was auto-configured based upon a local area network (Clone) route. L Link: Route involves references to Ethernet hardware. Default Routes 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 falls into a subnet that we know how to reach (Cloned routes), then the system checks to see if it can connect along that interface. If all known paths fail, the system has one last option: the default route. This route is a special type of gateway route (usually the only one present in the system), and is always marked with a c in the flags field. For hosts on a local area network, this gateway is set to whatever machine has a direct connection to the outside world (whether via PPP link, DSL, cable modem, T1, or another network interface). If you are configuring the default route for a machine which itself is functioning as the gateway to the outside world, then the default route will be the gateway machine at your Internet Service Provider's (ISP) site. Let us look at an example of default routes. This is a common configuration: [Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW] The hosts Local1 and Local2 are at your site. Local1 is connected to an ISP via a dial up PPP connection. This PPP server computer is connected through a local area network to another gateway computer through an external interface to the ISPs Internet feed. The default routes for each of your machines will be: Host Default Gateway Interface Local2 Local1 Ethernet Local1 T1-GW PPP A common question is Why (or how) would we set the T1-GW to be the default gateway for Local1, rather than the ISP server it is connected to?. Remember, since the PPP interface is using an address on the ISP's local network for your side of the connection, routes for any other machines on the ISP's local network will be automatically generated. Hence, you will already know how to reach the T1-GW machine, so there is no need for the intermediate step of sending traffic to the ISP server. It is common to use the address X.X.X.1 as the gateway address for your local network. So (using the same example), if your local class-C address space was 10.20.30 and your ISP was using 10.9.9 then the default routes would be: Host Default Route Local2 (10.20.30.2) Local1 (10.20.30.1) Local1 (10.20.30.1, 10.9.9.30) T1-GW (10.9.9.1) You can easily define the default route via the /etc/rc.conf file. In our example, on the Local2 machine, we added the following line in /etc/rc.conf: defaultrouter="10.20.30.1" It is also possible to do it directly from the command line with the &man.route.8; command: &prompt.root; route add default 10.20.30.1 For more information on manual manipulation of network routing tables, consult &man.route.8; manual page. Dual Homed Hosts dual homed hosts There is one other type of configuration that we should cover, and that is a host that sits on two different networks. Technically, any machine functioning as a gateway (in the example above, using a PPP connection) counts as a dual-homed host. But the term is really only used to refer to a machine that sits on two local-area networks. In one case, the machine has two Ethernet cards, each having an address on the separate subnets. Alternately, the machine may only have one Ethernet card, and be using &man.ifconfig.8; aliasing. The former is used if two physically separate Ethernet networks are in use, the latter if there is one physical network segment, but two logically separate subnets. Either way, routing tables are set up so that each subnet knows that this machine is the defined gateway (inbound route) to the other subnet. This configuration, with the machine acting as a router between the two subnets, is often used when we need to implement packet filtering or firewall security in either or both directions. If you want this machine to actually forward packets between the two interfaces, you need to tell FreeBSD to enable this ability. See the next section for more details on how to do this. Building a Router router A network router is simply a system that forwards packets from one interface to another. Internet standards and good engineering practice prevent the FreeBSD Project from enabling this by default in FreeBSD. You can enable this feature by changing the following variable to YES in &man.rc.conf.5;: gateway_enable=YES # Set to YES if this host will be a gateway This option will set the &man.sysctl.8; variable net.inet.ip.forwarding to 1. If you should need to stop routing temporarily, you can reset this to 0 temporarily. Your new router will need routes to know where to send the traffic. If your network is simple enough you can use static routes. FreeBSD also comes with the standard BSD routing daemon &man.routed.8;, which speaks RIP (both version 1 and version 2) and IRDP. Support for BGP v4, OSPF v2, and other sophisticated routing protocols is available with the net/zebra package. Commercial products such as &gated; are also available for more complex network routing solutions. BGP RIP OSPF Al Hoang Contributed by Setting Up Static Routes Manual Configuration Let us assume we have a network as follows: 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 our &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. We will assume that RouterB is already configured properly and knows how to get wherever it needs to go. (This is simple in this picture. Just add a default route on RouterB using 192.168.1.1 as the gateway.) If we look at the routing table for RouterA we would see something like the following: &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/24 link#1 UC 0 0 xl0 192.168.1/24 link#2 UC 0 0 xl1 With the current routing table RouterA will not be able to reach our Internal Net 2. It does not have a route for 192.168.2.0/24. One way to alleviate this is to manually add the route. The following command would add 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 hosts on the 192.168.2.0/24 network. Persistent Configuration The above example is perfect for configuring a static route on a running system. However, one problem is that the routing information will not persist if you reboot your &os; machine. The way to handle the addition of a static route is to put it in your /etc/rc.conf file: # Add Internal Net 2 as a 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. Each string references to a route name. In our above example we only have one string in static_routes. This string is internalnet2. We then add a configuration variable called route_internalnet2 where we put all of the configuration parameters we would give to the &man.route.8; command. For our example above we would have used the command: &prompt.root; route add -net 192.168.2.0/24 192.168.1.2 so we need "-net 192.168.2.0/24 192.168.1.2". As said above, we can have more than one string in static_routes. This allows us to create multiple static routes. The following lines shows an example of adding static routes for the 192.168.0.0/24 and 192.168.1.0/24 networks on an imaginary router: 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" Routing Propagation routing propagation We have already talked about how we define our routes to the outside world, but not about how the outside world finds us. We already know that routing tables can be set up so that all traffic for a particular address space (in our examples, a class-C subnet) can be sent to a particular host on that network, which will forward the packets inbound. When you get an address space assigned to your site, your service provider will set up their routing tables so that all traffic for your subnet will be sent down your PPP link to your site. But how do sites across the country know to send to your ISP? There is a system (much like the distributed DNS information) that keeps track of all assigned address-spaces, and defines their point of connection to the Internet Backbone. The Backbone are 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 your network. It is the task of your service provider to advertise to the backbone sites that they are the point of connection (and thus the path inward) for your site. This is known as route propagation. Troubleshooting traceroute Sometimes, there is a problem with routing propagation, and some sites are unable to connect to you. Perhaps the most useful command for trying to figure out where routing is breaking down is the &man.traceroute.8; command. It is equally useful if you cannot seem to make a connection to a remote machine (i.e. &man.ping.8; fails). The &man.traceroute.8; command is run with the name of the remote host you are trying to connect to. It 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, see the manual page for &man.traceroute.8;. Multicast Routing multicast routing kernel options MROUTING FreeBSD supports both multicast applications and multicast routing natively. Multicast applications do not require any special configuration of FreeBSD; applications will generally run out of the box. Multicast routing requires that support be compiled into the kernel: options MROUTING In addition, the multicast routing daemon, &man.mrouted.8; must be configured to set up tunnels and DVMRP via /etc/mrouted.conf. More details on multicast configuration may be found in the manual page for &man.mrouted.8;. Eric Anderson Written by Wireless Networking wireless networking 802.11 wireless networking Introduction It can be very useful to be able to use a computer without the annoyance of having a network cable attached at all times. FreeBSD can be used as a wireless client, and even as a wireless access point. Wireless Modes of Operation There are two different ways to configure 802.11 wireless devices: BSS and IBSS. BSS Mode BSS mode is the mode that typically is used. BSS mode is also called infrastructure mode. In this mode, a number of wireless access points are connected to a wired network. Each wireless network has its own name. This name is called the SSID of the network. Wireless clients connect to these wireless access points. The IEEE 802.11 standard defines the protocol that wireless networks use to connect. A wireless client can be tied to a specific network, when a SSID is set. A wireless client can also attach to any network by not explicitly setting a SSID. IBSS Mode IBSS mode, also called ad-hoc mode, is designed for point to point connections. There are actually two types of ad-hoc mode. One is IBSS mode, also called ad-hoc or IEEE ad-hoc mode. This mode is defined by the IEEE 802.11 standards. The second is called demo ad-hoc mode or Lucent ad-hoc mode (and sometimes, confusingly, ad-hoc mode). This is the old, pre-802.11 ad-hoc mode and should only be used for legacy installations. We will not cover either of the ad-hoc modes further. Infrastructure Mode Access Points Access points are wireless networking devices that allow one or more wireless clients to use the device as a central hub. When using an access point, all clients communicate through the access point. Multiple access points are often used to cover a complete area such as a house, business, or park with a wireless network. Access points typically have multiple network connections: the wireless card, and one or more wired Ethernet adapters for connection to the rest of the network. Access points can either be purchased prebuilt, or you can build your own with FreeBSD and a supported wireless card. Several vendors make wireless access points and wireless cards with various features. Building a FreeBSD Access Point wireless networking access point Requirements In order to set up a wireless access point with FreeBSD, you need to have a compatible wireless card. Currently, only cards with the Prism chipset are supported. You will also need a wired network card that is supported by FreeBSD (this should not be difficult to find, FreeBSD supports a lot of different devices). For this guide, we will assume you want to &man.bridge.4; all traffic between the wireless device and the network attached to the wired network card. The hostap functionality that FreeBSD uses to implement the access point works best with certain versions of firmware. Prism 2 cards should use firmware version 1.3.4 or newer. Prism 2.5 and Prism 3 cards should use firmware 1.4.9. Older versions of the firmware way or may not function correctly. At this time, the only way to update cards is with &windows; firmware update utilities available from your card's manufacturer. Setting It Up First, make sure your system can see the wireless card: &prompt.root; ifconfig -a wi0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7 inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255 ether 00:09:2d:2d:c9:50 media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps) status: no carrier ssid "" stationname "FreeBSD Wireless node" channel 10 authmode OPEN powersavemode OFF powersavesleep 100 wepmode OFF weptxkey 1 Do not worry about the details now, just make sure it shows you something to indicate you have a wireless card installed. If you have trouble seeing the wireless interface, and you are using a PC Card, you may want to check out &man.pccardc.8; and &man.pccardd.8; manual pages for more information. Next, you will need to load a module in order to get the bridging part of FreeBSD ready for the access point. To load the &man.bridge.4; module, simply run the following command: &prompt.root; kldload bridge It should not have produced any errors when loading the module. If it did, you may need to compile the &man.bridge.4; code into your kernel. The Bridging section of this handbook should be able to help you accomplish that task. Now that you have the bridging stuff done, we need to tell the FreeBSD kernel which interfaces to bridge together. We do that by using &man.sysctl.8;: &prompt.root; sysctl net.link.ether.bridge=1 &prompt.root; sysctl net.link.ether.bridge_cfg="wi0,xl0" &prompt.root; sysctl net.inet.ip.forwarding=1 On &os; 5.2-RELEASE and later, you have to use instead the following options: &prompt.root; sysctl net.link.ether.bridge.enable=1 &prompt.root; sysctl net.link.ether.bridge.config="wi0,xl0" &prompt.root; sysctl net.inet.ip.forwarding=1 Now it is time for the wireless card setup. The following command will set the card into an access point: &prompt.root; ifconfig wi0 ssid my_net channel 11 media DS/11Mbps mediaopt hostap up stationname "FreeBSD AP" The &man.ifconfig.8; line brings the wi0 interface up, sets its SSID to my_net, and sets the station name to FreeBSD AP. The sets the card into 11Mbps mode and is needed for any to take effect. The option places the interface into access point mode. The option sets the 802.11b channel to use. The &man.wicontrol.8; manual page has valid channel options for your regulatory domain. Now you should have a complete functioning access point up and running. You are encouraged to read &man.wicontrol.8;, &man.ifconfig.8;, and &man.wi.4; for further information. It is also suggested that you read the section on encryption that follows. Status Information Once the access point is configured and operational, operators will want to see the clients that are associated with the access point. At any time, the operator may type: &prompt.root; wicontrol -l 1 station: 00:09:b7:7b:9d:16 asid=04c0, flags=3<ASSOC,AUTH>, caps=1<ESS>, rates=f<1M,2M,5.5M,11M>, sig=38/15 This shows that there is one station associated, along with its parameters. The signal indicated should be used as a relative indication of strength only. Its translation to dBm or other units varies between different firmware revisions. Clients A wireless client is a system that accesses an access point or another client directly. Typically, wireless clients only have one network device, the wireless networking card. There are a few different ways to configure a wireless client. These are based on the different wireless modes, generally BSS (infrastructure mode, which requires an access point), and IBSS (ad-hoc, or peer-to-peer mode). In our example, we will use the most popular of the two, BSS mode, to talk to an access point. Requirements There is only one real requirement for setting up FreeBSD as a wireless client. You will need a wireless card that is supported by FreeBSD. Setting Up a Wireless FreeBSD Client You will need to know a few things about the wireless network you are joining before you start. In this example, we are joining a network that has a name of my_net, and encryption turned off. In this example, we are not using encryption, which is a dangerous situation. In the next section, you will learn how to turn on encryption, why it is important to do so, and why some encryption technologies still do not completely protect you. Make sure your card is recognized by FreeBSD: &prompt.root; ifconfig -a wi0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7 inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255 ether 00:09:2d:2d:c9:50 media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps) status: no carrier ssid "" stationname "FreeBSD Wireless node" channel 10 authmode OPEN powersavemode OFF powersavesleep 100 wepmode OFF weptxkey 1 Now, we can set the card to the correct settings for our network: &prompt.root; ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net Replace 192.168.0.20 and 255.255.255.0 with a valid IP address and netmask on your wired network. Remember, our access point is bridging the data between the wireless network, and the wired network, so it will appear to the other devices on your network that you are on the wired network just as they are. Once you have done that, you should be able to ping hosts on the wired network just as if you were connected using a standard wired connection. If you are experiencing problems with your wireless connection, check to make sure that you are associated (connected) to the access point: &prompt.root; ifconfig wi0 should return some information, and you should see: status: associated If it does not show associated, then you may be out of range of the access point, have encryption on, or possibly have a configuration problem. Encryption wireless networking encryption Encryption on a wireless network is important because you no longer have the ability to keep the network contained in a well protected area. Your wireless data will be broadcast across your entire neighborhood, so anyone who cares to read it can. This is where encryption comes in. By encrypting the data that is sent over the airwaves, you make it much more difficult for any interested party to grab your data right out of the air. The two most common ways to encrypt the data between your client and the access point are WEP, and &man.ipsec.4;. WEP WEP WEP is an abbreviation for Wired Equivalency Protocol. WEP is an attempt to make wireless networks as safe and secure as a wired network. Unfortunately, it has been cracked, and is fairly trivial to break. This also means it is not something to rely on when it comes to encrypting sensitive data. It is better than nothing, so use the following to turn on WEP on your new FreeBSD access point: &prompt.root; ifconfig wi0 inet up ssid my_net wepmode on wepkey 0x1234567890 media DS/11Mbps mediaopt hostap And you can turn on WEP on a client with this command: &prompt.root; ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net wepmode on wepkey 0x1234567890 Note that you should replace the 0x1234567890 with a more unique key. IPsec &man.ipsec.4; is a much more robust and powerful tool for encrypting data across a network. This is definitely the preferred way to encrypt data over a wireless network. You can read more about &man.ipsec.4; security and how to implement it in the IPsec section of this handbook. Tools There are a small number of tools available for use in debugging and setting up your wireless network, and here we will attempt to describe some of them and what they do. The <application>bsd-airtools</application> Package The bsd-airtools package is a complete toolset that includes wireless auditing tools for WEP key cracking, access point detection, etc. The bsd-airtools utilities can be installed from the net/bsd-airtools port. Information on installing ports can be found in of this handbook. The program dstumbler is the packaged tool that allows for access point discovery and signal to noise ratio graphing. If you are having a hard time getting your access point up and running, dstumbler may help you get started. To test your wireless network security, you may choose to use dweputils (dwepcrack, dwepdump and dwepkeygen) to help you determine if WEP is the right solution to your wireless security needs. The <command>wicontrol</command>, <command>ancontrol</command> and <command>raycontrol</command> Utilities These are the tools you can use to control how your wireless card behaves on the wireless network. In the examples above, we have chosen to use &man.wicontrol.8;, since our wireless card is a wi0 interface. If you had a Cisco wireless device, it would come up as an0, and therefore you would use &man.ancontrol.8;. The <command>ifconfig</command> Command ifconfig The &man.ifconfig.8; command can be used to do many of the same options as &man.wicontrol.8;, however it does lack a few options. Check &man.ifconfig.8; for command line parameters and options. Supported Cards Access Points The only cards that are currently supported for BSS (as an access point) mode are devices based on the Prism 2, 2.5, or 3 chipsets. For a complete list, look at &man.wi.4;. 802.11b Clients Almost all 802.11b wireless cards are currently supported under FreeBSD. Most cards based on Prism, Spectrum24, Hermes, Aironet, and Raylink will work as a wireless network card in IBSS (ad-hoc, peer-to-peer, and BSS) mode. 802.11a & 802.11g Clients The &man.ath.4; device driver supports 802.11a and 802.11g. If your card is based on an Atheros chipset, you may be able to use this driver. Unfortunately, there are still many vendors that do not provide schematics for their drivers to the open source community because they regard such information as trade secrets. Consequently, the developers of FreeBSD and other operating systems are left two choices: develop the drivers by a long and pain-staking process of reverse engineering or using the existing driver binaries available for the µsoft.windows; platforms. Most developers, including those involved with FreeBSD, have taken the latter approach. Thanks to the contributions of Bill Paul (wpaul), as of FreeBSD 5.3-RELEASE there is native support for the Network Driver Interface Specification (NDIS). The FreeBSD NDISulator (otherwise known as Project Evil) takes a &windows; driver binary and basically tricks it into thinking it is running on &windows;. This feature is still relatively new, but most test cases seem to work adequately. In order to use the NDISulator, you need three things: Kernel sources &windowsxp; driver binary (.SYS extension) &windowsxp; driver configuration file (.INF extension) You may need to compile the &man.ndis.4; mini port driver wrapper module. As root: &prompt.root; cd /usr/src/sys/modules/ndis &prompt.root; make && make install Locate the files for your specific card. Generally, they can be found on the included CDs or at the vendors' websites. In the following examples, we will use W32DRIVER.SYS and W32DRIVER.INF. The next step is to compile the driver binary into a loadable kernel module. To accomplish this, as root, go into the if_ndis module directory and copy the &windows; driver files into it: &prompt.root; cd /usr/src/sys/modules/if_ndis &prompt.root; cp /path/to/driver/W32DRIVER.SYS ./ &prompt.root; cp /path/to/driver/W32DRIVER.INF ./ We will now use the ndiscvt utility to create the driver definition header ndis_driver_data.h to build the module: &prompt.root; ndiscvt -i W32DRIVER.INF -s W32DRIVER.SYS -o ndis_driver_data.h The and options specify the configuration and binary files, respectively. We use the option because the Makefile will be looking for this file when it comes time to build the module. Some &windows; drivers require additional files to operate. You may include them with ndiscvt by using the option. Consult the &man.ndiscvt.8; manual page for more information. Finally, we can build and install the driver module: &prompt.root; make && make install To use the driver, you must load the appropriate modules: &prompt.root; kldload ndis &prompt.root; kldload if_ndis The first command loads the NDIS miniport driver wrapper, the second loads the actual network interface. Check &man.dmesg.8; to see if there were any errors loading. If all went well, you should get output resembling the following: ndis0: <Wireless-G PCI Adapter> mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1 ndis0: NDIS API version: 5.0 ndis0: Ethernet address: 0a:b1:2c:d3:4e:f5 ndis0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps From here you can treat the ndis0 device like any other wireless device (e.g. wi0) and consult the earlier sections of this chapter. Pav Lucistnik Written by
pav@oook.cz
 Bluetooth Bluetooth Introduction 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 the other popular wireless technology, Wi-Fi, Bluetooth offers higher level service profiles, e.g. FTP-like file servers, file pushing, voice transport, serial line emulation, and more. The Bluetooth stack in &os; is implemented using the Netgraph framework (see &man.netgraph.4;). A broad variety of Bluetooth USB dongles is supported by the &man.ng.ubt.4; driver. The Broadcom BCM2033 chip based Bluetooth devices are supported via 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 via &man.sio.4;, &man.ng.h4.4; and &man.hcseriald.8;. This section describes the use of the USB Bluetooth dongle. Bluetooth support is available in &os; 5.0 and newer systems. Plugging in the Device By default Bluetooth device drivers are available as kernel modules. Before attaching a device, you will need to load the driver into the kernel: &prompt.root; kldload ng_ubt If the Bluetooth device is present in the system during system startup, load the module from /boot/loader.conf: ng_ubt_load="YES" Plug in your USB dongle. The output similar to the following will appear on the console (or in syslog): 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 Copy /usr/share/examples/netgraph/bluetooth/rc.bluetooth into some convenient place, like /etc/rc.bluetooth. This script is used to start and stop the Bluetooth stack. It is a good idea to stop the stack before unplugging the device, but it is not (usually) fatal. When starting the stack, you will receive output similar to the following: &prompt.root; /etc/rc.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 HCI Host Controller Interface (HCI) Host Controller Interface (HCI) provides a command interface to the baseband controller and link manager, and access to hardware status and control registers. This interface provides a uniform method of accessing the Bluetooth baseband capabilities. HCI layer on the Host exchanges data and commands with the HCI firmware on the Bluetooth hardware. The Host Controller Transport Layer (i.e. physical bus) driver provides both HCI layers with the ability to exchange information with each other. A single Netgraph node of type hci is created for a single Bluetooth device. The HCI node is normally connected to the Bluetooth device driver node (downstream) and the L2CAP node (upstream). All HCI operations must be performed on the HCI node and not on the device driver node. Default name for the HCI node is devicehci. For more details refer to the &man.ng.hci.4; manual page. One of the most common tasks is discovery of Bluetooth devices in RF proximity. This operation is called inquiry. Inquiry and other HCI related operations are done with the &man.hccontrol.8; utility. The example below shows how to find out which Bluetooth devices are in range. You should receive the list of devices in a few seconds. Note that a remote device will only answer the inquiry if it put into 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] BD_ADDR is unique address of a Bluetooth device, similar to MAC addresses of a network card. This address is needed for further communication with a device. It is possible to assign human readable name to a BD_ADDR. The /etc/bluetooth/hosts file contains information regarding the known Bluetooth hosts. The following example shows how to obtain 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 you perform an inquiry on a remote Bluetooth device, it will find your 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 (only two Bluetooth units involved), or a point-to-multipoint connection. In the point-to-multipoint connection the connection 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. Note, that it is normally not required to do it 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] Refer to hccontrol help for a complete listing of available HCI commands. Most of the HCI commands do not require superuser privileges. L2CAP Logical Link Control and Adaptation Protocol (L2CAP) Logical Link Control and Adaptation Protocol (L2CAP) provides connection-oriented and connectionless data services to upper layer protocols with protocol multiplexing capability and segmentation and reassembly operation. 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. Channel is a logical connection on top of baseband connection. 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. A single Netgraph node of type l2cap is created for a single Bluetooth device. The L2CAP node is normally connected to the Bluetooth HCI node (downstream) and Bluetooth sockets nodes (upstream). Default name for the L2CAP node is devicel2cap. For more details refer to the &man.ng.l2cap.4; manual page. 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 does a job similar to as &man.netstat.1; does, 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 RFCOMM RFCOMM Protocol The RFCOMM protocol provides emulation of serial ports over the L2CAP protocol. The protocol is based on the ETSI standard TS 07.10. RFCOMM is a simple transport protocol, with additional provisions for emulating the 9 circuits of RS-232 (EIATIA-232-E) serial ports. The RFCOMM protocol 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 different devices (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 Bluetooth link from one device to another (direct connect). 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; the RFCOMM protocol is implemented at the Bluetooth sockets layer. pairing Pairing of Devices By default, Bluetooth communication is not authenticated, and any device can talk to any other device. A Bluetooth device (for example, cellular phone) may choose to require authentication to provide a particular service (for example, Dial-Up service). Bluetooth authentication is normally done with PIN codes. A PIN code is an ASCII string up to 16 characters in length. User is required to enter the same PIN code on both devices. Once 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 themselves or in a persistent storage. Next time both devices will use previously generated link key. The described above procedure is called pairing. Note that if the link key is lost by any device then pairing must be repeated. The &man.hcsecd.8; daemon is responsible for handling of all Bluetooth authentication requests. The default configuration file is /etc/bluetooth/hcsecd.conf. An example section for a cellular phone with the PIN code arbitrarily set to 1234 is shown below: device { bdaddr 00:80:37:29:19:a4; name "Pav's T39"; key nokey; pin "1234"; } There is no limitation on PIN codes (except length). Some devices (for example Bluetooth headsets) may have a fixed PIN code built in. The switch forces the &man.hcsecd.8; daemon 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 say that pairing was accepted, and request the PIN code. Enter the same PIN code as you have in hcsecd.conf. Now your PC and the remote device are paired. Alternatively, you can initiate pairing on the remote device. The following is a sample of the hcsecd 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 SDP Service Discovery Protocol (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 a priori 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 ... and so on. Note that each service has a list of attributes (RFCOMM channel for example). Depending on the service you might need to make a 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: &prompt.root; sdpd The local server application that wants to provide Bluetooth service to the remote clients will register service with the local SDP daemon. The example of such application is &man.rfcomm.pppd.8;. Once started it will register Bluetooth LAN service with the local SDP daemon. The list of services registered with the local SDP server can be obtained by issuing SDP browse query via local control channel: &prompt.root; sdpcontrol -l browse Dial-Up Networking (DUN) and Network Access with PPP (LAN) Profiles The Dial-Up Networking (DUN) profile is mostly used with modems and cellular phones. The scenarios covered by this profile are the following: use of a cellular phone or modem by a computer as a wireless modem for connecting to a dial-up Internet access server, or using other dial-up services; use of a cellular phone or modem by a computer to receive data calls. Network Access with PPP (LAN) profile can be used in the following situations: LAN access for a single Bluetooth device; LAN access for multiple Bluetooth devices; PC to PC (using PPP networking over serial cable emulation). In &os; both profiles are implemented with &man.ppp.8; and &man.rfcomm.pppd.8; - a wrapper that converts RFCOMM Bluetooth connection into something PPP can operate with. Before any profile can be used, a new PPP label in the /etc/ppp/ppp.conf must be created. Consult &man.rfcomm.pppd.8; manual page for examples. In the following example &man.rfcomm.pppd.8; will be used to open RFCOMM connection to remote device with BD_ADDR 00:80:37:29:19:a4 on DUN RFCOMM channel. The actual RFCOMM channel number will be obtained from the remote device via SDP. It is possible to specify RFCOMM channel by hand, and in this case &man.rfcomm.pppd.8; will not perform SDP query. Use &man.sdpcontrol.8; to find out RFCOMM channel on the remote device. &prompt.root; rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup In order to provide Network Access with PPP (LAN) service the &man.sdpd.8; server must be running. A new entry for LAN clients must be created in the /etc/ppp/ppp.conf file. Consult &man.rfcomm.pppd.8; manual page for examples. Finally, start RFCOMM PPP server on valid RFCOMM channel number. The RFCOMM PPP server will automatically register Bluetooth LAN service with the local SDP daemon. The example below shows how to start RFCOMM PPP server. &prompt.root; rfcomm_pppd -s -C 7 -l rfcomm-server OBEX OBEX Object Push (OPUSH) Profile 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 PIM applications. The OBEX server and client are implemented as a third-party package obexapp, which is available as comms/obexapp port. OBEX client is used to push and/or pull objects from the OBEX server. An object can, for example, be a business card or an appointment. The OBEX client can obtain RFCOMM channel number from the remote device via SDP. This can be done by specifying service name instead of RFCOMM channel number. Supported service names are: IrMC, FTRN and OPUSH. It is possible to specify RFCOMM channel as a number. Below is an example of an OBEX session, where device information object is pulled from the cellular phone, and a new object (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 OBEX Object Push service, &man.sdpd.8; server must be running. 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 OBEX server on valid RFCOMM channel number. The OBEX server will automatically register OBEX Object Push service with the local SDP daemon. The example below shows how to start OBEX server. &prompt.root; obexapp -s -C 10 Serial Port Profile (SPP) The Serial Port Profile (SPP) allows Bluetooth devices to perform RS232 (or similar) serial cable emulation. The scenario covered by this profile deals with legacy applications using Bluetooth as a cable replacement, through a virtual serial port abstraction. The &man.rfcomm.sppd.1; utility implements the Serial Port profile. A pseudo tty is used as a virtual serial port abstraction. The example below shows how to connect to a remote device Serial Port service. Note that you do not have to specify a RFCOMM channel - &man.rfcomm.sppd.1; can obtain it from the remote device via SDP. If you would like to override this, specify a RFCOMM channel on the command line. &prompt.root; rfcomm_sppd -a 00:07:E0:00:0B:CA -t /dev/ttyp6 rfcomm_sppd[94692]: Starting on /dev/ttyp6... Once connected, the pseudo tty can be used as serial port: &prompt.root; cu -l ttyp6 Troubleshooting A remote device cannot connect Some older Bluetooth devices do not support role switching. By default, when &os; is accepting a new connection, it tries to perform a role switch and become master. Devices, which do not support this will not be able to connect. Note that role switching is performed when a new connection is being established, so it is not possible to ask the remote device if it does support role switching. There is a HCI option to disable role switching on the local side: &prompt.root; hccontrol -n ubt0hci write_node_role_switch 0 Something is going wrong, can I see what exactly is happening? Yes, you can. Use the third-party package hcidump, which is available as comms/hcidump port. The hcidump utility is similar to &man.tcpdump.1;. It can be used to display the content of the Bluetooth packets on the terminal and to dump the Bluetooth packets to a file. Steve Peterson Written by Bridging Introduction IP subnet bridge It is sometimes useful to divide one physical network (such as an Ethernet segment) into two separate 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 FreeBSD system with two network interface cards can act as a bridge. The bridge works by learning the MAC layer addresses (Ethernet addresses) of the devices on each of its network interfaces. It forwards traffic between two networks only when its source and destination are on different networks. In many respects, a bridge is like an Ethernet switch with very few ports. Situations Where Bridging Is Appropriate There are two common situations in which a bridge is used today. High Traffic on a Segment Situation one is where your physical network segment is overloaded with traffic, but you do not want for whatever reason to subnet the network and interconnect the subnets with a router. Let us consider an example of a newspaper where the Editorial and Production departments are on the same subnetwork. The Editorial users all use server A for file service, and the Production users are on server B. An Ethernet network is used to connect all users together, and high loads on the network are slowing things down. If the Editorial users could be segregated on one network segment and the Production users on another, the two network segments could be connected with a bridge. Only the network traffic destined for interfaces on the other side of the bridge would be sent to the other network, reducing congestion on each network segment. Filtering/Traffic Shaping Firewall firewall network address translation The second common situation is where firewall functionality is needed without network address translation (NAT). An example is a small company that is connected via DSL or ISDN to their ISP. They have a 13 globally-accessible IP addresses from their ISP and have 10 PCs on their network. In this situation, using a router-based firewall is difficult because of subnetting issues. router DSL ISDN A bridge-based firewall can be configured and dropped into the path just downstream of their DSL/ISDN router without any IP numbering issues. Configuring a Bridge Network Interface Card Selection A bridge requires at least two network cards to function. Unfortunately, not all network interface cards as of FreeBSD 4.0 support bridging. Read &man.bridge.4; for details on the cards that are supported. Install and test the two network cards before continuing. Kernel Configuration Changes kernel options BRIDGE To enable kernel support for bridging, add the: options BRIDGE statement to your kernel configuration file, and rebuild your kernel. Firewall Support firewall If you are planning to use the bridge as a firewall, you will need to add the IPFIREWALL option as well. Read for general information on configuring the bridge as a firewall. If you need to allow non-IP packets (such as ARP) to flow through the bridge, there is a firewall option that must be set. This option is IPFIREWALL_DEFAULT_TO_ACCEPT. Note that this changes the default rule for the firewall to accept any packet. Make sure you know how this changes the meaning of your ruleset before you set it. Traffic Shaping Support If you want to use the bridge as a traffic shaper, you will need to add the DUMMYNET option to your kernel configuration. Read &man.dummynet.4; for further information. Enabling the Bridge Add the line: net.link.ether.bridge.enable=1 to /etc/sysctl.conf to enable the bridge at runtime, and the line: net.link.ether.bridge.config=if1,if2 to enable bridging on the specified interfaces (replace if1 and if2 with the names of your two network interfaces). If you want the bridged packets to be filtered by &man.ipfw.8;, you should add: net.link.ether.bridge.ipfw=1 as well. For versions prior to &os; 5.2-RELEASE, use instead the following lines: net.link.ether.bridge=1 net.link.ether.bridge_cfg=if1,if2 net.link.ether.bridge_ipfw=1 Other Information If you want to be able to &man.ssh.1; into the bridge from the network, it is correct to assign one of the network cards an IP address. The consensus is that assigning both cards an address is a bad idea. If you have multiple bridges on your network, there cannot be more than one path between any two workstations. Technically, this means that there is no support for spanning tree link management. A bridge can add latency to your &man.ping.8; times, especially for traffic from one segment to another. Jean-François Dockès Updated by Alex Dupre Reorganized and enhanced by Diskless Operation diskless workstation diskless operation A FreeBSD machine can boot over the network and operate without a local disk, using filesystems mounted from an NFS server. No system modification is necessary, beyond standard configuration files. Such a system is relatively easy to set up because all the necessary elements are readily available: There are at least two possible methods to load the kernel over the network: PXE: The &intel; Preboot eXecution Environment system is a form of smart boot ROM built into some networking cards or motherboards. See &man.pxeboot.8; for more details. The Etherboot port (net/etherboot) produces ROM-able code to boot kernels over the network. The code can be either burnt into a boot PROM on a network card, or loaded from a local floppy (or hard) disk drive, or from a running &ms-dos; system. Many network cards are supported. A sample script (/usr/share/examples/diskless/clone_root) eases the creation and maintenance of the workstation's root filesystem on the server. The script will probably require a little customization but it will get you started very quickly. Standard system startup files exist in /etc to detect and support a diskless system startup. Swapping, if needed, can be done either to an NFS file or to a local disk. There are many ways to set up diskless workstations. Many elements are involved, and most can be customized to suit local taste. The following will describe variations on the setup of a complete system, emphasizing simplicity and compatibility with the standard FreeBSD startup scripts. The system described has the following characteristics: The diskless workstations use a shared read-only / filesystem, and a shared read-only /usr. The root filesystem is a copy of a standard FreeBSD root (typically the server's), with some configuration files overridden by ones specific to diskless operation or, possibly, to the workstation they belong to. The parts of the root which have to be writable are overlaid with &man.mfs.8; (&os; 4.X) or &man.md.4; (&os; 5.X) filesystems. Any changes will be lost when the system reboots. The kernel is transferred and loaded either with Etherboot or PXE as some situations may mandate the use of either method. As described, this system is insecure. It should live in a protected area of a network, and be untrusted by other hosts. All the information in this section has been tested using &os; releases 4.9-RELEASE and 5.2.1-RELEASE. The text is primarily structured for 4.X usage. Notes have been inserted where appropriate to indicate 5.X changes. Background Information Setting up diskless workstations is both relatively straightforward and prone to errors. These are sometimes difficult to diagnose for a number of reasons. For example: Compile time options may determine different behaviors at runtime. Error messages are often cryptic or totally absent. In this context, having some knowledge of the background mechanisms involved is very useful to solve the problems that may arise. Several operations need to be performed for a successful bootstrap: The machine needs to obtain initial parameters such as its IP address, executable filename, server name, root path. This is done using the DHCP or BOOTP protocols. DHCP is a compatible extension of BOOTP, and uses the same port numbers and basic packet format. It is possible to configure a system to use only BOOTP. The &man.bootpd.8; server program is included in the base &os; system. However, DHCP has a number of advantages over BOOTP (nicer configuration files, possibility of using PXE, plus many others not directly related to diskless operation), and we will describe mainly a DHCP configuration, with equivalent examples using &man.bootpd.8; when possible. The sample configuration will use the ISC DHCP software package (release 3.0.1.r12 was installed on the test server). The machine needs to transfer one or several programs to local memory. Either TFTP or NFS are used. The choice between TFTP and NFS is a compile time option in several places. A common source of error is to specify filenames for the wrong protocol: TFTP typically transfers all files from a single directory on the server, and would expect filenames relative to this directory. NFS needs absolute file paths. The possible intermediate bootstrap programs and the kernel need to be initialized and executed. There are several important variations in this area: PXE will load &man.pxeboot.8;, which is a modified version of the &os; third stage loader. The &man.loader.8; will obtain most parameters necessary to system startup, and leave them in the kernel environment before transferring control. It is possible to use a GENERIC kernel in this case. Etherboot, will directly load the kernel, with less preparation. You will need to build a kernel with specific options. PXE and Etherboot work equally well with 4.X systems. Because 5.X kernels normally let the &man.loader.8; do more work for them, PXE is preferred for 5.X systems. If your BIOS and network cards support PXE, you should probably use it. However, it is still possible to start a 5.X system with Etherboot. Finally, the machine needs to access its filesystems. NFS is used in all cases. See also &man.diskless.8; manual page. Setup Instructions Configuration Using <application>ISC DHCP</application> DHCP diskless operation The ISC DHCP server can answer both BOOTP and DHCP requests. As of release 4.9, ISC DHCP 3.0 is not part of the base system. You will first need to install the net/isc-dhcp3-server port or the corresponding package. Once ISC DHCP is installed, it needs a configuration file to run, (normally named /usr/local/etc/dhcpd.conf). Here follows a commented example, where host margaux uses Etherboot and host corbieres uses PXE: default-lease-time 600; max-lease-time 7200; authoritative; option domain-name "example.com"; option domain-name-servers 192.168.4.1; option routers 192.168.4.1; subnet 192.168.4.0 netmask 255.255.255.0 { use-host-decl-names on; option subnet-mask 255.255.255.0; option broadcast-address 192.168.4.255; host margaux { hardware ethernet 01:23:45:67:89:ab; fixed-address margaux.example.com; next-server 192.168.4.4; filename "/data/misc/kernel.diskless"; option root-path "192.168.4.4:/data/misc/diskless"; } host corbieres { hardware ethernet 00:02:b3:27:62:df; fixed-address corbieres.example.com; next-server 192.168.4.4; filename "pxeboot"; option root-path "192.168.4.4:/data/misc/diskless"; } } This option tells dhcpd to send the value in the host declarations as the hostname for the diskless host. An alternate way would be to add an option host-name margaux inside the host declarations. The next-server directive designates the TFTP or NFS server to use for loading loader or kernel file (the default is to use the same host as the DHCP server). The filename directive defines the file that Etherboot or PXE will load for the next execution step. It must be specified according to the transfer method used. Etherboot can be compiled to use NFS or TFTP. The &os; port configures NFS by default. PXE uses TFTP, which is why a relative filename is used here (this may depend on the TFTP server configuration, but would be fairly typical). Also, PXE loads pxeboot, not the kernel. There are other interesting possibilities, like loading pxeboot from a &os; CD-ROM /boot directory (as &man.pxeboot.8; can load a GENERIC kernel, this makes it possible to use PXE to boot from a remote CD-ROM). The root-path option defines the path to the root filesystem, in usual NFS notation. When using PXE, it is possible to leave off the host's IP as long as you do not enable the kernel option BOOTP. The NFS server will then be the same as the TFTP one. Configuration Using BOOTP BOOTP diskless operation Here follows an equivalent bootpd configuration (reduced to one client). This would be found in /etc/bootptab. Please note that Etherboot must be compiled with the non-default option NO_DHCP_SUPPORT in order to use BOOTP, and that PXE needs DHCP. The only obvious advantage of bootpd is that it exists in the base system. .def100:\ :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\ :sm=255.255.255.0:\ :ds=192.168.4.1:\ :gw=192.168.4.1:\ :hd="/tftpboot":\ :bf="/kernel.diskless":\ :rp="192.168.4.4:/data/misc/diskless": margaux:ha=0123456789ab:tc=.def100 Preparing a Boot Program with <application>Etherboot</application> Etherboot Etherboot's Web site contains extensive documentation mainly intended for Linux systems, but nonetheless containing useful information. The following will just outline how you would use Etherboot on a FreeBSD system. You must first install the net/etherboot package or port. You can change the Etherboot configuration (i.e. to use TFTP instead of NFS) by editing the Config file in the Etherboot source directory. For our setup, we shall use a boot floppy. For other methods (PROM, or &ms-dos; program), please refer to the Etherboot documentation. To make a boot floppy, insert a floppy in the drive on the machine where you installed Etherboot, then change your current directory to the src directory in the Etherboot tree and type: &prompt.root; gmake bin32/devicetype.fd0 devicetype depends on the type of the Ethernet card in the diskless workstation. Refer to the NIC file in the same directory to determine the right devicetype. Booting with <acronym>PXE</acronym> By default, the &man.pxeboot.8; loader loads the kernel via NFS. It can be compiled to use TFTP instead by specifying the LOADER_TFTP_SUPPORT option in /etc/make.conf. See the comments in /etc/defaults/make.conf (or /usr/share/examples/etc/make.conf for 5.X systems) for instructions. There are two other undocumented make.conf options which may be useful for setting up a serial console diskless machine: BOOT_PXELDR_PROBE_KEYBOARD, and BOOT_PXELDR_ALWAYS_SERIAL (the latter only exists on &os; 5.X). To use PXE when the machine starts, you will usually need to select the Boot from network option in your BIOS setup, or type a function key during the PC initialization. Configuring the <acronym>TFTP</acronym> and <acronym>NFS</acronym> Servers TFTP diskless operation NFS diskless operation If you are using PXE or Etherboot configured to use TFTP, you need to enable tftpd on the file server: Create a directory from which tftpd will serve the files, e.g. /tftpboot. Add this line to your /etc/inetd.conf: tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpboot It appears that at least some PXE versions want the TCP version of TFTP. In this case, add a second line, replacing dgram udp with stream tcp. Tell inetd to reread its configuration file: &prompt.root; kill -HUP `cat /var/run/inetd.pid` You can place the tftpboot directory anywhere on the server. Make sure that the location is set in both inetd.conf and dhcpd.conf. In all cases, you also need to enable NFS and export the appropriate filesystem on the NFS server. Add this to /etc/rc.conf: nfs_server_enable="YES" Export the filesystem where the diskless root directory is located by adding the following to /etc/exports (adjust the volume mount point and replace margaux corbieres with the names of the diskless workstations): /data/misc -alldirs -ro margaux corbieres Tell mountd to reread its configuration file. If you actually needed to enable NFS in /etc/rc.conf at the first step, you probably want to reboot instead. &prompt.root; kill -HUP `cat /var/run/mountd.pid` Building a Diskless Kernel diskless operation kernel configuration If using Etherboot, you need to create a kernel configuration file for the diskless client with the following options (in addition to the usual ones): options BOOTP # Use BOOTP to obtain IP address/hostname options BOOTP_NFSROOT # NFS mount root filesystem using BOOTP info You may also want to use BOOTP_NFSV3, BOOT_COMPAT and BOOTP_WIRED_TO (refer to LINT in 4.X or NOTES on 5.X). These option names are historical and slightly misleading as they actually enable indifferent use of DHCP and BOOTP inside the kernel (it is also possible to force strict BOOTP or DHCP use). Build the kernel (see ), and copy it to the place specified in dhcpd.conf. When using PXE, building a kernel with the above options is not strictly necessary (though suggested). Enabling them will cause more DHCP requests to be issued during kernel startup, with a small risk of inconsistency between the new values and those retrieved by &man.pxeboot.8; in some special cases. The advantage of using them is that the host name will be set as a side effect. Otherwise you will need to set the host name by another method, for example in a client-specific rc.conf file. In order to be loadable with Etherboot, a 5.X kernel needs to have the device hints compiled in. You would typically set the following option in the configuration file (see the NOTES configuration comments file): hints "GENERIC.hints" Preparing the Root Filesystem root file system diskless operation You need to create a root filesystem for the diskless workstations, in the location listed as root-path in dhcpd.conf. The following sections describe two ways to do it. Using the <filename>clone_root</filename> Script This is the quickest way to create a root filesystem, but currently it is only supported on &os; 4.X. This shell script is located at /usr/share/examples/diskless/clone_root and needs customization, at least to adjust the place where the filesystem will be created (the DEST variable). Refer to the comments at the top of the script for instructions. They explain how the base filesystem is built, and how files may be selectively overridden by versions specific to diskless operation, to a subnetwork, or to an individual workstation. They also give examples for the diskless /etc/fstab and /etc/rc.conf files. The README files in /usr/share/examples/diskless contain a lot of interesting background information, but, together with the other examples in the diskless directory, they actually document a configuration method which is distinct from the one used by clone_root and the system startup scripts in /etc, which is a little confusing. Use them for reference only, except if you prefer the method that they describe, in which case you will need customized rc scripts. Using the Standard <command>make world</command> Procedure This method can be applied to either &os; 4.X or 5.X and will install a complete virgin system (not only the root filesystem) into DESTDIR. All you have to do is simply execute the following script: #!/bin/sh export DESTDIR=/data/misc/diskless mkdir -p ${DESTDIR} cd /usr/src; make world && make kernel cd /usr/src/etc; make distribution Once done, you may need to customize your /etc/rc.conf and /etc/fstab placed into DESTDIR according to your needs. Configuring Swap If needed, a swap file located on the server can be accessed via NFS. One of the methods commonly used to do this has been discontinued in release 5.X. <acronym>NFS</acronym> Swap with &os; 4.X The swap file location and size can be specified with BOOTP/DHCP &os;-specific options 128 and 129. Examples of configuration files for ISC DHCP 3.0 or bootpd follow: Add the following lines to dhcpd.conf: # Global section option swap-path code 128 = string; option swap-size code 129 = integer 32; host margaux { ... # Standard lines, see above option swap-path "192.168.4.4:/netswapvolume/netswap"; option swap-size 64000; } swap-path is the path to a directory where swap files will be located. Each file will be named swap.client-ip. Older versions of dhcpd used a syntax of option option-128 "..., which is no longer supported. /etc/bootptab would use the following syntax instead: T128="192.168.4.4:/netswapvolume/netswap":T129=0000fa00 In /etc/bootptab, the swap size must be expressed in hexadecimal format. On the NFS swap file server, create the swap file(s): &prompt.root; mkdir /netswapvolume/netswap &prompt.root; cd /netswapvolume/netswap &prompt.root; dd if=/dev/zero bs=1024 count=64000 of=swap.192.168.4.6 &prompt.root; chmod 0600 swap.192.168.4.6 192.168.4.6 is the IP address for the diskless client. On the NFS swap file server, add the following line to /etc/exports: /netswapvolume -maproot=0:10 -alldirs margaux corbieres Then tell mountd to reread the exports file, as above. <acronym>NFS</acronym> Swap with &os 5.X The kernel does not support enabling NFS swap at boot time. Swap must be enabled by the startup scripts, by mounting a writeable file system and creating and enabling a swap file. To create a swap file of appropriate size, you can do like this: &prompt.root; dd if=/dev/zero of=/path/to/swapfile bs=1k count=1 oseek=100000 To enable it you have to add the following line to your rc.conf: swapfile=/path/to/swapfile Miscellaneous Issues Running with a Read-only <filename>/usr</filename> diskless operation /usr read-only If the diskless workstation is configured to run X, you will have to adjust the XDM configuration file, which puts the error log on /usr by default. Using a Non-FreeBSD Server When the server for the root filesystem is not running FreeBSD, you will have to create the root filesystem on a FreeBSD machine, then copy it to its destination, using tar or cpio. In this situation, there are sometimes problems with the special files in /dev, due to differing major/minor integer sizes. A solution to this problem is to export a directory from the non-FreeBSD server, mount this directory onto a FreeBSD machine, and run MAKEDEV on the FreeBSD machine to create the correct device entries (FreeBSD 5.0 and later use &man.devfs.5; to allocate device nodes transparently for the user, running MAKEDEV on these versions is pointless). ISDN ISDN A good resource for information on ISDN technology and hardware is Dan Kegel's ISDN Page. A quick simple road map to ISDN follows: If you live in Europe you might want to investigate the ISDN card section. If you are planning to use ISDN primarily to connect to the Internet with an Internet Provider on a dial-up non-dedicated basis, you might look into Terminal Adapters. This will give you the most flexibility, with the fewest problems, if you change providers. If you are connecting two LANs together, or connecting to the Internet with a dedicated ISDN connection, you might consider the stand alone router/bridge option. Cost is a significant factor in determining what solution you will choose. The following options are listed from least expensive to most expensive. Hellmuth Michaelis Contributed by ISDN Cards ISDN cards FreeBSD's ISDN implementation supports only the DSS1/Q.931 (or Euro-ISDN) standard using passive cards. Starting with FreeBSD 4.4, some active cards are supported where the firmware also supports other signaling protocols; this also includes the first supported Primary Rate (PRI) ISDN card. The isdn4bsd software allows you to connect to other ISDN routers using either IP over raw HDLC or by using synchronous PPP: either by using kernel PPP with isppp, a modified &man.sppp.4; driver, or by using userland &man.ppp.8;. By using userland &man.ppp.8;, channel bonding of two or more ISDN B-channels is possible. A telephone answering machine application is also available as well as many utilities such as a software 300 Baud modem. Some growing number of PC ISDN cards are supported under FreeBSD and the reports show that it is successfully used all over Europe and in many other parts of the world. The passive ISDN cards supported are mostly the ones with the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets, but also ISDN cards with chips from Cologne Chip (ISA bus only), PCI cards with Winbond W6692 chips, some cards with the Tiger300/320/ISAC chipset combinations and some vendor specific chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the AVM Fritz!Card PnP. Currently the active supported ISDN cards are the AVM B1 (ISA and PCI) BRI cards and the AVM T1 PCI PRI cards. For documentation on isdn4bsd, have a look at /usr/share/examples/isdn/ directory on your FreeBSD system or at the homepage of isdn4bsd which also has pointers to hints, erratas and much more documentation such as the isdn4bsd handbook. In case you are interested in adding support for a different ISDN protocol, a currently unsupported ISDN PC card or otherwise enhancing isdn4bsd, please get in touch with &a.hm;. For questions regarding the installation, configuration and troubleshooting isdn4bsd, a &a.isdn.name; mailing list is available. ISDN Terminal Adapters Terminal adapters (TA), are to ISDN what modems are to regular phone lines. modem Most TA's use the standard Hayes modem AT command set, and can be used as a drop in replacement for a modem. A TA will operate basically the same as a modem except connection and throughput speeds will be much faster than your old modem. You will need to configure PPP exactly the same as for a modem setup. Make sure you set your serial speed as high as possible. PPP The main advantage of using a TA to connect to an Internet Provider is that you can do Dynamic PPP. As IP address space becomes more and more scarce, most providers are not willing to provide you with a static IP anymore. Most stand-alone routers are not able to accommodate dynamic IP allocation. TA's completely rely on the PPP daemon that you are running for their features and stability of connection. This allows you to upgrade easily from using a modem to ISDN on a FreeBSD machine, if you already have PPP set up. However, at the same time any problems you experienced with the PPP program and are going to persist. If you want maximum stability, use the kernel PPP option, not the userland PPP. The following TA's are known to work with FreeBSD: Motorola BitSurfer and Bitsurfer Pro Adtran Most other TA's will probably work as well, TA vendors try to make sure their product can accept most of the standard modem AT command set. The real problem with external TA's is that, like modems, you need a good serial card in your computer. You should read the FreeBSD Serial Hardware tutorial for a detailed understanding of serial devices, and the differences between asynchronous and synchronous serial ports. A TA running off a standard PC serial port (asynchronous) limits you to 115.2 Kbs, even though you have a 128 Kbs connection. To fully utilize the 128 Kbs that ISDN is capable of, you must move the TA to a synchronous serial card. Do not be fooled into buying an internal TA and thinking you have avoided the synchronous/asynchronous issue. Internal TA's simply have a standard PC serial port chip built into them. All this will do is save you having to buy another serial cable and find another empty electrical socket. A synchronous card with a TA is at least as fast as a stand-alone router, and with a simple 386 FreeBSD box driving it, probably more flexible. The choice of synchronous card/TA v.s. stand-alone router is largely a religious issue. There has been some discussion of this in the mailing lists. We suggest you search the archives for the complete discussion. Stand-alone ISDN Bridges/Routers ISDN stand-alone bridges/routers ISDN bridges or routers are not at all specific to FreeBSD or any other operating system. For a more complete description of routing and bridging technology, please refer to a networking reference book. In the context of this section, the terms router and bridge will be used interchangeably. As the cost of low end ISDN routers/bridges comes down, it will likely become a more and more popular choice. An ISDN router is a small box that plugs directly into your local Ethernet network, and manages its own connection to the other bridge/router. It has built in software to communicate via PPP and other popular protocols. A router will allow you much faster throughput than a standard TA, since it will be using a full synchronous ISDN connection. The main problem with ISDN routers and bridges is that interoperability between manufacturers can still be a problem. If you are planning to connect to an Internet provider, you should discuss your needs with them. If you are planning to connect two LAN segments together, such as your home LAN to the office LAN, this is the simplest lowest maintenance solution. Since you are buying the equipment for both sides of the connection you can be assured that the link will work. For example to connect a home computer or branch office network to a head office network the following setup could be used: Branch Office or Home Network 10 base 2 Network uses a bus based topology with 10 base 2 Ethernet (thinnet). Connect router to network cable with AUI/10BT transceiver, if necessary. ---Sun workstation | ---FreeBSD box | ---Windows 95 | Stand-alone router | ISDN BRI line 10 Base 2 Ethernet If your home/branch office is only one computer you can use a twisted pair crossover cable to connect to the stand-alone router directly. Head Office or Other LAN 10 base T Network uses a star topology with 10 base T Ethernet (Twisted Pair). -------Novell Server | H | | ---Sun | | | U ---FreeBSD | | | ---Windows 95 | B | |___---Stand-alone router | ISDN BRI line ISDN Network Diagram One large advantage of most routers/bridges is that they allow you to have 2 separate independent PPP connections to 2 separate sites at the same time. This is not supported on most TA's, except for specific (usually expensive) models that have two serial ports. Do not confuse this with channel bonding, MPP, etc. This can be a very useful feature if, for example, you have an dedicated ISDN connection at your office and would like to tap into it, but do not want to get another ISDN line at work. A router at the office location can manage a dedicated B channel connection (64 Kbps) to the Internet and use the other B channel for a separate data connection. The second B channel can be used for dial-in, dial-out or dynamically bonding (MPP, etc.) with the first B channel for more bandwidth. IPX/SPX An Ethernet bridge will also allow you to transmit more than just IP traffic. You can also send IPX/SPX or whatever other protocols you use. Chern Lee Contributed by Network Address Translation Overview natd FreeBSD's Network Address Translation daemon, commonly known as &man.natd.8; is a daemon that accepts incoming raw IP packets, changes the source to the local machine and re-injects these packets back into the outgoing IP packet stream. &man.natd.8; does this by changing the source IP address and port such that when data is received back, it is able to determine the original location of the data and forward it back to its original requester. Internet connection sharing IP masquerading The most common use of NAT is to perform what is commonly known as Internet Connection Sharing. Setup Due to the diminishing IP space in IPv4, and the increased number of users on high-speed consumer lines such as cable or DSL, people are increasingly in need of an Internet Connection Sharing solution. The ability to connect several computers online through one connection and IP address makes &man.natd.8; a reasonable choice. Most commonly, a user has a machine connected to a cable or DSL line with one IP address and wishes to use this one connected computer to provide Internet access to several more over a LAN. To do this, the FreeBSD machine on the Internet must act as a gateway. This gateway machine must have two NICs—one for connecting to the Internet router, the other connecting to a LAN. All the machines on the LAN are connected through a hub or switch. _______ __________ ________ | | | | | | | Hub |-----| Client B |-----| Router |----- Internet |_______| |__________| |________| | ____|_____ | | | Client A | |__________| Network Layout A setup like this is commonly used to share an Internet connection. One of the LAN machines is connected to the Internet. The rest of the machines access the Internet through that gateway machine. kernel configuration Configuration The following options must be in the kernel configuration file: options IPFIREWALL options IPDIVERT Additionally, at choice, the following may also be suitable: options IPFIREWALL_DEFAULT_TO_ACCEPT options IPFIREWALL_VERBOSE The following must be in /etc/rc.conf: gateway_enable="YES" firewall_enable="YES" firewall_type="OPEN" natd_enable="YES" natd_interface="fxp0" natd_flags="" Sets up the machine to act as a gateway. Running sysctl net.inet.ip.forwarding=1 would have the same effect. + + Enables the firewall rules in /etc/rc.firewall at boot. + + This specifies a predefined firewall ruleset that allows anything in. See /etc/rc.firewall for additional types. + + Indicates which interface to forward packets through (the interface connected to the Internet). + + Any additional configuration options passed to &man.natd.8; on boot. + Having the previous options defined in /etc/rc.conf would run natd -interface fxp0 at boot. This can also be run manually. It is also possible to use a configuration file for &man.natd.8; when there are too many options to pass. In this case, the configuration file must be defined by adding the following line to /etc/rc.conf: natd_flags="-f /etc/natd.conf" The /etc/natd.conf file will contain a list of configuration options, one per line. For example the next section case would use the following file: redirect_port tcp 192.168.0.2:6667 6667 redirect_port tcp 192.168.0.3:80 80 For more information about the configuration file, consult the &man.natd.8; manual page about the option. Each machine and interface behind the LAN should be assigned IP address numbers in the private network space as defined by RFC 1918 and have a default gateway of the natd machine's internal IP address. For example, client A and B behind the LAN have IP addresses of 192.168.0.2 and 192.168.0.3, while the natd machine's LAN interface has an IP address of 192.168.0.1. Client A and B's default gateway must be set to that of the natd machine, 192.168.0.1. The natd machine's external, or Internet interface does not require any special modification for &man.natd.8; to work. Port Redirection The drawback with &man.natd.8; is that the LAN clients are not accessible from the Internet. Clients on the LAN can make outgoing connections to the world but cannot receive incoming ones. This presents a problem if trying to run Internet services on one of the LAN client machines. A simple way around this is to redirect selected Internet ports on the natd machine to a LAN client. For example, an IRC server runs on client A, and a web server runs on client B. For this to work properly, connections received on ports 6667 (IRC) and 80 (web) must be redirected to the respective machines. The must be passed to &man.natd.8; with the proper options. The syntax is as follows: -redirect_port proto targetIP:targetPORT[-targetPORT] [aliasIP:]aliasPORT[-aliasPORT] [remoteIP[:remotePORT[-remotePORT]]] In the above example, the argument should be: -redirect_port tcp 192.168.0.2:6667 6667 -redirect_port tcp 192.168.0.3:80 80 This will redirect the proper tcp ports to the LAN client machines. The argument can be used to indicate port ranges over individual ports. For example, tcp 192.168.0.2:2000-3000 2000-3000 would redirect all connections received on ports 2000 to 3000 to ports 2000 to 3000 on client A. These options can be used when directly running &man.natd.8;, placed within the natd_flags="" option in /etc/rc.conf, or passed via a configuration file. For further configuration options, consult &man.natd.8; Address Redirection address redirection Address redirection is useful if several IP addresses are available, yet they must be on one machine. With this, &man.natd.8; can assign each LAN client its own external IP address. &man.natd.8; then rewrites outgoing packets from the LAN clients with the proper external IP address and redirects all traffic incoming on that particular IP address back to the specific LAN client. This is also known as static NAT. For example, the IP addresses 128.1.1.1, 128.1.1.2, and 128.1.1.3 belong to the natd gateway machine. 128.1.1.1 can be used as the natd gateway machine's external IP address, while 128.1.1.2 and 128.1.1.3 are forwarded back to LAN clients A and B. The syntax is as follows: -redirect_address localIP publicIP localIP The internal IP address of the LAN client. publicIP The external IP address corresponding to the LAN client. In the example, this argument would read: -redirect_address 192.168.0.2 128.1.1.2 -redirect_address 192.168.0.3 128.1.1.3 Like , these arguments are also placed within the natd_flags="" option of /etc/rc.conf, or passed via a configuration file. With address redirection, there is no need for port redirection since all data received on a particular IP address is redirected. The external IP addresses on the natd machine must be active and aliased to the external interface. Look at &man.rc.conf.5; to do so. Parallel Line IP (PLIP) PLIP Parallel Line IP PLIP PLIP lets us run TCP/IP between parallel ports. It is useful on machines without network cards, or to install on laptops. In this section, we will discuss: Creating a parallel (laplink) cable. Connecting two computers with PLIP. Creating a Parallel Cable You can purchase a parallel cable at most computer supply stores. If you cannot do that, or you just want to know how it is done, the following table shows how to make one out of a normal parallel printer cable. Wiring a Parallel Cable for Networking A-name A-End B-End Descr. Post/Bit DATA0 -ERROR 2 15 15 2 Data 0/0x01 1/0x08 DATA1 +SLCT 3 13 13 3 Data 0/0x02 1/0x10 DATA2 +PE 4 12 12 4 Data 0/0x04 1/0x20 DATA3 -ACK 5 10 10 5 Strobe 0/0x08 1/0x40 DATA4 BUSY 6 11 11 6 Data 0/0x10 1/0x80 GND 18-25 18-25 GND -
Setting Up PLIP First, you have to get a laplink cable. Then, confirm that both computers have a kernel with &man.lpt.4; driver support: &prompt.root; grep lp /var/run/dmesg.boot lpt0: <Printer> on ppbus0 lpt0: Interrupt-driven port The parallel port must be an interrupt driven port, under &os; 4.X, you should have a line similar to the following in your kernel configuration file: device ppc0 at isa? irq 7 Under &os; 5.X, the /boot/device.hints file should contain the following lines: hint.ppc.0.at="isa" hint.ppc.0.irq="7" Then check if the kernel configuration file has a device plip line or if the plip.ko kernel module is loaded. In both cases the parallel networking interface should appear when you directly use the &man.ifconfig.8; command. Under &os; 4.X like this: &prompt.root; ifconfig lp0 lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 and for &os; 5.X: &prompt.root; ifconfig plip0 plip0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 The device name used for parallel interface is different between &os; 4.X (lpX) and &os; 5.X (plipX). Plug in the laplink cable into the parallel interface on both computers. Configure the network interface parameters on both sites as root. For example, if you want connect the host host1 running &os; 4.X with host2 running &os; 5.X: host1 <-----> host2 IP Address 10.0.0.1 10.0.0.2 Configure the interface on host1 by doing: &prompt.root; ifconfig lp0 10.0.0.1 10.0.0.2 Configure the interface on host2 by doing: &prompt.root; ifconfig plip0 10.0.0.2 10.0.0.1 You now should have a working connection. Please read the manual pages &man.lp.4; and &man.lpt.4; for more details. You should also add both hosts to /etc/hosts: 127.0.0.1 localhost.my.domain localhost 10.0.0.1 host1.my.domain host1 10.0.0.2 host2.my.domain To confirm the connection works, go to each host and ping the other. For example, on host1: &prompt.root; ifconfig lp0 lp0: flags=8851<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet 10.0.0.1 --> 10.0.0.2 netmask 0xff000000 &prompt.root; netstat -r Routing tables Internet: Destination Gateway Flags Refs Use Netif Expire host2 host1 UH 0 0 lp0 &prompt.root; ping -c 4 host2 PING host2 (10.0.0.2): 56 data bytes 64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms --- host2 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms Aaron Kaplan Originally Written by Tom Rhodes Restructured and Added by Brad Davis Extended by IPv6 IPv6 (also know as IPng IP next generation) is the new version of the well known IP protocol (also know as IPv4). Like the other current *BSD systems, FreeBSD includes the KAME IPv6 reference implementation. So your FreeBSD system comes with all you will need to experiment with IPv6. This section focuses on getting IPv6 configured and running. In the early 1990s, people became aware of the rapidly diminishing address space of IPv4. Given the expansion rate of the Internet there were two major concerns: Running out of addresses. Today this is not so much of a concern anymore since private address spaces (10.0.0.0/8, 192.168.0.0/24, etc.) and Network Address Translation (NAT) are being employed. Router table entries were getting too large. This is still a concern today. IPv6 deals with these and many other issues: 128 bit address space. In other words theoretically there are 340,282,366,920,938,463,463,374,607,431,768,211,456 addresses available. This means there are approximately 6.67 * 10^27 IPv6 addresses per square meter on our planet. Routers will only store network aggregation addresses in their routing tables thus reducing the average space of a routing table to 8192 entries. There are also lots of other useful features of IPv6 such as: Address autoconfiguration (RFC2462) Anycast addresses (one-out-of many) Mandatory multicast addresses IPsec (IP security) Simplified header structure Mobile IP IPv6-to-IPv4 transition mechanisms For more information see: IPv6 overview at playground.sun.com KAME.net 6bone.net Background on IPv6 Addresses There are different types of IPv6 addresses: Unicast, Anycast and Multicast. Unicast addresses are the well known addresses. A packet sent to a unicast address arrives exactly at the interface belonging to the address. Anycast 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 (in router metric) interface. Anycast addresses may only be used by routers. Multicast 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. Reserved IPv6 addresses IPv6 address Prefixlength (Bits) Description Notes :: 128 bits unspecified cf. 0.0.0.0 in IPv4 ::1 128 bits loopback address cf. 127.0.0.1 in IPv4 ::00:xx:xx:xx:xx 96 bits embedded IPv4 The lower 32 bits are the IPv4 address. Also called IPv4 compatible IPv6 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:: - feb:: 10 bits link-local cf. loopback address in IPv4 fec0:: - fef:: 10 bits site-local   ff:: 8 bits multicast   001 (base 2) 3 bits global unicast All global unicast addresses are assigned from this pool. The first 3 bits are 001.
Reading IPv6 Addresses The canonical form is represented as: x:x:x:x:x:x:x:x, each x being a 16 Bit hex value. For example FEBC:A574:382B:23C1:AA49:4592:4EFE:9982 Often an address will have long substrings of all zeros therefore one such substring per address can be abbreviated by ::. Also up to three leading 0s per hexquad 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 Bit part in the well known (decimal) IPv4 style with dots . as separators. 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 writing 2002::a00:1. By now the reader should be able to understand the following: &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 fe80::200:21ff:fe03:8e1%rl0 is an auto configured link-local address. It is generated from the MAC address as part of the auto configuration. For further information on the structure of IPv6 addresses see RFC3513. Getting Connected Currently there are four ways to connect to other IPv6 hosts and networks: Join the experimental 6bone Getting an IPv6 network from your upstream provider. Talk to your Internet provider for instructions. Tunnel via 6-to-4 (RFC3068) Use the net/freenet6 port if you are on a dial-up connection. Here we will talk on how to connect to the 6bone since it currently seems to be the most popular way. First take a look at the 6bone site and find a 6bone connection nearest to you. Write to the responsible person and with a little bit of luck you will be given instructions on how to set up your connection. Usually this involves setting up a GRE (gif) tunnel. Here is a typical example on setting up a &man.gif.4; tunnel: &prompt.root; ifconfig gif0 create &prompt.root; ifconfig gif0 gif0: flags=8010<POINTOPOINT,MULTICAST> mtu 1280 &prompt.root; ifconfig gif0 tunnel MY_IPv4_ADDR HIS_IPv4_ADDR &prompt.root; ifconfig gif0 inet6 alias MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR Replace the capitalized words by the information you received from the upstream 6bone node. This establishes the tunnel. Check if the tunnel is working by &man.ping6.8; 'ing ff02::1%gif0. You should receive two ping replies. In case you are intrigued by the address ff02:1%gif0, this is a multicast address. %gif0 states that the multicast address at network interface gif0 is to be used. Since we ping a multicast address the other endpoint of the tunnel should reply as well. By now setting up a route to your 6bone uplink should be rather straightforward: &prompt.root; route add -inet6 default -interface gif0 &prompt.root; ping6 -n MY_UPLINK &prompt.root; traceroute6 www.jp.FreeBSD.org (3ffe:505:2008:1:2a0:24ff:fe57:e561) from 3ffe:8060:100::40:2, 30 hops max, 12 byte packets 1 atnet-meta6 14.147 ms 15.499 ms 24.319 ms 2 6bone-gw2-ATNET-NT.ipv6.tilab.com 103.408 ms 95.072 ms * 3 3ffe:1831:0:ffff::4 138.645 ms 134.437 ms 144.257 ms 4 3ffe:1810:0:6:290:27ff:fe79:7677 282.975 ms 278.666 ms 292.811 ms 5 3ffe:1800:0:ff00::4 400.131 ms 396.324 ms 394.769 ms 6 3ffe:1800:0:3:290:27ff:fe14:cdee 394.712 ms 397.19 ms 394.102 ms This output will differ from machine to machine. By now you should be able to reach the IPv6 site www.kame.net and see the dancing tortoise — that is if you have a IPv6 enabled browser such as www/mozilla, Konqueror, which is part of x11/kdebase3, or www/epiphany. DNS in the IPv6 World There used to be two types of DNS records for IPv6. The IETF has declared A6 records obsolete. AAAA records are the standard now. Using AAAA records is straightforward. Assign your hostname to the new IPv6 address you just received by adding: MYHOSTNAME AAAA MYIPv6ADDR To your primary zone DNS file. In case you do not serve your own DNS zones ask your DNS provider. Current versions of bind (version 8.3 and 9) and dns/djbdns (with the IPv6 patch) support AAAA records. Applying the needed changes to <filename>/etc/rc.conf</filename> IPv6 Client Settings These settings will help you configure a machine that will be on your LAN and act as a client, not a router. To have &man.rtsol.8; autoconfigure your interface on boot all you need to add is: ipv6_enable="YES" To statically assign an IP address such as 2001:471:1f11:251:290:27ff:fee0:2093, to your fxp0 interface, add: ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093" To assign a default router of 2001:471:1f11:251::1 add the following to /etc/rc.conf: ipv6_defaultrouter="2001:471:1f11:251::1" IPv6 Router/Gateway Settings This will help you take the directions that your tunnel provider, such as the 6bone, has given you and convert it into settings that will persist through reboots. To restore your tunnel on startup use something like the following in /etc/rc.conf: List the Generic Tunneling interfaces that will be configured, for example gif0: gif_interfaces="gif0" To configure the interface with a local endpoint of MY_IPv4_ADDR to a remote endpoint of REMOTE_IPv4_ADDR: gifconfig_gif0="MY_IPv4_ADDR REMOTE_IPv4_ADDR" To apply the IPv6 address you have been assigned for use as your IPv6 tunnel endpoint, add: ipv6_ifconfig_gif0="MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR" Then all you have to do is set the default route for IPv6. This is the other side of the IPv6 tunnel: ipv6_defaultrouter="MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR" Router Advertisement and Host Auto Configuration This section will help you setup &man.rtadvd.8; to advertise the IPv6 default route. To enable &man.rtadvd.8; you will need the following in your /etc/rc.conf: rtadvd_enable="YES" It is important that you specify the interface on which to do IPv6 router solicitation. For example to tell &man.rtadvd.8; to use fxp0: rtadvd_interfaces="fxp0" Now we must create the configuration file, /etc/rtadvd.conf. Here is an example: fxp0:\ :addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether: Replace fxp0 with the interface you are going to be using. Next, replace 2001:471:1f11:246:: with the prefix of your allocation. If you are dedicated a /64 subnet you will not need to change anything else. Otherwise, you will need to change the prefixlen# to the correct value. Harti Brandt Contributed by Asynchronous Transfer Mode (ATM) on &os; 5.X Configuring classical IP over ATM (PVCs) Classical IP over ATM (CLIP) is the simplest method to use Asynchronous Transfer Mode (ATM) with IP. It can be used with switched connections (SVCs) and with permanent connections (PVCs). This section describes how to set up a network based on PVCs. Fully meshed configurations The first method to set up a CLIP with PVCs is to connect each machine to each other machine in the network via a dedicated PVC. While this is simple to configure it tends to become impractical for a larger number of machines. The example supposes that we have four machines in the network, each connected to the ATM network with an ATM adapter card. The first step is the planning of the IP addresses and the ATM connections between the machines. We use the following: Host IP Address hostA 192.168.173.1 hostB 192.168.173.2 hostC 192.168.173.3 hostD 192.168.173.4 To build a fully meshed net we need one ATM connection between each pair of machines: Machines VPI.VCI couple hostA - hostB 0.100 hostA - hostC 0.101 hostA - hostD 0.102 hostB - hostC 0.103 hostB - hostD 0.104 hostC - hostD 0.105 The VPI and VCI values at each end of the connection may of course differ, but for simplicity we assume that they are the same. Next we need to configure the ATM interfaces on each host: hostA&prompt.root; ifconfig hatm0 192.168.173.1 up hostB&prompt.root; ifconfig hatm0 192.168.173.2 up hostC&prompt.root; ifconfig hatm0 192.168.173.3 up hostD&prompt.root; ifconfig hatm0 192.168.173.4 up assuming that the ATM interface is hatm0 on all hosts. Now the PVCs need to be configured on hostA (we assume that they are already configured on the ATM switches, you need to consult the manual for the switch on how to do this). hostA&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 100 llc/snap ubr hostA&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 101 llc/snap ubr hostA&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 102 llc/snap ubr hostB&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 100 llc/snap ubr hostB&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 103 llc/snap ubr hostB&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 104 llc/snap ubr hostC&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 101 llc/snap ubr hostC&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 103 llc/snap ubr hostC&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 105 llc/snap ubr hostD&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 102 llc/snap ubr hostD&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 104 llc/snap ubr hostD&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 105 llc/snap ubr Of course other traffic contracts than UBR can be used given the ATM adapter supports those. In this case the name of the traffic contract is followed by the parameters of the traffic. Help for the &man.atmconfig.8; tool can be obtained with: &prompt.root; atmconfig help natm add or in the &man.atmconfig.8; manual page. The same configuration can also be done via /etc/rc.conf. For hostA this would look like: network_interfaces="lo0 hatm0" ifconfig_hatm0="inet 192.168.173.1 up" natm_static_routes="hostB hostC hostD" route_hostB="192.168.173.2 hatm0 0 100 llc/snap ubr" route_hostC="192.168.173.3 hatm0 0 101 llc/snap ubr" route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr" The current state of all CLIP routes can be obtained with: hostA&prompt.root; atmconfig natm show diff --git a/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml b/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml index 7d817052c2..dcf88602f2 100644 --- a/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml @@ -1,1664 +1,1665 @@ Resources on the Internet The rapid pace of FreeBSD progress makes print media impractical as a means of following the latest developments. Electronic resources are the best, if not often the only, way stay informed of the latest advances. Since FreeBSD is a volunteer effort, the user community itself also generally serves as a technical support department of sorts, with electronic mail and USENET news being the most effective way of reaching that community. The most important points of contact with the FreeBSD user community are outlined below. If you are aware of other resources not mentioned here, please send them to the &a.doc; so that they may also be included. Mailing Lists Though many of the FreeBSD development members read USENET, we cannot always guarantee that we will get to your questions in a timely fashion (or at all) if you post them only to one of the comp.unix.bsd.freebsd.* groups. By addressing your questions to the appropriate mailing list you will reach both us and a concentrated FreeBSD audience, invariably assuring a better (or at least faster) response. The charters for the various lists are given at the bottom of this document. Please read the charter before joining or sending mail to any list. Most of our list subscribers now receive many hundreds of FreeBSD related messages every day, and by setting down charters and rules for proper use we are striving to keep the signal-to-noise ratio of the lists high. To do less would see the mailing lists ultimately fail as an effective communications medium for the project. When in doubt about what list to post a question to, see How to get best results from the FreeBSD-questions mailing list. Before posting to any list, please learn about how to best use the mailing lists, such as how to help avoid frequently-repeated discussions, by reading the Mailing List Frequently Asked Questions (FAQ) document. Archives are kept for all of the mailing lists and can be searched using the FreeBSD World Wide Web server. The keyword searchable archive offers an excellent way of finding answers to frequently asked questions and should be consulted before posting a question. List Summary General lists: The following are general lists which anyone is free (and encouraged) to join: List Purpose &a.cvsall.name; Changes made to the FreeBSD source tree &a.advocacy.name; FreeBSD Evangelism &a.announce.name; Important events and project milestones &a.arch.name; Architecture and design discussions &a.bugbusters.name; Discussions pertaining to the maintenance of the FreeBSD problem report database and related tools &a.bugs.name; Bug reports &a.chat.name; Non-technical items related to the FreeBSD community &a.current.name; Discussion concerning the use of &os.current; &a.isp.name; Issues for Internet Service Providers using FreeBSD &a.jobs.name; FreeBSD employment and consulting opportunities &a.newbies.name; New FreeBSD users activities and discussions &a.policy.name; FreeBSD Core team policy decisions. Low volume, and read-only &a.questions.name; User questions and technical support &a.security-notifications.name; Security notifications &a.stable.name; Discussion concerning the use of &os.stable; &a.test.name; Where to send your test messages instead of one of the actual lists Technical lists: The following lists are for technical discussion. You should read the charter for each list carefully before joining or sending mail to one as there are firm guidelines for their use and content. List Purpose &a.acpi.name; ACPI and power management development &a.afs.name; Porting AFS to FreeBSD &a.aic7xxx.name; Developing drivers for the &adaptec; AIC 7xxx &a.alpha.name; Porting FreeBSD to the Alpha &a.amd64.name; Porting FreeBSD to AMD64 systems &a.apache.name; Discussion about Apache related ports &a.arm.name; Porting FreeBSD to &arm; processors &a.atm.name; Using ATM networking with FreeBSD &a.audit.name; Source code audit project &a.binup.name; Design and development of the binary update system &a.cluster.name; Using FreeBSD in a clustered environment &a.cvsweb.name; CVSweb maintenance &a.database.name; Discussing database use and development under FreeBSD &a.doc.name; Creating FreeBSD related documents &a.emulation.name; Emulation of other systems such as Linux/&ms-dos;/&windows; &a.firewire.name; FreeBSD &firewire; (iLink, IEEE 1394) technical discussion &a.fs.name; File systems &a.geom.name; GEOM-specific discussions and implementations &a.gnome.name; Porting GNOME and GNOME applications &a.hackers.name; General technical discussion &a.hardware.name; General discussion of hardware for running FreeBSD &a.i18n.name; FreeBSD Internationalization &a.ia32.name; FreeBSD on the IA-32 (&intel; x86) platform &a.ia64.name; Porting FreeBSD to &intel;'s upcoming IA64 systems &a.ipfw.name; Technical discussion concerning the redesign of the IP firewall code &a.isdn.name; ISDN developers &a.java.name; &java; developers and people porting &jdk;s to FreeBSD &a.kde.name; Porting KDE and KDE applications &a.lfs.name; Porting LFS to FreeBSD &a.libh.name; The second generation installation and package system &a.mips.name; Porting FreeBSD to &mips; &a.mobile.name; Discussions about mobile computing &a.mozilla.name; Porting Mozilla to FreeBSD &a.multimedia.name; Multimedia applications &a.newbus.name; Technical discussions about bus architecture &a.net.name; Networking discussion and TCP/IP source code &a.openoffice.name; Porting OpenOffice.org and &staroffice; to FreeBSD &a.performance.name; Performance tuning questions for high performance/load installations &a.perl.name; Maintenance of a number of perl-related ports &a.pf.name; Discussion and questions about the packet filter firewall system &a.platforms.name; Concerning ports to non &intel; architecture platforms &a.ports.name; Discussion of the ports collection &a.ports-bugs.name; Discussion of the ports bugs/PRs &a.ppc.name; Porting FreeBSD to the &powerpc; &a.python.name; FreeBSD-specific Python issues &a.qa.name; Discussion of Quality Assurance, usually pending a release &a.realtime.name; Development of realtime extensions to FreeBSD &a.scsi.name; The SCSI subsystem &a.security.name; Security issues affecting FreeBSD &a.small.name; Using FreeBSD in embedded applications &a.smp.name; Design discussions for [A]Symmetric MultiProcessing &a.sparc.name; Porting FreeBSD to &sparc; based systems &a.standards.name; FreeBSD's conformance to the C99 and the &posix; standards &a.threads.name; Threading in FreeBSD &a.testing.name; FreeBSD Performance and Stability Tests &a.tokenring.name; Support Token Ring in FreeBSD &a.usb.name; Discussing &os; support for USB &a.vuxml.name; Discussion on VuXML infrastructure &a.x11.name; Maintenance and support of X11 on FreeBSD Limited lists: The following lists are for more specialized (and demanding) audiences and are probably not of interest to the general public. It is also a good idea to establish a presence in the technical lists before joining one of these limited lists so that you will understand the communications etiquette involved. List Purpose &a.hubs.name; People running mirror sites (infrastructural support) &a.usergroups.name; User group coordination &a.vendors.name; Vendors pre-release coordination &a.www.name; Maintainers of www.FreeBSD.org Digest lists: All of the above lists are available in a digest format. Once subscribed to a list, you can change your digest options in your account options section. CVS lists: The following lists are for people interested in seeing the log messages for changes to various areas of the source tree. They are Read-Only lists and should not have mail sent to them. List Source area Area Description (source for) &a.cvsall.name; /usr/(CVSROOT|doc|ports|projects|src) All changes to any place in the tree (superset of other CVS commit lists) &a.cvs-doc.name; /usr/(doc|www) All changes to the doc and www trees &a.cvs-ports.name; /usr/ports All changes to the ports tree &a.cvs-projects.name; /usr/projects All changes to the projects tree &a.cvs-src.name; /usr/src All changes to the src tree How to Subscribe To subscribe to a list, click on the list name above or go to &a.mailman.lists.link; and click on the list that you are interested in. The list page should contain all of the necessary subscription instructions. To actually post to a given list you simply send mail to listname@FreeBSD.org. It will then be redistributed to mailing list members world-wide. To unsubscribe yourself from a list, click on the URL found at the bottom of every email received from the list. It is also possible to send an email to listname-unsubscribe@FreeBSD.org to unsubscribe yourself. Again, we would like to request that you keep discussion in the technical mailing lists on a technical track. If you are only interested in important announcements then it is suggested that you join the &a.announce;, which is intended only for infrequent traffic. List Charters All FreeBSD mailing lists have certain basic rules which must be adhered to by anyone using them. Failure to comply with these guidelines will result in two (2) written warnings from the FreeBSD Postmaster postmaster@FreeBSD.org, after which, on a third offense, the poster will removed from all FreeBSD mailing lists and filtered from further posting to them. We regret that such rules and measures are necessary at all, but today's Internet is a pretty harsh environment, it would seem, and many fail to appreciate just how fragile some of its mechanisms are. Rules of the road: The topic of any posting should adhere to the basic charter of the list it is posted to, e.g. if the list is about technical issues then your posting should contain technical discussion. Ongoing irrelevant chatter or flaming only detracts from the value of the mailing list for everyone on it and will not be tolerated. For free-form discussion on no particular topic, the &a.chat; is freely available and should be used instead. No posting should be made to more than 2 mailing lists, and only to 2 when a clear and obvious need to post to both lists exists. For most lists, there is already a great deal of subscriber overlap and except for the most esoteric mixes (say -stable & -scsi), there really is no reason to post to more than one list at a time. If a message is sent to you in such a way that multiple mailing lists appear on the Cc line then the Cc line should also be trimmed before sending it out again. You are still responsible for your own cross-postings, no matter who the originator might have been. Personal attacks and profanity (in the context of an argument) are not allowed, and that includes users and developers alike. Gross breaches of netiquette, like excerpting or reposting private mail when permission to do so was not and would not be forthcoming, are frowned upon but not specifically enforced. However, there are also very few cases where such content would fit within the charter of a list and it would therefore probably rate a warning (or ban) on that basis alone. Advertising of non-FreeBSD related products or services is strictly prohibited and will result in an immediate ban if it is clear that the offender is advertising by spam. Individual list charters: &a.acpi.name; ACPI and power management development &a.afs.name; Andrew File System This list is for discussion on porting and using AFS from CMU/Transarc &a.announce.name; Important events / milestones This is the mailing list for people interested only in occasional announcements of significant FreeBSD events. This includes announcements about snapshots and other releases. It contains announcements of new FreeBSD capabilities. It may contain calls for volunteers etc. This is a low volume, strictly moderated mailing list. &a.arch.name; Architecture and design discussions This list is for discussion of the FreeBSD architecture. Messages will mostly be kept strictly technical in nature. Examples of suitable topics are: How to re-vamp the build system to have several customized builds running at the same time. What needs to be fixed with VFS to make Heidemann layers work. How do we change the device driver interface to be able to use the same drivers cleanly on many buses and architectures. How to write a network driver. &a.audit.name; Source code audit project This is the mailing list for the FreeBSD source code audit project. Although this was originally intended for security-related changes, its charter has been expanded to review any code changes. This list is very heavy on patches, and is probably of no interest to the average FreeBSD user. Security discussions not related to a particular code change are held on freebsd-security. Conversely, all developers are encouraged to send their patches here for review, especially if they touch a part of the system where a bug may adversely affect the integrity of the system. &a.binup.name; FreeBSD Binary Update Project This list exists to provide discussion for the binary update system, or binup. Design issues, implementation details, patches, bug reports, status reports, feature requests, commit logs, and all other things related to binup are fair game. &a.bugbusters.name; Coordination of the Problem Report handling effort The purpose of this list is to serve as a coordination and discussion forum for the Bugmeister, his Bugbusters, and any other parties who have a genuine interest in the PR database. This list is not for discussions about specific bugs, patches or PRs. &a.bugs.name; Bug reports This is the mailing list for reporting bugs in FreeBSD. Whenever possible, bugs should be submitted using the &man.send-pr.1; command or the WEB interface to it. &a.chat.name; Non technical items related to the FreeBSD community This list contains the overflow from the other lists about non-technical, social information. It includes discussion about whether Jordan looks like a toon ferret or not, whether or not to type in capitals, who is drinking too much coffee, where the best beer is brewed, who is brewing beer in their basement, and so on. Occasional announcements of important events (such as upcoming parties, weddings, births, new jobs, etc) can be made to the technical lists, but the follow ups should be directed to this -chat list. &a.core.name; FreeBSD core team This is an internal mailing list for use by the core members. Messages can be sent to it when a serious FreeBSD-related matter requires arbitration or high-level scrutiny. &a.current.name; Discussions about the use of &os.current; This is the mailing list for users of &os.current;. It includes warnings about new features coming out in -CURRENT that will affect the users, and instructions on steps that must be taken to remain -CURRENT. Anyone running CURRENT must subscribe to this list. This is a technical mailing list for which strictly technical content is expected. &a.cvsweb.name; FreeBSD CVSweb Project Technical discussions about use, development and maintenance of FreeBSD-CVSweb. &a.doc.name; Documentation project This mailing list is for the discussion of issues and projects related to the creation of documentation for FreeBSD. The members of this mailing list are collectively referred to as The FreeBSD Documentation Project. It is an open list; feel free to join and contribute! &a.firewire.name; &firewire; (iLink, IEEE 1394) This is a mailing list for discussion of the design and implementation of a &firewire; (aka IEEE 1394 aka iLink) subsystem for FreeBSD. Relevant topics specifically include the standards, bus devices and their protocols, adapter boards/cards/chips sets, and the architecture and implementation of code for their proper support. &a.fs.name; File systems Discussions concerning FreeBSD file systems. This is a technical mailing list for which strictly technical content is expected. &a.geom.name; GEOM Discussions specific to GEOM and related implementations. This is a technical mailing list for which strictly technical content is expected. &a.gnome.name; GNOME Discussions concerning The GNOME Desktop Environment for FreeBSD systems. This is a technical mailing list for which strictly technical content is expected. &a.ipfw.name; IP Firewall This is the forum for technical discussions concerning the redesign of the IP firewall code in FreeBSD. This is a technical mailing list for which strictly technical content is expected. &a.ia64.name; Porting FreeBSD to IA64 This is a technical mailing list for individuals actively working on porting FreeBSD to the IA-64 platform from &intel;, to bring up problems or discuss alternative solutions. Individuals interested in following the technical discussion are also welcome. &a.isdn.name; ISDN Communications This is the mailing list for people discussing the development of ISDN support for FreeBSD. &a.java.name; &java; Development This is the mailing list for people discussing the development of significant &java; applications for FreeBSD and the porting and maintenance of &jdk;s. &a.jobs.name; Jobs offered and sought This is a forum for posting employment notices and resumes specifically related to &os;, e.g. if you are seeking &os;-related employment or have a job involving &os; to advertise then this is the right place. This is not a mailing list for general employment issues since adequate forums for that already exist elsewhere. Note that this list, like other FreeBSD.org mailing lists, is distributed worldwide. Thus, you need to be clear about location and the extent to which telecommuting or assistance with relocation is available. Email should use open formats only — preferably plain text, but basic Portable Document Format (PDF), HTML, and a few others are acceptable to many readers. Closed formats such as µsoft; Word (.doc) will be rejected by the mailing list server. &a.kde.name; KDE Discussions concerning KDE on FreeBSD systems. This is a technical mailing list for which strictly technical content is expected. &a.hackers.name; Technical discussions This is a forum for technical discussions related to FreeBSD. This is the primary technical mailing list. It is for individuals actively working on FreeBSD, to bring up problems or discuss alternative solutions. Individuals interested in following the technical discussion are also welcome. This is a technical mailing list for which strictly technical content is expected. &a.hardware.name; General discussion of FreeBSD hardware General discussion about the types of hardware that FreeBSD runs on, various problems and suggestions concerning what to buy or avoid. &a.hubs.name; Mirror sites Announcements and discussion for people who run FreeBSD mirror sites. &a.isp.name; Issues for Internet Service Providers This mailing list is for discussing topics relevant to Internet Service Providers (ISPs) using FreeBSD. This is a technical mailing list for which strictly technical content is expected. &a.newbies.name; Newbies activities discussion We cover any of the activities of newbies that are not already dealt with elsewhere, including: independent learning and problem solving techniques, finding and using resources and asking for help elsewhere, how to use mailing lists and which lists to use, general chat, making mistakes, boasting, sharing ideas, stories, moral (but not technical) support, and taking an active part in the FreeBSD community. We take our problems and support questions to freebsd-questions, and use freebsd-newbies to meet others who are doing the same things that we do as newbies. &a.openoffice.name; OpenOffice.org Discussions concerning the porting and maintenance of OpenOffice.org and &staroffice;. &a.performance.name; Discussions about tuning or speeding up FreeBSD This mailing list exists to provide a place for hackers, administrators, and/or concerned parties to discuss performance related topics pertaining to FreeBSD. Acceptable topics includes talking about FreeBSD installations that are either under high load, are experiencing performance problems, or are pushing the limits of FreeBSD. Concerned parties that are willing to work toward improving the performance of FreeBSD are highly encouraged to subscribe to this list. This is a highly technical list ideally suited for experienced FreeBSD users, hackers, or administrators interested in keeping FreeBSD fast, robust, and scalable. This list is not a question-and-answer list that replaces reading through documentation, but it is a place to make contributions or inquire about unanswered performance related topics. &a.pf.name; Discussion and questions about the packet filter firewall system Discussion concerning the packet filter (pf) firewall system in terms of FreeBSD. Technical discussion and user questions are both welcome. This list is also a place to discuss the ALTQ QoS framework. &a.platforms.name; Porting to Non &intel; platforms Cross-platform FreeBSD issues, general discussion and proposals for non &intel; FreeBSD ports. This is a technical mailing list for which strictly technical content is expected. &a.policy.name; Core team policy decisions This is a low volume, read-only mailing list for FreeBSD Core Team Policy decisions. &a.ports.name; Discussion of ports Discussions concerning FreeBSD's ports collection (/usr/ports), ports infrastructure, and general ports coordination efforts. This is a technical mailing list for which strictly technical content is expected. &a.ports-bugs.name; Discussion of ports bugs Discussions concerning problem reports for FreeBSD's ports collection (/usr/ports), proposed ports, or modifications to ports. This is a technical mailing list for which strictly technical content is expected. &a.python.name; Python on FreeBSD This is a list for discussions related to improving Python-support on FreeBSD. This is a technical mailing list. It is for individuals working on porting Python, its 3rd party modules and Zope stuff to FreeBSD. Individuals interested in following the technical discussion are also welcome. + &a.questions.name; User questions This is the mailing list for questions about FreeBSD. You should not send how to questions to the technical lists unless you consider the question to be pretty technical. &a.scsi.name; SCSI subsystem This is the mailing list for people working on the SCSI subsystem for FreeBSD. This is a technical mailing list for which strictly technical content is expected. &a.security.name; Security issues FreeBSD computer security issues (DES, Kerberos, known security holes and fixes, etc). This is a technical mailing list for which strictly technical discussion is expected. Note that this is not a question-and-answer list, but that contributions (BOTH question AND answer) to the FAQ are welcome. &a.security-notifications.name; Security Notifications Notifications of FreeBSD security problems and fixes. This is not a discussion list. The discussion list is FreeBSD-security. &a.small.name; Using FreeBSD in embedded applications This list discusses topics related to unusually small and embedded FreeBSD installations. This is a technical mailing list for which strictly technical content is expected. &a.stable.name; Discussions about the use of &os.stable; This is the mailing list for users of &os.stable;. It includes warnings about new features coming out in -STABLE that will affect the users, and instructions on steps that must be taken to remain -STABLE. Anyone running STABLE should subscribe to this list. This is a technical mailing list for which strictly technical content is expected. &a.standards.name; C99 & POSIX Conformance This is a forum for technical discussions related to FreeBSD Conformance to the C99 and the POSIX standards. &a.usb.name; Discussing &os; support for USB This is a mailing list for technical discussions related to &os; support for USB. &a.usergroups.name; User Group Coordination List This is the mailing list for the coordinators from each of the local area Users Groups to discuss matters with each other and a designated individual from the Core Team. This mail list should be limited to meeting synopsis and coordination of projects that span User Groups. &a.vendors.name; Vendors Coordination discussions between The FreeBSD Project and Vendors of software and hardware for FreeBSD. Filtering on the Mailing Lists The &os; mailing lists are filtered in multiple ways to avoid the distribution of spam, viruses, and other unwanted emails. The filtering actions described in this section do not include all those used to protect the mailing lists. Only certain types of attachments are allowed on the mailing lists. All attachments with a MIME content type not found in the list below will be stripped before an email is distributed on the mailing lists. application/octet-stream application/pdf application/pgp-signature application/x-pkcs7-signature message/rfc822 multipart/alternative multipart/related multipart/signed text/html text/plain text/x-diff text/x-patch Some of the mailing lists might allow attachments of other MIME content types, but the above list should be applicable for most of the mailing lists. If an email contains both an HTML and a plain text version, the HTML version will be removed. If an email contains only an HTML version, it will be converted to plain text. Usenet Newsgroups In addition to two FreeBSD specific newsgroups, there are many others in which FreeBSD is discussed or are otherwise relevant to FreeBSD users. Keyword searchable archives are available for some of these newsgroups from courtesy of Warren Toomey wkt@cs.adfa.edu.au. BSD Specific Newsgroups comp.unix.bsd.freebsd.announce comp.unix.bsd.freebsd.misc de.comp.os.unix.bsd (German) fr.comp.os.bsd (French) it.comp.os.freebsd (Italian) Other &unix; Newsgroups of Interest comp.unix comp.unix.questions comp.unix.admin comp.unix.programmer comp.unix.shell comp.unix.user-friendly comp.security.unix comp.sources.unix comp.unix.advocacy comp.unix.misc comp.bugs.4bsd comp.bugs.4bsd.ucb-fixes comp.unix.bsd X Window System comp.windows.x.i386unix comp.windows.x comp.windows.x.apps comp.windows.x.announce comp.windows.x.intrinsics comp.windows.x.motif comp.windows.x.pex comp.emulators.ms-windows.wine World Wide Web Servers &chap.eresources.www.inc; Email Addresses The following user groups provide FreeBSD related email addresses for their members. The listed administrator reserves the right to revoke the address if it is abused in any way. Domain Facilities User Group Administrator ukug.uk.FreeBSD.org Forwarding only freebsd-users@uk.FreeBSD.org Lee Johnston lee@uk.FreeBSD.org Shell Accounts The following user groups provide shell accounts for people who are actively supporting the FreeBSD project. The listed administrator reserves the right to cancel the account if it is abused in any way. Host Access Facilities Administrator dogma.freebsd-uk.eu.org Telnet/FTP/SSH Email, Web space, Anonymous FTP Lee Johnston lee@uk.FreeBSD.org diff --git a/en_US.ISO8859-1/books/handbook/firewalls/chapter.sgml b/en_US.ISO8859-1/books/handbook/firewalls/chapter.sgml index 9476a58907..6bb7dadd40 100644 --- a/en_US.ISO8859-1/books/handbook/firewalls/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/firewalls/chapter.sgml @@ -1,2873 +1,2873 @@ Joseph J. Barbish Contributed by Brad Davis Converted to SGML and updated by Firewalls firewall security firewalls Introduction Firewalls make it possible to filter incoming and outgoing traffic that flows through your system. A firewall can use one or more sets of rules to inspect the network packets as they come in or go out of your network connections and either allows the traffic through or blocks it. The rules of a firewall can inspect one or more characteristics of the packets, including but not limited to the protocol type, the source or destination host address, and the source or destination port. Firewalls can greatly enhance the security of a host or a network. They can be used to do one or more of the following things: To protect and insulate the applications, services and machines of your internal network from unwanted traffic coming in from the public Internet. To limit or disable access from hosts of the internal network to services of the public Internet. To support network address translation (NAT), which allows your internal network to use private IP addresses and share a single connection to the public Internet (either with a single IP address or by a shared pool of automatically assigned public addresses). After reading this chapter, you will know: How to properly define packet filtering rules. The differences between the firewalls built into &os;. How to use and configure the OpenBSD PF firewall. How to use and configure IPFILTER. How to use and configure IPFW. Before reading this chapter, you should: Understand basic &os; and Internet concepts. Firewall Concepts There are two basic ways to create firewall rulesets: inclusive or exclusive. An exclusive firewall allows all traffic through except for the traffic matching the ruleset. An inclusive firewall does the reverse. It only allows traffic matching the rules through and blocks everything else. Inclusive firewalls are generally safer than exclusive firewalls because they significantly reduce the risk of allowing unwanted traffic to pass through the firewall. Security can be tightened further using a stateful firewall. With a stateful firewall the firewall keeps track of which connections are opened through the firewall and will only allow traffic through which either matches an existing connection or opens a new one. The disadvantage of a stateful firewall is that it can be vulnerable to Denial of Service (DoS) attacks if a lot of new connections are opened very fast. With most firewalls it is possible to use a combination of stateful and non-stateful behavior to make an optimal firewall for the site. Firewall Software Applications &os; has three different firewall software products built into the base system. They are IPFILTER (also known as IPF), IPFIREWALL (also known as IPFW) and PF (OpenBSD's PacketFilter). IPFIREWALL has the built in DUMMYNET traffic shaper facilities for controlling bandwidth usage. IPFILTER does not have a built in traffic shaper facility for controlling bandwidth usage, but the ALTQ port application can be used to accomplish the same function. The DUMMYNET feature and ALTQ is generally useful only to large ISPs or commercial users. IPF, IPFW and PF use rules to control the access of packets to and from your system, although they go about it different ways and have different rule syntaxes. The IPFW sample rule set (found in /etc/rc.firewall) delivered in the basic install is outdated, complicated and does not use stateful rules on the interface facing the public Internet. It exclusively uses legacy stateless rules which only have the ability to open or close the service ports. The IPFW example stateful rules sets presented here supercede the /etc/rc.firewall file distributed with the system. Stateful rules have technically advanced interrogation abilities capable of defending against the flood of different methods currently employed by attackers. All of these firewall software solutions IPF, IPFW and PF still maintain their legacy heritage of their original rule processing order and reliance on non-stateful rules. These outdated concepts are not covered here, only the new, modern stateful rule construct and rule processing order is presented. You should read about both of them and make your own decision on which one best fits your needs. The author prefers IPFILTER because its stateful rules are much less complicated to use in a NAT environment and it has a built in ftp proxy that simplifies the rules to allow secure outbound FTP usage. It is also more appropriate to the knowledge level of the inexperienced firewall user. Since all firewalls are based on interrogating the values of selected packet control fields, the creator of the firewall rules must have an understanding of how TCP/IP works, what the different values in the packet control fields are and how these values are used in a normal session conversation. For a good explanation go to: . The Packet Filter (PF) Firewall As of July 2003 the OpenBSD firewall software application known as PF was ported to &os; and was made available in the &os; ports collection; the first release that contained PF as an integrated part of the base system was &os; 5.3 in November 2004. PF is a complete, fully featured firewall that contains ALTQ for bandwidth usage management in a way similar to what DUMMYNET provides in IPFW. The OpenBSD project does an outstanding job of maintaining the PF users' guide that it will not be made part of this handbook firewall section as that would just be duplicated effort. For older 5.X version of &os; you can find PF in the &os; ports collection here: security/pf. More info can be found at the PF for &os; web site: . The OpenBSD PF user's guide is here: . PF in &os; 5.X is at the level of OpenBSD version 3.5. The port from the &os; ports collection is at the level of OpenBSD version 3.4. Keep that in mind when browsing the user's guide. Enabling PF PF is included in the basic &os; install for versions newer than 5.3 as a separate run time loadable module. The system will dynamically load the PF kernel loadable module when the rc.conf statement pf_enable="YES" is used. The loadable module was created with &man.pflog.4; logging enabled. Kernel options It is not a mandatory requirement that you enable PF by compiling the following options into the &os; kernel. It is only presented here as background information. Compiling PF into the kernel causes the loadable module to never be used. Sample kernel config PF option statements are in the /usr/src/sys/conf/NOTES kernel source and are reproduced here: device pf device pflog device pfsync device pf enables support for the Packet Filter firewall. device pflog enables the optional &man.pflog.4; pseudo network device which can be used to log traffic to a &man.bpf.4; descriptor. The &man.pflogd.8; daemon can be used to store the logging information to disk. device pfsync enables the optional &man.pfsync.4; pseudo network device that is used to monitor state changes. As this is not part of the loadable module one has to build a custom kernel to use it. These settings will take effect only after you have built and installed a kernel with them set. Available rc.conf Options You need the following statements in /etc/rc.conf to activate PF at boot time: pf_enable="YES" # Enable PF (load module if required) pf_rules="/etc/pf.conf" # rules definition file for pf pf_flags="" # additional flags for pfctl startup pflog_enable="YES" # start pflogd(8) pflog_logfile="/var/log/pflog" # where pflogd should store the logfile pflog_flags="" # additional flags for pflogd startup If you have a LAN behind this firewall and have to forward packets for the computers in the LAN or want to do NAT, you have to enable the following option as well: gateway_enable="YES" # Enable as Lan gateway The IPFILTER (IPF) Firewall The author of IPFILTER is Darren Reed. IPFILTER is not operating system dependent: it is an open source application and has been ported to &os;, NetBSD, OpenBSD, SunOS, HP/UX, and Solaris operating systems. IPFILTER is actively being supported and maintained, with updated versions being released regularly. IPFILTER is based on a kernel-side firewall and NAT mechanism that can be controlled and monitored by userland interface programs. The firewall rules can be set or deleted with the &man.ipf.8; utility. The NAT rules can be set or deleted with the &man.ipnat.1; utility. The &man.ipfstat.8; utility can print run-time statistics for the kernel parts of IPFILTER. The &man.ipmon.8; program can log IPFILTER actions to the system log files. IPF was originally written using a rule processing logic of the last matching rule wins and used only stateless type of rules. Over time IPF has been enhanced to include a quick option and a stateful keep state option which drastically modernized the rules processing logic. IPF's official documentation covers the legacy rule coding parameters and the legacy rule file processing logic. The modernized functions are only included as additional options, completely understating their benefits in producing a far superior secure firewall. The instructions contained in this section are based on using rules that contain the quick option and the stateful keep state option. This is the basic framework for coding an inclusive firewall rule set. An inclusive firewall only allows packets matching the rules to pass through. This way you can control what services can originate behind the firewall destined for the public Internet and also control the services which can originate from the public Internet accessing your private network. Everything else is blocked and logged by default design. Inclusive firewalls are much, much more secure than exclusive firewall rule sets and is the only rule set type covered herein. For detailed explanation of the legacy rules processing method see: and . The IPF FAQ is at . Enabling IPF IPF is included in the basic &os; install as a separate run time loadable module. The system will dynamically load the IPF kernel loadable module when the rc.conf statement ipfilter_enable="YES" is used. The loadable module was created with logging enabled and the default pass all options. You do not need to compile IPF into the &os; kernel just to change the default to block all , you can do that by just coding a block all rule at the end of your rule set. Kernel options It is not a mandatory requirement that you enable IPF by compiling the following options into the &os; kernel. It is only presented here as background information. Compiling IPF into the kernel causes the loadable module to never be used. Sample kernel config IPF option statements are in the /usr/src/sys/conf/NOTES kernel source (/usr/src/sys/arch/conf/LINT for &os; 4.X) and are reproduced here. options IPFILTER options IPFILTER_LOG options IPFILTER_DEFAULT_BLOCK options IPFILTER enables support for the IPFILTER firewall. options IPFILTER_LOG enables the option to have IPF log traffic by writing to the ipl packet logging pseudo—device for every rule that has the log keyword. options IPFILTER_DEFAULT_BLOCK changes the default behavior so any packet not matching a firewall pass rule gets blocked. These settings will take effect only after you have built and installed a kernel with them set. Available rc.conf Options You need the following statements in /etc/rc.conf to activate IPF at boot time: ipfilter_enable="YES" # Start ipf firewall ipfilter_rules="/etc/ipf.rules" # loads rules definition text file ipmon_enable="YES" # Start IP monitor log ipmon_flags="-Ds" # D = start as daemon # s = log to syslog # v = log tcp window, ack, seq # n = map IP & port to names If you have a LAN behind this firewall that uses the reserved private IP address ranges, then you need to add the following to enable NAT functionality. gateway_enable="YES" # Enable as Lan gateway ipnat_enable="YES" # Start ipnat function ipnat_rules="/etc/ipnat.rules" # rules definition file for ipnat IPF The ipf command is used to load your rules file. Normally you create a file containing your custom rules and use this command to replace in mass the currently running firewall internal rules. ipf -Fa -f /etc/ipf.rules means flush all internal rules tables. means this is the file to read for the rules to load. This gives you the ability to make changes to your custom rules file, run the above IPF command, and thus update the running firewall with a fresh copy of all the rules without having to reboot the system. This method is very convenient for testing new rules as the procedure can be executed as many times as needed. See the &man.ipf.8; manual page for details on the other flags available with this command. The &man.ipf.8; command expects the rules file to be a standard text file. It will not accept a rules file written as a script with symbolic substitution. There is a way to build IPF rules that utilizes the power of script symbolic substitution. For more information, see . IPFSTAT The default behavior of &man.ipfstat.8; is to retrieve and display the totals of the accumulated statistics gathered as a result of applying the user coded rules against packets going in and out of the firewall since it was last started, or since the last time the accumulators were reset to zero by the ipf -Z command. See the &man.ipfstat.8; manual page for details. The default &man.ipfstat.8; command output will look something like this: input packets: blocked 99286 passed 1255609 nomatch 14686 counted 0 output packets: blocked 4200 passed 1284345 nomatch 14687 counted 0 input packets logged: blocked 99286 passed 0 output packets logged: blocked 0 passed 0 packets logged: input 0 output 0 log failures: input 3898 output 0 fragment state(in): kept 0 lost 0 fragment state(out): kept 0 lost 0 packet state(in): kept 169364 lost 0 packet state(out): kept 431395 lost 0 ICMP replies: 0 TCP RSTs sent: 0 Result cache hits(in): 1215208 (out): 1098963 IN Pullups succeeded: 2 failed: 0 OUT Pullups succeeded: 0 failed: 0 Fastroute successes: 0 failures: 0 TCP cksum fails(in): 0 (out): 0 Packet log flags set: (0) When supplied with either for inbound or for outbound, it will retrieve and display the appropriate list of filter rules currently installed and in use by the kernel. ipfstat -in displays the inbound internal rules table with rule number. ipfstat -on displays the outbound - internal rules table with the rule number. + internal rules table with the rule number. The output will look something like this: @1 pass out on xl0 from any to any @2 block out on dc0 from any to any @3 pass out quick on dc0 proto tcp/udp from any to any keep state ipfstat -ih displays the inbound internal rules table, prefixing each rule with a count of how many times the rule was matched. ipfstat -oh displays the outbound internal rules table, prefixing each rule with a count of how many times the rule was matched. The output will look something like this: 2451423 pass out on xl0 from any to any 354727 block out on dc0 from any to any 430918 pass out quick on dc0 proto tcp/udp from any to any keep state One of the most important functions of the ipfstat command is the flag which displays the state table in a way similar to the way &man.top.1; shows the &os; running process table. When your firewall is under attack this function gives you the ability to identify, drill down to, and see the attacking packets. The optional sub-flags give the ability to select the destination or source IP, port, or protocol that you want to monitor in real time. See the &man.ipfstat.8; manual page for - details. + details. IPMON In order for ipmon to work properly, the kernel option IPFILTER_LOG must be turned on. This command has 2 different modes that it can be used in. Native mode is the default mode when you type the command on the command line without the flag. Daemon mode is for when you want to have a continuous system log file available so that you can review logging of past events. This is how &os; and IPFILTER are configured to work together. &os; has a built in facility to automatically rotate system logs. That is why outputting the log information to syslogd is better than the default of outputting to a regular file. In the default rc.conf file you see the ipmon_flags statement uses the flags ipmon_flags="-Ds" # D = start as daemon # s = log to syslog # v = log tcp window, ack, seq # n = map IP & port to names The benefits of logging are obvious. It provides the ability to review, after the fact, information such as which packets had been dropped, what addresses they came from and where they were going. These all give you a significant edge in tracking down attackers. Even with the logging facility enabled, IPF will not generate any rule logging on its own. The firewall administrator decides what rules in the rule set he wants to log and adds the log keyword to those rules. Normally only deny rules are logged. It is very customary to include a default deny everything rule with the log keyword included as your last rule in the rule set. This way you get to see all the packets that did not match any of the rules in the rule set. IPMON Logging Syslogd uses its own special method for segregation of log data. It uses special groupings called facility and level. IPMON in mode uses Local0 as the facility name. All IPMON logged data goes to Local0. The following levels can be used to further segregate the logged data if desired. LOG_INFO - packets logged using the "log" keyword as the action rather than pass or block. LOG_NOTICE - packets logged which are also passed LOG_WARNING - packets logged which are also blocked LOG_ERR - packets which have been logged and which can be considered short To setup IPFILTER to log all data to /var/log/ipfilter.log, you will need to create the file. The following command will do that: touch /var/log/ipfilter.log The syslog function is controlled by definition statements in the /etc/syslog.conf file. The syslog.conf file offers considerable flexibility in how syslog will deal with system messages issued by software applications like IPF. Add the following statement to /etc/syslog.conf : Local0.* /var/log/ipfilter.log The Local0.* means to write all the logged messages to the coded file location. To activate the changes to /etc/syslog.conf you can reboot or bump the syslog task into re-reading /etc/syslog.conf by running /etc/rc.d/syslogd restart ( kill -HUP PID in &os; 4.x. You get the PID (i.e. process identifier) by listing the tasks with the ps -ax command. Find syslog in the display and the PID is the number in the left column). Do not forget to change /etc/newsyslog.conf to rotate the new log you just created above. The Format of Logged Messages Messages generated by ipmon consist of data fields separated by white space. Fields common to all messages are: The date of packet receipt. The time of packet receipt. This is in the form HH:MM:SS.F, for hours, minutes, seconds, and fractions of a second (which can be several digits long). The name of the interface the packet was processed on, e.g. dc0. The group and rule number of the rule, e.g. @0:17. - These can be viewed with ipfstat -in. + These can be viewed with ipfstat -in. The action: p for passed, b for blocked, S for a short packet, n did not match any rules, L for a log rule. The order of precedence in showing flags is: S, p, b, n, L. A capital P or B means that the packet has been logged due to a global logging setting, not a particular rule. The addresses. This is actually three fields: the source address and port (separated by a comma), the -> symbol, and the destination address and port. 209.53.17.22,80 -> 198.73.220.17,1722. PR followed by the protocol name or number, e.g. PR tcp. len followed by the header length and total length of the packet, e.g. len 20 40. If the packet is a TCP packet, there will be an additional field starting with a hyphen followed by letters corresponding to any flags that were set. See the &man.ipmon.8; manual page for a list of letters and their flags. If the packet is an ICMP packet, there will be two fields at the end, the first always being ICMP, and the next being the ICMP message and sub-message type, separated by a slash, e.g. ICMP 3/3 for a port unreachable message. Building the Rule Script Some experienced IPF users create a file containing the rules and code them in a manner compatible with running them as a script with symbolic substitution. The major benefit of doing this is that you only have to change the value associated with the symbolic name and when the script is run all the rules containing the symbolic name will have the value substituted in the rules. Being a script, you can use symbolic substitution to code frequently used values and substitute them in multiple rules. You will see this in the following example. The script syntax used here is compatible with the sh, csh, and tcsh shells. Symbolic substitution fields are prefixed with a dollar sign: $. Symbolic fields do not have the $ prefix The value to populate the Symbolic field must be enclosed with "double quotes". Start your rule file with something like this: ############# Start of IPF rules script ######################## oif="dc0" # name of the outbound interface odns="192.0.2.11" # ISP's dns server IP address myip="192.0.2.7" # my static IP address from ISP ks="keep state" fks="flags S keep state" # You can use this same to build the /etc/ipf.rules file #cat >> /etc/ipf.rules << EOF # exec ipf command and read inline data, stop reading # when word EOF is found. There has to be one line # after the EOF line to work correctly. /sbin/ipf -Fa -f - << EOF # Allow out access to my ISP's Domain name server. pass out quick on $oif proto tcp from any to $odns port = 53 $fks pass out quick on $oif proto udp from any to $odns port = 53 $ks # Allow out non-secure standard www function pass out quick on $oif proto tcp from $myip to any port = 80 $fks # Allow out secure www function https over TLS SSL pass out quick on $oif proto tcp from $myip to any port = 443 $fks EOF ################## End of IPF rules script ######################## That is all there is to it. The rules are not important in this example; how the Symbolic substitution field are populated and used are. If the above example was in a file named /etc/ipf.rules.script, you could reload these rules by entering this on the command line: sh /etc/ipf.rules.script There is one problem with using a rules file with embedded symbolics. IPF has no problem with it, but the rc startup scripts that read rc.conf will have problems. To get around this limitation with a rc script, remove the following line from /etc/rc.conf: ipfilter_rules= Add a script like the following to your /usr/local/etc/rc.d/ startup directory. The script should have an obvious name like loadipfrules.sh - . The .sh extension is mandatory. + . The .sh extension is mandatory. #!/bin/sh sh /etc/ipf.rules.script The permissions on this script file must be read, write, execute for owner root. chmod 700 /usr/local/etc/rc.d/ipf.loadrules.sh Now, when your system boots your IPF rules will be loaded using the script. IPF Rule Sets A rule set is a group of ipf rules coded to pass or block packets based on the values contained in the packet. The bi-directional exchange of packets between hosts comprises a session conversation. The firewall rule set processes the packet 2 times, once on its arrival from the public Internet host and again as it leaves for its return trip back to the public Internet host. Each TCP/IP service (i.e. telnet, www, mail, etc.) is predefined by its protocol, source and destination IP address, or the source and destination port number. This is the basic selection criteria used to create rules which will pass or block services. IPF was originally written using a rules processing logic of the last matching rule wins and used only stateless rules. Over time IPF has been enhanced to include a quick option and a stateful keep state option which drastically modernized the rule processing logic. The instructions contained in this section are based on using rules that contain the quick option and the stateful keep state option. This is the basic framework for coding an inclusive firewall rule set. An inclusive firewall only allows services matching the rules through. This way you can control what services can originate behind the firewall destined for the public Internet and also control the services which can originate from the public Internet accessing your private network. Everything else is blocked and logged by default design. Inclusive firewalls are much, much securer than exclusive firewall rule sets and is the only rule set type covered herein. Warning, when working with the firewall rules, always, always do it from the root console of the system running the firewall or you can end up locking your self out. Rule Syntax The rule syntax presented here has been simplified to only address the modern stateful rule context and first matching rule wins logic. For the complete legacy rule syntax description see the &man.ipf.8; manual page. # is used to mark the start of a comment and may appear at the end of a rule line or on its own line. Blank lines are ignored. Rules contain keywords. These keywords have to be coded in a specific order from left to right on the line. Keywords are identified in bold type. Some keywords have sub-options which may be keywords themselves and also include more sub-options. Each of the headings in the below syntax has a bold section header which expands on the content. ACTION IN-OUT OPTIONS SELECTION STATEFUL PROTO SRC_ADDR,DST_ADDR OBJECT PORT_NUM TCP_FLAG STATEFUL ACTION = block | pass IN-OUT = in | out OPTIONS = log | quick | on interface-name SELECTION = proto value | source/destination IP | port = number | flags flag-value PROTO = tcp/udp | udp | tcp | icmp SRC_ADD,DST_ADDR = all | from object to object OBJECT = IP address | any PORT_NUM = port number TCP_FLAG = S STATEFUL = keep state ACTION The action indicates what to do with the packet if it matches the rest of the filter rule. Each rule must have a action. The following actions are recognized: block indicates that the packet should be dropped if the selection parameters match the packet. pass indicates that the packet should exit the firewall if the selection parameters match the packet. IN-OUT A mandatory requirement is that each filter rule explicitly state which side of the I/O it is to be used on. The next keyword must be either in or out and one or the other has to be coded or the rule will not pass syntax checks. in means this rule is being applied against an inbound packet which has just been received on the interface facing the public Internet. out means this rule is being applied against an outbound packet destined for the interface facing the public Internet. OPTIONS These options must be used in the order shown here. log indicates that the packet header will be written to the ipl log (as described in the LOGGING section below) if the selection parameters match the packet. quick indicates that if the selection parameters match the packet, this rule will be the last rule checked, allowing a "short-circuit" path to avoid processing any following rules for this packet. This option is a mandatory requirement for the modernized rules processing logic. on indicates the interface name to be incorporated into the selection parameters. Interface names are as displayed by &man.ifconfig.8;. Using this option, the rule will only match if the packet is going through that interface in the specified direction (in/out). This option is a mandatory requirement for the modernized rules processing logic. When a packet is logged, the headers of the packet are written to the IPL packet logging pseudo-device. Immediately following the log keyword, the following qualifiers may be used (in this order): body indicates that the first 128 bytes of the packet contents will be logged after the headers. first If the log keyword is being used in conjunction with a keep state option, it is recommended that this option is also applied so that only the triggering packet is logged and not every packet which thereafter matches the keep state information. SELECTION The keywords described in this section are used to describe attributes of the packet to be interrogated when determining whether rules match or not. There is a keyword subject, and it has sub-option keywords, one of which has to be selected. The following general-purpose attributes are provided for matching, and must be used in this order: PROTO proto is the subject keyword and must be coded along with one of its corresponding keyword sub-option values. The value allows a specific protocol to be matched against. This option is a mandatory requirement for the modernized rules processing logic. tcp/udp | udp | tcp | icmp or any protocol names found in /etc/protocols are recognized and may be used. The special protocol keyword tcp/udp may be used to match either a TCP or a UDP packet, and has been added as a convenience to save duplication of otherwise identical rules. SRC_ADDR/DST_ADDR The all keyword is essentially a synonym for from any to any with no other match parameters. from src to dst: the from and to keywords are used to match against IP addresses. Rules must specify BOTH source and destination parameters. any is a special keyword that matches any IP address. Examples of use: from any to any or from 0.0.0.0/0 to any or from any to 0.0.0.0/0 or from 0.0.0.0 to any or from any to 0.0.0.0. IP addresses may be specified as a dotted IP address numeric form/mask-length, or as single dotted IP address numeric form. There is no way to match ranges of IP addresses which do not express themselves easily as mask-length. See this web page for help on writing mask-length: PORT If a port match is included, for either or both of source and destination, then it is only applied to TCP and UDP packets. When composing port comparisons, either the service name from /etc/services or an integer port number may be used. When the port appears as part of the from object, it matches the source port number; when it appears as part of the to object, it matches the destination port number. The use of the port option with the to object is a mandatory requirement for the modernized rules processing logic. Example of use: from any to any port = 80 Port comparisons may be done in a number of forms, with a number of comparison operators, or port ranges may be specified. port "=" | "!=" | "<" | ">" | "<=" | ">=" | "eq" | "ne" | "lt" | "gt" | "le" | "ge". To specify port ranges, port "<>" | "><" Following the source and destination matching parameters, the following two parameters are mandatory requirements for the modernized rules processing logic. <acronym>TCP</acronym>_FLAG Flags are only effective for TCP filtering. The letters represents one of the possible flags that can be interrogated in the TCP packet header. The modernized rules processing logic uses the flags S parameter to identify the tcp session start request. STATEFUL keep state indicates that on a pass rule, any packets that match the rules selection parameters should activate the stateful filtering facility. This option is a mandatory requirement for the modernized rules processing logic. Stateful Filtering Stateful filtering treats traffic as a bi-directional exchange of packets comprising a session conversation. When activated, keep-state dynamically generates internal rules for each anticipated packet being exchanged during the bi-directional session conversation. It has the interrogation abilities to determine if the session conversation between the originating sender and the destination are following the valid procedure of bi-directional packet exchange. Any packets that do not properly fit the session conversation template are automatically rejected as impostors. Keep state will also allow ICMP packets related to a TCP or UDP session through. So if you get ICMP type 3 code 4 in response to some web surfing allowed out by a keep state rule, they will be automatically allowed in. Any packet that IPF can be certain is part of an active session, even if it is a different protocol, will be let in. What happens is: Packets destined to go out the interface connected to the public Internet are first checked against the dynamic state table, if the packet matches the next expected packet comprising in a active session conversation, then it exits the firewall and the state of the session conversation flow is updated in the dynamic state table, the remaining packets get checked against the outbound rule set. Packets coming in to the interface connected to the public Internet are first checked against the dynamic state table, if the packet matches the next expected packet comprising a active session conversation, then it exits the firewall and the state of the session conversation flow is updated in the dynamic state table, the remaining packets get checked against the inbound rule set. When the conversation completes it is removed from the dynamic state table. Stateful filtering allows you to focus on blocking/passing new sessions. If the new session is passed, all its subsequent packets will be allowed through automatically and any impostors automatically rejected. If a new session is blocked, none of its subsequent packets will be allowed through. Stateful filtering has technically advanced interrogation abilities capable of defending against the flood of different attack methods currently employed by attackers. Inclusive Rule Set Example The following rule set is an example of how to code a very secure inclusive type of firewall. An inclusive firewall only allows services matching pass rules through and blocks all other by default. All firewalls have at the minimum two interfaces which have to have rules to allow the firewall to function. All &unix; flavored systems including &os; are designed to use interface lo0 and IP address 127.0.0.1 for internal communication within the operating system. The firewall rules must contain rules to allow free unmolested movement of these special internally used packets. The interface which faces the public Internet is the one where you place your rules to authorize and control access out to the public Internet and access requests arriving from the public Internet. This can be your user PPP tun0 interface or your NIC that is connected to your DSL or cable modem. In cases where one or more NICs are cabled to private LANs behind the firewall, those interfaces must have a rule coded to allow free unmolested movement of packets originating from those LAN interfaces. The rules should be first organized into three major sections: all the free unmolested interfaces, the public interface outbound, and the public interface inbound. The rules in each of the public interface sections should have the most frequently matched rules placed before less commonly matched rules, with the last rule in the section blocking and logging all packets on that interface and direction. The Outbound section in the following rule set only contains 'pass' rules which contain selection values that uniquely identify the service that is authorized for public Internet access. All the rules have the 'quick', 'on', 'proto', 'port', and 'keep state' option coded. The 'proto tcp' rules have the 'flag' option included to identify the session start request as the triggering packet to activate the stateful facility. The Inbound section has all the blocking of undesirable packets first, for two different reasons. The first is that these things being blocked may be part of an otherwise valid packet which may be allowed in by the later authorized service rules. The second reason is that by having a rule that explicitly blocks selected packets that I receive on an infrequent basis and that I do not want to see in the log, they will not be caught by the last rule in the section which blocks and logs all packets which have fallen through the rules. The last rule in the section which blocks and logs all packets is how you create the legal evidence needed to prosecute the people who are attacking your system. Another thing you should take note of, is there is no response returned for any of the undesirable stuff, their packets just get dropped and vanish. This way the attacker has no knowledge if his packets have reached your system. The less the attackers can learn about your system the more secure it is. The inbound 'nmap OS fingerprint' attempts rule I log the first occurrence because this is something a attacker would do. Any time you see log messages on a rule with 'log first'. You should do an ipfstat -hio command to see the number of times the rule has been matched so you know if you are being flooded, i.e. under attack. When you log packets with port numbers you do not recognize, look it up in /etc/services or go to and do a port number lookup to find what the purpose of that port number is. Check out this link for port numbers used by Trojans The following rule set is a complete very secure 'inclusive' type of firewall rule set that I have used on my system. You can not go wrong using this rule set for your own. Just comment out any pass rules for services that you do not want to authorize. If you see messages in your log that you want to stop seeing just add a block rule in the inbound section. You have to change the dc0 interface name in every rule to the interface name of the Nic card that connects your system to the public Internet. For user PPP it would be tun0. Add the following statements to /etc/ipf.rules: ################################################################# # No restrictions on Inside LAN Interface for private network # Not needed unless you have LAN ################################################################# #pass out quick on xl0 all #pass in quick on xl0 all ################################################################# # No restrictions on Loopback Interface ################################################################# pass in quick on lo0 all pass out quick on lo0 all ################################################################# # Interface facing Public Internet (Outbound Section) # Interrogate session start requests originating from behind the # firewall on the private network # or from this gateway server destine for the public Internet. ################################################################# # Allow out access to my ISP's Domain name server. # xxx must be the IP address of your ISP's DNS. # Dup these lines if your ISP has more than one DNS server # Get the IP addresses from /etc/resolv.conf file pass out quick on dc0 proto tcp from any to xxx port = 53 flags S keep state pass out quick on dc0 proto udp from any to xxx port = 53 keep state # Allow out access to my ISP's DHCP server for cable or DSL networks. # This rule is not needed for 'user ppp' type connection to the # public Internet, so you can delete this whole group. # Use the following rule and check log for IP address. # Then put IP address in commented out rule & delete first rule pass out log quick on dc0 proto udp from any to any port = 67 keep state #pass out quick on dc0 proto udp from any to z.z.z.z port = 67 keep state # Allow out non-secure standard www function pass out quick on dc0 proto tcp from any to any port = 80 flags S keep state # Allow out secure www function https over TLS SSL pass out quick on dc0 proto tcp from any to any port = 443 flags S keep state # Allow out send & get email function pass out quick on dc0 proto tcp from any to any port = 110 flags S keep state pass out quick on dc0 proto tcp from any to any port = 25 flags S keep state # Allow out Time pass out quick on dc0 proto tcp from any to any port = 37 flags S keep state # Allow out nntp news pass out quick on dc0 proto tcp from any to any port = 119 flags S keep state # Allow out gateway & LAN users non-secure FTP ( both passive & active modes) # This function uses the IPNAT built in FTP proxy function coded in # the nat rules file to make this single rule function correctly. # If you want to use the pkg_add command to install application packages # on your gateway system you need this rule. pass out quick on dc0 proto tcp from any to any port = 21 flags S keep state # Allow out secure FTP, Telnet, and SCP # This function is using SSH (secure shell) pass out quick on dc0 proto tcp from any to any port = 22 flags S keep state # Allow out non-secure Telnet pass out quick on dc0 proto tcp from any to any port = 23 flags S keep state # Allow out FBSD CVSUP function pass out quick on dc0 proto tcp from any to any port = 5999 flags S keep state # Allow out ping to public Internet pass out quick on dc0 proto icmp from any to any icmp-type 8 keep state # Allow out whois for LAN PC to public Internet pass out quick on dc0 proto tcp from any to any port = 43 flags S keep state # Block and log only the first occurrence of everything # else that's trying to get out. # This rule enforces the block all by default logic. block out log first quick on dc0 all ################################################################# # Interface facing Public Internet (Inbound Section) # Interrogate packets originating from the public Internet # destine for this gateway server or the private network. ################################################################# # Block all inbound traffic from non-routable or reserved address spaces block in quick on dc0 from 192.168.0.0/16 to any #RFC 1918 private IP block in quick on dc0 from 172.16.0.0/12 to any #RFC 1918 private IP block in quick on dc0 from 10.0.0.0/8 to any #RFC 1918 private IP block in quick on dc0 from 127.0.0.0/8 to any #loopback block in quick on dc0 from 0.0.0.0/8 to any #loopback block in quick on dc0 from 169.254.0.0/16 to any #DHCP auto-config block in quick on dc0 from 192.0.2.0/24 to any #reserved for docs block in quick on dc0 from 204.152.64.0/23 to any #Sun cluster interconnect block in quick on dc0 from 224.0.0.0/3 to any #Class D & E multicast ##### Block a bunch of different nasty things. ############ # That I don't want to see in the log # Block frags block in quick on dc0 all with frags # Block short tcp packets block in quick on dc0 proto tcp all with short # block source routed packets block in quick on dc0 all with opt lsrr block in quick on dc0 all with opt ssrr # Block nmap OS fingerprint attempts # Log first occurrence of these so I can get their IP address block in log first quick on dc0 proto tcp from any to any flags FUP # Block anything with special options block in quick on dc0 all with ipopts # Block public pings block in quick on dc0 proto icmp all icmp-type 8 # Block ident block in quick on dc0 proto tcp from any to any port = 113 # Block all Netbios service. 137=name, 138=datagram, 139=session # Netbios is MS/Windows sharing services. # Block MS/Windows hosts2 name server requests 81 block in log first quick on dc0 proto tcp/udp from any to any port = 137 block in log first quick on dc0 proto tcp/udp from any to any port = 138 block in log first quick on dc0 proto tcp/udp from any to any port = 139 block in log first quick on dc0 proto tcp/udp from any to any port = 81 # Allow traffic in from ISP's DHCP server. This rule must contain # the IP address of your ISP's DHCP server as it's the only # authorized source to send this packet type. Only necessary for # cable or DSL configurations. This rule is not needed for # 'user ppp' type connection to the public Internet. # This is the same IP address you captured and # used in the outbound section. pass in quick on dc0 proto udp from z.z.z.z to any port = 68 keep state # Allow in standard www function because I have apache server pass in quick on dc0 proto tcp from any to any port = 80 flags S keep state # Allow in non-secure Telnet session from public Internet # labeled non-secure because ID/PW passed over public Internet as clear text. # Delete this sample group if you do not have telnet server enabled. #pass in quick on dc0 proto tcp from any to any port = 23 flags S keep state # Allow in secure FTP, Telnet, and SCP from public Internet # This function is using SSH (secure shell) pass in quick on dc0 proto tcp from any to any port = 22 flags S keep state # Block and log only first occurrence of all remaining traffic # coming into the firewall. The logging of only the first # occurrence stops a .denial of service. attack targeted # at filling up your log file space. # This rule enforces the block all by default logic. block in log first quick on dc0 all ################### End of rules file ##################################### <acronym>NAT</acronym> NAT stands for Network Address Translation. To those familiar with Linux, this concept is called IP Masquerading; NAT and IP Masquerading are the same thing. One of the many things the IPF NAT function enables is the ability to have a private Local Area Network (LAN) behind the firewall sharing a single ISP assigned IP address on the public Internet. You may ask why would someone want to do this. ISPs normally assign a dynamic IP address to their non-commercial users. Dynamic means that the IP address can be different each time you dial in and log on to your ISP, or for cable and DSL modem users when you power off and then power on your modems you can get assigned a different IP address. This IP address is how you are known to the public Internet. Now lets say you have 5 PCs at home and each one needs Internet access. You would have to pay your ISP for an individual Internet account for each PC and have 5 phone lines. With NAT you only need a single account with your ISP, then cable your other 4 PCs to a switch and the switch to the NIC in your &os; system which is going to service your LAN as a gateway. NAT will automatically translate the private LAN IP address for each separate PC on the LAN to the single public IP address as it exits the firewall bound for the public Internet. It also does the reverse translation for returning packets. NAT is most often accomplished without the approval, or knowledge, of your ISP and in most cases is grounds for your ISP terminating your account if found out. Commercial users pay a lot more for their Internet connection and usually get assigned a block of static IP address which never change. The ISP also expects and consents to their Commercial customers using NAT for their internal private LANs. There is a special range of IP addresses reserved for NATed private LAN IP address. According to RFC 1918, you can use the following IP ranges for private nets which will never be routed directly to the public Internet. Start IP 10.0.0.0 - Ending IP 10.255.255.255 Start IP 172.16.0.0 - Ending IP 172.31.255.255 Start IP 192.168.0.0 - Ending IP 192.168.255.255 IP<acronym>NAT</acronym> NAT rules are loaded by using the ipnat command. Typically the NAT rules are stored in /etc/ipnat.rules . See &man.ipnat.1 for details. When changing the NAT rules after NAT has been started, make your changes to the file containing the NAT rules, then run ipnat command with the flags to delete the internal in use NAT rules and flush the contents of the translation table of all active entries. To reload the NAT rules issue a command like this: ipnat -CF -f /etc/ipnat.rules To display some statistics about your NAT, use this command: ipnat -s To list the NAT table's current mappings, use this command: ipnat -l To turn verbose mode on, and display information relating to rule processing and active rules/table entries: ipnat -v IP<acronym>NAT</acronym> Rules NAT rules are very flexible and can accomplish many different things to fit the needs of commercial and home users. The rule syntax presented here has been simplified to what is most commonly used in a non-commercial environment. For a complete rule syntax description see the &man.ipnat.5; manual page. The syntax for a NAT rule looks something like this: map IF LAN_IP_RANGE -> PUBLIC_ADDRESS The keyword map starts the rule. Replace IF with the external interface. The LAN_IP_RANGE is what your internal clients use for IP Addressing, usually this is something like 192.168.1.0/24. The PUBLIC_ADDRESS can either be the external IP address or the special keyword `0.32', which means to use the IP address assigned to IF. How <acronym>NAT</acronym> works A packet arrives at the firewall from the LAN with a public destination. It passes through the outbound filter rules, NAT gets his turn at the packet and applies its rules top down, first matching rule wins. NAT tests each of its rules against the packets interface name and source IP address. When a packets interface name matches a NAT rule then the [source IP address, i.e. private Lan IP address] of the packet is checked to see if it falls within the IP address range specified to the left of the arrow symbol on the NAT rule. On a match the packet has its source IP address rewritten with the public IP address obtained by the `0.32' keyword. NAT posts a entry in its internal NAT table so when the packet returns from the public Internet it can be mapped back to its original private IP address and then passed to the filter rules for processing. Enabling IP<acronym>NAT</acronym> To enable IPNAT add these statements to /etc/rc.conf To enable your machine to route traffic between interfaces: gateway_enable="YES" To start IPNAT automatically each time: ipnat_enable="YES" To specify where to load the IPNAT rules from: ipnat_rules="/etc/ipnat.rules" <acronym>NAT</acronym> for a very large LAN For networks that have large numbers of PC's on the LAN or networks with more than a single LAN, the process of funneling all those private IP addresses into a single public IP address becomes a resource problem that may cause problems with the same port numbers being used many times across many NATed LAN PC's, causing collisions. There are 2 ways to relieve this resource problem. Assigning Ports to Use XXXBLAH map dc0 192.168.1.0/24 -> 0.32 In the above rule the packet's source port is unchanged as the packet passes through IPNAT. By adding the portmap keyword you can tell IPNAT to only use source ports in a range. For example the following rule will tell IPNAT to modify the source port to be within that range. map dc0 192.168.1.0/24 -> 0.32 portmap tcp/udp 20000:60000 Additionally we can make things even easier by using the auto keyword to tell IPNAT to determine by itself which ports are available to use: map dc0 192.168.1.0/24 -> 0.32 portmap tcp/udp auto Using a pool of public addresses In very large LANs there comes a point where there are just too many LAN addresses to fit into a single public address. By changing the following rule: map dc0 192.168.1.0/24 -> 204.134.75.1 Currently this rule maps all connections through 204.134.75.1. This can be changed to specify a range: map dc0 192.168.1.0/24 -> 204.134.75.1-10 Or a subnet using CIDR notation such as: map dc0 192.168.1.0/24 -> 204.134.75.0/24 Port Redirection A very common practice is to have a web server, email server, database server and DNS server each segregated to a different PC on the LAN. In this case the traffic from these servers still have to be NATed, but there has to be some way to direct the inbound traffic to the correct LAN PCs. IPNAT has the redirection facilities of NAT to solve this problem. Lets say you have your web server on LAN address 10.0.10.25 and your single public IP address is 20.20.20.5 you would code the rule like this: map dc0 20.20.20.5/32 port 80 -> 10.0.10.25 port 80 or map dc0 0/32 port 80 -> 10.0.10.25 port 80 or for a LAN DNS Server on LAN address of 10.0.10.33 that needs to receive public DNS requests map dc0 20.20.20.5/32 port 53 -> 10.0.10.33 port 53 udp FTP and <acronym>NAT</acronym> FTP is a dinosaur left over from the time before the Internet as it is known today, when research universities were leased lined together and FTP was used to share files among research Scientists. This was a time when data security was not a consideration. Over the years the FTP protocol became buried into the backbone of the emerging Internet and its username and password being sent in clear text was never changed to address new security concerns. FTP has two flavors, it can run in active mode or passive mode. The difference is in how the data channel is acquired. Passive mode is more secure as the data channel is acquired be the ordinal ftp session requester. For a real good explanation of FTP and the different modes see . IP<acronym>NAT</acronym> Rules IPNAT has a special built in FTP proxy option which can be specified on the NAT map rule. It can monitor all outbound packet traffic for FTP active or passive start session requests and dynamically create temporary filter rules containing only the port number really in use for the data channel. This eliminates the security risk FTP normally exposes the firewall to from having large ranges of high order port numbers open. This rule will handle all the traffic for the internal LAN: map dc0 10.0.10.0/29 -> 0/32 proxy port 21 ftp/tcp This rule handles the FTP traffic from the gateway. map dc0 0.0.0.0/0 -> 0/32 proxy port 21 ftp/tcp This rule handles all non-FTP traffic from the internal LAN. map dc0 10.0.10.0/29 -> 0/32 The FTP map rule goes before our regular map rule. All packets are tested against the first rule from the top. Matches on interface name, then private LAN source IP address, and then is it a FTP packet. If all that matches then the special FTP proxy creates temp filter rules to let the FTP session packets pass in and out, in addition to also NATing the FTP packets. All LAN packets that are not FTP do not match the first rule and fall through to the third rule and are tested, matching on interface and source IP, then are NATed. IP<acronym>NAT</acronym> FTP Filter Rules Only one filter rule is needed for FTP if the NAT FTP proxy is used. Without the FTP Proxy you will need the following three rules # Allow out LAN PC client FTP to public Internet # Active and passive modes pass out quick on rl0 proto tcp from any to any port = 21 flags S keep state # Allow out passive mode data channel high order port numbers pass out quick on rl0 proto tcp from any to any port > 1024 flags S keep state # Active mode let data channel in from FTP server pass in quick on rl0 proto tcp from any to any port = 20 flags S keep state FTP <acronym>NAT</acronym> Proxy Bug As of &os; 4.9 which includes IPFILTER version 3.4.31 the FTP proxy works as documented during the FTP session until the session is told to close. When the close happens packets returning from the remote FTP server are blocked and logged coming in on port 21. The NAT FTP/proxy appears to remove its temp rules prematurely, before receiving the response from the remote FTP server acknowledging the close. Posted problem report to ipf mailing list. Solution is to add filter rule like this one to get rid of these unwanted log messages or do nothing and ignore FTP inbound error messages in your log. Not like you do FTP session to the public Internet all the time, so this is not a big deal. Block in quick on rl0 proto tcp from any to any port = 21 IPFW The IPFIREWALL (IPFW) is a &os; sponsored firewall software application authored and maintained by &os; volunteer staff members. It uses the legacy stateless rules and a legacy rule coding technique to achieve what is referred to as Simple Stateful logic. The IPFW stateless rule syntax is empowered with technically sophisticated selection capabilities which far surpasses the knowledge level of the customary firewall installer. IPFW is targeted at the professional user or the advanced technical computer hobbyist who have advanced packet selection requirements. A high degree of detailed knowledge into how different protocols use and create their unique packet header information is necessary before the power of the IPFW rules can be unleashed. Providing that level of explanation is out of the scope of this section of the handbook. IPFW is composed of 7 components, the primary component is the kernel firewall filter rule processor and its integrated packet accounting facility, the logging facility, the 'divert' rule which triggers the NAT facility, and the advanced special purpose facilities, the dummynet traffic shaper facilities, the 'fwd rule' forward facility, the bridge facility, and the ipstealth facility. Enabling IPFW IPFW is included in the basic &os; install as a separate run time loadable module. The system will dynamically load the kernel module when the rc.conf statement firewall_enable="YES" is used. You do not need to compile IPFW into the &os; kernel unless you want NAT function enabled. After rebooting your system with firewall_enable="YES" in rc.conf the following white highlighted message is displayed on the screen as part of the boot process: IP packet filtering initialized, divert disabled, rule-based forwarding enabled, default to deny, logging disabled You can disregard this message as it is out dated and no longer is the true status of the IPFW loadable module. The loadable module really does have logging ability compiled in. To set the verbose logging limit, There is a knob you can set in /etc/sysctl.conf by adding this statement, logging will be enabled on future reboots. net.inet.ip.fw.verbose_limit=5 Kernel Options It is not a mandatory requirement that you enable IPFW by compiling the following options into the &os; kernel unless you need NAT function. It is presented here as background information. options IPFIREWALL This option enables IPFW as part of the kernel options IPFIREWALL_VERBOSE Enables logging of packets that pass through IPFW and have the 'log' keyword specified in the rule set. options IPFIREWALL_VERBOSE_LIMIT=5 This specifies the default number of packets from a particular rule is to be logged. Without this option, each repeated occurrences of the same packet will be logged, and eventually consuming all the free disk space resulting in services being denied do to lack of resources. The 5 is the number of consecutive times to log evidence of this unique occurrence. options IPFIREWALL_DEFAULT_TO_ACCEPT This option will allow everything to pass through the firewall by default, which is a good idea when you are first setting up your firewall. options IPV6FIREWALL options IPV6FIREWALL_VERBOSE options IPV6FIREWALL_VERBOSE_LIMIT options IPV6FIREWALL_DEFAULT_TO_ACCEPT These options are exactly the same as the IPv4 options but they are for IPv6. If you do not use IPv6 you might want to use IPV6FIREWALL without any rules to block all IPv6 options IPDIVERT This enables the use of NAT functionality. If you do not include IPFIREWALL_DEFAULT_TO_ACCEPT or set your rules to allow incoming packets you will block all packets going to and from this machine. <filename>/etc/rc.conf</filename> Options If you do not have IPFW compiled into your kernel you will need to load it with the following statement in your /etc/rc.conf: firewall_enable="YES" Set the script to run to activate your rules: firewall_script="/etc/ipfw.rules" Enable logging: firewall_logging="YES" The IPFW Command The ipfw command is the normal vehicle for making manual single rule additions or deletions to the firewall active internal rules while it is running. The problem with using this method is once your system is shutdown or halted all the rules you added or changed or deleted are lost. Writing all your rules in a file and using that file to load the rules at boot time, or to replace in mass the currently running firewall rules with changes you made to the files content is the recommended method used here. The ipfw command is still a very useful to display the running firewall rules to the console screen. The IPFW accounting facility dynamically creates a counter for each rule that counts each packet that matches the rule. During the process of testing a rule, listing the rule with its counter is the only way of determining if the rule is functioning. To list all the rules in sequence: ipfw list To list all the rules with a time stamp of when the last time the rule was matched: ipfw -t list To list the accounting information, packet count for matched rules along with the rules themselves. The first column is the rule number, followed by the number of outgoing matched packets, followed by the number of incoming matched packets, and then the rule itself. ipfw -a list List the dynamic rules in addition to the static rules: ipfw -d list Also show the expired dynamic rules: ipfw -d -e list Zero the counters: ipfw zero Zero the counters for just rule NUM : ipfw zero NUM IPFW Rule Sets A rule set is a group of ipfw rules coded to allow or deny packets based on the values contained in the packet. The bi-directional exchange of packets between hosts comprises a session conversation. The firewall rule set processes the packet 2 times, once on its arrival from the public Internet host and again as it leaves for its return trip back to the public Internet host. Each tcp/ip service (i.e. telnet, www, mail, etc.) is predefined by its protocol, and port number. This is the basic selection criteria used to create rules which will allow or deny services. When a packet enters the firewall it is compared against the first rule in the rule set and progress one rule at a time moving from top to bottom of the set in ascending rule number sequence order. When the packet matches a rule selection parameters, the rules action field value is executed and the search of the rule set terminates for that packet. This is referred to as the first match wins search method. If the packet does not match any of the rules, it gets caught by the mandatory ipfw default rule, number 65535 which denies all packets and discards them without any reply back to the originating destination. The instructions contained here are based on using rules that contain the stateful 'keep state', 'limit', 'in'/'out', and via options. This is the basic framework for coding an inclusive type firewall rule set. An inclusive firewall only allows services matching the rules through. This way you can control what services can originate behind the firewall destine for the public Internet and also control the services which can originate from the public Internet accessing your private network. Everything else is denied by default design. Inclusive firewalls are much, much more secure than exclusive firewall rule sets and is the only rule set type covered here in. When working with the firewall rules be careful, you can end up locking your self out. Rule Syntax The rule syntax presented here has been simplified to what is necessary to create a standard inclusive type firewall rule set. For a complete rule syntax description see the &man.ipfw.8; manual page. Rules contain keywords: these keywords have to be coded in a specific order from left to right on the line. Keywords are identified in bold type. Some keywords have sub-options which may be keywords them selves and also include more sub-options. # is used to mark the start of a comment and may appear at the end of a rule line or on its own lines. Blank lines are ignored. CMD RULE# ACTION LOGGING SELECTION STATEFUL CMD Each rule has to be prefixed with 'add' to add the rule to the internal table. RULE# Each rule has to have a rule number to go with it. ACTION A rule can be associated with one of the following actions, which will be executed when the packet matches the selection criterion of the rule. allow | accept | pass | permit These all mean the same thing which is to allow packets that match the rule to exit the firewall rule processing. The search terminates at this rule. check-state Checks the packet against the dynamic rules table. If a match is found, execute the action associated with the rule which generated this dynamic rule, otherwise move to the next rule. The check-state rule does not have selection criterion. If no check-state rule is present in the rule set, the dynamic rules table is checked at the first keep-state or limit rule. deny | drop Both words mean the same thing which is to discard packets that match this rule. The search terminates. Logging log or logamount When a packet matches a rule with the log keyword, a message will be logged to syslogd with a facility name of SECURITY. The logging only occurs if the number of packets logged so far for that particular rule does not exceed the logamount parameter. If no logamount is specified, the limit is taken from the sysctl variable net.inet.ip.fw.verbose_limit. In both cases, a value of zero removes the logging limit. Once the limit is reached, logging can be re-enabled by clearing the logging counter or the packet counter for that rule, see the ipfw reset log command. Note: logging is done after all other packet matching conditions have been successfully verified, and before performing the final action (accept, deny) on the packet. It is up to you to decide which rules you want to enable logging on. Selection The keywords described in this section are used to describe attributes of the packet to be interrogated when determining whether rules match the packet or not. The following general-purpose attributes are provided for matching, and must be used in this order: udp | tcp | icmp or any protocol names found in /etc/protocols are recognized and may be used. The value specified is protocol to be matched against. This is a mandatory requirement. from src to dst The from and to keywords are used to match against IP addresses. Rules must specify BOTH source and destination parameters. any is a special keyword that matches any IP address. me is a special keyword that matches any IP address configured on an interface in your &os; system to represent the PC the firewall is running on (i.e. this box) as in 'from me to any' or 'from any to me' or 'from 0.0.0.0/0 to any' or 'from any to 0.0.0.0/0' or 'from 0.0.0.0 to any' or 'from any to 0.0.0.0' or 'from me to 0.0.0.0'. IP addresses are specified as a dotted IP address numeric form/mask-length, or as single dotted IP address numeric form. This is a mandatory requirement. See this link for help on writing mask-lengths. port number For protocols which support port numbers (such as TCP and UDP). It is mandatory that you code the port number of the service you want to match on. Service names (from /etc/services) may be used instead of numeric port values. in | out Matches incoming or outgoing packets, respectively. The in and out are keywords and it is mandatory that you code one or the other as part of your rule matching criterion. via IF Matches packets going through the interface specified by exact name. The via keyword causes the interface to always be checked as part of the match process. setup This is a mandatory keyword that identifies the session start request for TCP packets. keep-state This is a mandatory> keyword. Upon a match, the firewall will create a dynamic rule, whose default behavior is to match bidirectional traffic between source and destination IP/port using the same protocol. limit {src-addr | src-port | dst-addr | dst-port} The firewall will only allow N connections with the same set of parameters as specified in the rule. One or more of source and destination addresses and ports can be specified. The 'limit' and 'keep-state' can not be used on same rule. Limit provides the same stateful function as 'keep-state' plus its own functions. Stateful Rule Option Stateful filtering treats traffic as a bi-directional exchange of packets comprising a session conversation. It has the interrogation abilities to determine if the session conversation between the originating sender and the destination are following the valid procedure of bi-directional packet exchange. Any packets that do not properly fit the session conversation template are automatically rejected as impostors. 'check-state' is used to identify where in the IPFW rules set the packet is to be tested against the dynamic rules facility. On a match the packet exits the firewall to continue on its way and a new rule is dynamic created for the next anticipated packet being exchanged during this bi-directional session conversation. On a no match the packet advances to the next rule in the rule set for testing. The dynamic rules facility is vulnerable to resource depletion from a SYN-flood attack which would open a huge number of dynamic rules. To counter this attack, &os; version 4.5 added another new option named limit. This option is used to limit the number of simultaneous session conversations by interrogating the rules source or destinations fields as directed by the limit option and using the packet's IP address found there, in a search of the open dynamic rules counting the number of times this rule and IP address combination occurred, if this count is greater that the value specified on the limit option, the packet is discarded. Logging Firewall Messages The benefits of logging are obvious: it provides the ability to review after the fact the rules you activated logging on which provides information like, what packets had been dropped, what addresses they came from, where they were going, giving you a significant edge in tracking down attackers. Even with the logging facility enabled, IPFW will not generate any rule logging on it's own. The firewall administrator decides what rules in the rule set he wants to log and adds the log verb to those rules. Normally only deny rules are logged, like the deny rule for incoming ICMP pings. It is very customary to duplicate the ipfw default deny everything rule with the log verb included as your last rule in the rule set. This way you get to see all the packets that did not match any of the rules in the rule set. Logging is a two edged sword, if you're not careful, you can lose yourself in the over abundance of log data and fill your disk up with growing log files. DoS attacks that fill up disk drives is one of the oldest attacks around. These log message are not only written to syslogd, but also are displayed on the root console screen and soon become very annoying. The IPFIREWALL_VERBOSE_LIMIT=5 kernel option limits the number of consecutive messages sent to the system logger syslogd, concerning the packet matching of a given rule. When this option is enabled in the kernel, the number of consecutive messages concerning a particular rule is capped at the number specified. There is nothing to be gained from 200 log messages saying the same identical thing. For instance, 5 consecutive messages concerning a particular rule would be logged to syslogd, the remainder identical consecutive messages would be counted and posted to the syslogd with a phrase like this: last message repeated 45 times All logged packets messages are written by default to /var/log/security file, which is defined in the /etc/syslog.conf file. Building a Rule Script Most experienced IPFW users create a file containing the rules and code them in a manner compatible with running them as a script. The major benefit of doing this is the firewall rules can be refreshed in mass without the need of rebooting the system to activate the new rules. This method is very convenient in testing new rules as the procedure can be executed as many times as needed. Being a script, you can use symbolic substitution to code frequent used values and substitution them in multiple rules. You will see this in the following example. The script syntax used here is compatible with the 'sh', 'csh', 'tcsh' shells. Symbolic substitution fields are prefixed with a dollar sign $. Symbolic fields do not have the $ prefix. The value to populate the Symbolic field must be enclosed to "double quotes". Start your rules file like this: ############### start of example ipfw rules script ############# # ipfw -q -f flush # Delete all rules # Set defaults oif="tun0" # out interface odns="192.0.2.11" # ISP's DNS server IP address cmd="ipfw -q add " # build rule prefix ks="keep-state" # just too lazy to key this each time $cmd 00500 check-state $cmd 00502 deny all from any to any frag $cmd 00501 deny tcp from any to any established $cmd 00600 allow tcp from any to any 80 out via $oif setup $ks $cmd 00610 allow tcp from any to $odns 53 out via $oif setup $ks $cmd 00611 allow udp from any to $odns 53 out via $oif $ks ################### End of example ipfw rules script ############ That is all there is to it. The rules are not important in this example, how the Symbolic substitution field are populated and used are. If the above example was in /etc/ipfw.rules file, you could reload these rules by entering on the command line. sh /etc/ipfw.rules The /etc/ipfw.rules file could be located anywhere you want and the file could be named any thing you would like. The same thing could also be accomplished by running these commands by hand: ipfw -q -f flush ipfw -q add check-state ipfw -q add deny all from any to any frag ipfw -q add deny tcp from any to any established ipfw -q add allow tcp from any to any 80 out via tun0 setup keep-state ipfw -q add allow tcp from any to 192.0.2.11 53 out via tun0 setup keep-state ipfw -q add 00611 allow udp from any to 192.0.2.11 53 out via tun0 keep-state Stateful Ruleset The following non-NATed rule set is a example of how to code a very secure 'inclusive' type of firewall. An inclusive firewall only allows services matching pass rules through and blocks all other by default. All firewalls have at the minimum two interfaces which have to have rules to allow the firewall to function. All &unix; flavored operating systems, &os; included, are designed to use interface lo0 and IP address 127.0.0.1 for internal communication with in the operating system. The firewall rules must contain rules to allow free unmolested movement of these special internally used packets. The interface which faces the public Internet, is the one which you code your rules to authorize and control access out to the public Internet and access requests arriving from the public Internet. This can be your ppp tun0 interface or your NIC that is connected to your DSL or cable modem. In cases where one or more than one NIC are connected to a private LANs behind the firewall, those interfaces must have rules coded to allow free unmolested movement of packets originating from those LAN interfaces. The rules should be first organized into three major sections, all the free unmolested interfaces, public interface outbound, and the public interface inbound. The order of the rules in each of the public interface sections should be in order of the most used rules being placed before less often used rules with the last rule in the section being a block log all packets on that interface and direction. The Outbound section in the following rule set only contains 'allow' rules which contain selection values that uniquely identify the service that is authorized for public Internet access. All the rules have the, proto, port, in/out, via and keep state option coded. The 'proto tcp' rules have the 'setup' option included to identify the start session request as the trigger packet to be posted to the keep state stateful table. The Inbound section has all the blocking of undesirable packets first for 2 different reasons. First is these things being blocked may be part of an otherwise valid packet which may be allowed in by the later authorized service rules. Second reason is that by having a rule that explicitly blocks selected packets that I receive on an infrequent bases and don't want to see in the log, this keeps them from being caught by the last rule in the section which blocks and logs all packets which have fallen through the rules. The last rule in the section which blocks and logs all packets is how you create the legal evidence needed to prosecute the people who are attacking your system. Another thing you should take note of, is there is no response returned for any of the undesirable stuff, their packets just get dropped and vanish. This way the attackers has no knowledge if his packets have reached your system. The less the attackers can learn about your system the more secure it is. When you log packets with port numbers you do not recognize, look the numbers up in /etc/services/ or go to and do a port number lookup to find what the purpose of that port number is. Check out this link for port numbers used by Trojans: . An Example Inclusive Ruleset The following non-NATed rule set is a complete inclusive type ruleset. You can not go wrong using this rule set for you own. Just comment out any pass rules for services you do not want. If you see messages in your log that you want to stop seeing just add a deny rule in the inbound section. You have to change the 'dc0' interface name in every rule to the interface name of the NIC that connects your system to the public Internet. For user ppp it would be 'tun0'. You will see a pattern in the usage of these rules. All statements that are a request to start a session to the public Internet use keep-state. All the authorized services that originate from the public Internet have the limit option to stop flooding. All rules use in or out to clarify direction. All rules use via interface name to specify the interface the packet is traveling over. The following rules go into /etc/ipfw.rules. ################ Start of IPFW rules file ############################### # Flush out the list before we begin. ipfw -q -f flush # Set rules command prefix cmd="ipfw -q add" pif="dc0" # public interface name of NIC # facing the public Internet ################################################################# # No restrictions on Inside LAN Interface for private network # Not needed unless you have LAN. # Change xl0 to your LAN NIC interface name ################################################################# #$cmd 00005 allow all from any to any via xl0 ################################################################# # No restrictions on Loopback Interface ################################################################# $cmd 00010 allow all from any to any via lo0 ################################################################# # Allow the packet through if it has previous been added to the # the "dynamic" rules table by a allow keep-state statement. ################################################################# $cmd 00015 check-state ################################################################# # Interface facing Public Internet (Outbound Section) # Interrogate session start requests originating from behind the # firewall on the private network or from this gateway server # destine for the public Internet. ################################################################# # Allow out access to my ISP's Domain name server. # x.x.x.x must be the IP address of your ISP.s DNS # Dup these lines if your ISP has more than one DNS server # Get the IP addresses from /etc/resolv.conf file $cmd 00110 allow tcp from any to x.x.x.x 53 out via $pif setup keep-state $cmd 00111 allow udp from any to x.x.x.x 53 out via $pif keep-state # Allow out access to my ISP's DHCP server for cable/DSL configurations. # This rule is not needed for .user ppp. connection to the public Internet. # so you can delete this whole group. # Use the following rule and check log for IP address. # Then put IP address in commented out rule & delete first rule $cmd 00120 allow log udp from any to any 67 out via $pif keep-state #$cmd 00120 allow udp from any to x.x.x.x 67 out via $pif keep-state # Allow out non-secure standard www function $cmd 00200 allow tcp from any to any 80 out via $pif setup keep-state # Allow out secure www function https over TLS SSL $cmd 00220 allow tcp from any to any 443 out via $pif setup keep-state # Allow out send & get email function $cmd 00230 allow tcp from any to any 25 out via $pif setup keep-state $cmd 00231 allow tcp from any to any 110 out via $pif setup keep-state # Allow out FBSD (make install & CVSUP) functions # Basically give user root "GOD" privileges. $cmd 00240 allow tcp from me to any out via $pif setup keep-state uid root # Allow out ping $cmd 00250 allow icmp from any to any out via $pif keep-state # Allow out Time $cmd 00260 allow tcp from any to any 37 out via $pif setup keep-state # Allow out nntp news (i.e. news groups) $cmd 00270 allow tcp from any to any 119 out via $pif setup keep-state # Allow out secure FTP, Telnet, and SCP # This function is using SSH (secure shell) $cmd 00280 allow tcp from any to any 22 out via $pif setup keep-state # Allow out whois $cmd 00290 allow tcp from any to any 43 out via $pif setup keep-state # deny and log everything else that.s trying to get out. # This rule enforces the block all by default logic. $cmd 00299 deny log all from any to any out via $pif ################################################################# # Interface facing Public Internet (Inbound Section) # Interrogate packets originating from the public Internet # destine for this gateway server or the private network. ################################################################# # Deny all inbound traffic from non-routable reserved address spaces $cmd 00300 deny all from 192.168.0.0/16 to any in via $pif #RFC 1918 private IP $cmd 00301 deny all from 172.16.0.0/12 to any in via $pif #RFC 1918 private IP $cmd 00302 deny all from 10.0.0.0/8 to any in via $pif #RFC 1918 private IP $cmd 00303 deny all from 127.0.0.0/8 to any in via $pif #loopback $cmd 00304 deny all from 0.0.0.0/8 to any in via $pif #loopback $cmd 00305 deny all from 169.254.0.0/16 to any in via $pif #DHCP auto-config $cmd 00306 deny all from 192.0.2.0/24 to any in via $pif #reserved for docs $cmd 00307 deny all from 204.152.64.0/23 to any in via $pif #Sun cluster interconnect $cmd 00308 deny all from 224.0.0.0/3 to any in via $pif #Class D & E multicast # Deny public pings $cmd 00310 deny icmp from any to any in via $pif # Deny ident $cmd 00315 deny tcp from any to any 113 in via $pif # Deny all Netbios service. 137=name, 138=datagram, 139=session # Netbios is MS/Windows sharing services. # Block MS/Windows hosts2 name server requests 81 $cmd 00320 deny tcp from any to any 137 in via $pif $cmd 00321 deny tcp from any to any 138 in via $pif $cmd 00322 deny tcp from any to any 139 in via $pif $cmd 00323 deny tcp from any to any 81 in via $pif # Deny any late arriving packets $cmd 00330 deny all from any to any frag in via $pif # Deny ACK packets that did not match the dynamic rule table $cmd 00332 deny tcp from any to any established in via $pif # Allow traffic in from ISP's DHCP server. This rule must contain # the IP address of your ISP.s DHCP server as it.s the only # authorized source to send this packet type. # Only necessary for cable or DSL configurations. # This rule is not needed for .user ppp. type connection to # the public Internet. This is the same IP address you captured # and used in the outbound section. #$cmd 00360 allow udp from any to x.x.x.x 67 in via $pif keep-state # Allow in standard www function because I have apache server $cmd 00400 allow tcp from any to me 80 in via $pif setup limit src-addr 2 # Allow in secure FTP, Telnet, and SCP from public Internet $cmd 00410 allow tcp from any to me 22 in via $pif setup limit src-addr 2 # Allow in non-secure Telnet session from public Internet # labeled non-secure because ID & PW are passed over public # Internet as clear text. # Delete this sample group if you do not have telnet server enabled. $cmd 00420 allow tcp from any to me 23 in via $pif setup limit src-addr 2 # Reject & Log all incoming connections from the outside $cmd 00499 deny log all from any to any in via $pif # Everything else is denied by default # deny and log all packets that fell through to see what they are $cmd 00999 deny log all from any to any ################ End of IPFW rules file ############################### An Example <acronym>NAT</acronym> and Stateful Ruleset There are some additional configuration statements that need to be enabled to activate the NAT function of IPFW. The kernel source needs 'option divert' statement added to the other IPFIREWALL statements compiled into a custom kernel. In addition to the normal IPFW options in /etc/rc.conf, the following are needed. natd_enable="YES" # Enable NATD function natd_interface="rl0" # interface name of public Internet NIC natd_flags="-dynamic -m" # -m = preserve port numbers if possible Utilizing stateful rules with divert natd rule (Network Address Translation) greatly complicates the rule set coding logic. The positioning of the check-state, and 'divert natd' rules in the rule set becomes very critical. This is no longer a simple fall-through logic flow. A new action type is used, called 'skipto'. To use the skipto command it is mandatory that you number each rule so you know exactly where the skipto rule number is you are really jumping to. The following is an uncommented example of one coding method, selected here to explain the sequence of the packet flow through the rule sets. The processing flow starts with the first rule from the top of the rule file and progress one rule at a time deeper into the file until the end is reach or the packet being tested to the selection criteria matches and the packet is released out of the firewall. It is important to take notice of the location of rule numbers 100 101, 450, 500, and 510. These rules control the translation of the outbound and inbound packets so their entries in the keep-state dynamic table always register the private Lan IP address. Next notice that all the allow and deny rules specified the direction the packet is going (IE outbound or inbound) and the interface. Also notice that all the start outbound session requests all skipto rule 500 for the network address translation. Lets say a LAN user uses their web browser to get a web page. Web pages use port 80 to communicate over. So the packet enters the firewall, It does not match 100 because it is headed out not in. It passes rule 101 because this is the first packet so it has not been posted to the keep-state dynamic table yet. The packet finally comes to rule 125 a matches. It is outbound through the NIC facing the public Internet. The packet still has it's source IP address as a private Lan IP address. On the match to this rule, two actions take place. The keep-state option will post this rule into the keep-state dynamic rules table and the specified action is executed. The action is part of the info posted to the dynamic table. In this case it is "skipto rule 500". Rule 500 NATs the packet IP address and out it goes. Remember this, this is very important. This packet makes its way to the destination and returns and enters the top of the rule set. This time it does match rule 100 and has it destination IP address mapped back to its corresponding Lan IP address. It then is processed by the check-state rule, it's found in the table as an existing session conversation and released to the LAN. It goes to the LAN PC that sent it and a new packet is sent requesting another segment of the data from the remote server. This time it gets checked by the check-state rule and its outbound entry is found, the associated action, 'skipto 500', is executed. The packet jumps to rule 500 gets NATed and released on it's way out. On the inbound side, everything coming in that is part of an existing session conversation is being automatically handled by the check-state rule and the properly placed divert natd rules. All we have to address is denying all the bad packets and only allowing in the authorized services. Lets say there is a apache server running on the firewall box and we want people on the public Internet to be able to access the local web site. The new inbound start request packet matches rule 100 and its IP address is mapped to LAN IP for the firewall box. The packet is them matched against all the nasty things we want to check for and finally matches against rule 425. On a match two things occur The packet rule is posted to the keep-state dynamic table but this time any new session requests originating from that source IP address is limited to 2. This defends against DoS attacks of service running on the specified port number. The action is allow so the packet is released to the LAN. On return the check-state rule recognizes the packet as belonging to an existing session conversation sends it to rule 500 for NATing and released to outbound interface. Example Ruleset #1: #!/bin/sh cmd="ipfw -q add" skip="skipto 500" pif=rl0 ks="keep-state" good_tcpo="22,25,37,43,53,80,443,110,119" ipfw -q -f flush $cmd 002 allow all from any to any via xl0 # exclude LAN traffic $cmd 003 allow all from any to any via lo0 # exclude loopback traffic $cmd 100 divert natd ip from any to any in via $pif $cmd 101 check-state # Authorized outbound packets $cmd 120 $skip udp from any to xx.168.240.2 53 out via $pif $ks $cmd 121 $skip udp from any to xx.168.240.5 53 out via $pif $ks $cmd 125 $skip tcp from any to any $good_tcpo out via $pif setup $ks $cmd 130 $skip icmp from any to any out via $pif $ks $cmd 135 $skip udp from any to any 123 out via $pif $ks # Deny all inbound traffic from non-routable reserved address spaces $cmd 300 deny all from 192.168.0.0/16 to any in via $pif #RFC 1918 private IP $cmd 301 deny all from 172.16.0.0/12 to any in via $pif #RFC 1918 private IP $cmd 302 deny all from 10.0.0.0/8 to any in via $pif #RFC 1918 private IP $cmd 303 deny all from 127.0.0.0/8 to any in via $pif #loopback $cmd 304 deny all from 0.0.0.0/8 to any in via $pif #loopback $cmd 305 deny all from 169.254.0.0/16 to any in via $pif #DHCP auto-config $cmd 306 deny all from 192.0.2.0/24 to any in via $pif #reserved for docs $cmd 307 deny all from 204.152.64.0/23 to any in via $pif #Sun cluster $cmd 308 deny all from 224.0.0.0/3 to any in via $pif #Class D & E multicast # Authorized inbound packets $cmd 400 allow udp from xx.70.207.54 to any 68 in $ks $cmd 420 allow tcp from any to me 80 in via $pif setup limit src-addr 1 $cmd 450 deny log ip from any to any # This is skipto location for outbound stateful rules $cmd 500 divert natd ip from any to any out via $pif $cmd 510 allow ip from any to any ######################## end of rules ################## The following is pretty much the same as above, but uses a self documenting coding style full of description comments to help the inexperienced IPFW rule writer to better understand what the rules are doing. Example Ruleset #2: #!/bin/sh ################ Start of IPFW rules file ############################### # Flush out the list before we begin. ipfw -q -f flush # Set rules command prefix cmd="ipfw -q add" skip="skipto 800" pif="rl0" # public interface name of NIC # facing the public Internet ################################################################# # No restrictions on Inside LAN Interface for private network # Change xl0 to your LAN NIC interface name ################################################################# $cmd 005 allow all from any to any via xl0 ################################################################# # No restrictions on Loopback Interface ################################################################# $cmd 010 allow all from any to any via lo0 ################################################################# # check if packet is inbound and nat address if it is ################################################################# $cmd 014 divert natd ip from any to any in via $pif ################################################################# # Allow the packet through if it has previous been added to the # the "dynamic" rules table by a allow keep-state statement. ################################################################# $cmd 015 check-state ################################################################# # Interface facing Public Internet (Outbound Section) # Interrogate session start requests originating from behind the # firewall on the private network or from this gateway server # destine for the public Internet. ################################################################# # Allow out access to my ISP's Domain name server. # x.x.x.x must be the IP address of your ISP's DNS # Dup these lines if your ISP has more than one DNS server # Get the IP addresses from /etc/resolv.conf file $cmd 020 $skip tcp from any to x.x.x.x 53 out via $pif setup keep-state # Allow out access to my ISP's DHCP server for cable/DSL configurations. $cmd 030 $skip udp from any to x.x.x.x 67 out via $pif keep-state # Allow out non-secure standard www function $cmd 040 $skip tcp from any to any 80 out via $pif setup keep-state # Allow out secure www function https over TLS SSL $cmd 050 $skip tcp from any to any 443 out via $pif setup keep-state # Allow out send & get email function $cmd 060 $skip tcp from any to any 25 out via $pif setup keep-state $cmd 061 $skip tcp from any to any 110 out via $pif setup keep-state # Allow out FreeBSD (make install & CVSUP) functions # Basically give user root "GOD" privileges. $cmd 070 $skip tcp from me to any out via $pif setup keep-state uid root # Allow out ping $cmd 080 $skip icmp from any to any out via $pif keep-state # Allow out Time $cmd 090 $skip tcp from any to any 37 out via $pif setup keep-state # Allow out nntp news (i.e. news groups) $cmd 100 $skip tcp from any to any 119 out via $pif setup keep-state # Allow out secure FTP, Telnet, and SCP # This function is using SSH (secure shell) $cmd 110 $skip tcp from any to any 22 out via $pif setup keep-state # Allow out whois $cmd 120 $skip tcp from any to any 43 out via $pif setup keep-state # Allow ntp time server $cmd 130 $skip udp from any to any 123 out via $pif keep-state ################################################################# # Interface facing Public Internet (Inbound Section) # Interrogate packets originating from the public Internet # destine for this gateway server or the private network. ################################################################# # Deny all inbound traffic from non-routable reserved address spaces $cmd 300 deny all from 192.168.0.0/16 to any in via $pif #RFC 1918 private IP $cmd 301 deny all from 172.16.0.0/12 to any in via $pif #RFC 1918 private IP $cmd 302 deny all from 10.0.0.0/8 to any in via $pif #RFC 1918 private IP $cmd 303 deny all from 127.0.0.0/8 to any in via $pif #loopback $cmd 304 deny all from 0.0.0.0/8 to any in via $pif #loopback $cmd 305 deny all from 169.254.0.0/16 to any in via $pif #DHCP auto-config $cmd 306 deny all from 192.0.2.0/24 to any in via $pif #reserved for docs $cmd 307 deny all from 204.152.64.0/23 to any in via $pif #Sun cluster $cmd 308 deny all from 224.0.0.0/3 to any in via $pif #Class D & E multicast # Deny ident $cmd 315 deny tcp from any to any 113 in via $pif # Deny all Netbios service. 137=name, 138=datagram, 139=session # Netbios is MS/Windows sharing services. # Block MS/Windows hosts2 name server requests 81 $cmd 320 deny tcp from any to any 137 in via $pif $cmd 321 deny tcp from any to any 138 in via $pif $cmd 322 deny tcp from any to any 139 in via $pif $cmd 323 deny tcp from any to any 81 in via $pif # Deny any late arriving packets $cmd 330 deny all from any to any frag in via $pif # Deny ACK packets that did not match the dynamic rule table $cmd 332 deny tcp from any to any established in via $pif # Allow traffic in from ISP's DHCP server. This rule must contain # the IP address of your ISP's DHCP server as it's the only # authorized source to send this packet type. # Only necessary for cable or DSL configurations. # This rule is not needed for 'user ppp' type connection to # the public Internet. This is the same IP address you captured # and used in the outbound section. $cmd 360 allow udp from x.x.x.x to any 68 in via $pif keep-state # Allow in standard www function because I have Apache server $cmd 370 allow tcp from any to me 80 in via $pif setup limit src-addr 2 # Allow in secure FTP, Telnet, and SCP from public Internet $cmd 380 allow tcp from any to me 22 in via $pif setup limit src-addr 2 # Allow in non-secure Telnet session from public Internet # labeled non-secure because ID & PW are passed over public # Internet as clear text. # Delete this sample group if you do not have telnet server enabled. $cmd 390 allow tcp from any to me 23 in via $pif setup limit src-addr 2 # Reject & Log all unauthorized incoming connections from the public Internet $cmd 400 deny log all from any to any in via $pif # Reject & Log all unauthorized out going connections to the public Internet $cmd 450 deny log all from any to any out via $pif # This is skipto location for outbound stateful rules $cmd 800 divert natd ip from any to any out via $pif $cmd 801 allow ip from any to any # Everything else is denied by default # deny and log all packets that fell through to see what they are $cmd 999 deny log all from any to any ################ End of IPFW rules file ############################### diff --git a/en_US.ISO8859-1/books/handbook/mac/chapter.sgml b/en_US.ISO8859-1/books/handbook/mac/chapter.sgml index db4d32e5e1..ce356dc37d 100644 --- a/en_US.ISO8859-1/books/handbook/mac/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/mac/chapter.sgml @@ -1,2293 +1,2294 @@ Tom Rhodes Written by Mandatory Access Control Synopsis MAC Mandatory Access Control MAC &os; 5.X introduced new security extensions from the TrustedBSD project based on the &posix;.1e draft. Two of the most significant new security mechanisms are file system Access Control Lists (ACLs) and Mandatory Access Control (MAC) facilities. Mandatory Access Control allows new access control modules to be loaded, implementing new security policies. Some provide protections of a narrow subset of the system, hardening a particular service, while others provide comprehensive labeled security across all subjects and objects. The mandatory part of the definition comes from the fact that the enforcement of the controls is done by administrators and the system, and is not left up to the discretion of users as is done with discretionary access control (DAC, the standard file and System V IPC permissions on &os;). This chapter will focus on the Mandatory Access Control Framework (MAC Framework), and a set of pluggable policy modules implementing various security policies. After reading this chapter, you will know: What MAC modules are currently included in &os; and their associated policies. What MAC policy modules implement as well as the difference between a labeled and non-labeled policy. How to efficiently configure a system to use the MAC framework. How to configure the different policies used by the MAC modules. How to implement a more secure environment using the MAC framework and the examples shown. How to test the MAC configuration to ensure the framework has been properly implemented. Before reading this chapter, you should: Understand &unix; and &os; basics (). Be familiar with the basics of kernel configuration/compilation (). Have some familiarity with security and how it pertains to &os; (). The improper use of the information in this chapter may cause loss of access to the system, aggravation of users, or inability to access the features provided by X11. More importantly, MAC should not be relied upon to completely secure a system. The MAC framework only augments existing security policy; without sound security practices and regular security checks, the system will never be completely secure. It should also be noted that the examples contained within this chapter are just that, examples. It is not recommended that these particular settings be rolled out on a production system. Implementing these policies takes a good deal of thought. One who does not fully understand exactly how everything works may find him or herself going back through the entire system and reconfiguring many files or directories. What Will Not Be Covered This chapter covers a broad range of security issues relating to the MAC framework; however, the development of new MAC policies will not be covered. A number of modules included with the MAC framework have specific characteristics which are provided for both testing and new module development. These include the &man.mac.test.4;, &man.mac.stub.4; and &man.mac.none.4; modules/policies. For more information on these modules and the various mechanisms they provide, please review the manual pages. Key Terms in this Chapter Before reading this chapter, a few key terms must be explained. This will hopefully clear up any confusion that may occur and avoid the abrupt introduction of new terms and information. compartment: A compartment is a a set of programs and data to be partitioned or separated, where users are given explicit access to specific components of a system. Also, a compartment represents a grouping, such as a work group, department, project, or topic. Using compartments, it is possible to implement a need-to-know policy. integrity: Integrity, as a key concept, is the level of trust which can be placed on data. As the integrity of the data is elevated, so does the ability to trust that data. label: A label is a security attribute which can be applied to files, directories, or other items in the system. It could be considered to be a confidentiality stamp; when a label is placed on a file it describes the security properties for that specific file and will only permit access by files, users, resources, etc. with a similar security setting. The meaning and interpretation of label values depends on the policy: while some policies might treat a label as representing the integrity or secrecy of an object, other policies might use labels to hold rules for access. level: The increased or decreased setting of a security attribute. As the level increases, its security is considered to elevate as well. multilabel: The property is a file system option which can be set in single user mode using the &man.tunefs.8; utility; set during the boot operation using the &man.fstab.5; file; or during the creation of a new file system. This option will permit an administrator to apply different MAC labels on different objects. This option only applies to labeled policies. object: An object or system object is an entity through which information flows under the direction of a subject. This includes directories, files, fields, screens, keyboards, memory, magnetic storage, printers or any other data storage/moving device. Basically, an object is a data container or a system resource; access to an object effectively means access to the data. policy: A collection of rules which defines how objectives are to be achieved. A policy usually documents how certain items are to be handled. This chapter will consider the term policy in this context as a security policy; i.e. a collection of rules which will control the flow of data and information and define whom will have access to that data and information. sensitivity: Usually used when discussing MLS. A sensitivity level is a term used to describe how important or secret the data should be. As the sensitivity level increases, so does the importance of the secrecy, or confidentiality of the data. single label: A single label is when the entire file system uses one label to enforce access control over the flow of data. When a file system has this set, which is any time when the option is not set, all files will conform to the same label setting. subject: a subject is any active entity that causes information to flow between objects; e.g. a user, user processor, system process, etc. On &os;, this is almost always a thread acting in a process on behalf of a user. Explanation of MAC With all of these new terms in mind, consider how the MAC framework augments the security of the system as a whole. The various security policies provided by the MAC framework could be used to protect the network and file systems, block users from accessing certain ports and sockets, and more. Perhaps the best use of the policies is to blend them together, by loading several security policy modules at a time, for a multi-layered security environment. In a multi-layered security environment, multiple policies are in effect to keep security in check. This is different then a hardening policy, which typically hardens elements of a system that is used only for specific purposes. The only downside is administrative overhead in cases of multiple file system labels, setting network access control user by user, etc. These downsides are minimal when compared to the lasting effect of the framework; for instance, the ability to pick choose which policies are required for a specific configuration keeps performance overhead down. The reduction of support for unneeded policies can increase the overall performance of the system as well as offer flexibility of choice. A good implementation would consider the overall security requirements and effectively implement the various policies offered by the framework. Thus a system utilizing MAC features should at least guarantee that a user will not be permitted to change security attributes at will; all user utilities, programs and scripts must work within the constraints of the access rules provided by the selected policies; and that total control of the MAC access rules are in the hands of the system administrator. It is the sole duty of the system administrator to carefully select the correct policies. Some environments may need to limit access control over the network; in these cases, the &man.mac.portacl.4;, &man.mac.ifoff.4; and even &man.mac.biba.4; policies might make good starting points. In other cases, strict confidentiality of file system objects might be required. Policies such as &man.mac.bsdextended.4; and &man.mac.mls.4; exist for this purpose. Policy decisions could be made based on network configuration. Perhaps only certain users should be permitted access to facilities provided by &man.ssh.1; to access the network or the Internet. The &man.mac.portacl.4; would be the policy of choice for these situations. But what should be done in the case of file systems? Should all access to certain directories be severed from other groups or specific users? Or should we limit user or utility access to specific files by setting certain objects as classified? In the file system case, access to objects might be considered confidential to some users but not to others. For an example, a large development team might be broken off into smaller groups of individuals. Developers in project A might not be permitted to access objects written by developers in project B. Yet they might need to access objects created by developers in project C; that is quite a situation indeed. Using the different policies provided by the MAC framework; users could be divided into these groups and then given access to the appropriate areas without the fear of information leakage. Thus, each policy has a unique way of dealing with the overall security of a system. Policy selection should be based on a well thought out security policy. In many cases, the overall policy may need to be revised and reimplemented on the system. Understanding the different policies offered by the MAC framework will help administrators choose the best policies for their situations. The default &os; kernel does not include the option for the MAC framework; thus the following kernel option must be added before trying any of the examples or information in this chapter: options MAC And the kernel will require a rebuild and a reinstall. While the various manual pages for MAC modules state that they may be built into the kernel, it is possible to lock the system out of the network and more. Implementing MAC is much like implementing a firewall, but care must be taken to prevent being completely locked out of the system. The ability to revert back to a previous configuration should be considered while the implementation of MAC remotely should be done with extreme caution. Understanding MAC Labels A MAC label is a security attribute which may be applied to subjects and objects throughout the system. When setting a label, the user must be able to comprehend what it is, exactly, that is being done. The attributes available on an object depend on the policy loaded, and that policies interpret their attributes in pretty different ways. If improperly configured due to lack of comprehension, or the inability to understand the implications, the result will be the unexpected and perhaps, undesired, behavior of the system. The security label on an object is used as a part of a security access control decision by a policy. With some policies, the label by itself contains all information necessary to make a decision; in other models, the labels may be processed as part of a larger rule set, etc. For instance, setting the label of biba/low on a file will represent a label maintained by the Biba policy, with a value of low. A few policies which support the labeling feature in &os; offers three specific predefined labels. These are the low, high, and equal labels. Although they enforce access control in a different manner with each policy, you can be sure that the low label will be the lowest setting, the equal label will set the subject or object to be disabled or unaffected, and the high label will enforce the highest setting available in the Biba and MLS policies. Within single label file system environments, only one label may be used on objects. This will enforce one set of access permissions across the entire system and in many environments may be all that is required. There are a few cases; however, where multiple labels may be set on objects or subjects in the file system. For those cases, the option may be passed to &man.tunefs.8;. In the case of Biba and MLS, a numeric label may be set to indicate the precise level of hierarchical control. This numeric level is used to partition or sort information into different groups of say, classification only permitting access to that group or a higher group level. In most cases the administrator will only be setting up a single label to use throughout the file system. Hey wait, this is similar to DAC! I thought MAC gave control strictly to the administrator. That statement still holds true, to some extent root is the one in control and who configures the policy so that users are placed in the appropriate categories/access levels. Alas, many policies can restrict the root user as well. Basic control over objects will then be released to the group but root may revoke or modify the settings at any time. This is the hierarchal/clearance model covered by policies such as Biba and MLS. Label Configuration Virtually all aspects of label policy configuration will be performed using the base system utilities. These commands provide a simple interface for object or subject configuration or the manipulation and verification of the configuration. All configuration may be done by use of the &man.setfmac.8; and &man.setpmac.8; utilities. The setfmac command is used to set MAC labels on system objects while the setpmac command is used to set the labels on system subjects. Observe: &prompt.root; setfmac biba/high test If no errors occurred with the command above, a prompt will be returned. The only time these commands are not quiescent is when an error occurred; similarly to the &man.chmod.1; and &man.chown.8; commands. In some cases this error may be a Permission denied and is usually obtained when the label is being set or modified on an object which is restricted.Other conditions may produce different failures. For instance, the file may not be owned by the user attempting to relabel the object, the object may not exist or may be read only. A mandatory policy will not allow the process to relabel the file, maybe because of a property of the file, a property of the process, or a property of the proposed new label value. For example: a user running at low integrity tries to change the label of a high integrity file. Or perhaps a user running at low integrity tries to change the label of a low integrity file to a high integrity label. The system administrator may use the following commands to overcome this: &prompt.root; setfmac biba/high test Permission denied &prompt.root; setpmac biba/low setfmac biba/high test &prompt.root; getfmac test test: biba/high As we see above, setpmac can be used to override the policy's settings by assigning a different label to the invoked process. The getpmac utility is usually used with currently running processes, such as sendmail: although it takes a process ID in place of a command the logic is extremely similar. If users attempt to manipulate a file not in their access, subject to the rules of the loaded policies, the Operation not permitted error will be displayed by the mac_set_link function. Common Label Types For the &man.mac.biba.4;, &man.mac.mls.4; and &man.mac.lomac.4; policy modules, the ability to assign simple labels is provided. These take the form of high, equal and low, what follows is a brief description of what these labels provide: The low label is considered the lowest label setting an object or subject may have. Setting this on objects or subjects will block their access to objects or subjects marked high. The equal label should only be placed on objects considered to be exempt from the policy. The high label grants an object or subject the highest possible setting. With respect to each policy module, each of those settings will instate a different information flow directive. Reading the proper manual pages will further explain the traits of these generic label configurations. Advanced Label Configuration Numeric grade numbers used for comparison:compartment+compartment; thus - the following: + the following: biba/10:2+3+6(5:2+3-20:2+3+4+5+6) May be interpreted as: Biba Policy Label/Grade 10 :Compartments 2, 3 and 6: (grade 5 ...) In this example, the first grade would be considered the effective grade with effective compartments, the second grade is the low grade and the last one is the high grade. In most configurations these settings will not be used; indeed, they offered for more advanced configurations. When applied to system objects, they will only have a current grade/compartments as opposed to system subjects as they reflect the range of available rights in the system, and network interfaces, where they are used for access control. The grade and compartments in a subject and object pair are used to construct a relationship referred to as dominance, in which a subject dominates an object, the object dominates the subject, neither dominates the other, or both dominate each other. The both dominate case occurs when the two labels are equal. Due to the information flow nature of Biba, you have rights to a set of compartments, need to know, that might correspond to projects, but objects also have a set of compartments. Users may have to subset their rights using su or setpmac in order to access objects in a compartment from which they are not restricted. + Users and Label Settings Users themselves are required to have labels so that their files and processes may properly interact with the security policy defined on the system. This is configured through the login.conf file by use of login classes. Every policy that uses labels will implement the user class setting. An example entry containing every policy is listed below: default:\ :copyright=/etc/COPYRIGHT:\ :welcome=/etc/motd:\ :setenv=MAIL=/var/mail/$,BLOCKSIZE=K:\ :path=~/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:\ :manpath=/usr/share/man /usr/local/man:\ :nologin=/usr/sbin/nologin:\ :cputime=1h30m:\ :datasize=8M:\ :vmemoryuse=100M:\ :stacksize=2M:\ :memorylocked=4M:\ :memoryuse=8M:\ :filesize=8M:\ :coredumpsize=8M:\ :openfiles=24:\ :maxproc=32:\ :priority=0:\ :requirehome:\ :passwordtime=91d:\ :umask=022:\ :ignoretime@:\ :label=partition/13,mls/5,biba/10(5-15),lomac10[2]: The label option is used to set the user class default label which will be enforced by MAC. Users will never be permitted to modify this value, thus it can be considered not optional in the user case. In a real configuration, however, the administrator will never wish to enable every policy. It is recommended that the rest of this chapter be reviewed before any of this configuration is implemented. Users may change their label after the initial login; however, this change is subject constraints of the policy. The example above tells the Biba policy that a process's minimum integrity is 5, its maximum is 15, but the default effective label is 10. The process will run at 10 until it chooses to change label, perhaps due to the user using the setpmac command, which will be constrained by Biba to the range set at login. In all cases, after a change to login.conf, the login class capability database must be rebuilt using cap_mkdb and this will be reflected throughout every forthcoming example or discussion. It is useful to note that many sites may have a particularly large number of users requiring several different user classes. In depth planning is required as this may get extremely difficult to manage. Future versions of &os; will include a new way to deal with mapping users to labels; however, this will not be available until some time after &os; 5.3. Network Interfaces and Label Settings Labels may also be set on network interfaces to help control the flow of data across the network. In all cases they function in the same way the policies function with respect to objects. Users at high settings in biba, for example, will not be permitted to access network interfaces with a label of low. The may be passed to ifconfig when setting the MAC label on network interfaces. For example: &prompt.root; ifconfig bge0 maclabel biba/equal will set the MAC label of biba/equal on the &man.bge.4; interface. When using a setting similar to biba/high(low-high) the entire label should be quoted; otherwise an error will be returned. Each policy which supports labeling has some tunable which may be used to disable the MAC label on network interfaces. Setting the label to will have a similar effect. Review the output from sysctl, the policy manual pages, or even the information found later in this chapter for those tunables. Singlelabel or Multilabel? By default the system will use the option. But what does this mean to the administrator? There are several differences which, in their own right, offer pros and cons to the flexibility in the systems security model. The only permits for one label, for instance biba/high to be used for each subject or object. It provides for lower administration overhead but decreases the flexibility of policies which support labeling. Many administrators may want to use the option in their security policy. The option will permit each subject or object to have its own independent MAC label in place of the standard option which will allow only one label throughout the partition. The and label options are only required for the policies which implement the labeling feature, including the Biba, Lomac, MLS and SEBSD policies. In many cases, the may not need to be set at all. Consider the following situation and security model: &os; web-server using the MAC framework and a mix of the various policies. This machine only requires one label, biba/high, for everything in the system. Here the file system would not require the option as a single label will always be in effect. But, this machine will be a web server and should have the web server run at biba/low to prevent write up capabilities. The Biba policy and how it works will be discussed later, so if the previous comment was difficult to interpret just continue reading and return. The server could use a separate partition set at biba/low for most if not all of its runtime state. Much is lacking from this example, for instance the restrictions on data, configuration and user settings; however, this is just a quick example to prove the aforementioned point. If any of the non-labeling policies are to be used, then the option would never be required. These include the seeotheruids, portacl and partition policies. It should also be noted that using with a partition and establishing a security model based on functionality could open the doors for higher administrative overhead as everything in the file system would have a label. This includes directories, files, and even device nodes. The following command will set on the file systems to have multiple labels. This may only be done in single user mode: &prompt.root; tunefs -l enable / This is not a requirement for the swap file system. Some users have experienced problems with setting the flag on the root partition. If this is the case, please review the of this chapter. Controlling MAC with Tunables Without any modules loaded, there are still some parts of MAC which may be configured using the sysctl interface. These tunables are described below and in all cases the number one (1) means enabled while the number zero (0) means disabled: security.mac.enforce_fs defaults to one (1) and enforces MAC file system policies on the file systems. security.mac.enforce_kld defaults to one (1) and enforces MAC kernel linking policies on the dynamic kernel linker (see &man.kld.4;). security.mac.enforce_network defaults to one (1) and enforces MAC network policies. security.mac.enforce_pipe defaults to one (1) and enforces MAC policies on pipes. security.mac.enforce_process defaults to one (1) and enforces MAC policies on processes which utilize inter-process communication. security.mac.enforce_socket defaults to one (1) and enforces MAC policies on sockets (see the &man.socket.2; manual page). security.mac.enforce_system defaults to one (1) and enforces MAC policies on system activities such as accounting and rebooting. security.mac.enforce_vm defaults to one (1) and enforces MAC policies on the virtual memory system. Every policy or MAC option supports tunables. These usually hang off of the security.mac.<policyname> tree. To view all of the tunables from MAC use the following command: &prompt.root; sysctl -da | grep mac This should be interpreted as all of the basic MAC policies are enforced by default. If the modules were built into the kernel the system would be extremely locked down and most likely unable to communicate with the local network or connect to the Internet, etc. This is why building the modules into the kernel is not completely recommended. Not because it limits the ability to disable features on the fly with sysctl, but it permits the administrator to instantly switch the policies of a system without the requirement of rebuilding and reinstalling a new system. Module Configuration Every module included with the MAC framework may be either compiled into the kernel as noted above or loaded as a run-time kernel module. The recommended method is to add the module name to the /boot/loader.conf file so that it will load during the initial boot operation. The following sections will discuss the various MAC modules and cover their features. Implementing them into a specific environment will also be a consideration of this chapter. Some modules support the use of labeling, which is controlling access by enforcing a label such as this is allowed and this is not. A label configuration file may control how files may be accessed, network communication can be exchanged, and more. The previous section showed how the flag could be set on file systems to enable per-file or per-partition access control. A single label configuration would enforce only one label across the system, that is why the tunefs option is called . The MAC seeotheruids Module MAC See Other UIDs Policy Module name: mac_seeotheruids.ko Kernel configuration line: options MAC_SEEOTHERUIDS Boot option: mac_seeotheruids_load="YES" The &man.mac.seeotheruids.4; module mimics and extends the security.bsd.see_other_uids and security.bsd.see_other_gids sysctl tunables. This option does not require any labels to be set before configuration and can operate transparently with the other modules. After loading the module, the following sysctl tunables may be used to control the features: security.mac.seeotheruids.enabled will enable the module's features and use the default settings. These default settings will deny users the ability to view processes and sockets owned by other users. security.mac.seeotheruids.specificgid_enabled will allow a certain group to be exempt from this policy. To exempt specific groups from this policy, use the security.mac.seeotheruids.specificgid=XXX sysctl tunable. In the above example, the XXX should be replaced with the numeric group ID to be exempted. security.mac.seeotheruids.primarygroup_enabled is used to exempt specific primary groups from this policy. When using this tunable, the security.mac.seeotheruids.specificgid_enabled may not be set. It should be noted that the root user is not exempt from this policy. This is one of the large differences between the MAC version and the standard tunable version included by default: security.bsd.seeotheruids. The MAC bsdextended Module MAC File System Firewall Policy Module name: mac_bsdextended.ko Kernel configuration line: options MAC_BSDEXTENDED Boot option: mac_bsdextended_load="YES" The &man.mac.bsdextended.4; module enforces the file system firewall. This module's policy provides an extension to the standard file system permissions model, permitting an administrator to create a firewall-like ruleset to protect files, utilities, and directories in the file system hierarchy. The policy may be created using a utility, &man.ugidfw.8;, that has a syntax similar to that of &man.ipfw.8;. More tools can be written by using the functions in the &man.libugidfw.3; library. Extreme caution should be taken when working with this module; incorrect use could block access to certain parts of the file system. Examples After the &man.mac.bsdextended.4; module has been loaded, the following command may be used to list the current rule configuration: &prompt.root; ugidfw list 0 slots, 0 rules As expected, there are no rules defined. This means that everything is still completely accessible. To create a rule which will block all access by users but leave root unaffected, simply run the following command: &prompt.root; ugidfw add subject not uid root new object not uid root mode n In releases prior to &os; 5.3, the add parameter did not exist. In those cases the set should be used instead. See below for a command example. This is a very bad idea as it will block all users from issuing even the most simple commands, such as ls. A more patriotic list of rules might be: &prompt.root; ugidfw set 2 subject uid user1 object uid user2 mode n &prompt.root; ugidfw set 3 subject uid user1 object gid user2 mode n This will block any and all access, including directory listings, to user2's home directory from the username user1. In place of user1, the could be passed. This will enforce the same access restrictions above for all users in place of just one user. The root user will be unaffected by these changes. This should give a general idea of how the &man.mac.bsdextended.4; module may be used to help fortify a file system. For more information, see the &man.mac.bsdextended.4; and the &man.ugidfw.8; manual pages. The MAC ifoff Module MAC Interface Silencing Policy Module name: mac_ifoff.ko Kernel configuration line: options MAC_IFOFF Boot option: mac_ifoff_load="YES" The &man.mac.ifoff.4; module exists solely to disable network interfaces on the fly and keep network interfaces from being brought up during the initial system boot. It does not require any labels to be set up on the system, nor does it have a dependency on other MAC modules. Most of the control is done through the sysctl tunables listed below. security.mac.ifoff.lo_enabled will enable/disable all traffic on the loopback (&man.lo.4;) interface. security.mac.ifoff.bpfrecv_enabled will enable/disable all traffic on the Berkeley Packet Filter interface (&man.bpf.4;) security.mac.ifoff.other_enabled will enable/disable traffic on all other interfaces. One of the most common uses of &man.mac.ifoff.4; is network monitoring in an environment where network traffic should not be permitted during the boot sequence. Another suggested use would be to write a script which uses security/aide to automatically block network traffic if it finds new or altered files in protected directories. The MAC portacl Module MAC Port Access Control List Policy Module name: mac_portacl.ko Kernel configuration line: MAC_PORTACL Boot option: mac_portacl_load="YES" The &man.mac.portacl.4; module is used to limit binding to local TCP and UDP ports using a variety of sysctl variables. In essence &man.mac.portacl.4; makes it possible to allow non-root users to bind to specified privileged ports, i.e. ports fewer than 1024. Once loaded, this module will enable the MAC policy on all sockets. The following tunables are available: security.mac.portacl.enabled will enable/disable the policy completely.Due to a bug the security.mac.portacl.enabled sysctl variable will not work on &os; 5.2.1 or previous releases. security.mac.portacl.port_high will set the highest port number that &man.mac.portacl.4; will enable protection for. security.mac.portacl.suser_exempt will, when set to a non-zero value, exempt the root user from this policy. security.mac.portacl.rules will specify the actual mac_portacl policy; see below. The actual mac_portacl policy, as specified in the security.mac.portacl.rules sysctl, is a text string of the form: rule[,rule,...] with as many rules as needed. Each rule is of the form: idtype:id:protocol:port. The idtype parameter can be uid or gid and used to interpret the id parameter as either a user id or group id, respectively. The protocol parameter is used to determine if the rule should apply to TCP or UDP by setting the parameter to tcp or udp. The final port parameter is the port number to allow the specified user or group to bind to. Since the ruleset is interpreted directly by the kernel only numeric values can be used for the user ID, group ID, and port parameters. I.e. user, group, and port service names cannot be used. By default, on &unix;-like systems, ports fewer than 1024 can only be used by/bound to privileged processes, i.e. those run as root. For &man.mac.portacl.4; to allow non-privileged processes to bind to ports below 1024 this standard &unix; restriction has to be disabled. This can be accomplished by setting the &man.sysctl.8; variables net.inet.ip.portrange.reservedlow and net.inet.ip.portrange.reservedhigh to zero. See the examples below or review the &man.mac.portacl.4; manual page for further information. Examples The following examples should illuminate the above discussion a little better: &prompt.root; sysctl security.mac.portacl.port_high=1023 &prompt.root; sysctl net.inet.ip.portrange.reservedlow=0 net.inet.ip.portrange.reservedhigh=0 First we set &man.mac.portacl.4; to cover the standard privileged ports and disable the normal &unix; bind restrictions. &prompt.root; sysctl security.mac.portacl.suser_exempt=1 The root user should not be crippled by this policy, thus set the security.mac.portacl.suser_exempt to a non-zero value. The &man.mac.portacl.4; module has now been set up to behave the same way &unix;-like systems behave by default. &prompt.root; sysctl security.mac.portacl.rules=uid:80:tcp:80 Allow the user with UID 80 (normally the www user) to bind to port 80. This can be used to allow the www user to run a web server without ever having root privilege. &prompt.root; sysctl security.mac.portacl.rules=uid:1001:tcp:110,uid:1001:tcp:995 Permit the user with the UID of 1001 to bind to the TCP ports 110 (pop3) and 995 (pop3s). This will permit this user to start a server that accepts connections on ports 110 and 995. MAC Policies with Labeling Features The next few sections will discuss MAC policies which use labels. From here on this chapter will focus on the features of &man.mac.biba.4;, &man.mac.lomac.4;, &man.mac.partition.4;, and &man.mac.mls.4;. This is an example configuration only and should not be considered for a production implementation. The goal is to document and show the syntax as well as examples for implementation and testing. For these policies to work correctly several preparations must be made. Preparation for Labeling Policies The following changes are required in the login.conf file: An insecure class, or another class of similar type, must be added. The login class of insecure is not required and just used as an example here; different configurations may use another class name. The insecure class should have the following settings and definitions. Several of these can be altered but the line which defines the default label is a requirement and must remain. insecure:\ :copyright=/etc/COPYRIGHT:\ :welcome=/etc/motd:\ :setenv=MAIL=/var/mail/$,BLOCKSIZE=K:\ :path=~/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:\ :manpath=/usr/share/man /usr/local/man:\ :nologin=/usr/sbin/nologin:\ :cputime=1h30m:\ :datasize=8M:\ :vmemoryuse=100M:\ :stacksize=2M:\ :memorylocked=4M:\ :memoryuse=8M:\ :filesize=8M:\ :coredumpsize=8M:\ :openfiles=24:\ :maxproc=32:\ :priority=0:\ :requirehome:\ :passwordtime=91d:\ :umask=022:\ :ignoretime@:\ :label=partition/13,mls/5,biba/low: The &man.cap.mkdb.1; command needs to be ran on &man.login.conf.5; before any of the users can be switched over to the new class. The root should also be placed into a login class; otherwise, almost every command executed by root will require the use of setpmac. Rebuilding the login.conf database may cause some errors later with the daemon class. Simply uncommenting the daemon account and rebuilding the database should alleviate these issues. Ensure that all partitions on which MAC labeling will be implemented support the . We must do this because many of the examples here contain different labels for testing purposes. Review the output from the mount command as a precautionary measure. Switch any users who will have the higher security mechanisms enforced over to the new user class. A quick run of &man.pw.8; or &man.vipw.8; should do the trick. The MAC partition Module MAC Process Partition Policy Module name: mac_partition.ko Kernel configuration line: options MAC_PARTITION Boot option: mac_partition_load="YES" The &man.mac.partition.4; policy will drop processes into specific partitions based on their MAC label. Think of it as a special type of &man.jail.8;, though that is hardly a worthy comparison. This is one module that should be added to the &man.loader.conf.5; file so that it loads and enables the policy during the boot process. Most configuration for this policy is done using the &man.setpmac.8; utility which will be explained below. The following sysctl tunable is available for this policy: security.mac.partition.enabled will enable the enforcement of MAC process partitions. When this policy is enabled, users will only be permitted to see their processes but will not be permitted to work with certain utilities. For instance, a user in the insecure class above will not be permitted to access the top command as well as many other commands that must spawn a process. To set or drop utilities into a partition label, use the setpmac utility: &prompt.root; setpmac partition/13 top This will add the top command to the label set on users in the insecure class. Note that all processes spawned by users in the insecure class will stay in the partition/13 label. Examples The following command will show you the partition label and the process list: &prompt.root; ps Zax This next command will allow the viewing of another user's process partition label and that user's currently running processes: &prompt.root; ps -ZU trhodes Users can see processes in root's label unless the &man.mac.seeotheruids.4; policy is loaded. A really crafty implementation could have all of the services disabled in /etc/rc.conf and started by a script that starts them with the proper labeling set. The following policies support integer settings in place of the three default labels offered. These options, including their limitations, are further explained in the module manual pages. The MAC Multi-Level Security Module MAC Multi-Level Security Policy Module name: mac_mls.ko Kernel configuration line: options MAC_MLS Boot option: mac_mls_load="YES" The &man.mac.mls.4; policy controls access between subjects and objects in the system by enforcing a strict information flow policy. In MLS environments, a clearance level is set in each subject or objects label, along with compartments. Since these clearance or sensibility levels can reach numbers greater than six thousand; it would be a daunting task for any system administrator to thoroughly configure each subject or object. Thankfully, three instant labels are already included in this policy. These labels are mls/low, mls/equal and mls/high. Since these labels are described in depth in the manual page, they will only get a brief description here: The mls/low label contains a low configuration which permits it to be dominated by all other objects. Anything labeled with mls/low will have a low clearance level and not be permitted to access information of a higher level. In addition, this label will prevent objects of a higher clearance level from writing or passing information on to them. The mls/equal label should be placed on objects considered to be exempt from the policy. The mls/high label is the highest level of clearance possible. Objects assigned this label will hold dominance over all other objects in the system; however, they will not permit the leaking of information to objects of a lower class. MLS provides for: A hierarchical security level with a set of non hierarchical categories; Fixed rules: no read up, no write down (a subject can have read access to objects on its own level or below, but not above. Similarly, a subject can have write access to objects on its own level or above but not beneath.); Secrecy (preventing inappropriate disclosure of data); Basis for the design of systems that concurrently handle data at multiple sensitivity levels (without leaking information between secret and confidential). The following sysctl tunables are available for the configuration of special services and interfaces: security.mac.mls.enabled is used to enable/disable the MLS policy. security.mac.mls.ptys_equal will label all &man.pty.4; devices as mls/equal during creation. security.mac.mls.revocation_enabled is used to revoke access to objects after their label changes to a label of a lower grade. security.mac.mls.max_compartments is used to set the maximum number of compartment levels with objects; basically the maximum compartment number allowed on a system. To manipulate the MLS labels, the &man.setfmac.8; command has been provided. To assign a label to an object, issue the following command: &prompt.root; setfmac mls/5 test To get the MLS label for the file test issue the following command: &prompt.root; getfmac test This is a summary of the MLS policy's features. Another approach is to create a master policy file in /etc which specifies the MLS policy information and to feed that file into the setfmac command. This method will be explained after all policies are covered. Observations: an object with lower clearance is unable to observe higher clearance processes. A basic policy would be to enforce mls/high on everything not to be read, even if it needs to be written. Enforce mls/low on everything not to be written, even if it needs to be read. And finally enforce mls/equal on the rest. All users marked insecure should be set at mls/low. The MAC Biba Module MAC Biba Integrity Policy Module name: mac_biba.ko Kernel configuration line: options MAC_BIBA Boot option: mac_biba_load="YES" The &man.mac.biba.4; module loads the MAC Biba policy. This policy works much like that of the MLS policy with the exception that the rules for information flow are slightly reversed. This is said to prevent the downward flow of sensitive information whereas the MLS policy prevents the upward flow of sensitive information; thus, much of this section can apply to both policies. In Biba environments, an integrity label is set on each subject or object. These labels are made up of hierarchal grades, and non-hierarchal components. As an object's or subject's grade ascends, so does its integrity. Supported labels are biba/low, biba/equal, and biba/high; as explained below: The biba/low label is considered the lowest integrity an object or subject may have. Setting this on objects or subjects will block their write access to objects or subjects marked high. They still have read access though. The biba/equal label should only be placed on objects considered to be exempt from the policy. The biba/high label will permit writing to objects set at a lower label but not permit reading that object. It is recommended that this label be placed on objects that affect the integrity of the entire system. Biba provides for: Hierarchical integrity level with a set of non hierarchical integrity categories; Fixed rules: no write up, no read down (opposite of MLS). A subject can have write access to objects on its own level or below, but not above. Similarly, a subject can have read access to objects on its own level or above, but not below; Integrity (preventing inappropriate modification of data); Integrity levels (instead of MLS sensitivity levels). The following sysctl tunables can be used to manipulate the Biba policy. security.mac.biba.enabled may be used to enable/disable enforcement of the Biba policy on the target machine. security.mac.biba.ptys_equal may be used to disable the Biba policy on &man.pty.4; devices. security.mac.biba.revocation_enabled will force the revocation of access to objects if the label is changed to dominate the subject. To access the Biba policy setting on system objects, use the setfmac and getfmac commands: &prompt.root; setfmac biba/low test &prompt.root; getfmac test test: biba/low Observations: a lower integrity subject is unable to write to a higher integrity subject; a higher integrity subject cannot observe or read a lower integrity object. The MAC LOMAC Module MAC LOMAC Module name: mac_lomac.ko Kernel configuration line: options MAC_LOMAC Boot option: mac_lomac_load="YES" Unlike the MAC Biba policy, the &man.mac.lomac.4; policy permits access to lower integrity objects only after decreasing the integrity level to not disrupt any integrity rules. The MAC version of the Low-watermark integrity policy, not to be confused with the older &man.lomac.4; implementation, works almost identically to Biba but with the exception of using floating labels to support subject demotion via an auxiliary grade compartment. This secondary compartment takes the form of [auxgrade]. When assigning a lomac policy with an auxiliary grade, it should look a little bit like: lomac/10[2] where the number two (2) is the auxiliary grade. The MAC LOMAC policy relies on the ubiquitous labeling of all system objects with integrity labels, permitting subjects to read from low integrity objects and then downgrading the label on the subject to prevent future writes to high integrity objects. This is the [auxgrade] option discussed above, thus the policy may provide for greater compatibility and require less initial configuration than Biba. Examples Like the Biba and MLS policies; the setfmac and setpmac utilities may be used to place labels on system objects: &prompt.root; setfmac /usr/home/trhodes lomac/high[low] &prompt.root; getfmac /usr/home/trhodes lomac/high[low] Notice the auxiliary grade here is low, this is a feature provided only by the MAC LOMAC policy. Implementing a Secure Environment with MAC MAC Example Implementation The following demonstration will implement a secure environment using various MAC modules with properly configured policies. This is only a test and should not be considered the complete answer to everyone's security woes. Just implementing a policy and ignoring it never works and could be disastrous in a production environment. Before beginning this process, the multilabel option must be set on each file system as stated at the beginning of this chapter. Not doing so will result in errors. Create an insecure User Class Begin the procedure by adding the following user class to the /etc/login.conf file: insecure:\ :copyright=/etc/COPYRIGHT:\ :welcome=/etc/motd:\ :setenv=MAIL=/var/mail/$,BLOCKSIZE=K:\ :path=~/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin :manpath=/usr/share/man /usr/local/man:\ :nologin=/usr/sbin/nologin:\ :cputime=1h30m:\ :datasize=8M:\ :vmemoryuse=100M:\ :stacksize=2M:\ :memorylocked=4M:\ :memoryuse=8M:\ :filesize=8M:\ :coredumpsize=8M:\ :openfiles=24:\ :maxproc=32:\ :priority=0:\ :requirehome:\ :passwordtime=91d:\ :umask=022:\ :ignoretime@:\ :label=partition/13,mls/5: And adding the following line to the default user class: :label=mls/equal,biba/equal,partition/equal: Once this is completed, the following command must be issued to rebuild the database: &prompt.root; cap_mkdb /etc/login.conf Boot with the Correct Modules Add the following lines to /boot/loader.conf so the required modules will load during system initialization: mac_biba_load="YES" mac_mls_load="YES" mac_seeotheruids_load="YES" mac_partition_load="YES" Set All Users to Insecure All user accounts that are not root or system users will now require a login class. The login class is required otherwise users will be refused access to common commands such as &man.vi.1;. The following sh script should do the trick: &prompt.root; for x in `awk -F: '($3 >= 1001) && ($3 != 65534) { print $1 }' \ /etc/passwd`; do pw usermod $x -L insecure; done; The cap_mkdb command will need to be run on /etc/master.passwd after this change. Complete the Configuration A contexts file should now be created; the following example was taken from Robert Watson's example policy and should be placed in /etc/policy.contexts. # This is the default BIBA/MLS policy for this system. .* biba/high,mls/high /sbin/dhclient biba/high(low),mls/high(low) /dev(/.*)? biba/equal,mls/equal # This is not an exhaustive list of all "privileged" devices. /dev/mdctl biba/high,mls/high /dev/pci biba/high,mls/high /dev/k?mem biba/high,mls/high /dev/io biba/high,mls/high /dev/agp.* biba/high,mls/high (/var)?/tmp(/.*)? biba/equal,mls/equal /tmp/\.X11-unix biba/high(equal),mls/high(equal) /tmp/\.X11-unix/.* biba/equal,mls/equal /proc(/.*)? biba/equal,mls/equal /mnt.* biba/low,mls/low (/usr)?/home biba/high(low),mls/high(low) (/usr)?/home/.* biba/low,mls/low /var/mail(/.*)? biba/low,mls/low /var/spool/mqueue(/.*)? biba/low,mls/low (/mnt)?/cdrom(/.*)? biba/high,mls/high (/usr)?/home/(ftp|samba)(/.*)? biba/high,mls/high /var/log/sendmail\.st biba/low,mls/low /var/run/utmp biba/equal,mls/equal /var/log/(lastlog|wtmp) biba/equal,mls/equal This policy will enforce security by setting restrictions on both the downward and upward flow of information with regards to the directories and utilities listed on the left. This can now be read into our system by issuing the following command: &prompt.root; setfsmac -ef /etc/policy.contexts / &prompt.root; setfsmac -ef /etc/policy.contexts /usr The above file system layout may be different depending on environment. The /etc/mac.conf file requires the following modifications in the main section: default_labels file ?biba,?mls default_labels ifnet ?biba,?mls default_labels process ?biba,?mls,?partition default_labels socket ?biba,?mls Testing the Configuration MAC Configuration Testing Add a user with the adduser command and place that user in the insecure class for these tests. The examples below will show a mix of root and regular user tests; use the prompt to distinguish between the two. Basic Labeling Tests &prompt.user; getpmac biba/15(15-15),mls/15(15-15),partition/15 &prompt.root; setpmac partition/15,mls/equal top The top process will be killed before we start another top process. MAC Seeotheruids Tests &prompt.user; ps Zax biba/15(15-15),mls/15(15-15),partition/15 1096 #C: S 0:00.03 -su (bash) biba/15(15-15),mls/15(15-15),partition/15 1101 #C: R+ 0:00.01 ps Zax We should not be permitted to see any processes owned by other users. MAC Partition Test Disable the MAC seeotheruids policy for the rest of these tests: &prompt.root; sysctl security.mac.seeotheruids.enabled=0 &prompt.user; ps Zax LABEL PID TT STAT TIME COMMAND biba/equal(low-high),mls/equal(low-high),partition/15 1122 #C: S+ 0:00.02 top biba/15(15-15),mls/15(15-15),partition/15 1096 #C: S 0:00.05 -su (bash) biba/15(15-15),mls/15(15-15),partition/15 1123 #C: R+ 0:00.01 ps Zax All users should be permitted to see every process in their partition. Testing Biba and MLS Labels &prompt.root; setpmac partition/15,mls/equal,biba/high\(high-high\) top &prompt.user; ps Zax LABEL PID TT STAT TIME COMMAND biba/high(high-high),mls/equal(low-high),partition/15 1251 #C: S+ 0:00.02 top biba/15(15-15),mls/15(15-15),partition/15 1096 #C: S 0:00.06 -su (bash) biba/15(15-15),mls/15(15-15),partition/15 1157 #C: R+ 0:00.00 ps Zax The Biba policy allows us to read higher-labeled objects. &prompt.root; setpmac partition/15,mls/equal,biba/low top &prompt.user; ps Zax LABEL PID TT STAT TIME COMMAND biba/15(15-15),mls/15(15-15),partition/15 1096 #C: S 0:00.07 -su (bash) biba/15(15-15),mls/15(15-15),partition/15 1226 #C: R+ 0:00.01 ps Zax The Biba policy does not allow lower-labeled objects to be read; however, MLS does. &prompt.user; ifconfig bge0 | grep maclabel maclabel biba/low(low-low),mls/low(low-low) &prompt.user; ping -c 1 192.0.34.166 PING 192.0.34.166 (192.0.34.166): 56 data bytes ping: sendto: Permission denied Users are unable to ping example.com, or any domain for that matter. To prevent this error from occurring, run the following command: &prompt.root; sysctl security.mac.biba.trust_all_interfaces=1 This sets the default interface label to insecure mode, so the default Biba policy label will not be enforced. &prompt.root; ifconfig bge0 maclabel biba/equal\(low-high\),mls/equal\(low-high\) &prompt.user; ping -c 1 192.0.34.166 PING 192.0.34.166 (192.0.34.166): 56 data bytes 64 bytes from 192.0.34.166: icmp_seq=0 ttl=50 time=204.455 ms --- 192.0.34.166 ping statistics --- 1 packets transmitted, 1 packets received, 0% packet loss round-trip min/avg/max/stddev = 204.455/204.455/204.455/0.000 ms By setting a more correct label, we can issue ping requests. Now to create a few files for some read and write testing procedures: &prompt.root; touch test1 test2 test3 test4 test5 &prompt.root; getfmac test1 test1: biba/equal,mls/equal &prompt.root; setfmac biba/low test1 test2; setfmac biba/high test4 test5; \ setfmac mls/low test1 test3; setfmac mls/high test2 test4 &prompt.root; setfmac mls/equal,biba/equal test3 && getfmac test? test1: biba/low,mls/low test2: biba/low,mls/high test3: biba/equal,mls/equal test4: biba/high,mls/high test5: biba/high,mls/equal &prompt.root; chown testuser:testuser test? All of these files should now be owned by our testuser user. And now for some read tests: &prompt.user; ls test1 test2 test3 test4 test5 &prompt.user; ls test? ls: test1: Permission denied ls: test2: Permission denied ls: test4: Permission denied test3 test5 We should not be permitted to observe pairs; e.g.: (biba/low,mls/low), (biba/low,mls/high) and (biba/high,mls/high). And of course, read access should be denied. Now for some write tests: &prompt.user; for i in `echo test*`; do echo 1 > $i; done -su: test1: Permission denied -su: test4: Permission denied -su: test5: Permission denied Like with the read tests, write access should not be permitted to write pairs; e.g.: (biba/low,mls/high) and (biba/equal,mls/equal). &prompt.user; cat test? cat: test1: Permission denied cat: test2: Permission denied 1 cat: test4: Permission denied And now as root: &prompt.root; cat test2 1 Another Example: Using MAC to Constrain a Web Server A separate location for the web data which users must be capable of accessing will be appointed. This will permit biba/high processes access rights to the web data. Begin by creating a directory to store the web data in: &prompt.root; mkdir /usr/home/cvs Now initialize it with cvs: &prompt.root; cvs -d /usr/home/cvs init The first goal is to enable the biba policy, thus the mac_biba_enable="YES" should be placed in /boot/loader.conf. This assumes that support for MAC has been enabled in the kernel. From this point on everything in the system should be set at biba/high by default. The following modification must be made to the login.conf file, under the default user class: :ignoretime@:\ :umask=022:\ :label=biba/high: Every user should now be placed in the default class; a command such as: &prompt.root; for x in `awk -F: '($3 >= 1001) && ($3 != 65534) { print $1 }' \ /etc/passwd`; do pw usermod $x -L default; done; will accomplish this task in a few moments. Now create another class, web, a copy of default, with the label setting of biba/low. Create a user who will be used to work with the main web data stored in a cvs repository. This user must be placed in our new login class, web. Since the default is biba/high everywhere, the repository will be the same. The web data must also be the same for users to have read/write access to it; however, since our web server will be serving data that biba/high users must access, we will need to downgrade the data as a whole. The perfect tools for this are &man.sh.1; and &man.cron.8; and are already provided in &os;. The following script should do everything we want: PATH=/bin:/usr/bin:/usr/local/bin; export PATH; CVSROOT=/home/repo; export CVSROOT; cd /home/web; cvs -qR checkout -P htdocs; exit; In many cases the cvs Id tags must be placed into the web site data files. This script may now be placed into web's home directory and the following &man.crontab.1; entry added: # Check out the web data as biba/low every twelve hours: 0 */12 * * * web /home/web/checkout.sh This will check out the HTML sources every twelve hours on the machine. The default startup method for the web server must also be modified to start the process as biba/low. This can be done by making the following modification to the /usr/local/etc/rc.d/apache.sh script: command="setpmac biba/low /usr/local/sbin/httpd" The Apache configuration must be altered to work with the biba/low policy. In this case the software must be configured to append to the log files in a directory set at biba/low or else access denied errors will be returned. Following this example requires that the docroot directive be set to /home/web/htdocs; otherwise, Apache will fail when trying to locate the directory to serve documents from. Other configuration variables must be altered as well, including the PID file, Scoreboardfile, DocumentRoot, log file locations, or any other variable which requires write access. When using biba, all write access will be denied to the server in areas not set at biba/low. Troubleshooting the MAC Framework MAC Troubleshooting During the development stage, a few users reported problems with normal configuration. Some of these problems are listed below: The <option>multilabel</option> option cannot be enabled on <filename>/</filename> The flag does not stay enabled on my root (/) partition! It seems that one out of every fifty users has this problem, indeed, we had this problem during our initial configuration. Further observation of this so called bug has lead me to believe that it is a result of either incorrect documentation or misinterpretation of the documentation. Regardless of why it happened, the following steps may be taken to resolve it: Edit /etc/fstab and set the root partition at for read-only. Reboot into single user mode. Run tunefs on /. Reboot the system into normal mode. Run mount / and change the back to in /etc/fstab and reboot the system again. Double-check the output from the mount to ensure that has been properly set on the root file system. Cannot start a X11 server after <acronym>MAC</acronym> After establishing a secure environment with MAC, I am no longer able to start X! This could be caused by the MAC partition policy or by a mislabeling in one of the MAC labeling policies. To debug, try the following: Check the error message; if the user is in the insecure class, the partition policy may be the culprit. Try setting the user's class back to the default class and rebuild the database with the cap_mkdb command. If this does not alleviate the problem, go to step two. Double-check the label policies. Ensure that the policies are set correctly for the user in question, the X11 application, and the /dev entries. If neither of these resolve the problem, send the error message and a description of your environment to the TrustedBSD discussion lists located at the TrustedBSD website or to the &a.questions; mailing list. Error: &man..secure.path.3; cannot stat <filename>.login_conf</filename> When I attempt to switch from the root to another user in the system, the error message _secure_path: unable to state .login_conf. This message is usually shown when the user has a higher label setting then that of the user whom they are attempting to become. For instance a user on the system, joe, has a default label of . The root user, who has a label of , cannot view joe's home directory. This will happen regardless if root has used the su command to become joe, or not. In this scenario, the Biba integrity model will not permit root to view objects set at a lower integrity level. The <username>root</username> username is broken! In normal or even single user mode, the root is not recognized. The whoami command returns 0 (zero) and su returns who are you?. What could be going on? This can happen if a labeling policy has been disabled, either by a &man.sysctl.8; or the policy module was unloaded. If the policy is being disabled or has been temporarily disabled, then the login capabilities database needs to be reconfigured with the option being removed. Double check the login.conf file to ensure that all options have been removed and rebuild the database with the cap_mkdb command.