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 875b4d6568..55336fb3ab 100644 --- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml @@ -1,4173 +1,4173 @@ 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 informations on manual manipulation of network + 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 Even when FreeBSD is configured in this way, it does not completely comply with the Internet standard requirements for routers. It comes close enough for ordinary use, however. 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 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 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=1 to /etc/sysctl.conf to enable the bridge at runtime, and the line: net.link.ether.bridge_cfg=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 &os; 5.2-RELEASE and later, use instead the following lines: net.link.ether.bridge.enable=1 net.link.ether.bridge.config=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 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/boot/chapter.sgml b/en_US.ISO8859-1/books/handbook/boot/chapter.sgml index 48b9f95806..757036c565 100644 --- a/en_US.ISO8859-1/books/handbook/boot/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/boot/chapter.sgml @@ -1,799 +1,799 @@ The FreeBSD Booting Process Synopsis booting bootstrap The process of starting a computer and loading the operating system is referred to as the bootstrap process, or simply booting. FreeBSD's boot process provides a great deal of flexibility in customizing what happens when you start the system, allowing you to select from different operating systems installed on the same computer, or even different versions of the same operating system or installed kernel. This chapter details the configuration options you can set and how to customize the FreeBSD boot process. This includes everything that happens until the FreeBSD kernel has started, probed for devices, and started &man.init.8;. If you are not quite sure when this happens, it occurs when the text color changes from bright white to grey. After reading this chapter, you will know: What the components of the FreeBSD bootstrap system are, and how they interact. The options you can give to the components in the FreeBSD bootstrap to control the boot process. The basics of &man.device.hints.5;. x86 Only This chapter only describes the boot process for FreeBSD running on Intel x86 systems. The Booting Problem Turning on a computer and starting the operating system poses an interesting dilemma. By definition, the computer does not know how to do anything until the operating system is started. This includes running programs from the disk. So if the computer can not run a program from the disk without the operating system, and the operating system programs are on the disk, how is the operating system started? This problem parallels one in the book The Adventures of Baron Munchausen. A character had fallen part way down a manhole, and pulled himself out by grabbing his bootstraps, and lifting. In the early days of computing the term bootstrap was applied to the mechanism used to load the operating system, which has become shortened to booting. On x86 hardware the Basic Input/Output System (BIOS) is responsible for loading the operating system. To do this, the BIOS looks on the hard disk for the Master Boot Record (MBR), which must be located on a specific place on the disk. The BIOS has enough knowledge to load and run the MBR, and assumes that the MBR can then carry out the rest of the tasks involved in loading the operating system. BIOS Basic Input/Output System If you only have one operating system installed on your disks then the standard MBR will suffice. This MBR searches for the first bootable slice on the disk, and then runs the code on that slice to load the remainder of the operating system. If you have installed multiple operating systems on your disks then you can install a different MBR, one that can display a list of different operating systems, and allows you to choose the one to boot from. FreeBSD comes with one such MBR which can be installed, and other operating system vendors also provide alternative MBRs. The remainder of the FreeBSD bootstrap system is divided into three stages. The first stage is run by the MBR, which knows just enough to get the computer into a specific state and run the second stage. The second stage can do a little bit more, before running the third stage. The third stage finishes the task of loading the operating system. The work is split into these three stages because the PC standards put limits on the size of the programs that can be run at stages one and two. Chaining the tasks together allows FreeBSD to provide a more flexible loader. kernel init The kernel is then started and it begins to probe for devices and initialize them for use. Once the kernel boot process is finished, the kernel passes control to the user process &man.init.8;, which then makes sure the disks are in a usable state. &man.init.8; then starts the user-level resource configuration which mounts file systems, sets up network cards to communicate on the network, and generally starts all the processes that usually are run on a FreeBSD system at startup. The MBR, and Boot Stages One, Two, and Three MBR, <filename>/boot/boot0</filename> Master Boot Record (MBR) The FreeBSD MBR is located in /boot/boot0. This is a copy of the MBR, as the real MBR must be placed on a special part of the disk, outside the FreeBSD area. boot0 is very simple, since the program in the MBR can only be 512 bytes in size. If you have installed the FreeBSD MBR and have installed multiple operating systems on your hard disks then you will see a display similar to this one at boot time: <filename>boot0</filename> Screenshot F1 DOS F2 FreeBSD F3 Linux F4 ?? F5 Drive 1 Default: F2 Other operating systems, in particular &windows; 95, have been known to overwrite an existing MBR with their own. If this happens to you, or you want to replace your existing MBR with the FreeBSD MBR then use the following command: &prompt.root; fdisk -B -b /boot/boot0 device Where device is the device that you boot from, such as ad0 for the first IDE disk, ad2 for the first IDE disk on a second IDE controller, da0 for the first SCSI disk, and so on. If you are a Linux user, however, and prefer that LILO control the boot process, you can edit the /etc/lilo.conf file for FreeBSD, or select during the FreeBSD installation process. If you have installed the FreeBSD boot manager, you can boot back into Linux and modify the LILO configuration file /etc/lilo.conf and add the following option: other=/dev/hdXY table=/dev/hdb loader=/boot/chain.b label=FreeBSD which will permit the booting of FreeBSD and Linux via LILO. In our example, we use XY to determine drive number and partition. If you are using a SCSI drive, you will want to change /dev/hdXY to read something similar to /dev/sdXY, which again uses the XY syntax. The can be omitted if you have both operating systems on the same drive. You can now run /sbin/lilo -v to commit your new changes to the system, this should be verified with screen messages. Stage One, <filename>/boot/boot1</filename>, and Stage Two, <filename>/boot/boot2</filename> Conceptually the first and second stages are part of the same program, on the same area of the disk. Because of space constraints they have been split into two, but you would always install them together. They are found on the boot sector of the boot slice, which is where boot0, or any other program on the MBR expects to find the program to run to continue the boot process. The files in the /boot directory are copies of the real files, which are stored outside of the FreeBSD file system. boot1 is very simple, since it too can only be 512 bytes in size, and knows just enough about the FreeBSD disklabel, which stores information about the slice, to find and execute boot2. boot2 is slightly more sophisticated, and understands the FreeBSD file system enough to find files on it, and can provide a simple interface to choose the kernel or loader to run. Since the loader is much more sophisticated, and provides a nice easy-to-use boot configuration, boot2 usually runs it, but previously it was tasked to run the kernel directly. <filename>boot2</filename> Screenshot >> FreeBSD/i386 BOOT Default: 0:ad(0,a)/kernel boot: If you ever need to replace the installed boot1 and boot2 use &man.disklabel.8;: &prompt.root; disklabel -B diskslice where diskslice is the disk and slice you boot from, such as ad0s1 for the first slice on the first IDE disk. Dangerously Dedicated Mode If you use just the disk name, such as ad0, in the &man.disklabel.8; command you will create a dangerously dedicated disk, without slices. This is almost certainly not what you want to do, so make sure you double check the &man.disklabel.8; command before you press Return. Stage Three, <filename>/boot/loader</filename> boot-loader The loader is the final stage of the three-stage bootstrap, and is located on the file system, usually as /boot/loader. The loader is intended as a user-friendly method for configuration, using an easy-to-use built-in command set, backed up by a more powerful interpreter, with a more complex command set. Loader Program Flow During initialization, the loader will probe for a console and for disks, and figure out what disk it is booting from. It will set variables accordingly, and an interpreter is started where user commands can be passed from a script or interactively. loader loader configuration The loader will then read /boot/loader.rc, which by default reads in /boot/defaults/loader.conf which sets reasonable defaults for variables and reads /boot/loader.conf for local changes to those variables. loader.rc then acts on these variables, loading whichever modules and kernel are selected. Finally, by default, the loader issues a 10 second wait for key presses, and boots the kernel if it is not interrupted. If interrupted, the user is presented with a prompt which understands the easy-to-use command set, where the user may adjust variables, unload all modules, load modules, and then finally boot or reboot. Loader Built-In Commands These are the most commonly used loader commands. For a complete discussion of all available commands, please see &man.loader.8;. autoboot seconds Proceeds to boot the kernel if not interrupted within the time span given, in seconds. It displays a countdown, and the default time span is 10 seconds. boot -options kernelname Immediately proceeds to boot the kernel, with the given options, if any, and with the kernel name given, if it is. boot-conf Goes through the same automatic configuration of modules based on variables as what happens at boot. This only makes sense if you use unload first, and change some variables, most commonly kernel. help topic Shows help messages read from /boot/loader.help. If the topic given is index, then the list of available topics is given. include filename … Processes the file with the given filename. The file is read in, and interpreted line by line. An error immediately stops the include command. load type filename Loads the kernel, kernel module, or file of the type given, with the filename given. Any arguments after filename are passed to the file. ls path Displays a listing of files in the given path, or the root directory, if the path is not specified. If is specified, file sizes will be shown too. lsdev Lists all of the devices from which it may be possible to load modules. If is specified, more details are printed. lsmod Displays loaded modules. If is specified, more details are shown. more filename Displays the files specified, with a pause at each LINES displayed. reboot Immediately reboots the system. set variable set variable=value Sets the loader's environment variables. unload Removes all loaded modules. Loader Examples Here are some practical examples of loader usage: single-user mode To simply boot your usual kernel, but in single-user mode: boot -s To unload your usual kernel and modules, and then load just your old (or another) kernel: kernel.old unload load kernel.old You can use kernel.GENERIC to refer to the generic kernel that comes on the install disk, or kernel.old to refer to your previously installed kernel (when you have upgraded or configured your own kernel, for example). Use the following to load your usual modules with another kernel: unload set kernel="kernel.old" boot-conf To load a kernel configuration script (an automated script which does the things you would normally do in the kernel boot-time configurator): load -t userconfig_script /boot/kernel.conf Kernel Interaction During Boot kernel boot interaction Once the kernel is loaded by either loader (as usual) or boot2 (bypassing the loader), it examines its boot flags, if any, and adjusts its behavior as necessary. kernel bootflags Kernel Boot Flags Here are the more common boot flags: during kernel initialization, ask for the device to mount as the root file system. boot from CDROM. run UserConfig, the boot-time kernel configurator boot into single-user mode be more verbose during kernel startup There are other boot flags, read &man.boot.8; for more information on them. Tom Rhodes Contributed by device.hints Device Hints This is a FreeBSD 5.0 and later feature which does not exist in earlier versions. During initial system startup, the boot &man.loader.8; will read the &man.device.hints.5; file. This file stores kernel boot information known as variables, sometimes referred to as device hints. These device hints are used by device drivers for device configuration. Device hints may also be specified at the Stage 3 boot loader prompt. Variables can be added using set, removed with unset, and viewed with the show commands. Variables set in the /boot/device.hints file can be overridden here also. Device hints entered at the boot loader are not permanent and will be forgotten on the next reboot. Once the system is booted, the &man.kenv.1; command can be used to dump all of the variables. The syntax for the /boot/device.hints file is one variable per line, using the standard hash # as comment markers. Lines are constructed as follows: hint.driver.unit.keyword="value" The syntax for the Stage 3 boot loader is: set hint.driver.unit.keyword=value driver is the device driver name, unit is the device driver unit number, and keyword is the hint keyword. The keyword may consist of the following options: at: specifies the bus which the device is attached to. port: specifies the start address of the I/O to be used. irq: specifies the interrupt request number to be used. drq: specifies the DMA channel number. maddr: specifies the physical memory address occupied by the device. flags: sets various flag bits for the device. disabled: if set to 1 the device is disabled. Device drivers may accept (or require) more hints not listed here, viewing their manual page is recommended. For more information, consult the &man.device.hints.5;, &man.kenv.1;, &man.loader.conf.5;, and &man.loader.8; manual pages. init Init: Process Control Initialization Once the kernel has finished booting, it passes control to the user process &man.init.8;, which is located at /sbin/init, or the program path specified in the init_path variable in loader. Automatic Reboot Sequence The automatic reboot sequence makes sure that the file systems available on the system are consistent. If they are not, and &man.fsck.8; cannot fix the inconsistencies, &man.init.8; drops the system into single-user mode for the system administrator to take care of the problems directly. Single-User Mode single-user mode console This mode can be reached through the automatic reboot sequence, or by the user booting with the option or setting the boot_single variable in loader. It can also be reached by calling &man.shutdown.8; without the reboot () or halt () options, from multi-user mode. If the system console is set to insecure in /etc/ttys, then the system prompts for the root password before initiating single-user mode. An Insecure Console in <filename>/etc/ttys</filename> # name getty type status comments # # If console is marked "insecure", then init will ask for the root password # when going to single-user mode. console none unknown off insecure An insecure console means that you consider your physical security to the console to be insecure, and want to make sure only someone who knows the root password may use single-user mode, and it does not mean that you want to run your console insecurely. Thus, if you want security, choose insecure, not secure. Multi-User Mode multi-user mode If &man.init.8; finds your file systems to be in order, or once the user has finished in single-user mode, the system enters multi-user mode, in which it starts the resource configuration of the system. rc files Resource Configuration (rc) The resource configuration system reads in configuration defaults from /etc/defaults/rc.conf, and system-specific details from /etc/rc.conf, and then proceeds to mount the system file systems mentioned in /etc/fstab, start up networking services, start up miscellaneous system daemons, and finally runs the startup scripts of locally installed packages. The &man.rc.8; manual page is a good reference to the resource configuration system, as is examining the scripts themselves. Shutdown Sequence shutdown Upon controlled shutdown, via &man.shutdown.8;, &man.init.8; will attempt to run the script /etc/rc.shutdown, and then proceed to send all processes the TERM signal, and subsequently the KILL signal to any that do not terminate timely. To power down a FreeBSD machine on architectures and systems that support power management, simply use the command shutdown -p now to turn the power off immediately. To just reboot a FreeBSD system, just use shutdown -r now. You need to be root or a member of operator group to run &man.shutdown.8;. The &man.halt.8; and &man.reboot.8; commands can also be used, please refer to their manual pages and to &man.shutdown.8;'s one - for more informations. + for more information. Power management requires &man.acpi.4; support in the kernel or loaded as module for FreeBSD 5.X and &man.apm.4; support for FreeBSD 4.X. diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml index c6ce089552..0ea5cd7189 100644 --- a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml @@ -1,962 +1,962 @@ Andrey A. Chernov Contributed by Michael C. Wu Rewritten by Localization - I18N/L10N Usage and Setup Synopsis FreeBSD is a very distributed project with users and contributors located all over the world. This chapter discusses the internationalization and localization features of FreeBSD that allow non-English speaking users to get real work done. There are many aspects of the i18n implementation in both the system and application levels, so where applicable we refer the reader to more specific sources of documentation. After reading this chapter, you will know: How different languages and locales are encoded on modern operating systems. How to set the locale for your login shell. How to configure your console for non-English languages. How to use X Window System effectively with different languages. Where to find more information about writing i18n-compliant applications. Before reading this chapter, you should: Know how to install additional third-party applications (). The Basics What Is I18N/L10N? internationalization localization Developers shortened internationalization into the term I18N, counting the number of letters between the first and the last letters of internationalization. L10N uses the same naming scheme, coming from localization. Combined together, I18N/L10N methods, protocols, and applications allow users to use languages of their choice. I18N applications are programmed using I18N kits under libraries. It allows for developers to write a simple file and translate displayed menus and texts to each language. We strongly encourage programmers to follow this convention. Why Should I Use I18N/L10N? I18N/L10N is used whenever you wish to either view, input, or process data in non-English languages. What Languages Are Supported in the I18N Effort? I18N and L10N are not FreeBSD specific. Currently, one can choose from most of the major languages of the World, including but not limited to: Chinese, German, Japanese, Korean, French, Russian, Vietnamese and others. Using Localization In all its splendor, I18N is not FreeBSD-specific and is a convention. We encourage you to help FreeBSD in following this convention. locale Localization settings are based on three main terms: Language Code, Country Code, and Encoding. Locale names are constructed from these parts as follows: LanguageCode_CountryCode.Encoding Language and Country Codes language codes country codes In order to localize a FreeBSD system to a specific language (or any other I18N-supporting &unix; like systems), the user needs to find out the codes for the specify country and language (country codes tell applications what variation of given language to use). In addition, web browsers, SMTP/POP servers, web servers, etc. make decisions based on them. The following are examples of language/country codes: Language/Country Code Description en_US English - United States ru_RU Russian for Russia zh_TW Traditional Chinese for Taiwan Encodings encodings ASCII Some languages use non-ASCII encodings that are 8-bit, wide or multibyte characters, see &man.multibyte.3; for more details. Older applications do not recognize them and mistake them for control characters. Newer applications usually do recognize 8-bit characters. Depending on the implementation, users may be required to compile an application with wide or multibyte characters support, or configure it correctly. To be able to input and process wide or multibyte characters, the FreeBSD Ports collection has provided each language with different programs. Refer to the I18N documentation in the respective FreeBSD Port. Specifically, the user needs to look at the application documentation to decide on how to configure it correctly or to pass correct values into the configure/Makefile/compiler. Some things to keep in mind are: Language specific single C chars character sets (see &man.multibyte.3;), e.g. ISO-8859-1, ISO-8859-15, KOI8-R, CP437. Wide or multibyte encodings, e.g. EUC, Big5. You can check the active list of character sets at the IANA Registry. FreeBSD versions 4.5 and up use X11-compatible locale encodings instead. I18N Applications In the FreeBSD Ports and Package system, I18N applications have been named with I18N in their names for easy identification. However, they do not always support the language needed. Setting Locale Usually it is sufficient to export the value of the locale name as LANG in the login shell. This could be done in the user's ~/.login_conf file or in the startup file of the user's shell (~/.profile, ~/.bashrc, ~/.cshrc). There is no need to set the locale subsets such as LC_CTYPE, LC_CTIME. Please refer to language-specific FreeBSD documentation for more information. You should set the following two environment variables in your configuration files: POSIX LANG for &posix; &man.setlocale.3; family functions MIME MM_CHARSET for applications' MIME character set This includes the user shell configuration, the specific application configuration, and the X11 configuration. Setting Locale Methods locale login class There are two methods for setting locale, and both are described below. The first (recommended one) is by assigning the environment variables in login class, and the second is by adding the environment variable assignments to the system's shell startup file. Login Classes Method This method allows environment variables needed for locale name and MIME character sets to be assigned once for every possible shell instead of adding specific shell assignments to each shell's startup file. User Level Setup can be done by an user himself and Administrator Level Setup require superuser privileges. User Level Setup Here is a minimal example of a .login_conf file in user's home directory which has both variables set for Latin-1 encoding: me:\ :charset=ISO-8859-1:\ :lang=de_DE.ISO8859-1: Traditional ChineseBIG-5 encoding Here is an example of a .login_conf that sets the variables for Traditional Chinese in BIG-5 encoding. Notice the many more variables set because some software does not respect locale variables correctly for Chinese, Japanese, and Korean. #Users who do not wish to use monetary units or time formats #of Taiwan can manually change each variable me:\ :lang=zh_TW.Big5:\ :lc_all=zh_TW.Big:\ :lc_collate=zh_TW.Big5:\ :lc_ctype=zh_TW.Big5:\ :lc_messages=zh_TW.Big5:\ :lc_monetary=zh_TW.Big5:\ :lc_numeric=zh_TW.Big5:\ :lc_time=zh_TW.Big5:\ :charset=big5:\ :xmodifiers="@im=xcin": #Setting the XIM Input Server See Administrator Level Setup and &man.login.conf.5; for more details. Administrator Level Setup Verify that the user's login class in /etc/login.conf sets the correct language. Make sure these settings appear in /etc/login.conf: language_name:accounts_title:\ :charset=MIME_charset:\ :lang=locale_name:\ :tc=default: So sticking with our previous example using Latin-1, it would look like this: german:German Users Accounts:\ :charset=ISO-8859-1:\ :lang=de_DE.ISO8859-1:\ :tc=default: Changing Login Classes with &man.vipw.8; vipw Use vipw to add new users, and make the entry look like this: user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh Changing Login Classes with &man.adduser.8; adduser login class Use adduser to add new users, and do the following: Set defaultclass = language in /etc/adduser.conf. Keep in mind you must enter a default class for all users of other languages in this case. An alternative variant is answering the specified language each time that Enter login class: default []: appears from &man.adduser.8;. Another alternative is to use the following for each user of a different language that you wish to add: &prompt.root; adduser -class language Changing Login Classes with &man.pw.8; pw If you use &man.pw.8; for adding new users, call it in this form: &prompt.root; pw useradd user_name -L language Shell Startup File Method This method is not recommended because it requires a different setup for each possible shell program chosen. Use the Login Class Method instead. MIME locale To add the locale name and MIME character set, just set the two environment variables shown below in the /etc/profile and/or /etc/csh.login shell startup files. We will use the German language as an example below: In /etc/profile: LANG=de_DE.ISO8859-1; export LANG MM_CHARSET=ISO-8859-1; export MM_CHARSET Or in /etc/csh.login: setenv LANG de_DE.ISO8859-1 setenv MM_CHARSET ISO-8859-1 Alternatively, you can add the above instructions to /usr/share/skel/dot.profile (similar to what was used in /etc/profile above), or /usr/share/skel/dot.login (similar to what was used in /etc/csh.login above). For X11: In $HOME/.xinitrc: LANG=de_DE.ISO8859-1; export LANG Or: setenv LANG de_DE.ISO8859-1 Depending on your shell (see above). Console Setup For all single C chars character sets, set the correct console fonts in /etc/rc.conf for the language in question with: font8x16=font_name font8x14=font_name font8x8=font_name The font_name here is taken from the /usr/share/syscons/fonts directory, without the .fnt suffix. sysinstall keymap screenmap Also be sure to set the correct keymap and screenmap for your single C chars character set through /stand/sysinstall. Once inside sysinstall, choose Configure, then Console. Alternatively, you can add the following to /etc/rc.conf: scrnmap=screenmap_name keymap=keymap_name keychange="fkey_number sequence" The screenmap_name here is taken from the /usr/share/syscons/scrnmaps directory, without the .scm suffix. A screenmap with a corresponding mapped font is usually needed as a workaround for expanding bit 8 to bit 9 on a VGA adapter's font character matrix in pseudographics area, i.e., to move letters out of that area if screen font uses a bit 8 column. If you have the moused daemon enabled by setting the following in your /etc/rc.conf: moused_enable="YES" then examine the mouse cursor information in the next paragraph. moused By default the mouse cursor of the &man.syscons.4; driver occupies the 0xd0-0xd3 range in the character set. If your language uses this range, you need to move the cursor's range outside of it. To enable the workaround for FreeBSD versions before 5.0, insert the following line into your kernel configuration: options SC_MOUSE_CHAR=0x03 For FreeBSD versions 4.4 and up insert the following line into /etc/rc.conf: mousechar_start=3 The keymap_name here is taken from the /usr/share/syscons/keymaps directory, without the .kbd suffix. If you're uncertain which keymap to use, you use can &man.kbdmap.1; to test keymaps without rebooting. The keychange is usually needed to program function keys to match the selected terminal type because function key sequences cannot be defined in the key map. Also be sure to set the correct console terminal type in /etc/ttys for all ttyv* entries. Current pre-defined correspondences are: Character Set Terminal Type ISO-8859-1 or ISO-8859-15 cons25l1 ISO-8859-2 cons25l2 ISO-8859-7 cons25l7 KOI8-R cons25r KOI8-U cons25u CP437 (VGA default) cons25 US-ASCII cons25w For wide or multibyte characters languages, use the correct FreeBSD port in your /usr/ports/language directory. Some ports appear as console while the system sees it as serial vtty's, hence you must reserve enough vtty's for both X11 and the pseudo-serial console. Here is a partial list of applications for using other languages in console: Language Location Traditional Chinese (BIG-5) chinese/big5con Japanese japanese/kon2-16dot or japanese/mule-freewnn Korean korean/han X11 Setup Although X11 is not part of the FreeBSD Project, we have included some information here for FreeBSD users. For more details, refer to the &xfree86; web site or whichever X11 Server you use. In ~/.Xresources, you can additionally tune application specific I18N settings (e.g., fonts, menus, etc.). Displaying Fonts X11 True Type font server Install &xorg; server (x11-servers/xorg-server) or &xfree86; server (x11-servers/XFree86-4-Server), then install the language &truetype; fonts. Setting the correct locale should allow you to view your selected language in menus and such. Inputting Non-English Characters X11 Input Method (XIM) The X11 Input Method (XIM) Protocol is a new standard for all X11 clients. All X11 applications should be written as XIM clients that take input from XIM Input servers. There are several XIM servers available for different languages. Printer Setup Some single C chars character sets are usually hardware coded into printers. Wide or multibyte character sets require special setup and we recommend using apsfilter. You may also convert the document to &postscript; or PDF formats using language specific converters. Kernel and File Systems The FreeBSD fast filesystem (FFS) is 8-bit clean, so it can be used with any single C chars character set (see &man.multibyte.3;), but there is no character set name stored in the filesystem; i.e., it is raw 8-bit and does not know anything about encoding order. Officially, FFS does not support any form of wide or multibyte character sets yet. However, some wide or multibyte character sets have independent patches for FFS enabling such support. They are only temporary unportable solutions or hacks and we have decided to not include them in the source tree. Refer to respective languages' web sites for more - informations and the patch files. + information and the patch files. DOS Unicode The FreeBSD &ms-dos; filesystem has the configurable ability to convert between &ms-dos;, Unicode character sets and chosen FreeBSD filesystem character sets. See &man.mount.msdos.8; for details. Compiling I18N Programs Many FreeBSD Ports have been ported with I18N support. Some of them are marked with -I18N in the port name. These and many other programs have built in support for I18N and need no special consideration. MySQL However, some applications such as MySQL need to be have the Makefile configured with the specific charset. This is usually done in the Makefile or done by passing a value to configure in the source. Localizing FreeBSD to Specific Languages Andrey A. Chernov Originally contributed by Russian Language (KOI8-R Encoding) localization Russian For more information about KOI8-R encoding, see the KOI8-R References (Russian Net Character Set). Locale Setup Put the following lines into your ~/.login_conf file: me:My Account:\ :charset=KOI8-R:\ :lang=ru_RU.KOI8-R: See earlier in this chapter for examples of setting up the locale. Console Setup For the FreeBSD versions before 5.0 add the following line to your kernel configuration file: options SC_MOUSE_CHAR=0x03 For FreeBSD versions 4.4 and up insert the following line into /etc/rc.conf: mousechar_start=3 Use following settings in /etc/rc.conf: keymap="ru.koi8-r" scrnmap="koi8-r2cp866" font8x16="cp866b-8x16" font8x14="cp866-8x14" font8x8="cp866-8x8" For each ttyv* entry in /etc/ttys, use cons25r as the terminal type. See earlier in this chapter for examples of setting up the console. Printer Setup printers Since most printers with Russian characters come with hardware code page CP866, a special output filter is needed to convert from KOI8-R to CP866. Such a filter is installed by default as /usr/libexec/lpr/ru/koi2alt. A Russian printer /etc/printcap entry should look like: lp|Russian local line printer:\ :sh:of=/usr/libexec/lpr/ru/koi2alt:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs: See &man.printcap.5; for a detailed description. &ms-dos; FS and Russian Filenames The following example &man.fstab.5; entry enables support for Russian filenames in mounted &ms-dos; filesystems: /dev/ad0s2 /dos/c msdos rw,-Wkoi2dos,-Lru_RU.KOI8-R 0 0 The option selects the locale name used, and sets the character conversion table. To use the option, be sure to mount /usr before the &ms-dos; partition because the conversion tables are located in /usr/libdata/msdosfs. For more - informations, see the &man.mount.msdos.8; manual + information, see the &man.mount.msdos.8; manual page. X11 Setup Do non-X locale setup first as described. The Russian KOI8-R locale may not work with old &xfree86; releases (lower than 3.3). &xfree86; 4.X is now the default version of the X Window System on FreeBSD. This should not be an issue unless you are using an old version of FreeBSD. Go to the russian/X.language directory and issue the following command: &prompt.root; make install The above port installs the latest version of the KOI8-R fonts. &xfree86; 3.3 already has some KOI8-R fonts, but these are scaled better. Check the "Files" section in your /etc/XF86Config file. The following lines must be added before any other FontPath entries: FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc" FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi" FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi" If you use a high resolution video mode, swap the 75 dpi and 100 dpi lines. To activate a Russian keyboard, add the following to the "Keyboard" section of your XF86Config file. For &xfree86; 3.X: XkbLayout "ru" XkbOptions "grp:caps_toggle" For &xfree86; 4.X: Option "XkbLayout" "ru" Option "XkbOptions" "grp:caps_toggle" Also make sure that XkbDisable is turned off (commented out) there. The RUS/LAT switch will be CapsLock. The old CapsLock function is still available via ShiftCapsLock (in LAT mode only). If you have &windows; keys on your keyboard, and notice that some non-alphabetical keys are mapped incorrectly in RUS mode, add the following line in your XF86Config file. For &xfree86; 3.X: XkbVariant "winkeys" For &xfree86; 4.X: Option "XkbVariant" "winkeys" The Russian XKB keyboard may not work with old &xfree86; versions, see the above note for more information. The Russian XKB keyboard may also not work with non-localized applications as well. Minimally localized applications should call a XtSetLanguageProc (NULL, NULL, NULL); function early in the program. See KOI8-R for X Window for more instructions on localizing X11 applications. Traditional Chinese Localization for Taiwan localization Traditional Chinese The FreeBSD-Taiwan Project has an Chinese HOWTO for FreeBSD at using many Chinese ports. Current editor for the FreeBSD Chinese HOWTO is Shen Chuan-Hsing statue@freebsd.sinica.edu.tw. Chuan-Hsing Shen statue@freebsd.sinica.edu.tw has created the Chinese FreeBSD Collection (CFC) using FreeBSD-Taiwan's zh-L10N-tut. The packages and the script files are available at . German Language Localization (for All ISO 8859-1 Languages) localization German Slaven Rezic eserte@cs.tu-berlin.de wrote a tutorial how to use umlauts on a FreeBSD machine. The tutorial is written in German and available at . Japanese and Korean Language Localization localization Japanese localization Korean For Japanese, refer to , and for Korean, refer to . Non-English FreeBSD Documentation Some FreeBSD contributors have translated parts of FreeBSD to other languages. They are available through links on the main site or in /usr/share/doc. diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml index ced90fc016..a0bb3e3bdd 100644 --- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml @@ -1,3349 +1,3349 @@ Jim Mock Restructured and parts updated by Brian N. Handy Originally contributed by Rich Murphey Linux Binary Compatibility Synopsis Linux binary compatibility binary compatibility Linux FreeBSD provides binary compatibility with several other &unix; like operating systems, including Linux. At this point, you may be asking yourself why exactly, does FreeBSD need to be able to run Linux binaries? The answer to that question is quite simple. Many companies and developers develop only for Linux, since it is the latest hot thing in the computing world. That leaves the rest of us FreeBSD users bugging these same companies and developers to put out native FreeBSD versions of their applications. The problem is, that most of these companies do not really realize how many people would use their product if there were FreeBSD versions too, and most continue to only develop for Linux. So what is a FreeBSD user to do? This is where the Linux binary compatibility of FreeBSD comes into play. In a nutshell, the compatibility allows FreeBSD users to run about 90% of all Linux applications without modification. This includes applications such as &staroffice;, the Linux version of &netscape;, &adobe; &acrobat;, RealPlayer, VMware, &oracle;, WordPerfect, Doom, Quake, and more. It is also reported that in some situations, Linux binaries perform better on FreeBSD than they do under Linux. Linux /proc file system There are, however, some Linux-specific operating system features that are not supported under FreeBSD. Linux binaries will not work on FreeBSD if they overly use the Linux /proc file system (which is different from FreeBSD's /proc file system), or &i386; specific calls, such as enabling virtual 8086 mode. After reading this chapter, you will know: How to enable Linux binary compatibility on your system. How to install additional Linux shared libraries. How to install Linux applications on your FreeBSD system. The implementation details of Linux compatibility in FreeBSD. Before reading this chapter, you should: Know how to install additional third-party software (). Installation KLD (kernel loadable object) Linux binary compatibility is not turned on by default. The easiest way to enable this functionality is to load the linux KLD object (Kernel LoaDable object). You can load this module by simply typing linux at the command prompt. If you would like Linux compatibility to always be enabled, then you should add the following line to /etc/rc.conf: linux_enable="YES" The &man.kldstat.8; command can be used to verify that the KLD is loaded: &prompt.user; kldstat Id Refs Address Size Name 1 2 0xc0100000 16bdb8 kernel 7 1 0xc24db000 d000 linux.ko kernel options LINUX If for some reason you do not want to or cannot load the KLD, then you may statically link Linux binary compatibility into the kernel by adding options COMPAT_LINUX to your kernel configuration file. Then install your new kernel as described in . Installing Linux Runtime Libraries Linux installing Linux libraries This can be done one of two ways, either by using the linux_base port, or by installing them manually. Installing Using the linux_base Port ports collection This is by far the easiest method to use when installing the runtime libraries. It is just like installing any other port from the ports collection. Simply do the following: &prompt.root; cd /usr/ports/emulators/linux_base &prompt.root; make install distclean You should now have working Linux binary compatibility. Some programs may complain about incorrect minor versions of the system libraries. In general, however, this does not seem to be a problem. There may be multiple versions of the emulators/linux_base port available, corresponding to different versions of various Linux distributions. You should install the port most closely resembling the requirements of the Linux applications you would like to install. Installing Libraries Manually If you do not have the ports collection installed, you can install the libraries by hand instead. You will need the Linux shared libraries that the program depends on and the runtime linker. Also, you will need to create a shadow root directory, /compat/linux, for Linux libraries on your FreeBSD system. Any shared libraries opened by Linux programs run under FreeBSD will look in this tree first. So, if a Linux program loads, for example, /lib/libc.so, FreeBSD will first try to open /compat/linux/lib/libc.so, and if that does not exist, it will then try /lib/libc.so. Shared libraries should be installed in the shadow tree /compat/linux/lib rather than the paths that the Linux ld.so reports. Generally, you will need to look for the shared libraries that Linux binaries depend on only the first few times that you install a Linux program on your FreeBSD system. After a while, you will have a sufficient set of Linux shared libraries on your system to be able to run newly imported Linux binaries without any extra work. How to Install Additional Shared Libraries shared libraries What if you install the linux_base port and your application still complains about missing shared libraries? How do you know which shared libraries Linux binaries need, and where to get them? Basically, there are 2 possibilities (when following these instructions you will need to be root on your FreeBSD system). If you have access to a Linux system, see what shared libraries the application needs, and copy them to your FreeBSD system. Look at the following example: Let us assume you used FTP to get the Linux binary of Doom, and put it on a Linux system you have access to. You then can check which shared libraries it needs by running ldd linuxdoom, like so: &prompt.user; ldd linuxdoom libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 symbolic links You would need to get all the files from the last column, and put them under /compat/linux, with the names in the first column as symbolic links pointing to them. This means you eventually have these files on your FreeBSD system: /compat/linux/usr/X11/lib/libXt.so.3.1.0 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
Note that if you already have a Linux shared library with a matching major revision number to the first column of the ldd output, you will not need to copy the file named in the last column to your system, the one you already have should work. It is advisable to copy the shared library anyway if it is a newer version, though. You can remove the old one, as long as you make the symbolic link point to the new one. So, if you have these libraries on your system: /compat/linux/lib/libc.so.4.6.27 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27 and you find a new binary that claims to require a later version according to the output of ldd: libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29 If it is only one or two versions out of date in the in the trailing digit then do not worry about copying /lib/libc.so.4.6.29 too, because the program should work fine with the slightly older version. However, if you like, you can decide to replace the libc.so anyway, and that should leave you with: /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
The symbolic link mechanism is only needed for Linux binaries. The FreeBSD runtime linker takes care of looking for matching major revision numbers itself and you do not need to worry about it.
Installing Linux ELF Binaries Linux ELF binaries ELF binaries sometimes require an extra step of branding. If you attempt to run an unbranded ELF binary, you will get an error message like the following: &prompt.user; ./my-linux-elf-binary ELF binary type not known Abort To help the FreeBSD kernel distinguish between a FreeBSD ELF binary from a Linux binary, use the &man.brandelf.1; utility. &prompt.user; brandelf -t Linux my-linux-elf-binary GNU toolchain The GNU toolchain now places the appropriate branding information into ELF binaries automatically, so this step should become increasingly unnecessary in the future. Configuring the Hostname Resolver If DNS does not work or you get this message: resolv+: "bind" is an invalid keyword resolv+: "hosts" is an invalid keyword You will need to configure a /compat/linux/etc/host.conf file containing: order hosts, bind multi on The order here specifies that /etc/hosts is searched first and DNS is searched second. When /compat/linux/etc/host.conf is not installed, Linux applications find FreeBSD's /etc/host.conf and complain about the incompatible FreeBSD syntax. You should remove bind if you have not configured a name server using the /etc/resolv.conf file. Murray Stokely Updated for Mathematica 4.X by Bojan Bistrovic Merged with work by Installing &mathematica; applications Mathematica This document describes the process of installing the Linux version of &mathematica; 4.X onto a FreeBSD system. The Linux version of &mathematica; runs perfectly under FreeBSD however the binaries shipped by Wolfram need to be branded so that FreeBSD knows to use the Linux ABI to execute them. The Linux version of &mathematica; or &mathematica; for Students can be ordered directly from Wolfram at . Branding the Linux Binaries The Linux binaries are located in the Unix directory of the &mathematica; CDROM distributed by Wolfram. You need to copy this directory tree to your local hard drive so that you can brand the Linux binaries with &man.brandelf.1; before running the installer: &prompt.root; mount /cdrom &prompt.root; cp -rp /cdrom/Unix/ /localdir/ &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm &prompt.root; cd /localdir/Installers/Linux/ &prompt.root; ./MathInstaller Alternatively, you can simply set the default ELF brand to Linux for all unbranded binaries with the command: &prompt.root; sysctl kern.fallback_elf_brand=3 This will make FreeBSD assume that unbranded ELF binaries use the Linux ABI and so you should be able to run the installer straight from the CDROM. Obtaining Your &mathematica; Password Before you can run &mathematica; you will have to obtain a password from Wolfram that corresponds to your machine ID. Ethernet MAC address Once you have installed the Linux compatibility runtime libraries and unpacked &mathematica; you can obtain the machine ID by running the program mathinfo in the installation directory. This machine ID is based solely on the MAC address of your first Ethernet card. &prompt.root; cd /localdir/Files/SystemFiles/Installation/Binaries/Linux &prompt.root; mathinfo disco.example.com 7115-70839-20412 When you register with Wolfram, either by email, phone or fax, you will give them the machine ID and they will respond with a corresponding password consisting of groups of numbers. You can then enter this information when you attempt to run &mathematica; for the first time exactly as you would for any other &mathematica; platform. Running the &mathematica; Frontend over a Network &mathematica; uses some special fonts to display characters not present in any of the standard font sets (integrals, sums, Greek letters, etc.). The X protocol requires these fonts to be install locally. This means you will have to copy these fonts from the CDROM or from a host with &mathematica; installed to your local machine. These fonts are normally stored in /cdrom/Unix/Files/SystemFiles/Fonts on the CDROM, or /usr/local/mathematica/SystemFiles/Fonts on your hard drive. The actual fonts are in the subdirectories Type1 and X. There are several ways to use them, as described below. The first way is to copy them into one of the existing font directories in /usr/X11R6/lib/X11/fonts. This will require editing the fonts.dir file, adding the font names to it, and changing the number of fonts on the first line. Alternatively, you should also just be able to run &man.mkfontdir.1; in the directory you have copied them to. The second way to do this is to copy the directories to /usr/X11R6/lib/X11/fonts: &prompt.root; cd /usr/X11R6/lib/X11/fonts &prompt.root; mkdir X &prompt.root; mkdir MathType1 &prompt.root; cd /cdrom/Unix/Files/SystemFiles/Fonts &prompt.root; cp X/* /usr/X11R6/lib/X11/fonts/X &prompt.root; cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1 &prompt.root; cd /usr/X11R6/lib/X11/fonts/X &prompt.root; mkfontdir &prompt.root; cd ../MathType1 &prompt.root; mkfontdir Now add the new font directories to your font path: &prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/X &prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/MathType1 &prompt.root; xset fp rehash If you are using the &xfree86; server, you can have these font directories loaded automatically by adding them to your XF86Config file. fonts If you do not already have a directory called /usr/X11R6/lib/X11/fonts/Type1, you can change the name of the MathType1 directory in the example above to Type1. Aaron Kaplan Contributed by Robert Getschmann Thanks to Installing &maple; applications Maple &maple; is a commercial mathematics program similar to &mathematica;. You must purchase this software from and then register there for a license file. To install this software on FreeBSD, please follow these simple steps. Execute the INSTALL shell script from the product distribution. Choose the RedHat option when prompted by the installation program. A typical installation directory might be /usr/local/maple. If you have not done so, order a license for &maple; from Maple Waterloo Software () and copy it to /usr/local/maple/license/license.dat. Install the FLEXlm license manager by running the INSTALL_LIC install shell script that comes with &maple;. Specify the primary hostname for your machine for the license server. Patch the /usr/local/maple/bin/maple.system.type file with the following: ----- snip ------------------ *** maple.system.type.orig Sun Jul 8 16:35:33 2001 --- maple.system.type Sun Jul 8 16:35:51 2001 *************** *** 72,77 **** --- 72,78 ---- # the IBM RS/6000 AIX case MAPLE_BIN="bin.IBM_RISC_UNIX" ;; + "FreeBSD"|\ "Linux") # the Linux/x86 case # We have two Linux implementations, one for Red Hat and ----- snip end of patch ----- Please note that after the "FreeBSD"|\ no other whitespace should be present. This patch instructs &maple; to recognize FreeBSD as a type of Linux system. The bin/maple shell script calls the bin/maple.system.type shell script which in turn calls uname -a to find out the operating system name. Depending on the OS name it will find out which binaries to use. Start the license server. The following script, installed as /usr/local/etc/rc.d/lmgrd.sh is a convenient way to start up lmgrd: ----- snip ------------ #! /bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX export PATH LICENSE_FILE=/usr/local/maple/license/license.dat LOG=/var/log/lmgrd.log case "$1" in start) lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2 echo -n " lmgrd" ;; stop) lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2 ;; *) echo "Usage: `basename $0` {start|stop}" 1>&2 exit 64 ;; esac exit 0 ----- snip ------------ Test-start &maple;: &prompt.user; cd /usr/local/maple/bin &prompt.user; ./xmaple You should be up and running. Make sure to write Maplesoft to let them know you would like a native FreeBSD version! Common Pitfalls The FLEXlm license manager can be a difficult tool to work with. Additional documentation on the subject can be found at . lmgrd is known to be very picky about the license file and to core dump if there are any problems. A correct license file should look like this: # ======================================================= # License File for UNIX Installations ("Pointer File") # ======================================================= SERVER chillig ANY #USE_SERVER VENDOR maplelmg FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \ PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \ ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \ SN=XXXXXXXXX Serial number and key 'X''ed out. chillig is a hostname. Editing the license file works as long as you do not touch the FEATURE line (which is protected by the license key). Dan Pelleg Contributed by Installing &matlab; applications MATLAB This document describes the process of installing the Linux version of &matlab; version 6.5 onto a &os; system. It works quite well, with the exception of the &java.virtual.machine; (see ). The Linux version of &matlab; can be ordered directly from The MathWorks at . Make sure you also get the license file or instructions how to create it. While you are there, let them know you would like a native &os; version of their software. Installing &matlab; To install &matlab;, do the following: Insert the installation CD and mount it. Become root, as recommended by the installation script. To start the installation script type: &prompt.root; /compat/linux/bin/sh /cdrom/install The installer is graphical. If you get errors about not being able to open a display, type setenv HOME ~USER, where USER is the user you did a &man.su.1; as. When asked for the &matlab; root directory, type: /compat/linux/usr/local/matlab. For easier typing on the rest of the installation process, type this at your shell prompt: set MATLAB=/compat/linux/usr/local/matlab Edit the license file as instructed when obtaining the &matlab; license. You can prepare this file in advance using your favorite editor, and copy it to $MATLAB/license.dat before the installer asks you to edit it. Complete the installation process. At this point your &matlab; installation is complete. The following steps apply glue to connect it to your &os; system. License Manager Startup Create symlinks for the license manager scripts: &prompt.root; ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW &prompt.root; ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW Create a startup file at /usr/local/etc/rc.d/flexlm.sh. The example below is a modified version of the distributed $MATLAB/etc/rc.lm.glnx86. The changes are file locations, and startup of the license manager under Linux emulation. #!/bin/sh case "$1" in start) if [ -f /usr/local/etc/lmboot_TMW ]; then /compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u username && echo 'MATLAB_lmgrd' fi ;; stop) if [ -f /usr/local/etc/lmdown_TMW ]; then /compat/linux/bin/sh /usr/local/etc/lmdown_TMW > /dev/null 2>&1 fi ;; *) echo "Usage: $0 {start|stop}" exit 1 ;; esac exit 0 The file must be made executable: &prompt.root; chmod +x /usr/local/etc/rc.d/flexlm.sh You must also replace username above with the name of a valid user on your system (and not root). Start the license manager with the command: &prompt.root; /usr/local/etc/rc.d/flexlm.sh start Linking the &java; Runtime Environment Change the &java; Runtime Environment (JRE) link to one working under &os;: &prompt.root; cd $MATLAB/sys/java/jre/glnx86/ &prompt.root; unlink jre; ln -s ./jre1.1.8 ./jre Creating a &matlab; Startup Script Place the following startup script in /usr/local/bin/matlab: #!/bin/sh /compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@" Then type the command chmod +x /usr/local/bin/matlab. Depending on your version of emulators/linux_base, you may run into errors when running this script. To avoid that, edit the file /compat/linux/usr/local/matlab/bin/matlab, and change the line that says: if [ `expr "$lscmd" : '.*->.*'` -ne 0 ]; then (in version 13.0.1 it is on line 410) to this line: if test -L $newbase; then Creating a &matlab; Shutdown Script The following is needed to solve a problem with &matlab; not exiting correctly. Create a file $MATLAB/toolbox/local/finish.m, and in it put the single line: ! $MATLAB/bin/finish.sh The $MATLAB is literal. In the same directory, you will find the files finishsav.m and finishdlg.m, which let you save your workspace before quitting. If you use either of them, insert the line above immediately after the save command. Create a file $MATLAB/bin/finish.sh, which will contain the following: #!/usr/compat/linux/bin/sh (sleep 5; killall -1 matlab_helper) & exit 0 Make the file executable: &prompt.root; chmod +x $MATLAB/bin/finish.sh Using &matlab; At this point you are ready to type matlab and start using it. Marcel Moolenaar Contributed by Installing &oracle; applications Oracle Preface This document describes the process of installing &oracle; 8.0.5 and &oracle; 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD machine. Installing the Linux Environment Make sure you have both emulators/linux_base and devel/linux_devtools from the ports collection installed. If you run into difficulties with these ports, you may have to use the packages or older versions available in the ports collection. If you want to run the intelligent agent, you will also need to install the Red Hat Tcl package: tcl-8.0.3-20.i386.rpm. The general command for installing packages with the official RPM port (archivers/rpm) is: &prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm package Installation of the package should not generate any errors. Creating the &oracle; Environment Before you can install &oracle;, you need to set up a proper environment. This document only describes what to do specially to run &oracle; for Linux on FreeBSD, not what has been described in the &oracle; installation guide. Kernel Tuning kernel tuning As described in the &oracle; installation guide, you need to set the maximum size of shared memory. Do not use SHMMAX under FreeBSD. SHMMAX is merely calculated out of SHMMAXPGS and PGSIZE. Therefore define SHMMAXPGS. All other options can be used as described in the guide. For example: options SHMMAXPGS=10000 options SHMMNI=100 options SHMSEG=10 options SEMMNS=200 options SEMMNI=70 options SEMMSL=61 Set these options to suit your intended use of &oracle;. Also, make sure you have the following options in your kernel configuration file: options SYSVSHM #SysV shared memory options SYSVSEM #SysV semaphores options SYSVMSG #SysV interprocess communication &oracle; Account Create an oracle account just as you would create any other account. The oracle account is special only that you need to give it a Linux shell. Add /compat/linux/bin/bash to /etc/shells and set the shell for the oracle account to /compat/linux/bin/bash. Environment Besides the normal &oracle; variables, such as ORACLE_HOME and ORACLE_SID you must set the following environment variables: Variable Value LD_LIBRARY_PATH $ORACLE_HOME/lib CLASSPATH $ORACLE_HOME/jdbc/lib/classes111.zip PATH /compat/linux/bin /compat/linux/sbin /compat/linux/usr/bin /compat/linux/usr/sbin /bin /sbin /usr/bin /usr/sbin /usr/local/bin $ORACLE_HOME/bin It is advised to set all the environment variables in .profile. A complete example is: ORACLE_BASE=/oracle; export ORACLE_BASE ORACLE_HOME=/oracle; export ORACLE_HOME LD_LIBRARY_PATH=$ORACLE_HOME/lib export LD_LIBRARY_PATH ORACLE_SID=ORCL; export ORACLE_SID ORACLE_TERM=386x; export ORACLE_TERM CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip export CLASSPATH PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin export PATH Installing &oracle; Due to a slight inconsistency in the Linux emulator, you need to create a directory named .oracle in /var/tmp before you start the installer. Either make it world writable or let it be owned by the oracle user. You should be able to install &oracle; without any problems. If you have problems, check your &oracle; distribution and/or configuration first! After you have installed &oracle;, apply the patches described in the next two subsections. A frequent problem is that the TCP protocol adapter is not installed right. As a consequence, you cannot start any TCP listeners. The following actions help solve this problem: &prompt.root; cd $ORACLE_HOME/network/lib &prompt.root; make -f ins_network.mk ntcontab.o &prompt.root; cd $ORACLE_HOME/lib &prompt.root; ar r libnetwork.a ntcontab.o &prompt.root; cd $ORACLE_HOME/network/lib &prompt.root; make -f ins_network.mk install Do not forget to run root.sh again! Patching root.sh When installing &oracle;, some actions, which need to be performed as root, are recorded in a shell script called root.sh. This script is written in the orainst directory. Apply the following patch to root.sh, to have it use to proper location of chown or alternatively run the script under a Linux native shell. *** orainst/root.sh.orig Tue Oct 6 21:57:33 1998 --- orainst/root.sh Mon Dec 28 15:58:53 1998 *************** *** 31,37 **** # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h ! CHOWN=/bin/chown # # Define variables to be used in this script --- 31,37 ---- # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h ! CHOWN=/usr/sbin/chown # # Define variables to be used in this script When you do not install &oracle; from CD, you can patch the source for root.sh. It is called rthd.sh and is located in the orainst directory in the source tree. Patching genclntsh The script genclntsh is used to create a single shared client library. It is used when building the demos. Apply the following patch to comment out the definition of PATH: *** bin/genclntsh.orig Wed Sep 30 07:37:19 1998 --- bin/genclntsh Tue Dec 22 15:36:49 1998 *************** *** 32,38 **** # # Explicit path to ensure that we're using the correct commands #PATH=/usr/bin:/usr/ccs/bin export PATH ! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH # # each product MUST provide a $PRODUCT/admin/shrept.lst --- 32,38 ---- # # Explicit path to ensure that we're using the correct commands #PATH=/usr/bin:/usr/ccs/bin export PATH ! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH # # each product MUST provide a $PRODUCT/admin/shrept.lst Running &oracle; When you have followed the instructions, you should be able to run &oracle; as if it was run on Linux itself. Holger Kipp Contributed by Valentino Vaschetto Original version converted to SGML by Installing &sap.r3; applications SAP R/3 Installations of &sap; Systems using FreeBSD will not be supported by the &sap; support team — they only offer support for certified platforms. Preface This document describes a possible way of installing a &sap.r3; System with &oracle; Database for Linux onto a FreeBSD machine, including the installation of FreeBSD and &oracle;. Two different configurations will be described: &sap.r3; 4.6B (IDES) with &oracle; 8.0.5 on FreeBSD 4.3-STABLE &sap.r3; 4.6C with &oracle; 8.1.7 on FreeBSD 4.5-STABLE Even though this document tries to describe all important steps in a greater detail, it is not intended as a replacement for the &oracle; and &sap.r3; installation guides. Please see the documentation that comes with the &sap.r3; Linux edition for &sap; and &oracle; specific questions, as well as resources from &oracle; and &sap; OSS. Software The following CD-ROMs have been used for &sap; installations: &sap.r3; 4.6B, &oracle; 8.0.5 Name Number Description KERNEL 51009113 SAP Kernel Oracle / Installation / AIX, Linux, Solaris RDBMS 51007558 Oracle / RDBMS 8.0.5.X / Linux EXPORT1 51010208 IDES / DB-Export / Disc 1 of 6 EXPORT2 51010209 IDES / DB-Export / Disc 2 of 6 EXPORT3 51010210 IDES / DB-Export / Disc 3 of 6 EXPORT4 51010211 IDES / DB-Export / Disc 4 of 6 EXPORT5 51010212 IDES / DB-Export / Disc 5 of 6 EXPORT6 51010213 IDES / DB-Export / Disc 6 of 6 Additionally, we used the &oracle; 8 Server (Pre-production version 8.0.5 for Linux, Kernel Version 2.0.33) CD which is not really necessary, and FreeBSD 4.3-STABLE (it was only a few days past 4.3 RELEASE). &sap.r3; 4.6C SR2, &oracle; 8.1.7 Name Number Description KERNEL 51014004 SAP Kernel Oracle / SAP Kernel Version 4.6D / DEC, Linux RDBMS 51012930 Oracle 8.1.7/ RDBMS / Linux EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 1 of 4 EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 2 of 4 EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 3 of 4 EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 4 of 4 LANG1 51013954 Release 4.6C SR2 / Language / DE, EN, FR / Disc 1 of 3 Depending on the languages you would like to install, additional language CDs might be necessary. Here we are just using DE and EN, so the first language CD is the only one needed. As a little note, the numbers for all four EXPORT CDs are identical. All three language CDs also have the same number (this is different from the 4.6B IDES release CD numbering). At the time of writing this installation is running on FreeBSD 4.5-STABLE (20.03.2002). &sap; Notes The following notes should be read before installing &sap.r3; and proved to be useful during installation: &sap.r3; 4.6B, &oracle; 8.0.5 Number Title 0171356 SAP Software on Linux: Essential Comments 0201147 INST: 4.6C R/3 Inst. on UNIX - Oracle 0373203 Update / Migration Oracle 8.0.5 --> 8.0.6/8.1.6 LINUX 0072984 Release of Digital UNIX 4.0B for Oracle 0130581 R3SETUP step DIPGNTAB terminates 0144978 Your system has not been installed correctly 0162266 Questions and tips for R3SETUP on Windows NT / W2K &sap.r3; 4.6C, &oracle; 8.1.7 Number Title 0015023 Initializing table TCPDB (RSXP0004) (EBCDIC) 0045619 R/3 with several languages or typefaces 0171356 SAP Software on Linux: Essential Comments 0195603 RedHat 6.1 Enterprise version: Known problems 0212876 The new archiving tool SAPCAR 0300900 Linux: Released DELL Hardware 0377187 RedHat 6.2: important remarks 0387074 INST: R/3 4.6C SR2 Installation on UNIX 0387077 INST: R/3 4.6C SR2 Inst. on UNIX - Oracle 0387078 SAP Software on UNIX: OS Dependencies 4.6C SR2 Hardware Requirements The following equipment is sufficient for the installation of a &sap.r3; System. For production use, a more exact sizing is of course needed: Component 4.6B 4.6C Processor 2 x 800MHz &pentium; III 2 x 800MHz &pentium; III Memory 1GB ECC 2GB ECC Hard Disk Space 50-60GB (IDES) 50-60GB (IDES) For use in production, &xeon; Processors with large cache, high-speed disk access (SCSI, RAID hardware controller), USV and ECC-RAM is recommended. The large amount of hard disk space is due to the preconfigured IDES System, which creates 27 GB of database files during installation. This space is also sufficient for initial production systems and application data. &sap.r3; 4.6B, &oracle; 8.0.5 The following off-the-shelf hardware was used: a dual processor board with 2 800 MHz &pentium; III processors, &adaptec; 29160 Ultra160 SCSI adapter (for accessing a 40/80 GB DLT tape drive and CDROM), &mylex; &acceleraid; (2 channels, firmware 6.00-1-00 with 32 MB RAM). To the &mylex; RAID controller are attached two 17 GB hard disks (mirrored) and four 36 GB hard disks (RAID level 5). &sap.r3; 4.6C, &oracle; 8.1.7 For this installation a &dell; &poweredge; 2500 was used: a dual processor board with two 1000 MHz &pentium; III processors (256 kB Cache), 2 GB PC133 ECC SDRAM, PERC/3 DC PCI RAID Controller with 128 MB, and an EIDE DVD-ROM drive. To the RAID controller are attached two 18 GB hard disks (mirrored) and four 36 GB hard disks (RAID level 5). Installation of FreeBSD First you have to install FreeBSD. There are several ways to do this (FreeBSD 4.3 was installed via FTP, FreeBSD 4.5 directly from - the RELEASE CD) for more informations read the . Disk Layout To keep it simple, the same disk layout both for the &sap.r3; 46B and &sap.r3; 46C SR2 installation was used. Only the device names changed, as the installations were on different hardware (/dev/da and /dev/amr respectively, so if using an AMI &megaraid;, one will see /dev/amr0s1a instead of /dev/da0s1a): File system Size (1k-blocks) Size (GB) Mounted on /dev/da0s1a 1.016.303 1 / /dev/da0s1b 6 swap /dev/da0s1e 2.032.623 2 /var /dev/da0s1f 8.205.339 8 /usr /dev/da1s1e 45.734.361 45 /compat/linux/oracle /dev/da1s1f 2.032.623 2 /compat/linux/sapmnt /dev/da1s1g 2.032.623 2 /compat/linux/usr/sap Configure and initialize the two logical drives with the &mylex; or PERC/3 RAID software beforehand. The software can be started during the BIOS boot phase. Please note that this disk layout differs slightly from the &sap; recommendations, as &sap; suggests mounting the &oracle; subdirectories (and some others) separately — we decided to just create them as real subdirectories for simplicity. <command>make world</command> and a New Kernel Download the latest -STABLE sources. Rebuild world and your custom kernel after configuring your kernel configuration file. Here you should also include the kernel parameters which are required for both &sap.r3; and &oracle;. Installing the Linux Environment Installing the Linux Base System First the linux_base port needs to be installed (as root): &prompt.root; cd /usr/ports/emulators/linux_base &prompt.root; make install distclean Installing Linux Development Environment The Linux development environment is needed, if you want to install &oracle; on FreeBSD according to the : &prompt.root; cd /usr/ports/devel/linux_devtools &prompt.root; make install distclean The Linux development environment has only been installed for the &sap.r3; 46B IDES installation. It is not needed, if the &oracle; DB is not relinked on the FreeBSD system. This is the case if you are using the &oracle; tarball from a Linux system. Installing the Necessary RPMs RPMs To start the R3SETUP program, PAM support is needed. During the first &sap; Installation on FreeBSD 4.3-STABLE we tried to install PAM with all the required packages and finally forced the installation of the PAM package, which worked. For &sap.r3; 4.6C SR2 we directly forced the installation of the PAM RPM, which also works, so it seems the dependent packages are not needed: &prompt.root; rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm \ pam-0.68-7.i386.rpm For &oracle; 8.0.5 to run the intelligent agent, we also had to install the RedHat Tcl package tcl-8.0.5-30.i386.rpm (otherwise the relinking during &oracle; installation will not work). There are some other issues regarding relinking of &oracle;, but that is a &oracle; Linux issue, not FreeBSD specific. Some Additional Hints It might also be a good idea to add linprocfs - to /etc/fstab, for more informations, see the &man.linprocfs.5; manual page. + to /etc/fstab, for more information, see the &man.linprocfs.5; manual page. Another parameter to set is kern.fallback_elf_brand=3 which is done in the file /etc/sysctl.conf. Creating the &sap.r3; Environment Creating the Necessary File Systems and Mountpoints For a simple installation, it is sufficient to create the following file systems: mount point size in GB /compat/linux/oracle 45 GB /compat/linux/sapmnt 2 GB /compat/linux/usr/sap 2 GB It is also necessary to created some links. Otherwise the &sap; Installer will complain, as it is checking the created links: &prompt.root; ln -s /compat/linux/oracle /oracle &prompt.root; ln -s /compat/linux/sapmnt /sapmnt &prompt.root; ln -s /compat/linux/usr/sap /usr/sap Possible error message during installation (here with System PRD and the &sap.r3; 4.6C SR2 installation): INFO 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:200 Checking existence of symbolic link /usr/sap/PRD/SYS/exe/dbg to /sapmnt/PRD/exe. Creating if it does not exist... WARNING 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:400 Link /usr/sap/PRD/SYS/exe/dbg exists but it points to file /compat/linux/sapmnt/PRD/exe instead of /sapmnt/PRD/exe. The program cannot go on as long as this link exists at this location. Move the link to another location. ERROR 2002-03-19 16:45:36 R3LINKS_IND_IND Ins_SetupLinks:0 can not setup link '/usr/sap/PRD/SYS/exe/dbg' with content '/sapmnt/PRD/exe' Creating Users and Directories &sap.r3; needs two users and three groups. The user names depend on the &sap; system ID (SID) which consists of three letters. Some of these SIDs are reserved by &sap; (for example SAP and NIX. For a complete list please see the &sap; documentation). For the IDES installation we used IDS, for the 4.6C SR2 installation PRD, as that system is intended for production use. We have therefore the following groups (group IDs might differ, these are just the values we used with our installation): group ID group name description 100 dba Data Base Administrator 101 sapsys &sap; System 102 oper Data Base Operator For a default &oracle; installation, only group dba is used. As oper group, one also uses group dba (see &oracle; and &sap; documentation for further information). We also need the following users: user ID user name generic name group additional groups description 1000 idsadm/prdadm sidadm sapsys oper &sap; Administrator 1002 oraids/oraprd orasid dba oper &oracle; Administrator Adding the users with &man.adduser.8; requires the following (please note shell and home directory) entries for &sap; Administrator: Name: sidadm Password: ****** Fullname: SAP Administrator SID Uid: 1000 Gid: 101 (sapsys) Class: Groups: sapsys dba HOME: /home/sidadm Shell: bash (/compat/linux/bin/bash) and for &oracle; Administrator: Name: orasid Password: ****** Fullname: Oracle Administrator SID Uid: 1002 Gid: 100 (dba) Class: Groups: dba HOME: /oracle/sid Shell: bash (/compat/linux/bin/bash) This should also include group oper in case you are using both groups dba and oper. Creating Directories These directories are usually created as separate file systems. This depends entirely on your requirements. We choose to create them as simple directories, as they are all located on the same RAID 5 anyway: First we will set owners and rights of some directories (as user root): &prompt.root; chmod 775 /oracle &prompt.root; chmod 777 /sapmnt &prompt.root; chown root:dba /oracle &prompt.root; chown sidadm:sapsys /compat/linux/usr/sap &prompt.root; chmod 775 /compat/linux/usr/sap Second we will create directories as user orasid. These will all be subdirectories of /oracle/SID: &prompt.root; su - orasid &prompt.root; cd /oracle/SID &prompt.root; mkdir mirrlogA mirrlogB origlogA origlogB &prompt.root; mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6 &prompt.root; mkdir saparch sapreorg &prompt.root; exit For the &oracle; 8.1.7 installation some additional directories are needed: &prompt.root; su - orasid &prompt.root; cd /oracle &prompt.root; mkdir 805_32 &prompt.root; mkdir client stage &prompt.root; mkdir client/80x_32 &prompt.root; mkdir stage/817_32 &prompt.root; cd /oracle/SID &prompt.root; mkdir 817_32 The directory client/80x_32 is used with exactly this name. Do not replace the x with some number or anything. In the third step we create directories as user sidadm: &prompt.root; su - sidadm &prompt.root; cd /usr/sap &prompt.root; mkdir SID &prompt.root; mkdir trans &prompt.root; exit Entries in <filename>/etc/services</filename> &sap.r3; requires some entries in file /etc/services, which will not be set correctly during installation under FreeBSD. Please add the following entries (you need at least those entries corresponding to the instance number — in this case, 00. It will do no harm adding all entries from 00 to 99 for dp, gw, sp and ms). If you are going to use a SAProuter or need to access &sap; OSS, you also need 99, as port 3299 is usually used for the SAProuter process on the target system: sapdp00 3200/tcp # SAP Dispatcher. 3200 + Instance-Number sapgw00 3300/tcp # SAP Gateway. 3300 + Instance-Number sapsp00 3400/tcp # 3400 + Instance-Number sapms00 3500/tcp # 3500 + Instance-Number sapmsSID 3600/tcp # SAP Message Server. 3600 + Instance-Number sapgw00s 4800/tcp # SAP Secure Gateway 4800 + Instance-Number Necessary Locales locale &sap; requires at least two locales that are not part of the default RedHat installation. &sap; offers the required RPMs as download from their FTP server (which is only accessible if you are a customer with OSS access). See note 0171356 for a list of RPMs you need. It is also possible to just create appropriate links (for example from de_DE and en_US ), but we would not recommend this for a production system (so far it worked with the IDES system without any problems, though). The following locales are needed: de_DE.ISO-8859-1 en_US.ISO-8859-1 Create the links like this: &prompt.root; cd /compat/linux/usr/share/locale &prompt.root; ln -s de_DE de_DE.ISO-8859-1 &prompt.root; ln -s en_US en_US.ISO-8859-1 If they are not present, there will be some problems during the installation. If these are then subsequently ignored (by setting the STATUS of the offending steps to OK in file CENTRDB.R3S), it will be impossible to log onto the &sap; system without some additional effort. Kernel Tuning kernel tuning &sap.r3; systems need a lot of resources. We therefore added the following parameters to the kernel configuration file: # Set these for memory pigs (SAP and Oracle): options MAXDSIZ="(1024*1024*1024)" options DFLDSIZ="(1024*1024*1024)" # System V options needed. options SYSVSHM #SYSV-style shared memory options SHMMAXPGS=262144 #max amount of shared mem. pages #options SHMMAXPGS=393216 #use this for the 46C inst.parameters options SHMMNI=256 #max number of shared memory ident if. options SHMSEG=100 #max shared mem.segs per process options SYSVMSG #SYSV-style message queues options MSGSEG=32767 #max num. of mes.segments in system options MSGSSZ=32 #size of msg-seg. MUST be power of 2 options MSGMNB=65535 #max char. per message queue options MSGTQL=2046 #max amount of msgs in system options SYSVSEM #SYSV-style semaphores options SEMMNU=256 #number of semaphore UNDO structures options SEMMNS=1024 #number of semaphores in system options SEMMNI=520 #number of semaphore identifiers options SEMUME=100 #number of UNDO keys The minimum values are specified in the documentation that comes from &sap;. As there is no description for Linux, see the HP-UX section (32-bit) for further information. As the system for the 4.6C SR2 installation has more main memory, the shared segments can be larger both for &sap; and &oracle;, therefore choose a larger number of shared memory pages. With the default installation of FreeBSD 4.5 on &i386;, leave MAXDSIZ and DFLDSIZ at 1 GB maximum. Otherwise, strange errors like ORA-27102: out of memory and Linux Error: 12: Cannot allocate memory might happen. Installing &sap.r3; Preparing &sap; CDROMs There are many CDROMs to mount and unmount during the installation. Assuming you have enough CDROM drives, you can just mount them all. We decided to copy the CDROMs contents to corresponding directories: /oracle/SID/sapreorg/cd-name where cd-name was one of KERNEL, RDBMS, EXPORT1, EXPORT2, EXPORT3, EXPORT4, EXPORT5 and EXPORT6 for the 4.6B/IDES installation, and KERNEL, RDBMS, DISK1, DISK2, DISK3, DISK4 and LANG for the 4.6C SR2 installation. All the filenames on the mounted CDs should be in capital letters, otherwise use the option for mounting. So use the following commands: &prompt.root; mount_cd9660 -g /dev/cd0a /mnt &prompt.root; cp -R /mnt/* /oracle/SID/sapreorg/cd-name &prompt.root; umount /mnt Running the Installation Script First you have to prepare an install directory: &prompt.root; cd /oracle/SID/sapreorg &prompt.root; mkdir install &prompt.root; cd install Then the installation script is started, which will copy nearly all the relevant files into the install directory: &prompt.root; /oracle/SID/sapreorg/KERNEL/UNIX/INSTTOOL.SH The IDES installation (4.6B) comes with a fully customized &sap.r3; demonstration system, so there are six instead of just three EXPORT CDs. At this point the installation template CENTRDB.R3S is for installing a standard central instance (&r3; and database), not the IDES central instance, so one needs to copy the corresponding CENTRDB.R3S from the EXPORT1 directory, otherwise R3SETUP will only ask for three EXPORT CDs. The newer &sap; 4.6C SR2 release comes with four EXPORT CDs. The parameter file that controls the installation steps is CENTRAL.R3S. Contrary to earlier releases there are no separate installation templates for a central instance with or without database. &sap; is using a separate template for database installation. To restart the installation later it is however sufficient to restart with the original file. During and after installation, &sap; requires hostname to return the computer name only, not the fully qualified domain name. So either set the hostname accordingly, or set an alias with alias hostname='hostname -s' for both orasid and sidadm (and for root at least during installation steps performed as root). It is also possible to adjust the installed .profile and .login files of both users that are installed during &sap; installation. Start <command>R3SETUP</command> 4.6B Make sure LD_LIBRARY_PATH is set correctly: &prompt.root; export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/lib Start R3SETUP as root from installation directory: &prompt.root; cd /oracle/IDS/sapreorg/install &prompt.root; ./R3SETUP -f CENTRDB.R3S The script then asks some questions (defaults in brackets, followed by actual input): Question Default Input Enter SAP System ID [C11] IDSEnter Enter SAP Instance Number [00] Enter Enter SAPMOUNT Directory [/sapmnt] Enter Enter name of SAP central host [troubadix.domain.de] Enter Enter name of SAP db host [troubadix] Enter Select character set [1] (WE8DEC) Enter Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.6 1Enter Extract Oracle Client archive [1] (Yes, extract) Enter Enter path to KERNEL CD [/sapcd] /oracle/IDS/sapreorg/KERNEL Enter path to RDBMS CD [/sapcd] /oracle/IDS/sapreorg/RDBMS Enter path to EXPORT1 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT1 Directory to copy EXPORT1 CD [/oracle/IDS/sapreorg/CD4_DIR] Enter Enter path to EXPORT2 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT2 Directory to copy EXPORT2 CD [/oracle/IDS/sapreorg/CD5_DIR] Enter Enter path to EXPORT3 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT3 Directory to copy EXPORT3 CD [/oracle/IDS/sapreorg/CD6_DIR] Enter Enter path to EXPORT4 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT4 Directory to copy EXPORT4 CD [/oracle/IDS/sapreorg/CD7_DIR] Enter Enter path to EXPORT5 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT5 Directory to copy EXPORT5 CD [/oracle/IDS/sapreorg/CD8_DIR] Enter Enter path to EXPORT6 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT6 Directory to copy EXPORT6 CD [/oracle/IDS/sapreorg/CD9_DIR] Enter Enter amount of RAM for SAP + DB 850Enter (in Megabytes) Service Entry Message Server [3600] Enter Enter Group-ID of sapsys [101] Enter Enter Group-ID of oper [102] Enter Enter Group-ID of dba [100] Enter Enter User-ID of sidadm [1000] Enter Enter User-ID of orasid [1002] Enter Number of parallel procs [2] Enter If you had not copied the CDs to the different locations, then the &sap; installer cannot find the CD needed (identified by the LABEL.ASC file on the CD) and would then ask you to insert and mount the CD and confirm or enter the mount path. The CENTRDB.R3S might not be error free. In our case, it requested EXPORT4 CD again but indicated the correct key (6_LOCATION, then 7_LOCATION etc.), so one can just continue with entering the correct values. Apart from some problems mentioned below, everything should go straight through up to the point where the &oracle; database software needs to be installed. Start <command>R3SETUP</command> 4.6C SR2 Make sure LD_LIBRARY_PATH is set correctly. This is a different value from the 4.6B installation with &oracle; 8.0.5: &prompt.root; export LD_LIBRARY_PATH=/sapmnt/PRD/exe:/oracle/PRD/817_32/lib Start R3SETUP as user root from installation directory: &prompt.root; cd /oracle/PRD/sapreorg/install &prompt.root; ./R3SETUP -f CENTRAL.R3S The script then asks some questions (defaults in brackets, followed by actual input): Question Default Input Enter SAP System ID [C11] PRDEnter Enter SAP Instance Number [00] Enter Enter SAPMOUNT Directory [/sapmnt] Enter Enter name of SAP central host [majestix] Enter Enter Database System ID [PRD] PRDEnter Enter name of SAP db host [majestix] Enter Select character set [1] (WE8DEC) Enter Enter Oracle server version (2) Oracle 8.1.7 2Enter Extract Oracle Client archive [1] (Yes, extract) Enter Enter path to KERNEL CD [/sapcd] /oracle/PRD/sapreorg/KERNEL Enter amount of RAM for SAP + DB 2044 1800Enter (in Megabytes) Service Entry Message Server [3600] Enter Enter Group-ID of sapsys [100] Enter Enter Group-ID of oper [101] Enter Enter Group-ID of dba [102] Enter Enter User-ID of oraprd [1002] Enter Enter User-ID of prdadm [1000] Enter LDAP support 3Enter (no support) Installation step completed [1] (continue) Enter Choose installation service [1] (DB inst,file) Enter So far, creation of users gives an error during installation in phases OSUSERDBSID_IND_ORA (for creating user orasid) and OSUSERSIDADM_IND_ORA (creating user sidadm). Apart from some problems mentioned below, everything should go straight through up to the point where the &oracle; database software needs to be installed. Installing &oracle; 8.0.5 Please see the corresponding &sap; Notes and &oracle; Readmes regarding Linux and &oracle; DB for possible problems. Most if not all problems stem from incompatible libraries. For more information on installing &oracle;, refer to the Installing &oracle; chapter. Installing the &oracle; 8.0.5 with <command>orainst</command> If &oracle; 8.0.5 is to be used, some additional libraries are needed for successfully relinking, as &oracle; 8.0.5 was linked with an old glibc (RedHat 6.0), but RedHat 6.1 already uses a new glibc. So you have to install the following additional packages to ensure that linking will work: compat-libs-5.2-2.i386.rpm compat-glibc-5.2-2.0.7.2.i386.rpm compat-egcs-5.2-1.0.3a.1.i386.rpm compat-egcs-c++-5.2-1.0.3a.1.i386.rpm compat-binutils-5.2-2.9.1.0.23.1.i386.rpm See the corresponding &sap; Notes or &oracle; Readmes for further information. If this is no option (at the time of installation we did not have enough time to check this), one could use the original binaries, or use the relinked binaries from an original RedHat system. For compiling the intelligent agent, the RedHat Tcl package must be installed. If you cannot get tcl-8.0.3-20.i386.rpm, a newer one like tcl-8.0.5-30.i386.rpm for RedHat 6.1 should also do. Apart from relinking, the installation is straightforward: &prompt.root; su - oraids &prompt.root; export TERM=xterm &prompt.root; export ORACLE_TERM=xterm &prompt.root; export ORACLE_HOME=/oracle/IDS &prompt.root; cd $ORACLE_HOME/orainst_sap &prompt.root; ./orainst Confirm all screens with Enter until the software is installed, except that one has to deselect the &oracle; On-Line Text Viewer, as this is not currently available for Linux. &oracle; then wants to relink with i386-glibc20-linux-gcc instead of the available gcc, egcs or i386-redhat-linux-gcc . Due to time constrains we decided to use the binaries from an &oracle; 8.0.5 PreProduction release, after the first attempt at getting the version from the RDBMS CD working, failed, and finding and accessing the correct RPMs was a nightmare at that time. Installing the &oracle; 8.0.5 Pre-production Release for Linux (Kernel 2.0.33) This installation is quite easy. Mount the CD, start the installer. It will then ask for the location of the &oracle; home directory, and copy all binaries there. We did not delete the remains of our previous RDBMS installation tries, though. Afterwards, &oracle; Database could be started with no problems. Installing the &oracle; 8.1.7 Linux Tarball Take the tarball oracle81732.tgz you produced from the installation directory on a Linux system and untar it to /oracle/SID/817_32/. Continue with &sap.r3; Installation First check the environment settings of users idsamd (sidadm) and oraids (orasid). They should now both have the files .profile, .login and .cshrc which are all using hostname. In case the system's hostname is the fully qualified name, you need to change hostname to hostname -s within all three files. Database Load Afterwards, R3SETUP can either be restarted or continued (depending on whether exit was chosen or not). R3SETUP then creates the tablespaces and loads the data (for 46B IDES, from EXPORT1 to EXPORT6, for 46C from DISK1 to DISK4) with R3load into the database. When the database load is finished (might take a few hours), some passwords are requested. For test installations, one can use the well known default passwords (use different ones if security is an issue!): Question Input Enter Password for sapr3 sapEnter Confirum Password for sapr3 sapEnter Enter Password for sys change_on_installEnter Confirm Password for sys change_on_installEnter Enter Password for system managerEnter Confirm Password for system managerEnter At this point We had a few problems with dipgntab during the 4.6B installation. Listener Start the &oracle; Listener as user orasid as follows: &prompt.user; umask 0; lsnrctl start Otherwise you might get the error ORA-12546 as the sockets will not have the correct permissions. See &sap; Note 072984. Updating MNLS Tables If you plan to import non-Latin-1 languages into the &sap; system, you have to update the Multi National Language Support tables. This is described in the &sap; OSS Notes 15023 and 45619. Otherwise, you can skip this question during &sap; installation. If you do not need MNLS, it is still necessary to check the table TCPDB and initializing it if this has not been done. See &sap; note 0015023 and 0045619 for further information. Post-installation Steps Request &sap.r3; License Key You have to request your &sap.r3; License Key. This is needed, as the temporary license that was installed during installation is only valid for four weeks. First get the hardware key. Log on as user idsadm and call saplicense: &prompt.root; /sapmnt/IDS/exe/saplicense -get Calling saplicense without parameters gives a list of options. Upon receiving the license key, it can be installed using: &prompt.root; /sapmnt/IDS/exe/saplicense -install You are then required to enter the following values: SAP SYSTEM ID = SID, 3 chars CUSTOMER KEY = hardware key, 11 chars INSTALLATION NO = installation, 10 digits EXPIRATION DATE = yyyymmdd, usually "99991231" LICENSE KEY = license key, 24 chars Creating Users Create a user within client 000 (for some tasks required to be done within client 000, but with a user different from users sap* and ddic). As a user name, We usually choose wartung (or service in English). Profiles required are sap_new and sap_all. For additional safety the passwords of default users within all clients should be changed (this includes users sap* and ddic). Configure Transport System, Profile, Operation Modes, Etc. Within client 000, user different from ddic and sap*, do at least the following: Task Transaction Configure Transport System, e.g. as Stand-Alone Transport Domain Entity STMS Create / Edit Profile for System RZ10 Maintain Operation Modes and Instances RZ04 These and all the other post-installation steps are thoroughly described in &sap; installation guides. Edit <filename>init<replaceable>sid</replaceable>.sap</filename> (<filename>initIDS.sap</filename>) The file /oracle/IDS/dbs/initIDS.sap contains the &sap; backup profile. Here the size of the tape to be used, type of compression and so on need to be defined. To get this running with sapdba / brbackup, we changed the following values: compress = hardware archive_function = copy_delete_save cpio_flags = "-ov --format=newc --block-size=128 --quiet" cpio_in_flags = "-iuv --block-size=128 --quiet" tape_size = 38000M tape_address = /dev/nsa0 tape_address_rew = /dev/sa0 Explanations: compress: The tape we use is a HP DLT1 which does hardware compression. archive_function: This defines the default behavior for saving &oracle; archive logs: new logfiles are saved to tape, already saved logfiles are saved again and are then deleted. This prevents lots of trouble if you need to recover the database, and one of the archive-tapes has gone bad. cpio_flags: Default is to use which sets block size to 5120 Bytes. For DLT Tapes, HP recommends at least 32 K block size, so we used for 64 K. is needed because we have inode numbers greater than 65535. The last option is needed as otherwise brbackup complains as soon as cpio outputs the numbers of blocks saved. cpio_in_flags: Flags needed for loading data back from tape. Format is recognized automatically. tape_size: This usually gives the raw storage capability of the tape. For security reason (we use hardware compression), the value is slightly lower than the actual value. tape_address: The non-rewindable device to be used with cpio. tape_address_rew: The rewindable device to be used with cpio. Configuration Issues after Installation The following &sap; parameters should be tuned after installation (examples for IDES 46B, 1 GB memory): Name Value ztta/roll_extension 250000000 abap/heap_area_dia 300000000 abap/heap_area_nondia 400000000 em/initial_size_MB 256 em/blocksize_kB 1024 ipc/shm_psize_40 70000000 &sap; Note 0013026: Name Value ztta/dynpro_area 2500000 &sap; Note 0157246: Name Value rdisp/ROLL_MAXFS 16000 rdisp/PG_MAXFS 30000 With the above parameters, on a system with 1 gigabyte of memory, one may find memory consumption similar to: Mem: 547M Active, 305M Inact, 109M Wired, 40M Cache, 112M Buf, 3492K Free Problems during Installation Restart <command>R3SETUP</command> after Fixing a Problem R3SETUP stops if it encounters an error. If you have looked at the corresponding logfiles and fixed the error, you have to start R3SETUP again, usually selecting REPEAT as option for the last step R3SETUP complained about. To restart R3SETUP, just start it with the corresponding R3S file: &prompt.root; ./R3SETUP -f CENTRDB.R3S for 4.6B, or with &prompt.root; ./R3SETUP -f CENTRAL.R3S for 4.6C, no matter whether the error occurred with CENTRAL.R3S or DATABASE.R3S. At some stages, R3SETUP assumes that both database and &sap; processes are up and running (as those were steps it already completed). Should errors occur and for example the database could not be started, you have to start both database and &sap; by hand after you fixed the errors and before starting R3SETUP again. Do not forget to also start the &oracle; listener again (as orasid with umask 0; lsnrctl start) if it was also stopped (for example due to a necessary reboot of the system). OSUSERSIDADM_IND_ORA during <command>R3SETUP</command> If R3SETUP complains at this stage, edit the template file R3SETUP used at that time (CENTRDB.R3S (4.6B) or either CENTRAL.R3S or DATABASE.R3S (4.6C)). Locate [OSUSERSIDADM_IND_ORA] or search for the only STATUS=ERROR entry and edit the following values: HOME=/home/sidadm (was empty) STATUS=OK (had status ERROR) Then you can restart R3SETUP again. OSUSERDBSID_IND_ORA during <command>R3SETUP</command> Possibly R3SETUP also complains at this stage. The error here is similar to the one in phase OSUSERSIDADM_IND_ORA. Just edit the template file R3SETUP used at that time (CENTRDB.R3S (4.6B) or either CENTRAL.R3S or DATABASE.R3S (4.6C)). Locate [OSUSERDBSID_IND_ORA] or search for the only STATUS=ERROR entry and edit the following value in that section: STATUS=OK Then restart R3SETUP. <errorname>oraview.vrf FILE NOT FOUND</errorname> during &oracle; Installation You have not deselected &oracle; On-Line Text Viewer before starting the installation. This is marked for installation even though this option is currently not available for Linux. Deselect this product inside the &oracle; installation menu and restart installation. <errorname>TEXTENV_INVALID</errorname> during <command>R3SETUP</command>, RFC or SAPgui Start If this error is encountered, the correct locale is missing. &sap; Note 0171356 lists the necessary RPMs that need be installed (e.g. saplocales-1.0-3, saposcheck-1.0-1 for RedHat 6.1). In case you ignored all the related errors and set the corresponding STATUS from ERROR to OK (in CENTRDB.R3S) every time R3SETUP complained and just restarted R3SETUP, the &sap; system will not be properly configured and you will then not be able to connect to the system with a SAPgui, even though the system can be started. Trying to connect with the old Linux SAPgui gave the following messages: Sat May 5 14:23:14 2001 *** ERROR => no valid userarea given [trgmsgo. 0401] Sat May 5 14:23:22 2001 *** ERROR => ERROR NR 24 occured [trgmsgi. 0410] *** ERROR => Error when generating text environment. [trgmsgi. 0435] *** ERROR => function failed [trgmsgi. 0447] *** ERROR => no socket operation allowed [trxio.c 3363] Speicherzugriffsfehler This behavior is due to &sap.r3; being unable to correctly assign a locale and also not being properly configured itself (missing entries in some database tables). To be able to connect to &sap;, add the following entries to file DEFAULT.PFL (see Note 0043288): abap/set_etct_env_at_new_mode = 0 install/collate/active = 0 rscp/TCP0B = TCP0B Restart the &sap; system. Now you can connect to the system, even though country-specific language settings might not work as expected. After correcting country settings (and providing the correct locales), these entries can be removed from DEFAULT.PFL and the &sap; system can be restarted. <errorcode>ORA-00001</errorcode> This error only happened with &oracle; 8.1.7 on FreeBSD 4.5. The reason was that the &oracle; database could not initialize itself properly and crashed, leaving semaphores and shared memory on the system. The next try to start the database then returned ORA-00001. Find them with ipcs -a and remove them with ipcrm. <errorcode>ORA-00445</errorcode> (Background Process PMON Did Not Start) This error happened with &oracle; 8.1.7. This error is reported if the database is started with the usual startsap script (for example startsap_majestix_00) as user prdadm. A possible workaround is to start the database as user oraprd instead with svrmgrl: &prompt.user; svrmgrl SVRMGR> connect internal; SVRMGR> startup; SVRMGR> exit <errorcode>ORA-12546</errorcode> (Start Listener with Correct Permissions) Start the &oracle; listener as user oraids with the following commands: &prompt.root; umask 0; lsnrctl start Otherwise you might get ORA-12546 as the sockets will not have the correct permissions. See &sap; Note 0072984. <errorcode>ORA-27102</errorcode> (Out of Memory) This error happened whilst trying to use values for MAXDSIZ and DFLDSIZ greater than 1 GB (1024x1024x1024). Additionally, we got Linux Error 12: Cannot allocate memory. [DIPGNTAB_IND_IND] during <command>R3SETUP</command> In general, see &sap; Note 0130581 (R3SETUP step DIPGNTAB terminates). During the IDES-specific installation, for some reasons the installation process was not using the proper &sap; system name IDS, but the empty string "" instead. This lead to some minor problems with accessing directories, as the paths are generated dynamically using SID (in this case IDS). So instead of accessing: /usr/sap/IDS/SYS/... /usr/sap/IDS/DVMGS00 the following paths were used: /usr/sap//SYS/... /usr/sap/D00 To continue with the installation, we created a link and an additional directory: &prompt.root; pwd /compat/linux/usr/sap &prompt.root; ls -l total 4 drwxr-xr-x 3 idsadm sapsys 512 May 5 11:20 D00 drwxr-x--x 5 idsadm sapsys 512 May 5 11:35 IDS lrwxr-xr-x 1 root sapsys 7 May 5 11:35 SYS -> IDS/SYS drwxrwxr-x 2 idsadm sapsys 512 May 5 13:00 tmp drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans We also found &sap; Notes (0029227 and 0008401) describing this behavior. We did not encounter any of these problems with the &sap; 4.6C installation. [RFCRSWBOINI_IND_IND] during <command>R3SETUP</command> During installation of &sap; 4.6C, this error was just the result of another error happening earlier during installation. In this case, you have to look through the corresponding logfiles and correct the real problem. If after looking through the logfiles this error is indeed the correct one (check the &sap; Notes), you can set STATUS of the offending step from ERROR to OK (file CENTRDB.R3S) and restart R3SETUP. After installation, you have to execute the report RSWBOINS from transaction SE38. See &sap; Note 0162266 for additional information about phase RFCRSWBOINI and RFCRADDBDIF. [RFCRADDBDIF_IND_IND] during <command>R3SETUP</command> Here the same restrictions apply: make sure by looking through the logfiles, that this error is not caused by some previous problems. If you can confirm that &sap; Note 0162266 applies, just set STATUS of the offending step from ERROR to OK (file CENTRDB.R3S) and restart R3SETUP. After installation, you have to execute the report RADDBDIF from transaction SE38. <errorcode>sigaction sig31: File size limit exceeded</errorcode> This error occurred during start of &sap; processes disp+work. If starting &sap; with the startsap script, subprocesses are then started which detach and do the dirty work of starting all other &sap; processes. As a result, the script itself will not notice if something goes wrong. To check whether the &sap; processes did start properly, have a look at the process status with ps ax | grep SID, which will give you a list of all &oracle; and &sap; processes. If it looks like some processes are missing or if you cannot connect to the &sap; system, look at the corresponding logfiles which can be found at /usr/sap/SID/DVEBMGSnr/work/. The files to look at are dev_ms and dev_disp. Signal 31 happens here if the amount of shared memory used by &oracle; and &sap; exceed the one defined within the kernel configuration file and could be resolved by using a larger value: # larger value for 46C production systems: options SHMMAXPGS=393216 # smaller value sufficient for 46B: #options SHMMAXPGS=262144 Start of <command>saposcol</command> Failed There are some problems with the program saposcol (version 4.6D). The &sap; system is using saposcol to collect data about the system performance. This program is not needed to use the &sap; system, so this problem can be considered a minor one. The older versions (4.6B) does work, but does not collect all the data (many calls will just return 0, for example for CPU usage). Advanced Topics If you are curious as to how the Linux binary compatibility works, this is the section you want to read. Most of what follows is based heavily on an email written to &a.chat; by Terry Lambert tlambert@primenet.com (Message ID: <199906020108.SAA07001@usr09.primenet.com>). How Does It Work? execution class loader FreeBSD has an abstraction called an execution class loader. This is a wedge into the &man.execve.2; system call. What happens is that FreeBSD has a list of loaders, instead of a single loader with a fallback to the #! loader for running any shell interpreters or shell scripts. Historically, the only loader on the &unix; platform examined the magic number (generally the first 4 or 8 bytes of the file) to see if it was a binary known to the system, and if so, invoked the binary loader. If it was not the binary type for the system, the &man.execve.2; call returned a failure, and the shell attempted to start executing it as shell commands. The assumption was a default of whatever the current shell is. Later, a hack was made for &man.sh.1; to examine the first two characters, and if they were :\n, then it invoked the &man.csh.1; shell instead (we believe SCO first made this hack). What FreeBSD does now is go through a list of loaders, with a generic #! loader that knows about interpreters as the characters which follow to the next whitespace next to last, followed by a fallback to /bin/sh. ELF For the Linux ABI support, FreeBSD sees the magic number as an ELF binary (it makes no distinction between FreeBSD, &solaris;, Linux, or any other OS which has an ELF image type, at this point). Solaris The ELF loader looks for a specialized brand, which is a comment section in the ELF image, and which is not present on SVR4/&solaris; ELF binaries. For Linux binaries to function, they must be branded as type Linux from &man.brandelf.1;: &prompt.root; brandelf -t Linux file When this is done, the ELF loader will see the Linux brand on the file. ELF branding When the ELF loader sees the Linux brand, the loader replaces a pointer in the proc structure. All system calls are indexed through this pointer (in a traditional &unix; system, this would be the sysent[] structure array, containing the system calls). In addition, the process is flagged for special handling of the trap vector for the signal trampoline code, and several other (minor) fix-ups that are handled by the Linux kernel module. The Linux system call vector contains, among other things, a list of sysent[] entries whose addresses reside in the kernel module. When a system call is called by the Linux binary, the trap code dereferences the system call function pointer off the proc structure, and gets the Linux, not the FreeBSD, system call entry points. In addition, the Linux mode dynamically reroots lookups; this is, in effect, what the option to file system mounts (not the unionfs file system type!) does. First, an attempt is made to lookup the file in the /compat/linux/original-path directory, then only if that fails, the lookup is done in the /original-path directory. This makes sure that binaries that require other binaries can run (e.g., the Linux toolchain can all run under Linux ABI support). It also means that the Linux binaries can load and execute FreeBSD binaries, if there are no corresponding Linux binaries present, and that you could place a &man.uname.1; command in the /compat/linux directory tree to ensure that the Linux binaries could not tell they were not running on Linux. In effect, there is a Linux kernel in the FreeBSD kernel; the various underlying functions that implement all of the services provided by the kernel are identical to both the FreeBSD system call table entries, and the Linux system call table entries: file system operations, virtual memory operations, signal delivery, System V IPC, etc… The only difference is that FreeBSD binaries get the FreeBSD glue functions, and Linux binaries get the Linux glue functions (most older OS's only had their own glue functions: addresses of functions in a static global sysent[] structure array, instead of addresses of functions dereferenced off a dynamically initialized pointer in the proc structure of the process making the call). Which one is the native FreeBSD ABI? It does not matter. Basically the only difference is that (currently; this could easily be changed in a future release, and probably will be after this) the FreeBSD glue functions are statically linked into the kernel, and the Linux glue functions can be statically linked, or they can be accessed via a kernel module. Yeah, but is this really emulation? No. It is an ABI implementation, not an emulation. There is no emulator (or simulator, to cut off the next question) involved. So why is it sometimes called Linux emulation? To make it hard to sell FreeBSD! Really, it is because the historical implementation was done at a time when there was really no word other than that to describe what was going on; saying that FreeBSD ran Linux binaries was not true, if you did not compile the code in or load a module, and there needed to be a word to describe what was being loaded—hence the Linux emulator. diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml index c2a1118495..9f0bca3f9b 100644 --- a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml @@ -1,1322 +1,1322 @@ Installing Applications: Packages and Ports Synopsis ports packages FreeBSD is bundled with a rich collection of system tools as part of the base system. However, there is only so much one can do before needing to install an additional third-party application to get real work done. FreeBSD provides two complementary technologies for installing third party software on your system: the FreeBSD Ports Collection, and binary software packages. Either system may be used to install the newest version of your favorite applications from local media or straight off the network. After reading this chapter, you will know: How to install third-party binary software packages. How to build third-party software from the ports collection. How to remove previously installed packages or ports. How to override the default values that the ports collection uses. How to find the appropriate software package. How to upgrade your ports. Overview of Software Installation If you have used a &unix; system before you will know that the typical procedure for installing third party software goes something like this: Download the software, which might be distributed in source code format, or as a binary. Unpack the software from its distribution format (typically a tarball compressed with &man.compress.1;, &man.gzip.1;, or &man.bzip2.1;). Locate the documentation (perhaps an INSTALL or README file, or some files in a doc/ subdirectory) and read up on how to install the software. If the software was distributed in source format, compile it. This may involve editing a Makefile, or running a configure script, and other work. Test and install the software. And that is only if everything goes well. If you are installing a software package that was not deliberately ported to FreeBSD you may even have to go in and edit the code to make it work properly. Should you want to, you can continue to install software the traditional way with FreeBSD. However, FreeBSD provides two technologies which can save you a lot of effort: packages and ports. At the time of writing, over &os.numports; third party applications have been made available in this way. For any given application, the FreeBSD package for that application is a single file which you must download. The package contains pre-compiled copies of all the commands for the application, as well as any configuration files or documentation. A downloaded package file can be manipulated with FreeBSD package management commands, such as &man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so on. Installing a new application can be carried out with a single command. A FreeBSD port for an application is a collection of files designed to automate the process of compiling an application from source code. Remember that there are a number of steps you would normally carry out if you compiled a program yourself (downloading, unpacking, patching, compiling, installing). The files that make up a port contain all the necessary information to allow the system to do this for you. You run a handful of simple commands and the source code for the application is automatically downloaded, extracted, patched, compiled, and installed for you. In fact, the ports system can also be used to generate packages which can later be manipulated with pkg_add and the other package management commands that will be introduced shortly. Both packages and ports understand dependencies. Suppose you want to install an application that depends on a specific library being installed. Both the application and the library have been made available as FreeBSD ports and packages. If you use the pkg_add command or the ports system to add the application, both will notice that the library has not been installed, and automatically install the library first. Given that the two technologies are quite similar, you might be wondering why FreeBSD bothers with both. Packages and ports both have their own strengths, and which one you use will depend on your own preference. Package Benefits A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application. Packages do not require any additional compilation. For large applications, such as Mozilla, KDE, or GNOME this can be important, particularly if you are on a slow system. Packages do not require any understanding of the process involved in compiling software on FreeBSD. Ports Benefits Packages are normally compiled with conservative options, because they have to run on the maximum number of systems. By installing from the port, you can tweak the compilation options to (for example) generate code that is specific to a Pentium IV or Athlon processor. Some applications have compile time options relating to what they can and cannot do. For example, Apache can be configured with a wide variety of different built-in options. By building from the port you do not have to accept the default options, and can set them yourself. In some cases, multiple packages will exist for the same application to specify certain settings. For example, Ghostscript is available as a ghostscript package and a ghostscript-nox11 package, depending on whether or not you have installed an X11 server. This sort of rough tweaking is possible with packages, but rapidly becomes impossible if an application has more than one or two different compile time options. The licensing conditions of some software distributions forbid binary distribution. They must be distributed as source code. Some people do not trust binary distributions. At least with source code, you can (in theory) read through it and look for potential problems yourself. If you have local patches, you will need the source in order to apply them. Some people like having code around, so they can read it if they get bored, hack it, borrow from it (license permitting, of course), and so on. To keep track of updated ports, subscribe to the &a.ports; and the &a.ports-bugs;. Before installing any application, you should check for security issues related to your application. You can also install security/portaudit which will automatically check all installed applications for known vulnerabilities; a check will be also performed before any port build. Meanwhile, you can use the command portaudit -F -a after you have installed some packages. The remainder of this chapter will explain how to use packages and ports to install and manage third party software on FreeBSD. Finding Your Application Before you can install any applications you need to know what you want, and what the application is called. FreeBSD's list of available applications is growing all the time. Fortunately, there are a number of ways to find what you want: The FreeBSD web site maintains an up-to-date searchable list of all the available applications, at http://www.FreeBSD.org/ports/. The ports are divided into categories, and you may either search for an application by name (if you know it), or see all the applications available in a category. FreshPorts Dan Langille maintains FreshPorts, at . FreshPorts tracks changes to the applications in the ports tree as they happen, allows you to watch one or more ports, and can send you email when they are updated. FreshMeat If you do not know the name of the application you want, try using a site like FreshMeat () to find an application, then check back at the FreeBSD site to see if the application has been ported yet. If you know the exact name of the port, but just need to find out which category it is in, you can use the &man.whereis.1; command. Simply type whereis file, where file is the program you want to install. If it is found on your system, you will be told where it is, as follows: &prompt.root; whereis lsof lsof: /usr/ports/sysutils/lsof This tells us that lsof (a system utility) can be found in the /usr/ports/sysutils/lsof directory. Yet another way to find a particular port is by using the ports collection's built-in search mechanism. To use the search feature, you will need to be in the /usr/ports directory. Once in that directory, run make search name=program-name where program-name is the name of the program you want to find. For example, if you were looking for lsof: &prompt.root; cd /usr/ports &prompt.root; make search name=lsof Port: lsof-4.56.4 Path: /usr/ports/sysutils/lsof Info: Lists information about open files (similar to fstat(1)) Maint: obrien@FreeBSD.org Index: sysutils B-deps: R-deps: The part of the output you want to pay particular attention to is the Path: line, since that tells you where to find the port. The other information provided is not needed in order to install the port, so it will not be covered here. For more in-depth searching you can also use make search key=string where string is some text to search for. This searches port names, comments, descriptions and dependencies and can be used to find ports which relate to a particular subject if you don't know the name of the program you are looking for. In both of these cases, the search string is case-insensitive. Searching for LSOF will yield the same results as searching for lsof. Chern Lee Contributed by Using the Packages System Installing a Package packages installing pkg_add You can use the &man.pkg.add.1; utility to install a FreeBSD software package from a local file or from a server on the network. Downloading a Package Manually and Installing It Locally &prompt.root; ftp -a ftp2.FreeBSD.org Connected to ftp2.FreeBSD.org. 220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready. 331 Guest login ok, send your email address as password. 230- 230- This machine is in Vienna, VA, USA, hosted by Verio. 230- Questions? E-mail freebsd@vienna.verio.net. 230- 230- 230 Guest login ok, access restrictions apply. Remote system type is UNIX. Using binary mode to transfer files. ftp> cd /pub/FreeBSD/ports/packages/sysutils/ 250 CWD command successful. ftp> get lsof-4.56.4.tgz local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz 200 PORT command successful. 150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes). 100% |**************************************************| 92375 00:00 ETA 226 Transfer complete. 92375 bytes received in 5.60 seconds (16.11 KB/s) ftp> exit &prompt.root; pkg_add lsof-4.56.4.tgz If you do not have a source of local packages (such as a FreeBSD CD-ROM set) then it will probably be easier to use the option to &man.pkg.add.1;. This will cause the utility to automatically determine the correct object format and release and then fetch and install the package from an FTP site. pkg_add &prompt.root; pkg_add -r lsof The example above would download the correct package and add it without any further user intervention. If you want to specify an alternative &os; Packages Mirror, instead of the main distribution site, you have to set PACKAGESITE accordingly, to override the default settings. &man.pkg.add.1; uses &man.fetch.3; to download the files, which honors various environment variables, including FTP_PASSIVE_MODE, FTP_PROXY, and FTP_PASSWORD. You may need to set one or more of these if you are behind a firewall, or need to use an FTP/HTTP proxy. See &man.fetch.3; for the complete list. Note that in the example above lsof is used instead of lsof-4.56.4. When the remote fetching feature is used, the version number of the package must be removed. &man.pkg.add.1; will automatically fetch the latest version of the application. &man.pkg.add.1; will download the latest version of your application if you are using &os.current; or &os.stable;. If you run a -RELEASE version, it will grab the version of the package that was built with your release. It is possible to change this behavior by overriding the PACKAGESITE environment variable. Package files are distributed in .tgz and .tbz formats. You can find them at , or on the FreeBSD CD-ROM distribution. Every CD on the FreeBSD 4-CD set (and the PowerPak, etc.) contains packages in the /packages directory. The layout of the packages is similar to that of the /usr/ports tree. Each category has its own directory, and every package can be found within the All directory. The directory structure of the package system matches the ports layout; they work with each other to form the entire package/port system. Managing Packages packages managing &man.pkg.info.1; is a utility that lists and describes the various packages installed. pkg_info &prompt.root; pkg_info cvsup-16.1 A general network file distribution system optimized for CV docbook-1.2 Meta-port for the different versions of the DocBook DTD ... &man.pkg.version.1; is a utility that summarizes the versions of all installed packages. It compares the package version to the current version found in the ports tree. pkg_version &prompt.root; pkg_version cvsup = docbook = ... The symbols in the second column indicate the relative age of the installed version and the version available in the local ports tree. Symbol Meaning = The version of the installed package matches the one found in the local ports tree. < The installed version is older than the one available in the ports tree. >The installed version is newer than the one found in the local ports tree. (The local ports tree is probably out of date.) ?The installed package cannot be found in the ports index. (This can happen, for instance, if an installed port is removed from the ports collection or renamed.) *There are multiple versions of the package. Deleting a Package pkg_delete packages deleting To remove a previously installed software package, use the &man.pkg.delete.1; utility. &prompt.root; pkg_delete xchat-1.7.1 Miscellaneous All package information is stored within the /var/db/pkg directory. The installed file list and descriptions of each package can be found within files in this directory. Using the Ports Collection The following sections provide basic instructions on using the ports collection to install or remove programs from your system. Obtaining the Ports Collection Before you can install ports, you must first obtain the ports collection—which is essentially a set of Makefiles, patches, and description files placed in /usr/ports. When installing your FreeBSD system, sysinstall asked if you would like to install the ports collection. If you chose no, you can follow these instructions to obtain the ports collection: Sysinstall Method This method involves using sysinstall again to manually install the ports collection. As root, run /stand/sysinstall as shown below: &prompt.root; /stand/sysinstall Scroll down and select Configure, press Enter. Scroll down and select Distributions, press Enter. Scroll down to ports, press Space. Scroll up to Exit, press Enter. Select your desired installation media, such as CDROM, FTP, and so on. Scroll up to Exit and press Enter. Press X to exit sysinstall. The alternative method to obtain and keep your ports collection up to date is by using CVSup. Look at the ports CVSup file, /usr/share/examples/cvsup/ports-supfile. See Using CVSup () for more information on using CVSup and this file. CVSup Method This is a quick method for getting the ports collection using CVSup. If you want to keep your ports tree up to date, or learn more about CVSup, read the previously mentioned sections. Install the net/cvsup port. See CVSup Installation () for more details. As root, copy /usr/share/examples/cvsup/ports-supfile to a new location, such as /root or your home directory. Edit ports-supfile. Change CHANGE_THIS.FreeBSD.org to a CVSup server near you. See CVSup Mirrors () for a complete listing of mirror sites. Run cvsup: &prompt.root; cvsup -g -L 2 /root/ports-supfile Running this command later will download and apply all the recent changes to your ports collection, except actually rebuilding the ports for your own system. Installing Ports ports installing The first thing that should be explained when it comes to the ports collection is what is actually meant by a skeleton. In a nutshell, a port skeleton is a minimal set of files that tell your FreeBSD system how to cleanly compile and install a program. Each port skeleton includes: A Makefile. The Makefile contains various statements that specify how the application should be compiled and where it should be installed on your system. A distinfo file. This file contains information about the files that must be downloaded to build the port and their checksums, to verify that files have not been corrupted during the download using &man.md5.1;. A files directory. This directory contains patches to make the program compile and install on your FreeBSD system. Patches are basically small files that specify changes to particular files. They are in plain text format, and basically say Remove line 10 or Change line 26 to this .... Patches are also known as diffs because they are generated by the &man.diff.1; program. This directory may also contain other files used to build the port. A pkg-descr file. This is a more detailed, often multiple-line, description of the program. A pkg-plist file. This is a list of all the files that will be installed by the port. It also tells the ports system what files to remove upon deinstallation. Some ports have other files, such as pkg-message. The ports system uses these files to handle special situations. If you want more details on these files, and on ports in general, check out the FreeBSD Porter's Handbook. The port includes instructions on how to build source code, but does not include the actual source code. You can get the source code from a CD-ROM or from the Internet. Source code is distributed in whatever manner the software author desires. Frequently this is a tarred and gzipped file, but it might be compressed with some other tool or even uncompressed. The program source code, whatever form it comes in, is called a distfile. The two methods for installing a &os; port are described below. You must be logged in as root to install ports. Before installing any port, you should be sure to have an up-to-date ports collection and you should check for security issues related to your port. A security vulnerabilities check can be automatically done by portaudit before any new application installation. This tool can be found in the ports collection (security/portaudit). Consider running portaudit -F before installing a new port, to fetch the current vulnerabilities database. A security audit and an update of the database will be performed during the daily security system check. For more - informations read the &man.portaudit.1; and &man.periodic.8; + information read the &man.portaudit.1; and &man.periodic.8; manual pages. Installing Ports from a CD-ROM ports installing from CD-ROM The FreeBSD Project's official CD-ROM images no longer include distfiles. They take up a lot of room that is better used for precompiled packages. CD-ROM products such as the FreeBSD PowerPak do include distfiles, and you can order these sets from a vendor such as the FreeBSD Mall. This section assumes you have such a FreeBSD CD-ROM set. Place your FreeBSD CD-ROM in the drive. Mount it on /cdrom. (If you use a different mount point, the install will not work.) To begin, change to the directory for the port you want to install: &prompt.root; cd /usr/ports/sysutils/lsof Once inside the lsof directory, you will see the port skeleton. The next step is to compile, or build, the port. This is done by simply typing make at the prompt. Once you have done so, you should see something like this: &prompt.root; make >> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/. >> Attempting to fetch from file:/cdrom/ports/distfiles/. ===> Extracting for lsof-4.57 ... [extraction output snipped] ... >> Checksum OK for lsof_4.57D.freebsd.tar.gz. ===> Patching for lsof-4.57 ===> Applying FreeBSD patches for lsof-4.57 ===> Configuring for lsof-4.57 ... [configure output snipped] ... ===> Building for lsof-4.57 ... [compilation output snipped] ... &prompt.root; Notice that once the compile is complete you are returned to your prompt. The next step is to install the port. In order to install it, you simply need to tack one word onto the make command, and that word is install: &prompt.root; make install ===> Installing for lsof-4.57 ... [installation output snipped] ... ===> Generating temporary packing list ===> Compressing manual pages for lsof-4.57 ===> Registering installation for lsof-4.57 ===> SECURITY NOTE: This port has installed the following binaries which execute with increased privileges. &prompt.root; Once you are returned to your prompt, you should be able to run the application you just installed. Since lsof is a program that runs with increased privileges, a security warning is shown. During the building and installation of ports, you should take heed of any other warnings that may appear. You can save an extra step by just running make install instead of make and make install as two separate steps. Some shells keep a cache of the commands that are available in the directories listed in the PATH environment variable, to speed up lookup operations for the executable file of these commands. If you are using one of these shells, you might have to use the rehash command after installing a port, before the newly installed commands can be used. This is true for both shells that are part of the base-system (such as tcsh) and shells that are available as ports (for instance, shells/zsh). Please be aware that the licenses of a few ports do not allow for inclusion on the CD-ROM. This could be because a registration form needs to be filled out before downloading or redistribution is not allowed, or for another reason. If you wish to install a port not included on the CD-ROM, you will need to be online in order to do so (see the next section). Installing Ports from the Internet As with the last section, this section makes an assumption that you have a working Internet connection. If you do not, you will need to perform the CD-ROM installation, or put a copy of the distfile into /usr/ports/distfiles manually. Installing a port from the Internet is done exactly the same way as it would be if you were installing from a CD-ROM. The only difference between the two is that the distfile is downloaded from the Internet instead of read from the CD-ROM. The steps involved are identical: &prompt.root; make install >> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/. >> Attempting to fetch from ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/. Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100% 439860 bytes transferred in 18.0 seconds (23.90 kBps) ===> Extracting for lsof-4.57 ... [extraction output snipped] ... >> Checksum OK for lsof_4.57D.freebsd.tar.gz. ===> Patching for lsof-4.57 ===> Applying FreeBSD patches for lsof-4.57 ===> Configuring for lsof-4.57 ... [configure output snipped] ... ===> Building for lsof-4.57 ... [compilation output snipped] ... ===> Installing for lsof-4.57 ... [installation output snipped] ... ===> Generating temporary packing list ===> Compressing manual pages for lsof-4.57 ===> Registering installation for lsof-4.57 ===> SECURITY NOTE: This port has installed the following binaries which execute with increased privileges. &prompt.root; As you can see, the only difference is the line that tells you where the system is fetching the port distfile from. The ports system uses &man.fetch.1; to download the files, which honors various environment variables, including FTP_PASSIVE_MODE, FTP_PROXY, and FTP_PASSWORD. You may need to set one or more of these if you are behind a firewall, or need to use an FTP/HTTP proxy. See &man.fetch.3; for the complete list. For users which cannot be connected all the time, the make fetch option is provided. Just run this command at the top level directory (/usr/ports) and the required files will be downloaded for you. This command will also work in the lower level categories, for example: /usr/ports/net. Note that if a port depends on libraries or other ports this will not fetch the distfiles of those ports too. Replace fetch with fetch-recursive if you want to fetch all the dependencies of a port too. You can build all the ports in a category or as a whole by running make in the top level directory, just like the aforementioned make fetch method. This is dangerous, however, as some ports cannot co-exist. In other cases, some ports can install two different files with the same filename. In some rare cases, users may need to acquire the tarballs from a site other than the MASTER_SITES (the location where files are downloaded from). You can override the MASTER_SITES option with the following command: &prompt.root; cd /usr/ports/directory &prompt.root; make MASTER_SITE_OVERRIDE= \ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch In this example we change the MASTER_SITES option to ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/. Some ports allow (or even require) you to provide build options which can enable/disable parts of the application which are unneeded, certain security options, and other customizations. A few which come to mind are www/mozilla, security/gpgme, and mail/sylpheed-claws. A message will be displayed when options such as these are available. Overriding the Default Ports Directories Sometimes it is useful (or mandatory) to use a different distfiles and ports directory. The PORTSDIR and PREFIX variables can override the default directories. For example: &prompt.root; make PORTSDIR=/usr/home/example/ports install will compile the port in /usr/home/example/ports and install everything under /usr/local. &prompt.root; make PREFIX=/usr/home/example/local install will compile it in /usr/ports and install it in /usr/home/example/local. And of course, &prompt.root; make PORTSDIR=../ports PREFIX=../local install will combine the two (it is too long to completely write on this page, but it should give you the general idea). Alternatively, these variables can also be set as part of your environment. Read the manual page for your shell for instructions on doing so. Dealing with <command>imake</command> Some ports that use imake (a part of the X Window System) do not work well with PREFIX, and will insist on installing under /usr/X11R6. Similarly, some Perl ports ignore PREFIX and install in the Perl tree. Making these ports respect PREFIX is a difficult or impossible job. Removing Installed Ports ports removing Now that you know how to install ports, you are probably wondering how to remove them, just in case you install one and later on decide that you installed the wrong port. We will remove our previous example (which was lsof for those of you not paying attention). As with installing ports, the first thing you must do is change to the port directory, /usr/ports/sysutils/lsof. After you change directories, you are ready to uninstall lsof. This is done with the make deinstall command: &prompt.root; cd /usr/ports/sysutils/lsof &prompt.root; make deinstall ===> Deinstalling for lsof-4.57 That was easy enough. You have removed lsof from your system. If you would like to reinstall it, you can do so by running make reinstall from the /usr/ports/sysutils/lsof directory. The make deinstall and make reinstall sequence does not work once you have run make clean. If you want to deinstall a port after cleaning, use &man.pkg.delete.1; as discussed in the Packages section of the Handbook. Ports and Disk Space ports disk-space Using the ports collection will use up disk space over time. For this reason you should always remember to clean up the temporary work directories using the make clean command. This will remove the work directory after a port has been built and installed. You can also remove the source distribution files from the distfiles directory, and remove the installed ports if the need for them has passed. Some users choose to limit the available port categories by placing an entry in the refuse file. This way, when they run the CVSup application, it will not download the files in that category. More information regarding the refuse file can be found in . Upgrading Ports portupgrade ports upgrading Once you updated your ports collection, before attempting a port upgrade, you should check the /usr/ports/UPDATING file. This file describes various issues and additional steps users may encounter and need to perform when updating a port. Keeping your ports up to date can be a tedious job. For instance, to upgrade a port you would go to the ports directory, build the port, deinstall the old port, install the new port, and then clean up after the build. Imagine doing that for five ports, tedious right? This was a large problem for system administrators to deal with, and now we have utilities which do this for us. For instance the sysutils/portupgrade utility will do everything for you! Just install it like you would any other port, using the make install clean command. Now create a database with the pkgdb -F command. This will read the list of installed ports and create a database file in the /var/db/pkg directory. Now when you run portupgrade -a, it will read this and the ports INDEX file. Finally, portupgrade will begin to download, build, backup, install, and clean the ports which have been updated. portupgrade comes with a lot of options for different use cases, the most important ones will be presented below. If you want to upgrade only a certain application, not the complete database, use portupgrade pkgname, include the flags if portupgrade should act on all those packages depending on the given package as well, and to act on all packages required by the given packages. To use packages instead of ports for installation, provide . With this option portupgrade searches the local directories listed in PKG_PATH, or fetches packages from remote site if it is not found locally. If packages can not be found locally or fetched remotely, portupgrade will use ports. To avoid using ports, specify . To just fetch distfiles (or packages, if is specified) without building or installing anything, use . For further information see &man.portupgrade.1;. It is important to regularly update the package database using pkgdb -F to fix inconsistencies, especially when portupgrade asks you to. Do not abort portupgrade while it is updating the package database, this will leave you an inconsistent database. Other utilities exist which will do this, check out the ports/sysutils directory and see what you come up with. Post-installation Activities After installing a new application you will normally want to read any documentation it may have included, edit any configuration files that are required, ensure that the application starts at boot time (if it is a daemon), and so on. The exact steps you need to take to configure each application will obviously be different. However, if you have just installed a new application and are wondering What now? these tips might help: Use &man.pkg.info.1; to find out which files were installed, and where. For example, if you have just installed FooPackage version 1.0.0, then this command &prompt.root; pkg_info -L foopackage-1.0.0 | less will show all the files installed by the package. Pay special attention to files in man/ directories, which will be manual pages, etc/ directories, which will be configuration files, and doc/, which will be more comprehensive documentation. If you are not sure which version of the application was just installed, a command like this &prompt.root; pkg_info | grep -i foopackage will find all the installed packages that have foopackage in the package name. Replace foopackage in your command line as necessary. Once you have identified where the application's manual pages have been installed, review them using &man.man.1;. Similarly, look over the sample configuration files, and any additional documentation that may have been provided. If the application has a web site, check it for additional documentation, frequently asked questions, and so forth. If you are not sure of the web site address it may be listed in the output from &prompt.root; pkg_info foopackage-1.0.0 A WWW: line, if present, should provide a URL for the application's web site. Ports that should start at boot (such as Internet servers) will usually install a sample script in /usr/local/etc/rc.d. You should review this script for correctness and edit or rename it if needed. See Starting Services for more information. Dealing with Broken Ports If you come across a port that does not work for you, there are a few things you can do, including: Fix it! The Porter's Handbook includes detailed information on the Ports infrastructure so that you can fix the occasional broken port or even submit your own! Gripe—by email only! Send email to the maintainer of the port first. Type make maintainer or read the Makefile to find the maintainer's email address. Remember to include the name and version of the port (send the $FreeBSD: line from the Makefile) and the output leading up to the error when you email the maintainer. If you do not get a response from the maintainer, you can use &man.send-pr.1; to submit a bug report. Grab the package from an FTP site near you. The master package collection is on ftp.FreeBSD.org in the packages directory, but be sure to check your local mirror first! These are more likely to work than trying to compile from source and are a lot faster as well. Use the &man.pkg.add.1; program to install the package on your system. diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml index e657ae8d70..e59487c73b 100644 --- a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml @@ -1,1801 +1,1801 @@ Ken Tom Updated for X.Org's X11 server by Marc Fonvieille The X Window System Synopsis FreeBSD uses X11 to provide users with a powerful graphical user interface. X11 is an open-source implementation of the X Window System that includes both &xorg; and &xfree86;. &os; versions up to and including &os; 4.10-RELEASE and &os; 5.2.1-RELEASE will find the default installation to be &xfree86;, the X11 server released by The &xfree86; Project, Inc. As of &os; 5.3-RELEASE, the default and official flavor of X11 was changed to &xorg;, the X11 server developed by the X.Org Foundation. This chapter will cover the installation and configuration of X11 with emphasis on &xorg;. For more information on the video hardware that X11 supports, check either the &xorg; or &xfree86; web sites. After reading this chapter, you will know: The various components of the X Window System, and how they interoperate. How to install and configure X11. How to install and use different window managers. How to use &truetype; fonts in X11. How to set up your system for graphical logins (XDM). Before reading this chapter, you should: Know how to install additional third-party software (). This chapter covers the installation and the configuration of both &xorg; and &xfree86; X11 servers. For the most part, configuration files, commands and syntaxes are identical. In the case where there are differences, both &xorg; and &xfree86; syntaxes will be shown. Understanding X Using X for the first time can be somewhat of a shock to someone familiar with other graphical environments, such as µsoft.windows; or &macos;. While it is not necessary to understand all of the details of various X components and how they interact, some basic knowledge makes it possible to take advantage of X's strengths. Why X? X is not the first window system written for &unix;, but it is the most popular of them. X's original development team had worked on another window system prior to writing X. That system's name was W (for Window). X was just the next letter in the Roman alphabet. X can be called X, X Window System, X11, and a number of other terms. You may find that using the term X Windows to describe X11 can be offensive to some people; for a bit more insight on this, see &man.X.7;. The X Client/Server Model X was designed from the beginning to be network-centric, and adopts a client-server model. In the X model, the X server runs on the computer that has the keyboard, monitor, and mouse attached. The server's responsibility includes tasks such as managing the display, handling input from the keyboard and mouse, and so on. Each X application (such as XTerm, or &netscape;) is a client. A client sends messages to the server such as Please draw a window at these coordinates, and the server sends back messages such as The user just clicked on the OK button. In a home or small office environment, the X server and the X clients commonly run on the same computer. However, it is perfectly possible to run the X server on a less powerful desktop computer, and run X applications (the clients) on, say, the powerful and expensive machine that serves the office. In this scenario the communication between the X client and server takes place over the network. This confuses some people, because the X terminology is exactly backward to what they expect. They expect the X server to be the big powerful machine down the hall, and the X client to be the machine on their desk. It is important to remember that the X server is the machine with the monitor and keyboard, and the X clients are the programs that display the windows. There is nothing in the protocol that forces the client and server machines to be running the same operating system, or even to be running on the same type of computer. It is certainly possible to run an X server on µsoft.windows; or Apple's &macos;, and there are various free and commercial applications available that do exactly that. Starting with &os; 5.3-RELEASE, the X server that installs with &os; is &xorg;, and is available for free, under a license very similar to the FreeBSD license. Commercial X servers for FreeBSD are also available. The Window Manager The X design philosophy is much like the &unix; design philosophy, tools, not policy. This means that X does not try to dictate how a task is to be accomplished. Instead, tools are provided to the user, and it is the user's responsibility to decide how to use those tools. This philosophy extends to X not dictating what windows should look like on screen, how to move them around with the mouse, what keystrokes should be used to move between windows (i.e., Alt Tab , in the case of µsoft.windows;), what the title bars on each window should look like, whether or not they have close buttons on them, and so on. Instead, X delegates this responsibility to an application called a Window Manager. There are dozens of window managers available for X: AfterStep, Blackbox, ctwm, Enlightenment, fvwm, Sawfish, twm, Window Maker, and more. Each of these window managers provides a different look and feel; some of them support virtual desktops; some of them allow customized keystrokes to manage the desktop; some have a Start button or similar device; some are themeable, allowing a complete change of look-and-feel by applying a new theme. These window managers, and many more, are available in the x11-wm category of the Ports Collection. In addition, the KDE and GNOME desktop environments both have their own window managers which integrate with the desktop. Each window manager also has a different configuration mechanism; some expect configuration file written by hand, others feature GUI tools for most of the configuration tasks; at least one (Sawfish) has a configuration file written in a dialect of the Lisp language. Focus Policy Another feature the window manager is responsible for is the mouse focus policy. Every windowing system needs some means of choosing a window to be actively receiving keystrokes, and should visibly indicate which window is active as well. A familiar focus policy is called click-to-focus. This is the model utilized by µsoft.windows;, in which a window becomes active upon receiving a mouse click. X does not support any particular focus policy. Instead, the window manager controls which window has the focus at any one time. Different window managers will support different focus methods. All of them support click to focus, and the majority of them support several others. The most popular focus policies are: focus-follows-mouse The window that is under the mouse pointer is the window that has the focus. This may not necessarily be the window that is on top of all the other windows. The focus is changed by pointing at another window, there is no need to click in it as well. sloppy-focus This policy is a small extension to focus-follows-mouse. With focus-follows-mouse, if the mouse is moved over the root window (or background) then no window has the focus, and keystrokes are simply lost. With sloppy-focus, focus is only changed when the cursor enters a new window, and not when exiting the current window. click-to-focus The active window is selected by mouse click. The window may then be raised, and appear in front of all other windows. All keystrokes will now be directed to this window, even if the cursor is moved to another window. Many window managers support other policies, as well as variations on these. Be sure to consult the documentation for the window manager itself. Widgets The X approach of providing tools and not policy extends to the widgets seen on screen in each application. Widget is a term for all the items in the user interface that can be clicked or manipulated in some way; buttons, check boxes, radio buttons, icons, lists, and so on. µsoft.windows; calls these controls. µsoft.windows; and Apple's &macos; both have a very rigid widget policy. Application developers are supposed to ensure that their applications share a common look and feel. With X, it was not considered sensible to mandate a particular graphical style, or set of widgets to adhere to. As a result, do not expect X applications to have a common look and feel. There are several popular widget sets and variations, including the original Athena widget set from MIT, &motif; (on which the widget set in µsoft.windows; was modeled, all bevelled edges and three shades of grey), OpenLook, and others. Most newer X applications today will use a modern-looking widget set, either Qt, used by KDE, or GTK+, used by the GNOME project. In this respect, there is some convergence in look-and-feel of the &unix; desktop, which certainly makes things easier for the novice user. Installing X11 &xorg; or &xfree86; may be installed on &os;. Beginning with &os; 5.3-RELEASE, &xorg; is the default X11 implementation for &os;. &xorg; is the X11 server of the X11R6.7 distribution released by the X.Org Foundation. X11R6.7 is based on the code of &xfree86 4.4RC2 and X11R6.6. The X.Org Foundation released X11R6.7 in April 2004. To build and install &xorg; from the ports collection: &prompt.root; cd /usr/ports/x11/xorg &prompt.root; make install clean To build &xorg; in its entirety, be sure to have at least 4 GB of free space available. To build and install &xfree86; from the ports collection: &prompt.root; cd /usr/ports/x11/XFree86-4 &prompt.root; make install clean Alternatively, X11 can be installed directly from packages. Binary packages to use with &man.pkg.add.1; tool are also available for X11. When the remote fetching feature of &man.pkg.add.1; is used, the version number of the package must be removed. &man.pkg.add.1; will automatically fetch the latest version of the application. So to fetch and install the package of &xorg;, simply type: &prompt.root; pkg_add -r xorg The &xfree86; 4.X package can be installed by typing: &prompt.root; pkg-add -r XFree86 The examples above will install the complete X11 distribution including the servers, clients, fonts etc. Separate packages and ports of X11 are also available. The rest of this chapter will explain how to configure X11, and how to set up a productive desktop environment. Moving from <application>&xfree86;</application> to <application>&xorg;</application> As with any port, you should check the /usr/ports/UPDATING file for changes. Included in this file are instructions for converting your system from &xfree86; to &xorg;. Use CVSup to update your ports tree prior to attempting any conversion. You will also need to install sysutils/portupgrade prior to converting your X11 installation. In your /etc/make.conf you will need to add the variable X_WINDOW_SYSTEM=xorg. This ensures that your system knows which X11 is being used. The older XFREE86_VERSION variable has been deprecated and has been replaced with the X_WINDOW_SYSTEM variable. Then, use the following commands: &prompt.root; pkg_delete -f /var/db/pkg/imake-4* /var/db/pkg/XFree86-* &prompt.root; cd /usr/ports/x11/xorg &prompt.root; make install clean &prompt.root; pkgdb -F The &man.pkgdb.1; command is part of the portupgrade software and will update various package dependencies. To build &xorg; in its entirety, be sure to have at least 4 GB of free space available. Christopher Shumway Contributed by X11 Configuration &xfree86; 4.X &xfree86; &xorg; X11 Before Starting Before configuration of X11 the following information about the target system is needed: Monitor specifications Video Adapter chipset Video Adapter memory horizontal scan rate vertical scan rate The specifications for the monitor are used by X11 to determine the resolution and refresh rate to run at. These specifications can usually be obtained from the documentation that came with the monitor or from the manufacturer's website. There are two ranges of numbers that are needed, the horizontal scan rate and the vertical synchronization rate. The video adapter's chipset defines what driver module X11 uses to talk to the graphics hardware. With most chipsets, this can be automatically determined, but it is still useful to know in case the automatic detection does not work correctly. Video memory on the graphic adapter determines the resolution and color depth which the system can run at. This is important to know so the user knows the limitations of the system. Configuring X11 Configuration of X11 is a multi-step process. The first step is to build an initial configuration file. As the super user, simply run: &prompt.root; Xorg -configure In the case of &xfree86; type: &prompt.root; XFree86 -configure This will generate an X11 configuration skeleton file in the /root directory called xorg.conf.new (whether you &man.su.1; or do a direct login affects the inherited supervisor $HOME directory variable). For &xfree86;, this configuration file is called XF86Config.new. The X11 program will attempt to probe the graphics hardware on the system and write a configuration file to load the proper drivers for the detected hardware on the target system. The next step is to test the existing configuration to verify that &xorg; can work with the graphics hardware on the target system. To perform this task, type: &prompt.root; Xorg -config xorg.conf.new &xfree86; users will type: &prompt.root; XFree86 -xf86config XF86Config.new If a black and grey grid and an X mouse cursor appear, the configuration was successful. To exit the test, just press Ctrl Alt Backspace simultaneously. If the mouse does not work, you will need to first configure it before proceeding. See in the &os; install chapter. X11 Tuning Next, tune the xorg.conf.new (or XF86Config.new if you are running &xfree86;) configuration file to taste. Open the file in a text editor such as &man.emacs.1; or &man.ee.1;. First, add the frequencies for the target system's monitor. These are usually expressed as a horizontal and vertical synchronization rate. These values are added to the xorg.conf.new file under the "Monitor" section: Section "Monitor" Identifier "Monitor0" VendorName "Monitor Vendor" ModelName "Monitor Model" HorizSync 30-107 VertRefresh 48-120 EndSection The HorizSync and VertRefresh keywords may be missing in the configuration file. If they are, they need to be added, with the correct horizontal synchronization rate placed after the HorizSync keyword and the vertical synchronization rate after the VertRefresh keyword. In the example above the target monitor's rates were entered. X allows DPMS (Energy Star) features to be used with capable monitors. The &man.xset.1; program controls the time-outs and can force standby, suspend, or off modes. If you wish to enable DPMS features for your monitor, you must add the following line to the monitor section: Option "DPMS" xorg.conf XF86Config While the xorg.conf.new (or XF86Config.new) configuration file is still open in an editor, select the default resolution and color depth desired. This is defined in the "Screen" section: Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" DefaultDepth 24 SubSection "Display" Viewport 0 0 Depth 24 Modes "1024x768" EndSubSection EndSection The DefaultDepth keyword describes the color depth to run at by default. This can be overridden with the command line switch to &man.Xorg.1; (or &man.XFree86.1;). The Modes keyword describes the resolution to run at for the given color depth. Note that only VESA standard modes are supported as defined by the target system's graphics hardware. In the example above, the default color depth is twenty-four bits per pixel. At this color depth, the accepted resolution is 1024 by 768 pixels. Finally, write the configuration file and test it using the test mode given above. One of the tools available to assist you during troubleshooting process are the X11 log files, which contain information on each device that the X11 server attaches to. &xorg; log file names are in the format of /var/log/Xorg.0.log (&xfree86; log file names follow the format of XFree86.0.log). The exact name of the log can vary from Xorg.0.log to Xorg.8.log and so forth. If all is well, the configuration file needs to be installed in a common location where &man.Xorg.1; (or &man.XFree86.1;) can find it. This is typically /etc/X11/xorg.conf or /usr/X11R6/etc/X11/xorg.conf (for &xfree86; it is called /etc/X11/XF86Config or /usr/X11R6/etc/X11/XF86Config). &prompt.root; cp xorg.conf.new /etc/X11/xorg.conf For &xfree86;: &prompt.root; cp XF86Config.new /etc/X11/XF86Config The X11 configuration process is now complete. In order to start &xfree86; 4.X with &man.startx.1;, install the x11/wrapper port. &xorg; already includes the wrapper code and does not require the installation of the wrapper port. The X11 server may also be started with the use of &man.xdm.1;. There is also a graphical configuration tool, &man.xorgcfg.1; (&man.xf86cfg.1; for &xfree86;), that comes with the X11 distribution. It allows you to interactively define your configuration by choosing the appropriate drivers and settings. This program can be invoked from the console, by typing the command xorgcfg -textmode. For more details, refer to the &man.xorgcfg.1; and &man.xf86cfg.1; manual pages. Alternatively, there is also a tool called &man.xorgconfig.1; (&man.xf86config.1; for &xfree86;), this program is a console utility that is less user friendly, but it may work in situations where the other tools do not. Advanced Configuration Topics Configuration with &intel; i810 Graphics Chipsets Intel i810 graphic chipset Configuration with &intel; i810 integrated chipsets requires the agpgart AGP programming interface for X11 to drive the card. The &man.agp.4; driver is in the GENERIC kernel since releases 4.8-RELEASE and 5.0-RELEASE. On prior releases, you will have to add the following line: device agp in your kernel configuration file and rebuild a new kernel. Instead, you may want to load the agp.ko kernel module automatically with the &man.loader.8; at boot time. For that, simply add this line to /boot/loader.conf: agp_load="YES" Next, if you are running FreeBSD 4.X or earlier, a device node needs to be created for the programming interface. To create the AGP device node, run &man.MAKEDEV.8; in the /dev directory: &prompt.root; cd /dev &prompt.root; sh MAKEDEV agpgart FreeBSD 5.X or later will use &man.devfs.5; to allocate device nodes transparently, therefore the &man.MAKEDEV.8; step is not required. This will allow configuration of the hardware as any other graphics board. Note on systems without the &man.agp.4; driver compiled in the kernel, trying to load the module with &man.kldload.8; will not work. This driver has to be in the kernel at boot time through being compiled in or using /boot/loader.conf. If you are using &xfree86; 4.1.0 (or later) and messages about unresolved symbols like fbPictureInit appear, try adding the following line after Driver "i810" in the X11 configuration file: Option "NoDDC" Murray Stokely Contributed by Using Fonts in X11 Type1 Fonts The default fonts that ship with X11 are less than ideal for typical desktop publishing applications. Large presentation fonts show up jagged and unprofessional looking, and small fonts in &netscape; are almost completely unintelligible. However, there are several free, high quality Type1 (&postscript;) fonts available which can be readily used with X11. For instance, the URW font collection (x11-fonts/urwfonts) includes high quality versions of standard type1 fonts (Times Roman, Helvetica, Palatino and others). The Freefonts collection (x11-fonts/freefonts) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts. In addition, X11 can be configured to use &truetype; fonts with a minimum of effort. For more details on this, see the &man.X.7; manual page or the section on &truetype; fonts. To install the above Type1 font collections from the ports collection, run the following commands: &prompt.root; cd /usr/ports/x11-fonts/urwfonts &prompt.root; make install clean And likewise with the freefont or other collections. To have the X server detect these fonts, add an appropriate line to the X server configuration file in /etc/X11/ (xorg.conf for &xorg; and XF86Config for &xfree86;), which reads: FontPath "/usr/X11R6/lib/X11/fonts/URW/" Alternatively, at the command line in the X session run: &prompt.user; xset fp+ /usr/X11R6/lib/X11/fonts/URW &prompt.user; xset fp rehash This will work but will be lost when the X session is closed, unless it is added to the startup file (~/.xinitrc for a normal startx session, or ~/.xsession when logging in through a graphical login manager like XDM). A third way is to use the new /usr/X11R6/etc/fonts/local.conf file: see the section on anti-aliasing. &truetype; Fonts TrueType Fonts fonts TrueType Both &xfree86; 4.X and &xorg; have built in support for rendering &truetype; fonts. There are two different modules that can enable this functionality. The freetype module is used in this example because it is more consistent with the other font rendering back-ends. To enable the freetype module just add the following line to the "Module" section of the /etc/X11/xorg.conf or /etc/X11/XF86Config file. Load "freetype" For &xfree86; 3.3.X, a separate &truetype; font server is needed. Xfstt is commonly used for this purpose. To install Xfstt, simply install the port x11-servers/Xfstt. Now make a directory for the &truetype; fonts (for example, /usr/X11R6/lib/X11/fonts/TrueType) and copy all of the &truetype; fonts into this directory. Keep in mind that &truetype; fonts cannot be directly taken from a &macintosh;; they must be in &unix;/&ms-dos;/&windows; format for use by X11. Once the files have been copied into this directory, use ttmkfdir to create a fonts.dir file, so that the X font renderer knows that these new files have been installed. ttmkfdir is available from the FreeBSD Ports Collection as x11-fonts/ttmkfdir. &prompt.root; cd /usr/X11R6/lib/X11/fonts/TrueType &prompt.root; ttmkfdir > fonts.dir Now add the &truetype; directory to the font path. This is just the same as described above for Type1 fonts, that is, use &prompt.user; xset fp+ /usr/X11R6/lib/X11/fonts/TrueType &prompt.user; xset fp rehash or add a FontPath line to the xorg.conf (or XF86Config) file. That's it. Now &netscape;, Gimp, &staroffice;, and all of the other X applications should now recognize the installed &truetype; fonts. Extremely small fonts (as with text in a high resolution display on a web page) and extremely large fonts (within &staroffice;) will look much better now. Joe Marcus Clarke Updated by Anti-Aliased Fonts anti-aliased fonts fonts anti-aliased Anti-aliasing has been available in X11 since &xfree86; 4.0.2. However, font configuration was cumbersome before the introduction of &xfree86; 4.3.0. Beginning with &xfree86; 4.3.0, all fonts in X11 that are found in /usr/X11R6/lib/X11/fonts/ and ~/.fonts/ are automatically made available for anti-aliasing to Xft-aware applications. Not all applications are Xft-aware, but many have received Xft support. Examples of Xft-aware applications include Qt 2.3 and higher (the toolkit for the KDE desktop), GTK+ 2.0 and higher (the toolkit for the GNOME desktop), and Mozilla 1.2 and higher. In order to control which fonts are anti-aliased, or to configure anti-aliasing properties, create (or edit, if it already exists) the file /usr/X11R6/etc/fonts/local.conf. Several advanced features of the Xft font system can be tuned using this file; this section describes only some simple possibilities. For more details, please see &man.fonts-conf.5;. XML This file must be in XML format. Pay careful attention to case, and make sure all tags are properly closed. The file begins with the usual XML header followed by a DOCTYPE definition, and then the <fontconfig> tag: <?xml version="1.0"?> <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> <fontconfig> As previously stated, all fonts in /usr/X11R6/lib/X11/fonts/ as well as ~/.fonts/ are already made available to Xft-aware applications. If you wish to add another directory outside of these two directory trees, add a line similar to the following to /usr/X11R6/etc/fonts/local.conf: <dir>/path/to/my/fonts</dir> After adding new fonts, and especially new font directories, you should run the following command to rebuild the font caches: &prompt.root; fc-cache -f Anti-aliasing makes borders slightly fuzzy, which makes very small text more readable and removes staircases from large text, but can cause eyestrain if applied to normal text. To exclude font sizes smaller than 14 point from anti-aliasing, include these lines: <match target="font"> <test name="size" compare="less"> <double>14</double> </test> <edit name="antialias" mode="assign"> <bool>false</bool> </edit> </match> <match target="font"> <test name="pixelsize" compare="less" qual="any"> <double>14</double> </test> <edit mode="assign" name="antialias"> <bool>false</bool> </edit> </match> fonts spacing Spacing for some monospaced fonts may also be inappropriate with anti-aliasing. This seems to be an issue with KDE, in particular. One possible fix for this is to force the spacing for such fonts to be 100. Add the following lines: <match target="pattern" name="family"> <test qual="any" name="family"> <string>fixed</string> </test> <edit name="family" mode="assign"> <string>mono</string> </edit> </match> <match target="pattern" name="family"> <test qual="any" name="family"> <string>console</string> </test> <edit name="family" mode="assign"> <string>mono</string> </edit> </match> (this aliases the other common names for fixed fonts as "mono"), and then add: <match target="pattern" name="family"> <test qual="any" name="family"> <string>mono</string> </test> <edit name="spacing" mode="assign"> <int>100</int> </edit> </match> Certain fonts, such as Helvetica, may have a problem when anti-aliased. Usually this manifests itself as a font that seems cut in half vertically. At worst, it may cause applications such as Mozilla to crash. To avoid this, consider adding the following to local.conf: <match target="pattern" name="family"> <test qual="any" name="family"> <string>Helvetica</string> </test> <edit name="family" mode="assign"> <string>sans-serif</string> </edit> </match> Once you have finished editing local.conf make sure you end the file with the </fontconfig> tag. Not doing this will cause your changes to be ignored. The default font set that comes with X11 is not very desirable when it comes to anti-aliasing. A much better set of default fonts can be found in the x11-fonts/bitstream-vera port. This port will install a /usr/X11R6/etc/fonts/local.conf file if one does not exist already. If the file does exist, the port will create a /usr/X11R6/etc/fonts/local.conf-vera file. Merge the contents of this file into /usr/X11R6/etc/fonts/local.conf, and the Bitstream fonts will automatically replace the default X11 Serif, Sans Serif, and Monospaced fonts. Finally, users can add their own settings via their personal .fonts.conf files. To do this, each user should simply create a ~/.fonts.conf. This file must also be in XML format. LCD screen Fonts LCD screen One last point: with an LCD screen, sub-pixel sampling may be desired. This basically treats the (horizontally separated) red, green and blue components separately to improve the horizontal resolution; the results can be dramatic. To enable this, add the line somewhere in the local.conf file: <match target="font"> <test qual="all" name="rgba"> <const>unknown</const> </test> <edit name="rgba" mode="assign"> <const>rgb</const> </edit> </match> Depending on the sort of display, rgb may need to be changed to bgr, vrgb or vbgr: experiment and see which works best. Mozilla web browsers Mozilla Mozilla Anti-aliasing should be enabled the next time the X server is started. However, programs must know how to take advantage of it. At present, the Qt toolkit does, so the entire KDE environment can use anti-aliased fonts (see on KDE for details). GTK+ and GNOME can also be made to use anti-aliasing via the Font capplet (see for details). By default, Mozilla 1.2 and greater will automatically use anti-aliasing. To disable this, rebuild Mozilla with the -DWITHOUT_XFT flag. Seth Kingsley Contributed by The X Display Manager Overview X Display Manager The X Display Manager (XDM) is an optional part of the X Window System that is used for login session management. This is useful for several types of situations, including minimal X Terminals, desktops, and large network display servers. Since the X Window System is network and protocol independent, there are a wide variety of possible configurations for running X clients and servers on different machines connected by a network. XDM provides a graphical interface for choosing which display server to connect to, and entering authorization information such as a login and password combination. Think of XDM as providing the same functionality to the user as the &man.getty.8; utility (see for details). That is, it performs system logins to the display being connected to and then runs a session manager on behalf of the user (usually an X window manager). XDM then waits for this program to exit, signaling that the user is done and should be logged out of the display. At this point, XDM can display the login and display chooser screens for the next user to login. Using XDM The XDM daemon program is located in /usr/X11R6/bin/xdm. This program can be run at any time as root and it will start managing the X display on the local machine. If XDM is to be run every time the machine boots up, a convenient way to do this is by adding an entry to /etc/ttys. For more information about the format and usage of this file, see . There is a line in the default /etc/ttys file for running the XDM daemon on a virtual terminal: ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure By default this entry is disabled; in order to enable it change field 5 from off to on and restart &man.init.8; using the directions in . The first field, the name of the terminal this program will manage, is ttyv8. This means that XDM will start running on the 9th virtual terminal. Configuring XDM The XDM configuration directory is located in /usr/X11R6/lib/X11/xdm. In this directory there are several files used to change the behavior and appearance of XDM. Typically these files will be found: File Description Xaccess Client authorization ruleset. Xresources Default X resource values. Xservers List of remote and local displays to manage. Xsession Default session script for logins. Xsetup_* Script to launch applications before the login interface. xdm-config Global configuration for all displays running on this machine. xdm-errors Errors generated by the server program. xdm-pid The process ID of the currently running XDM. Also in this directory are a few scripts and programs used to set up the desktop when XDM is running. The purpose of each of these files will be briefly described. The exact syntax and usage of all of these files is described in &man.xdm.1;. The default configuration is a simple rectangular login window with the hostname of the machine displayed at the top in a large font and Login: and Password: prompts below. This is a good starting point for changing the look and feel of XDM screens. Xaccess The protocol for connecting to XDM controlled displays is called the X Display Manager Connection Protocol (XDMCP). This file is a ruleset for controlling XDMCP connections from remote machines. By default, it allows any client to connect, but that does not matter unless the xdm-config is changed to listen for remote connections. Xresources This is an application-defaults file for the display chooser and the login screens. This is where the appearance of the login program can be modified. The format is identical to the app-defaults file described in the X11 documentation. Xservers This is a list of the remote displays the chooser should provide as choices. Xsession This is the default session script for XDM to run after a user has logged in. Normally each user will have a customized session script in ~/.xsession that overrides this script. Xsetup_* These will be run automatically before displaying the chooser or login interfaces. There is a script for each display being used, named Xsetup_ followed by the local display number (for instance Xsetup_0). Typically these scripts will run one or two programs in the background such as xconsole. xdm-config This contains settings in the form of app-defaults that are applicable to every display that this installation manages. xdm-errors This contains the output of the X servers that XDM is trying to run. If a display that XDM is trying to start hangs for some reason, this is a good place to look for error messages. These messages are also written to the user's ~/.xsession-errors file on a per-session basis. Running a Network Display Server In order for other clients to connect to the display server, edit the access control rules, and enable the connection listener. By default these are set to conservative values. To make XDM listen for connections, first comment out a line in the xdm-config file: ! SECURITY: do not listen for XDMCP or Chooser requests ! Comment out this line if you want to manage X terminals with xdm DisplayManager.requestPort: 0 and then restart XDM. Remember that comments in app-defaults files begin with a ! character, not the usual #. More strict access controls may be desired. Look at the example entries in Xaccess, and refer to the &man.xdm.1; manual page. Replacements for XDM Several replacements for the default XDM program exist. One of them, kdm (bundled with KDE) is described later in this chapter. The kdm display manager offers many visual improvements and cosmetic frills, as well as the functionality to allow users to choose their window manager of choice at login time. Valentino Vaschetto Contributed by Desktop Environments This section describes the different desktop environments available for X on FreeBSD. A desktop environment can mean anything ranging from a simple window manager to a complete suite of desktop applications, such as KDE or GNOME. GNOME About GNOME GNOME GNOME is a user-friendly desktop environment that enables users to easily use and configure their computers. GNOME includes a panel (for starting applications and displaying status), a desktop (where data and applications can be placed), a set of standard desktop tools and applications, and a set of conventions that make it easy for applications to cooperate and be consistent with each other. Users of other operating systems or environments should feel right at home using the powerful graphics-driven environment that GNOME provides. More information regarding GNOME on FreeBSD can be found on the FreeBSD GNOME Project's web site. Installing GNOME The easiest way to install GNOME is through the Desktop Configuration menu during the FreeBSD installation process as described in of Chapter 2. It can also be easily installed from a package or the ports collection: To install the GNOME package from the network, simply type: &prompt.root; pkg_add -r gnome2 To build GNOME from source, use the ports tree: &prompt.root; cd /usr/ports/x11/gnome2 &prompt.root; make install clean Once GNOME is installed, the X server must be told to start GNOME instead of a default window manager. If a custom .xinitrc is already in place, simply replace the line that starts the current window manager with one that starts /usr/X11R6/bin/gnome-session instead. If nothing special has been done to configuration file, then it is enough to simply type: &prompt.user; echo "/usr/X11R6/bin/gnome-session" > ~/.xinitrc Next, type startx, and the GNOME desktop environment will be started. If a display manager, like XDM, is being used, this will not work. Instead, create an executable .xsession file with the same command in it. To do this, edit the file and replace the existing window manager command with /usr/X11R6/bin/gnome-session: &prompt.user; echo "#!/bin/sh" > ~/.xsession &prompt.user; echo "/usr/X11R6/bin/gnome-session" >> ~/.xsession &prompt.user; chmod +x ~/.xsession Another option is to configure the display manager to allow choosing the window manager at login time; the section on KDE details explains how to do this for kdm, the display manager of KDE. Anti-aliased Fonts with GNOME GNOME anti-aliased fonts X11 supports anti-aliasing via its RENDER extension. GTK+ 2.0 and greater (the toolkit used by GNOME) can make use of this functionality. Configuring anti-aliasing is described in . So, with up-to-date software, anti-aliasing is possible within the GNOME desktop. Just go to Applications Desktop Preferences Font, and select either Best shapes, Best contrast, or Subpixel smoothing (LCDs). For a GTK+ application that is not part of the GNOME desktop, set the environment variable GDK_USE_XFT to 1 before launching the program. KDE KDE About KDE KDE is an easy to use contemporary desktop environment. Some of the things that KDE brings to the user are: A beautiful contemporary desktop A desktop exhibiting complete network transparency An integrated help system allowing for convenient, consistent access to help on the use of the KDE desktop and its applications Consistent look and feel of all KDE applications Standardized menu and toolbars, keybindings, color-schemes, etc. Internationalization: KDE is available in more than 40 languages Centralized consisted dialog driven desktop configuration A great number of useful KDE applications KDE has an office application suite based on KDE's KParts technology consisting of a spread-sheet, a presentation application, an organizer, a news client and more. KDE also comes with a web browser called Konqueror, which represents a solid competitor to other existing web browsers on &unix; systems. More information on KDE can be found on the KDE - website. For FreeBSD specific informations and + website. For FreeBSD specific information and resources on KDE, consult the FreeBSD-KDE team's website. Installing KDE Just as with GNOME or any other desktop environment, the easiest way to install KDE is through the Desktop Configuration menu during the FreeBSD installation process as described in of Chapter 2. Once again, the software can be easily installed from a package or from the ports collection: To install the KDE package from the network, simply type: &prompt.root; pkg_add -r kde &man.pkg.add.1; will automatically fetch the latest version of the application. To build KDE from source, use the ports tree: &prompt.root; cd /usr/ports/x11/kde3 &prompt.root; make install clean After KDE has been installed, the X server must be told to launch this application instead of the default window manager. This is accomplished by editing the .xinitrc file: &prompt.user; echo "exec startkde" > ~/.xinitrc Now, whenever the X Window System is invoked with startx, KDE will be the desktop. If a display manager such as XDM is being used, the configuration is slightly different. Edit the .xsession file instead. Instructions for kdm are described later in this chapter. More Details on KDE Now that KDE is installed on the system, most things can be discovered through the help pages, or just by pointing and clicking at various menus. &windows; or &mac; users will feel quite at home. The best reference for KDE is the on-line documentation. KDE comes with its own web browser, Konqueror, dozens of useful applications, and extensive documentation. The remainder of this section discusses the technical items that are difficult to learn by random exploration. The KDE Display Manager KDE display manager An administrator of a multi-user system may wish to have a graphical login screen to welcome users. XDM can be used, as described earlier. However, KDE includes an alternative, kdm, which is designed to look more attractive and include more login-time options. In particular, users can easily choose (via a menu) which desktop environment (KDE, GNOME, or something else) to run after logging on. To begin with, run the KDE control panel, kcontrol, as root. It is generally considered unsafe to run the entire X environment as root. Instead, run the window manager as a normal user, open a terminal window (such as xterm or KDE's konsole), become root with su (the user must be in the wheel group in /etc/group for this), and then type kcontrol. Click on the icon on the left marked System, then on Login manager. On the right there are various configurable options, which the KDE manual will explain in greater detail. Click on sessions on the right. Click New type to add various window managers and desktop environments. These are just labels, so they can say KDE and GNOME rather than startkde or gnome-session. Include a label failsafe. Play with the other menus as well, they are mainly cosmetic and self-explanatory. When you are done, click on Apply at the bottom, and quit the control center. To make sure kdm understands what the labels (KDE, GNOME etc) mean, edit the files used by XDM. In KDE 2.2 this has changed: kdm now uses its own configuration files. Please see the KDE 2.2 documentation for details. In a terminal window, as root, edit the file /usr/X11R6/lib/X11/xdm/Xsession. There is a section in the middle like this: case $# in 1) case $1 in failsafe) exec xterm -geometry 80x24-0-0 ;; esac esac A few lines need to be added to this section. Assuming the labels from used were KDE and GNOME, use the following: case $# in 1) case $1 in kde) exec /usr/local/bin/startkde ;; GNOME) exec /usr/X11R6/bin/gnome-session ;; failsafe) exec xterm -geometry 80x24-0-0 ;; esac esac For the KDE login-time desktop background to be honored, the following line needs to be added to /usr/X11R6/lib/X11/xdm/Xsetup_0: /usr/local/bin/kdmdesktop Now, make sure kdm is listed in /etc/ttys to be started at the next bootup. To do this, simply follow the instructions from the previous section on XDM and replace references to the /usr/X11R6/bin/xdm program with /usr/local/bin/kdm. Anti-aliased Fonts KDE anti-aliased fonts X11 supports anti-aliasing via its RENDER extension, and starting with version 2.3, Qt (the toolkit used by KDE) supports this extension. Configuring this is described in on antialiasing X11 fonts. So, with up-to-date software, anti-aliasing is possible on a KDE desktop. Just go to the KDE menu, go to Preferences Look and Feel Fonts, and click on the check box Use Anti-Aliasing for Fonts and Icons. For a Qt application which is not part of KDE, the environment variable QT_XFT needs to be set to true before starting the program. XFce About XFce XFce is a desktop environment based on the GTK+ toolkit used by GNOME, but is much more lightweight and meant for those who want a simple, efficient desktop which is nevertheless easy to use and configure. Visually, it looks very much like CDE, found on commercial &unix; systems. Some of XFce's features are: A simple, easy-to-handle desktop Fully configurable via mouse, with drag and drop, etc Main panel similar to CDE, with menus, applets and applications launchers Integrated window manager, file manager, sound manager, GNOME compliance module, and other things Themeable (since it uses GTK+) Fast, light and efficient: ideal for older/slower machines or machines with memory limitations More information on XFce can be found on the XFce website. Installing XFce A binary package for XFce exists (at the time of writing). To install, simply type: &prompt.root; pkg_add -r xfce4 Alternatively, to build from source, use the ports collection: &prompt.root; cd /usr/ports/x11-wm/xfce4 &prompt.root; make install clean Now, tell the X server to launch XFce the next time X is started. Simply type this: &prompt.user; echo "/usr/X11R6/bin/startxfce4" > ~/.xinitrc The next time X is started, XFce will be the desktop. As before, if a display manager like XDM is being used, create an .xsession, as described in the section on GNOME, but with the /usr/X11R6/bin/startxfce4 command; or, configure the display manager to allow choosing a desktop at login time, as explained in the section on kdm.