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 767f4c8e22..0c0f737bf5 100644 --- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml @@ -1,4538 +1,4540 @@ Advanced Networking Synopsis The following chapter will cover some of the more frequently used network services on Unix systems. This, of course, will pertain to configuring said services on your FreeBSD system. Coranth Gryphon Contributed Gateways and Routes routing gateway subnet For one machine to be able to find another, 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, send along 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. An example To illustrate different aspects of routing, we will use the following example which is the output of the command netstat -r: 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 foobar.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.foobar.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 it 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 anyway. Ethernet MAC address The next thing that stands out are the 0:e0:... addresses. These are Ethernet hardware 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. In this case the route 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 foobar.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 (ie. 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 of 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 is 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. The final line (destination subnet 224) deals with MultiCasting, which will be covered in a another section. The other column that we should talk about are the Flags. Each route has different attributes that are described in the 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 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, or your hardware device attached to a dedicated data line). 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, with the formed being your PPP connection to your ISP's Terminal Server. Your ISP has a local network at their site, which has, among other things, the server where you connect and a hardware device (T1-GW) attached to the ISP's 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. As a final note, it is common to use the address ...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: 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) 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 as 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 Bridge between the two subnets, is often used when we need to implement packet filtering or firewall security in either or both directions. Routing propagation routing propogation 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 a 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;. Steve Peterson Written Bridging Introduction IP subnet bridge It is sometimes useful to divide one physical network (i.e., 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. and a FreeBSD system with two network interface cards can act as a bridge. The bridge works by learning the MAC layer addresses (i.e., 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 don't want for whatever reason to subnet the network and interconnect the subnets with a router. Let's 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 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 IP Masquerading The second common situation is where firewall functionality is needed without IP Masquerading (NAT). An example is a small company that is connected via DSL or ISDN to their ISP. They have a 13 address global IP allocation for 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 configuration kernel configuration 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 an undocumented 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. If you want the bridged packets to be filtered by &man.ipfw.8;, you should also add net.link.ether.bridge_ipfw=1 as well. Performance My bridge/firewall is a Pentium 90 with one 3Com 3C900B and one 3C905B. The protected side of the network runs at 10mbps half duplex and the connection between the bridge and my router (a Cisco 675) runs at 100mbps full duplex. With no filtering enabled, I've found that the bridge adds about 0.4 milliseconds of latency to pings from the protected 10mbps network to the Cisco 675. Other information If you want to be able to telnet into the bridge from the network, it is OK 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. Bill Swingle Written NFS NFS Among the many different file systems that FreeBSD supports is a very unique type, the Network File System or NFS. NFS allows you to share directories and files on one machine with one or more other machines via the network they are attached to. Using NFS, users and programs can access files on remote systems as if they were local files. NFS has several benefits: Local workstations don't need as much disk space because commonly used data can be stored on a single machine and still remain accessible to everyone on the network. There is no need for users to have unique home directories on every machine on your network. Once they have an established directory that is available via NFS it can be accessed from anywhere. Storage devices such as floppies and CDROM drives can be used by other machines on the network eliminating the need for extra hardware. How It Works NFS is composed of two sides – a client side and a server side. Think of it as a want/have relationship. The client wants the data that the server side has. The server shares its data with the client. In order for this system to function properly a few processes have to be configured and running properly. The server has to be running the following daemons: NFS server portmap mountd nfsd nfsd - The NFS Daemon which services requests from NFS clients. mountd - The NFS Mount Daemon which actually carries out requests that &man.nfsd.8; passes on to it. portmap - The portmapper daemon which allows NFS clients to find out which port the NFS server is using. The client side only needs to run a single daemon: NFS client nfsiod nfsiod - The NFS async I/O Daemon which services requests from its NFS server. Configuring NFS NFS configuration Luckily for us, on a FreeBSD system this setup is a snap. The processes that need to be running can all be run at boot time with a few modifications to your /etc/rc.conf file. On the NFS server make sure you have: portmap_enable="YES" nfs_server_enable="YES" nfs_server_flags="-u -t -n 4" mountd_flags="-r" mountd is automatically run whenever the NFS server is enabled. The and flags to nfsd tell it to serve UDP and TCP clients. The flag tells nfsd to start 4 copies of itself. On the client, make sure you have: nfs_client_enable="YES" nfs_client_flags="-n 4" Like nfsd, the tells nfsiod to start 4 copies of itself. The last configuration step requires that you create a file called /etc/exports. The exports file specifies which file systems on your server will be shared (a.k.a., exported) and with what clients they will be shared. Each line in the file specifies a file system to be shared. There are a handful of options that can be used in this file but only a few will be mentioned here. You can find out about the rest in the &man.exports.5; man page. Here are a few example /etc/exports entries: NFS exporting filesystems The following line exports /cdrom to three silly machines that have the same domain name as the server (hence the lack of a domain name for each) or have entries in your /etc/hosts file. The flag makes the shared file system read-only. With this flag, the remote system will not be able to make any changes to the shared file system. /cdrom -ro moe larry curly The following line exports /home to three hosts by IP address. This is a useful setup if you have a private network but do not have DNS running. The flag allows all the directories below the specified file system to be exported as well. /home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4 The following line exports /a to two machines that have different domain names than the server. The flag allows the root user on the remote system to write to the shared file system as root. Without the -maproot=0 flag even if someone has root access on the remote system they won't be able to modify files on the shared file system. /a -maproot=0 host.domain.com box.example.com In order for a client to share an exported file system it must have permission to do so. Make sure your client is listed in your /etc/exports file. It's important to remember that you must restart mountd whenever you modify /etc/exports so that your changes take effect. This can be accomplished by sending the hangup signal to the mountd process : &prompt.root; kill -HUP `cat /var/run/mountd.pid` Now that you have made all these changes you can just reboot and let FreeBSD start everything for you at boot time or you can run the following commands as root: On the NFS server: &prompt.root; portmap &prompt.root; nfsd -u -t -n 4 &prompt.root; mountd -r On the NFS client: &prompt.root; nfsiod -n 4 Now you should be ready to actually mount a remote file system. This can be done one of two ways. In these examples the server's name will be server and the client's name will be client. If you just want to temporarily mount a remote file system or just want to test out your config you can run a command like this as root on the client: NFS mounting filesystems &prompt.root; mount server:/home /mnt This will mount /home on the server on /mnt on the client. If everything is setup correctly you should be able to go into /mnt on the client and see all the files that are on the server. If you want to permanently (each time you reboot) mount a remote file system you need to add it to your /etc/fstab file. Here is an example line: server:/home /mnt nfs rw 0 0 Read the &man.fstab.5; man page for more options. Practical Uses There are many very cool uses for NFS. Some of the more common ones are listed below. NFS uses Have several machines on a network and share a CDROM or floppy drive among them. This is cheaper and often more convenient. With so many machines on a network, it gets old having your personal files strewn all over the place. You can have a central NFS server that houses all user home directories and shares them with the rest of the machines on the LAN, so no matter where you log in you will have the same home directory. When you get to reinstalling FreeBSD on one of your machines, NFS is the way to go! Just pop your distribution CDROM into your file server and away you go! Have a common /usr/ports/distfiles directory that all your machines share. That way, when you go to install a port that you've already installed on a different machine, you do not have to download the source all over again! John Lind Contributed Problems integrating with other systems Certain Ethernet adapters for ISA PC systems have limitations which can lead to serious network problems, particularly with NFS. This difficulty is not specific to FreeBSD, but FreeBSD systems are affected by it. The problem nearly always occurs when (FreeBSD) PC systems are networked with high-performance workstations, such as those made by Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS mount will work fine, and some operations may succeed, but suddenly the server will seem to become unresponsive to the client, even though requests to and from other systems continue to be processed. This happens to the client system, whether the client is the FreeBSD system or the workstation. On many systems, there is no way to shut down the client gracefully once this problem has manifested itself. The only solution is often to reset the client, because the NFS situation cannot be resolved. Though the correct solution is to get a higher performance and capacity Ethernet adapter for the FreeBSD system, there is a simple workaround that will allow satisfactory operation. If the FreeBSD system is the server, include the option on the mount from the client. If the FreeBSD system is the client, then mount the NFS file system with the option . These options may be specified using the fourth field of the fstab entry on the client for automatic mounts, or by using the parameter of the mount command for manual mounts. It should be noted that there is a different problem, sometimes mistaken for this one, when the NFS servers and clients are on different networks. If that is the case, make certain that your routers are routing the necessary UDP information, or you will not get anywhere, no matter what else you are doing. In the following examples, fastws is the host (interface) name of a high-performance workstation, and freebox is the host (interface) name of a FreeBSD system with a lower-performance Ethernet adapter. Also, /sharedfs will be the exported NFS filesystem (see man exports), and /project will be the mount point on the client for the exported file system. In all cases, note that additional options, such as or and may be desirable in your application. Examples for the FreeBSD system (freebox) as the client: in /etc/fstab on freebox: fastws:/sharedfs /project nfs rw,-r=1024 0 0 As a manual mount command on freebox: &prompt.root; mount -t nfs -o -r=1024 fastws:/sharedfs /project Examples for the FreeBSD system as the server: in /etc/fstab on fastws: freebox:/sharedfs /project nfs rw,-w=1024 0 0 As a manual mount command on fastws: &prompt.root; mount -t nfs -o -w=1024 freebox:/sharedfs /project Nearly any 16-bit Ethernet adapter will allow operation without the above restrictions on the read or write size. For anyone who cares, here is what happens when the failure occurs, which also explains why it is unrecoverable. NFS typically works with a block size of 8k (though it may do fragments of smaller sizes). Since the maximum Ethernet packet is around 1500 bytes, the NFS block gets split into multiple Ethernet packets, even though it is still a single unit to the upper-level code, and must be received, assembled, and acknowledged as a unit. The high-performance workstations can pump out the packets which comprise the NFS unit one right after the other, just as close together as the standard allows. On the smaller, lower capacity cards, the later packets overrun the earlier packets of the same unit before they can be transferred to the host and the unit as a whole cannot be reconstructed or acknowledged. As a result, the workstation will time out and try again, but it will try again with the entire 8K unit, and the process will be repeated, ad infinitum. By keeping the unit size below the Ethernet packet size limitation, we ensure that any complete Ethernet packet received can be acknowledged individually, avoiding the deadlock situation. Overruns may still occur when a high-performance workstations is slamming data out to a PC system, but with the better cards, such overruns are not guaranteed on NFS units. When an overrun occurs, the units affected will be retransmitted, and there will be a fair chance that they will be received, assembled, and acknowledged. Martin Renters Contributed Diskless Operation diskless workstation netboot.com/netboot.rom allow you to boot your FreeBSD machine over the network and run FreeBSD without having a disk on your client. Under 2.0 it is now possible to have local swap. Swapping over NFS is also still supported. Supported Ethernet cards include: Western Digital/SMC 8003, 8013, 8216 and compatibles; NE1000/NE2000 and compatibles (requires recompile) Setup Instructions Find a machine that will be your server. This machine will require enough disk space to hold the FreeBSD 2.0 binaries and have bootp, tftp and NFS services available. Tested machines: HP-UX HP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't work) Solaris Sun/Solaris 2.3. (you may need to get bootp) Set up a bootp server to provide the client with IP address, gateway, netmask. diskless:\ :ht=ether:\ :ha=0000c01f848a:\ :sm=255.255.255.0:\ :hn:\ :ds=192.1.2.3:\ :ip=192.1.2.4:\ :gw=192.1.2.5:\ :vm=rfc1048: TFTP bootp Set up a TFTP server (on same machine as bootp server) to provide booting information to client. The name of this file is cfg.X.X.X.X (or /tftpboot/cfg.X.X.X.X, it will try both) where X.X.X.X is the IP address of the client. The contents of this file can be any valid netboot commands. Under 2.0, netboot has the following commands: help print help list ip print/set client's IP address server print/set bootp/tftp server address netmask print/set netmask hostname name print/set hostname kernel print/set kernel name rootfs print/set root filesystem swapfs print/set swap filesystem swapsize set diskless swapsize in KBytes diskboot boot from disk autoboot continue boot process trans | turn transceiver on|off flags set boot flags A typical completely diskless config file might contain: rootfs 192.1.2.3:/rootfs/myclient swapfs 192.1.2.3:/swapfs swapsize 20000 hostname myclient.mydomain A config file for a machine with local swap might contain: rootfs 192.1.2.3:/rootfs/myclient hostname myclient.mydomain Ensure that your NFS server has exported the root (and swap if applicable) filesystems to your client, and that the client has root access to these filesystems A typical /etc/exports file on FreeBSD might look like: /rootfs/myclient -maproot=0:0 myclient.mydomain /swapfs -maproot=0:0 myclient.mydomain And on HP-UX: /rootfs/myclient -root=myclient.mydomain /swapfs -root=myclient.mydomain NFS swapping over If you are swapping over NFS (completely diskless configuration) create a swap file for your client using dd. If your swapfs command has the arguments /swapfs and the size 20000 as in the example above, the swapfile for myclient will be called /swapfs/swap.X.X.X.X where X.X.X.X is the client's IP address, e.g.: &prompt.root; dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000 Also, the client's swap space might contain sensitive information once swapping starts, so make sure to restrict read and write access to this file to prevent unauthorized access: &prompt.root; chmod 0600 /swapfs/swap.192.1.2.4 Unpack the root filesystem in the directory the client will use for its root filesystem (/rootfs/myclient in the example above). On HP-UX systems: The server should be running HP-UX 9.04 or later for HP9000/800 series machines. Prior versions do not allow the creation of device files over NFS. When extracting /dev in /rootfs/myclient, beware that some systems (HPUX) will not create device files that FreeBSD is happy with. You may have to go to single user mode on the first bootup (press control-c during the bootup phase), cd /dev and do a sh ./MAKEDEV all from the client to fix this. Run netboot.com on the client or make an EPROM from the netboot.rom file Using Shared <filename>/</filename> and <filename>/usr</filename> filesystems Although this is not an officially sanctioned or supported way of doing this, some people report that it works quite well. If anyone has any suggestions on how to do this cleanly, please tell &a.doc;. Compiling netboot for specific setups Netboot can be compiled to support NE1000/2000 cards by changing the configuration in /sys/i386/boot/netboot/Makefile. See the comments at the top of this file. 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 ISDN Cards ISDN cards This section is really only relevant to ISDN users in countries where the DSS1/Q.931 ISDN standard is supported. Some growing number of PC ISDN cards are supported under FreeBSD 2.2.X and up by the isdn4bsd driver package. It is still under development but the reports show that it is successfully used all over Europe. isdn4bsd The latest isdn4bsd version is available from ftp://isdn4bsd@ftp.consol.de/pub/, the main isdn4bsd FTP site (you have to log in as user isdn4bsd , give your mail address as the password and change to the pub directory. Anonymous FTP as user ftp or anonymous will not give the desired result). Isdn4bsd allows you to connect to other ISDN routers using either IP over raw HDLC or by using synchronous PPP. A telephone answering machine application is also available. Many ISDN PC cards are supported, mostly the ones with a Siemens ISDN chipset (ISAC/HSCX), support for other chipsets (from Motorola, Cologne Chip Designs) is currently under development. For an up-to-date list of supported cards, please have a look at the README file. 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 hm@kts.org. A majordomo maintained mailing list is available. To join the list, send mail to &a.majordomo; and specify: subscribe freebsd-isdn in the body of your message. 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 setup. 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 user-land iijPPP. The following TA's are know 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 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.2Kbs, even though you have a 128Kbs connection. To fully utilize the 128Kbs 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 sync/TA v.s. stand-alone router is largely a religious issue. There has been some discussion of this in the mailing lists. I 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 page, 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(or card), and manages its own connection to the other bridge/router. It has all the software to do PPP and other protocols built in. A router will allow you much faster throughput that 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, ie: 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 (Do not admit to owning it) | 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(expensive) models that have two serial ports. Do not confuse this with channel bonding, MPP etc. This can be very useful feature, for example if you have an dedicated ISDN connection at your office and would like to tap into it, but don't want to get another ISDN line at work. A router at the office location can manage a dedicated B channel connection (64Kbs) to the Internet, as well as a use the other B channel for a separate data connection. The second B channel can be used for dial-in, dial-out or dynamically bond(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. Bill Swingle Written Eric Ogren Enahanced Udo Erdelhoff Enhanced NIS/YP What is it? NIS Solaris HP-UX AIX Linux NetBSD OpenBSD NIS, which stands for Network Information Services, was developed by Sun Microsystems to centralize administration of Unix (originally SunOS) systems. It has now essentially become an industry standard; all major Unix systems (Solaris, HP-UX, AIX, Linux, NetBSD, OpenBSD, FreeBSD, etc) support NIS. yellow pagesNIS NIS was formerly known as Yellow Pages, but because of trademark issues, Sun changed the name. The old term (and yp) is still often seen and used. NIS domains It is a RPC-based client/server system that allows a group of machines within an NIS domain to share a common set of configuration files. This permits a system administrator to set up NIS client systems with only minimal configuration data and add, remove or modify configuration data from a single location. Windows NT It is similar to Windows NT's domain system; although the internal implementation of the two aren't at all similar, the basic functionality can be compared. Terms/processes you should know There are several terms and several important user processes that you will come across when attempting to implement NIS on FreeBSD, whether you are trying to create an NIS server or act an NIS client: The NIS domainname. An NIS master server and all of its clients (including its slave servers) have a NIS domainname. Similar to an NT domain name, the NIS domainname does not have anything to do with DNS. portmap portmap. portmap must be running in order to enable RPC (Remote Procedure Call, a network protocol used by NIS). If portmap is not running, it will be impossible to run an NIS server, or to act as an NIS client. ypbind. ypbind “binds” an NIS client to its NIS server. It will take the NIS domainname from the system, and using RPC, connect to the server. ypbind is the core of client-server communication in an NIS environment; if ypbind dies on a client machine, it will not be able to access the NIS server. ypserv. ypserv, which should only be running on NIS servers, is the NIS server process itself. If &man.ypserv.8; dies, then the server will no longer be able to respond to NIS requests (hopefully, there is a slave server to take over for it). There are some implementations of NIS (but not the FreeBSD one), that don't try to reconnect to another server if the server it used before dies. Often, the only thing that helps in this case is to restart the server process (or even the whole server) or the ypbind process on the client. rpc.yppasswdd. rpc.yppasswdd, another process that should only be running on NIS master servers, is a daemon that will allow NIS clients to change their NIS passwords. If this daemon is not running, users will have to login to the NIS master server and change their passwords there. How does it work? There are three types of hosts in an NIS environment; master servers, slave servers, and clients. Servers act as a central repository for host configuration information. Master servers hold the authoritative copy of this information, while slave servers mirror this information for redundancy. Clients rely on the servers to provide this information to them. Information in many files can be shared in this manner. The master.passwd, group, and hosts files are commonly shared via NIS. Whenever a process on a client needs information that would normally be found in these files locally, it makes a query to the server it is bound to, to get this information. Machine types NIS master server A NIS master server. This server, analogous to a Windows NT primary domain controller, maintains the files used by all of the NIS clients. The passwd, group, and other various files used by the NIS clients live on the master server. It is possible for one machine to be an NIS master server for more than one NIS domain. However, this will not be covered in this introduction, which assumes a relatively small-scale NIS environment. NIS slave server NIS slave servers. Similar to NT's backup domain controllers, NIS slave servers maintain copies of the NIS master's data files. NIS slave servers provide the redundancy, which is needed in important environments. They also help to balance the load of the master server: NIS Clients always attach to the NIS server whose response they get first, and this includes slave-server-replies. NIS client NIS clients. NIS clients, like most NT workstations, authenticate against the NIS server (or the NT domain controller in the NT Workstation case) to log on. Using NIS/YP This section will deal with setting up a sample NIS environment. This section assumes that you are running FreeBSD 3.3 or later. The instructions given here will probably work for any version of FreeBSD greater than 3.0, but there are no guarantees that this is true. Planning Let's assume that you are the administrator of a small university lab. This lab, which consists of 15 FreeBSD machines, currently has no centralized point of administration; each machine has its own /etc/passwd and /etc/master.passwd. These files are kept in sync with each other only through manual intervention; currently, when you add a user to the lab, you must run adduser on all 15 machines. Clearly, this has to change, so you have decided to convert the lab to use NIS, using two of the machines as servers. Therefore, the configuration of the lab now looks something like: Machine name IP address Machine role ellington 10.0.0.2 NIS master coltrane 10.0.0.3 NIS slave basie 10.0.0.4 Faculty workstation bird 10.0.0.5 Client machine cli[1-11] 10.0.0.[6-17] Other client machines If you are setting up a NIS scheme for the first time, it is a good idea to think through how you want to go about it. No matter what the size of your network, there are a few decisions that need to be made. Choosing a NIS Domain Name NIS domainname This might not be the domainname that you are used to. It is more accurately called the NIS domainname. When a client broadcasts its requests for info, it includes the name of the NIS domain that it is part of. This is how multiple servers on one network can tell which server should answer which request. Think of the NIS domainname as the name for a group of hosts that are related in some way. Some organizations choose to use their Internet domainname for their NIS domainname. This is not recommended as it can cause confusion when trying to debug network problems. The NIS domainname should be unique within your network and it is helpful if it describes the group of machines it represents. For example, the Art department at Acme Inc. might be in the "acme-art" NIS domain. For this example, assume you have chosen the name test-domain. SunOS However, some operating systems (notably SunOS) use their NIS domain name as their Internet domain name. If one or more machines on your network have this restriction, you must use the Internet domain name as your NIS domain name. Physical Server Requirements There are several things to keep in mind when choosing a machine to use as a NIS server. One of the unfortunate things about NIS is the level of dependency the clients have on the server. If a client cannot contact the server for its NIS domain, very often the machine becomes unusable. The lack of user and group information causes most systems to temporarily freeze up. With this in mind you should make sure to choose a machine that won't be prone to being rebooted regularly, or one that might be used for development. The NIS server should ideally be a stand alone machine whose sole purpose in life is to be an NIS server. If you have a network that is not very heavily used, it is acceptable to put the NIS server on a machine running other services, just keep in mind that if the NIS server becomes unavailable, it will affect all of your NIS clients adversely. NIS Servers The canonical copies of all NIS information are stored on a single machine called the NIS master server. The databases used to store the information are called NIS maps. In FreeBSD, these maps are stored in /var/yp/[domainname] where [domainname] is the name of the NIS domain being served. A single NIS server can support several domains at once, therefore it is possible to have several such directories, one for each supported domain. Each domain will have its own independent set of maps. NIS master and slave servers handle all NIS requests with the ypserv daemon. Ypserv is responsible for receiving incoming requests from NIS clients, translating the requested domain and map name to a path to the corresponding database file and transmitting data from the database back to the client. Setting up a NIS master server NIS server configuration Setting up a master NIS server can be relatively straight forward, depending on your needs. FreeBSD comes with support for NIS out-of-the-box. All you need is to add the following lines to /etc/rc.conf, and FreeBSD will do the rest for you. nisdomainname="test-domain" This line will set the NIS domainname to test-domain upon network setup (e.g. after reboot). nis_server_enable="YES" This will tell FreeBSD to start up the NIS server processes when the networking is next brought up. nis_yppasswdd_enable="YES" This will enable the rpc.yppasswdd daemon, which, as mentioned above, will allow users to change their NIS password from a client machine. Now, all you have to do is to run the command /etc/netstart as superuser. It will setup everything for you, using the values you defined in /etc/rc.conf. Initializing the NIS maps NIS maps The NIS maps are database files, that are kept in the /var/yp directory. They are generated from configuration files in the /etc directory of the NIS master, with one exception: the /etc/master.passwd file. This is for a good reason; you don't want to propagate passwords to your root and other administrative accounts to all the servers in the NIS domain. Therefore, before we initialize the NIS maps, you should: &prompt.root; cp /etc/master.passwd /var/yp/master.passwd &prompt.root; cd /var/yp &prompt.root; vi master.passwd You should remove all entries regarding system accounts (bin, tty, kmem, games, etc), as well as any accounts that you don't want to be propagated to the NIS clients (for example root and any other UID 0 (superuser) accounts). Make sure the /var/yp/master.passwd is neither group nor world readable (mode 600)! Use the chmod command, if appropriate. Tru64 Unix When you have finished, it's time to initialize the NIS maps! FreeBSD includes a script named ypinit to do this for you (see its man page for more information). Note that this script is available on most Unix Operating Systems, but not on all. On Digital Unix/Compaq Tru64 Unix it is called ypsetup. Because we are generating maps for an NIS master, we are going to pass the option to ypinit. To generate the NIS maps, assuming you already performed the steps above, run: ellington&prompt.root; ypinit -m test-domain Server Type: MASTER Domain: test-domain Creating an YP server will require that you answer a few questions. Questions will all be asked at the beginning of the procedure. Do you want this procedure to quit on non-fatal errors? [y/n: n] n Ok, please remember to go back and redo manually whatever fails. If you don't, something might not work. At this point, we have to construct a list of this domains YP servers. rod.darktech.org is already known as master server. Please continue to add any slave servers, one per line. When you are done with the list, type a <control D>. master server : ellington next host to add: coltrane next host to add: ^D The current list of NIS servers looks like this: ellington coltrane Is this correct? [y/n: y] y [..output from map generation..] NIS Map update completed. ellington has been setup as an YP master server without any errors. ypinit should have created /var/yp/Makefile from /var/yp/Makefile.dist. When created, this file assumes that you are operating in a single server NIS environment with only FreeBSD machines. Since test-domain has a slave server as well, you must edit /var/yp/Makefile: ellington&prompt.root; vi /var/yp/Makefile You should comment out the line that says `NOPUSH = "True"' (if it is not commented out already). Setting up a NIS slave server NIS configuring a slave server Setting up an NIS slave server is even more simple than setting up the master. Log on to the slave server and edit the file /etc/rc.conf as you did before. The only difference is that we now must use the option when running ypinit. The option requires the name of the NIS master be passed to it as well, so our command line looks like: coltrane&prompt.root; ypinit -s ellington test-domain Server Type: SLAVE Domain: test-domain Master: ellington Creating an YP server will require that you answer a few questions. Questions will all be asked at the beginning of the procedure. Do you want this procedure to quit on non-fatal errors? [y/n: n] n Ok, please remember to go back and redo manually whatever fails. If you don't, something might not work. There will be no further questions. The remainder of the procedure should take a few minutes, to copy the databases from ellington. Transferring netgroup... ypxfr: Exiting: Map successfully transferred Transferring netgroup.byuser... ypxfr: Exiting: Map successfully transferred Transferring netgroup.byhost... ypxfr: Exiting: Map successfully transferred Transferring master.passwd.byuid... ypxfr: Exiting: Map successfully transferred Transferring passwd.byuid... ypxfr: Exiting: Map successfully transferred Transferring passwd.byname... ypxfr: Exiting: Map successfully transferred Transferring group.bygid... ypxfr: Exiting: Map successfully transferred Transferring group.byname... ypxfr: Exiting: Map successfully transferred Transferring services.byname... ypxfr: Exiting: Map successfully transferred Transferring rpc.bynumber... ypxfr: Exiting: Map successfully transferred Transferring rpc.byname... ypxfr: Exiting: Map successfully transferred Transferring protocols.byname... ypxfr: Exiting: Map successfully transferred Transferring master.passwd.byname... ypxfr: Exiting: Map successfully transferred Transferring networks.byname... ypxfr: Exiting: Map successfully transferred Transferring networks.byaddr... ypxfr: Exiting: Map successfully transferred Transferring netid.byname... ypxfr: Exiting: Map successfully transferred Transferring hosts.byaddr... ypxfr: Exiting: Map successfully transferred Transferring protocols.bynumber... ypxfr: Exiting: Map successfully transferred Transferring ypservers... ypxfr: Exiting: Map successfully transferred Transferring hosts.byname... ypxfr: Exiting: Map successfully transferred coltrane has been setup as an YP slave server without any errors. Don't forget to update map ypservers on ellington. You should now have a directory called /var/yp/test-domain. Copies of the NIS master server's maps should be in this directory. You will need to make sure that these stay updated. The following /etc/crontab entries on your slave servers should do the job: 20 * * * * root /usr/libexec/ypxfr passwd.byname 21 * * * * root /usr/libexec/ypxfr passwd.byuid These two lines force the slave to sync its maps with the maps on the master server. Although this is not mandatory, because the master server tries to make sure any changes to its NIS maps are communicated to its slaves, the password information is so vital to systems that depend on the server, that it is a good idea to force the updates. This is more important on busy networks where map updates might not always complete. Now, run the command /etc/netstart on the slave server as well, which again starts the NIS server. NIS Clients An NIS client establishes what is called a binding to a particular NIS server using the ypbind daemon. ypbind checks the system's default domain (as set by the domainname command), and begins broadcasting RPC requests on the local network. These requests specify the name of the domain for which ypbind is attempting to establish a binding. If a server that has been configured to serve the requested domain receives one of the broadcasts, it will respond to ypbind, which will record the server's address. If there are several servers available (a master and several slaves, for example), ypbind will use the address of the first one to respond. From that point on, the client system will direct all of its NIS requests to that server. Ypbind will occasionally ping the server to make sure it is still up and running. If it fails to receive a reply to one of its pings within a reasonable amount of time, ypbind will mark the domain as unbound and begin broadcasting again in the hopes of locating another server. Setting up an NIS client NIS client configuration Setting up a FreeBSD machine to be a NIS client is fairly straightforward. Edit the file /etc/rc.conf and add the following lines in order to set the NIS domainname and start ypbind upon network startup: nisdomainname="test-domain" nis_client_enable="YES" To import all possible password entries from the NIS server, add this line to your /etc/master.passwd file, using vipw: +::::::::: This line will afford anyone with a valid account in the NIS server's password maps an account. There are many ways to configure your NIS client by changing this line. See the netgroups part below for more information. For more detailed reading see O'Reilly's book on Managing NFS and NIS. To import all possible group entries from the NIS server, add this line to your /etc/group file: +:*:: After completing these steps, you should be able to run ypcat passwd and see the NIS server's passwd map. NIS Security In general, any remote user can issue an RPC to &man.ypserv.8; and retrieve the contents of your NIS maps, provided the remote user knows your domainname. To prevent such unauthorized transactions, &man.ypserv.8; supports a feature called securenets which can be used to restrict access to a given set of hosts. At startup, &man.ypserv.8; will attempt to load the securenets information from a file called /var/yp/securenets. This path varies depending on the path specified with the option. This file contains entries that consist of a network specification and a network mask separated by white space. Lines starting with # are considered to be comments. A sample securenets file might look like this: # allow connections from local host -- mandatory 127.0.0.1 255.255.255.255 # allow connections from any host # on the 192.168.128.0 network 192.168.128.0 255.255.255.0 # allow connections from any host # between 10.0.0.0 to 10.0.15.255 # this includes the machines in the testlab 10.0.0.0 255.255.240.0 If &man.ypserv.8; receives a request from an address that matches one of these rules, it will process the request normally. If the address fails to match a rule, the request will be ignored and a warning message will be logged. If the /var/yp/securenets file does not exist, ypserv will allow connections from any host. The ypserv program also has support for Wietse Venema's tcpwrapper package. This allows the administrator to use the tcpwrapper configuration files for access control instead of /var/yp/securenets. While both of these access control mechanisms provide some security, they, like the privileged port test, are vulnerable to IP spoofing attacks. All NIS-related traffic should be blocked at your firewall. Servers using /var/yp/securenets may fail to serve legitimate NIS clients with archaic TCP/IP implementations. Some of these implementations set all host bits to zero when doing broadcasts and/or fail to observe the subnet mask when calculating the broadcast address. While some of these problems can be fixed by changing the client configuration, other problems may force the retirement of the client systems in question or the abandonment of /var/yp/securenets. Using /var/yp/securenets on a server with such an archaic implementation of TCP/IP is a really bad idea and will lead to loss of NIS functionality for large parts of your network. tcpwrapper The use of the tcpwrapper package increases the latency of your NIS server. The additional delay may be long enough to cause timeouts in client programs, especially in busy networks or with slow NIS servers. If one or more of your client systems suffers from these symptoms, you should convert the client systems in question into NIS slave servers and force them to bind to themselves. Barring some users from logging on In our lab, there is a machine basie that is supposed to be a faculty only workstation. We don't want to take this machine out of the NIS domain, yet the passwd file on the master NIS server contains accounts for both faculty and students. What can we do? There is a way to bar specific users from logging on to a machine, even if they are present in the NIS database. To do this, all you must do is add -username to the end of the /etc/master.passwd file on the client machine, where username is the username of the user you wish to bar from logging in. This should preferably be done using vipw, since vipw will sanity check your changes to /etc/master.passwd, as well as automatically rebuild the password database when you finish editing. For example, if we wanted to bar user bill from logging on to basie we would: basie&prompt.root; vipw [add -bill to the end, exit] vipw: rebuilding the database... vipw: done basie&prompt.root; cat /etc/master.passwd root:[password]:0:0::0:0:The super-user:/root:/bin/csh toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin operator:*:2:5::0:0:System &:/:/sbin/nologin bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin news:*:8:8::0:0:News Subsystem:/:/sbin/nologin man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin +::::::::: -bill basie&prompt.root; Udo Erdelhoff Contributed Using netgroups netgroups The method shown in the previous chapter works reasonably well if you need special rules for a very small number of users and/or machines. On larger networks, you will forget to bar some users from logging onto sensitive machines, or you may even have to modify each machine separately, thus losing the main benefit of NIS, centralized administration. The NIS developers' solution for this problem is called netgroups. Their purpose and semantics can be compared to the normal groups used by Unix file systems. The main differences are the lack of a numeric id and the ability to define a netgroup by including both user accounts and other netgroups. Netgroups were developed to handle large, complex networks with hundreds of users and machines. On one hand, this is a Good Thing if you are forced to deal with such a situation. On the other hand, this complexity makes it almost impossible to explain netgroups with really simple examples. The example used in the remainder of this chapter demonstrates this problem. Let us assume that your successful introduction of NIS in your laboratory caught your superiors' interest. Your next job is to extend your NIS domain to cover some of the other machines on campus. The two tables contain the names of the new users and new machines as well as brief descriptions of them. User Name(s) Description alpha, beta Normal employees of the IT department charlie, delta The new apprentices of the IT department echo, foxtrott, golf, ... Ordinary employees able, baker, ... The current interns Machine Name(s) Description war, death, famine, pollution Your most important servers. Only the IT employees are allowed to log onto these machines. pride, greed, envy, wrath, lust, sloth Less important servers. All members of the IT department are allowed to login onto these machines. one, two, three, four, ... Ordinary workstations. Only the real employees are allowed to use these machines. trashcan A very old machine without any critical data. Even the intern is allowed to use this box. If you tried to implement these restrictions by separately blocking each user, you would have to add one -user line to each system's passwd for each user who is not allowed to login onto that system. If you forget just one entry, you could be in trouble. It may be feasible to do this correctly during the initial setup, however you will eventually forget to add the lines for new users during day-to-day operations. After all, Murphy was an optimist. Handling this situation with netgroups offers several advantages. Each user need not be handled separately; you assign a user to one or more netgroups and allow or forbid logins for all members of the netgroup. If you add a new machine, you will only have to define login restrictions for netgroups. If a new user is added, you will only have to add the user to one or more netgroups. Those changes are independent of each other; no more for each combination of user and machine do... If your NIS setup is planned carefully, you will only have to modify exactly one central configuration file to grant or deny access to machines. The first step is the initialization of the NIS map netgroup. FreeBSD's &man.ypinit.8; does not create this map by default, but its NIS implementation will support it once it has been created. To create an empty map, simply type ellington&prompt.root; vi /var/yp/netgroup and start adding content. For our example, we need at least four netgroups: IT employees, IT apprentices, normal employees and interns. IT_EMP (,alpha,test-domain) (,beta,test-domain) IT_APP (,charlie,test-domain) (,delta,test-domain) USERS (,echo,test-domain) (,foxtrott,test-domain) \ (,golf,test-domain) INTERNS (,able,test-domain) (,baker,test-domain) IT_EMP, IT_APP etc. are the names of the netgroups. Each bracketed group adds one or more user accounts to it. The three fields inside a group are: The name of the host(s) where the following items are valid. If you do not specify a hostname, the entry is valid on all hosts. If you do specify a hostname, you will enter a realm of darkness, horror and utter confusion. The name of the account that belongs to this netgroup. The NIS domain for the account. You can import accounts from other NIS domains into your netgroup if you are one of unlucky fellows with more than one NIS domain. Each of these fields can contain wildcards. See &man.netgroup.5; for details. netgroups Netgroup names longer than 8 characters should not be used, especially if you have machines running other operating systems within your NIS domain. The names are case sensitive; using capital letters for your netgroup names is an easy way to distinguish between user, machine and netgroup names. Some NIS clients (other than FreeBSD) cannot handle netgroups with a large number of entries. For example, some older versions of SunOS start to cause trouble if a netgroup contains more than 15 entries. You can circumvent this limit by creating several sub-netgroups with 15 users or less and a real netgroup that consists of the sub-netgroups: BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...] BIGGRP2 (,joe16,domain) (,joe17,domain) [...] BIGGRP3 (,joe31,domain) (,joe32,domain) BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3 You can repeat this process if you need more than 225 users within a single netgroup. Activating and distributing your new NIS map is easy: ellington&prompt.root; cd /var/yp ellington&prompt.root; make This will generate the three NIS maps netgroup, netgroup.byhost and netgroup.byuser. Use &man.ypcat.1; to check if your new NIS maps are available: ellington&prompt.user; ypcat -k netgroup ellington&prompt.user; ypcat -k netgroup.byhost ellington&prompt.user; ypcat -k netgroup.byuser The output of the first command should resemble the contents of /var/yp/netgroup. The second command will not produce output if you have not specified host-specific netgroups. The third command can be used to get the list of netgroups for a user. The client setup is quite simple. To configure the server war, you only have to start &man.vipw.8; and replace the line +::::::::: with +@IT_EMP::::::::: Now, only the data for the users defined in the netgroup IT_EMP is imported into war's password database and only these users are allowed to login. Unfortunately, this limitation also applies to the ~ function of the shell and all routines converting between user names and numerical user ids. In other words, cd ~user will not work, ls -l will show the numerical id instead of the username and find . -user joe -print will fail with No such user. To fix this, you will have to import all user entries without allowing them to login onto your servers. This can be achieved by adding another line to /etc/master.passwd. This line should contain +:::::::::/sbin/nologin, meaning Import all entries but replace the shell with /sbin/nologin in the imported entries. You can replace any field in the passwd entry by placing a default value in your /etc/master.passwd. Make sure that the line +:::::::::/sbin/nologin is placed after +@IT_EMP:::::::::. Otherwise, all user accounts imported from NIS will have /sbin/nologin as their login shell. After this change, you will only have to change one NIS map if a new employee joins the IT department. You could use a similar approach for the less important servers by replacing the old +::::::::: in their local version of /etc/master.passwd with something like this: +@IT_EMP::::::::: +@IT_APP::::::::: +:::::::::/sbin/nologin The corresponding lines for the normal workstations could be: +@IT_EMP::::::::: +@USERS::::::::: +:::::::::/sbin/nologin And everything would be fine until there is a policy change a few weeks later: The IT department starts hiring interns. The IT interns are allowed to use the normal workstations and the less important servers; and the IT apprentices are allowed to login onto the main servers. You add a new netgroup IT_INTERN, add the new IT interns to this netgroup and start to change the config on each and every machine... As the old saying goes: Errors in centralized planning lead to global mess. NIS' ability to create netgroups from other netgroups can be used to prevent situations like these. One possibility is the creation of role-based netgroups. For example, you could create a netgroup called BIGSRV to define the login restrictions for the important servers, another netgroup called SMALLSRV for the less important servers and a third netgroup called USERBOX for the normal workstations. Each of these netgroups contains the netgroups that are allowed to login onto these machines. The new entries for your NIS map netgroup should look like this: BIGSRV IT_EMP IT_APP SMALLSRV IT_EMP IT_APP ITINTERN USERBOX IT_EMP ITINTERN USERS This method of defining login restrictions works reasonably well if you can define groups of machines with identical restrictions. Unfortunately, this is the exception and not the rule. Most of the time, you will need the ability to define login restrictions on a per-machine basis. Machine-specific netgroup definitions are the other possibility to deal with the policy change outlined above. In this scenario, the /etc/master.passwd of each box contains two lines starting with ``+''. The first of them adds a netgroup with the accounts allowed to login onto this machine, the second one adds all other accounts with /sbin/nologin as shell. It is a good idea to use the ALL-CAPS version of the machine name as the name of the netgroup. In other words, the lines should look like this: +@BOXNAME::::::::: +:::::::::/sbin/nologin Once you have completed this task for all your machines, you will not have to modify the local versions of /etc/master.passwd ever again. All further changes can be handled by modifying the NIS map. Here is an example of a possible netgroup map for this scenario with some additional goodies. # Define groups of users first IT_EMP (,alpha,test-domain) (,beta,test-domain) IT_APP (,charlie,test-domain) (,delta,test-domain) DEPT1 (,echo,test-domain) (,foxtrott,test-domain) DEPT2 (,golf,test-domain) (,hotel,test-domain) DEPT3 (,india,test-domain) (,juliet,test-domain) ITINTERN (,kilo,test-domain) (,lima,test-domain) D_INTERNS (,able,test-domain) (,baker,test-domain) # # Now, define some groups based on roles USERS DEPT1 DEPT2 DEPT3 BIGSRV IT_EMP IT_APP SMALLSRV IT_EMP IT_APP ITINTERN USERBOX IT_EMP ITINTERN USERS # # And a groups for a special tasks # Allow echo and golf to access our anti-virus-machine SECURITY IT_EMP (,echo,test-domain) (,golf,test-domain) # # machine-based netgroups # Our main servers WAR BIGSRV FAMINE BIGSRV # User india needs access to this server POLLUTION BIGSRV (,india,test-domain) # # This one is really important and needs more access restrictions DEATH IT_EMP # # The anti-virus-machine mentioned above ONE SECURITY # # Restrict a machine to a single user TWO (,hotel,test-domain) # [...more groups to follow] If you are using some kind of database to manage your user accounts, you should be able to create the first part of the map with your database's report tools. This way, new users will automatically have access to the boxes. One last word of caution: It may not always be advisable to use machine-based netgroups. If you are deploying a couple dozen or even hundreds of identical machines for student labs, you should use role-based netgroups instead of machine-based netgroups to keep the size of the NIS map within reasonable limits. Important things to remember There are still a couple of things that you will need to do differently now that you are in an NIS environment. Every time you wish to add a user to the lab, you must add it to the master NIS server only, and you must remember to rebuild the NIS maps. If you forget to do this, the new user will not be able to login anywhere except on the NIS master. For example, if we needed to add a new user “jsmith” to the lab, we would: &prompt.root; pw useradd jsmith &prompt.root; cd /var/yp &prompt.root; make test-domain You could also run adduser jsmith instead of pw useradd jsmith. Keep the administration accounts out of the NIS maps. You don't want to be propagating administrative accounts and passwords to machines that will have users that shouldn't have access to those accounts. Keep the NIS master and slave secure, and minimize their downtime. If somebody either hacks or simply turns off these machines, they have effectively rendered many people without the ability to login to the lab. This is the chief weakness of any centralized administration system, and it is probably the most important weakness. If you do not protect your NIS servers, you will have a lot of angry users! NIS v1 compatibility FreeBSD's ypserv has some support for serving NIS v1 clients. FreeBSD's NIS implementation only uses the NIS v2 protocol, however other implementations include support for the v1 protocol for backwards compatibility with older systems. The ypbind daemons supplied with these systems will try to establish a binding to an NIS v1 server even though they may never actually need it (and they may persist in broadcasting in search of one even after they receive a response from a v2 server). Note that while support for normal client calls is provided, this version of ypserv does not handle v1 map transfer requests; consequently, it cannot be used as a master or slave in conjunction with older NIS servers that only support the v1 protocol. Fortunately, there probably are not any such servers still in use today. NIS servers that are also NIS clients Care must be taken when running ypserv in a multi-server domain where the server machines are also NIS clients. It is generally a good idea to force the servers to bind to themselves rather than allowing them to broadcast bind requests and possibly become bound to each other. Strange failure modes can result if one server goes down and others are dependent upon on it. Eventually all the clients will time out and attempt to bind to other servers, but the delay involved can be considerable and the failure mode is still present since the servers might bind to each other all over again. You can force a host to bind to a particular server by running ypbind with the flag. libscrypt v.s. libdescrypt NIS crypto library One of the most common issues that people run into when trying to implement NIS is crypt library compatibility. If your NIS server is using the DES crypt libraries, it will only support clients that are using DES as well. To check which one your server and clients are using look at the symlinks in /usr/lib. If the machine is configured to use the DES libraries, it will look something like this: &prompt.user; ls -l /usr/lib/*crypt* lrwxrwxrwx 1 root wheel 13 Jul 15 08:55 libcrypt.a@ -> libdescrypt.a lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 libcrypt.so@ -> libdescrypt.so lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 libcrypt.so.2@ -> libdescrypt.so.2 lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 libcrypt_p.a@ -> libdescrypt_p.a -r--r--r-- 1 root wheel 13018 Nov 8 14:27 libdescrypt.a lrwxr-xr-x 1 root wheel 16 Nov 8 14:27 libdescrypt.so@ -> libdescrypt.so.2 -r--r--r-- 1 root wheel 12965 Nov 8 14:27 libdescrypt.so.2 -r--r--r-- 1 root wheel 14750 Nov 8 14:27 libdescrypt_p.a If the machine is configured to use the standard FreeBSD MD5 crypt libraries they will look something like this: &prompt.user; ls -l /usr/lib/*crypt* lrwxrwxrwx 1 root wheel 13 Jul 15 08:55 libcrypt.a@ -> libscrypt.a lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 libcrypt.so@ -> libscrypt.so lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 libcrypt.so.2@ -> libscrypt.so.2 lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 libcrypt_p.a@ -> libscrypt_p.a -r--r--r-- 1 root wheel 6194 Nov 8 14:27 libscrypt.a lrwxr-xr-x 1 root wheel 14 Nov 8 14:27 libscrypt.so@ -> libscrypt.so.2 -r--r--r-- 1 root wheel 7579 Nov 8 14:27 libscrypt.so.2 -r--r--r-- 1 root wheel 6684 Nov 8 14:27 libscrypt_p.a If you have trouble authenticating on an NIS client, this is a pretty good place to start looking for possible problems. If you want to deploy an NIS server for a heterogenous network, you will probably have to use DES on all systems because it is the lowest common standard. Greg Sutter Written DHCP What is DHCP? Dynamic Host Configuration Protocol DHCP Internet Software Consortium (ISC) DHCP, the Dynamic Host Configuration Protocol, describes the means by which a system can connect to a network and obtain the necessary information for communication upon that network. FreeBSD uses the ISC (Internet Software Consortium) DHCP implementation, so all implementation-specific information here is for use with the ISC distribution. What This Section Covers This handbook section attempts to describe only the parts of the DHCP system that are integrated with FreeBSD; consequently, the server portions are not described. The DHCP manual pages, in addition to the references below, are useful resources. How it Works UDP When dhclient, the DHCP client, is executed on the client machine, it begins broadcasting requests for configuration information. By default, these requests are on UDP port 68. The server replies on UDP 67, giving the client an IP address and other relevant network information such as netmask, router, and DNS servers. All of this information comes in the form of a DHCP "lease" and is only valid for a certain time (configured by the DHCP server maintainer). In this manner, stale IP addresses for clients no longer connected to the network can be automatically reclaimed. DHCP clients can obtain a great deal of information from the server. An exhaustive list may be found in &man.dhcp-options.5;. FreeBSD Integration FreeBSD fully integrates the ISC DHCP client, dhclient. DHCP client support is provided within both the installer and the base system, obviating the need for detailed knowledge of network configurations on any network that runs a DHCP server. dhclient has been included in all FreeBSD distributions since 3.2. sysinstall DHCP is supported by sysinstall. When configuring a network interface within sysinstall, the first question asked is, "Do you want to try dhcp configuration of this interface?" Answering affirmatively will execute dhclient, and if successful, will fill in the network configuration information automatically. There are two things you must do to have your system use DHCP upon startup: DHCP requirements Make sure that the bpf device is compiled into your kernel. To do this, add pseudo-device bpf to your kernel configuration file, and rebuild the kernel. For more information about building kernels, see . The bpf device is already part of the GENERIC kernel that is supplied with FreeBSD, so if you don't have a custom kernel, you shouldn't need to create one in order to get DHCP working. For those who are particularly security conscious, you should be warned that bpf is also the device that allows packet sniffers to work correctly (although they still have to be run as root). bpf is required to use DHCP, but if you are very sensitive about security, you probably shouldn't add bpf to your kernel in the expectation that at some point in the future you will be using DHCP. Edit your /etc/rc.conf to include the following: ifconfig_fxp0="DHCP" Be sure to replace fxp0 with the designation for the interface that you wish to dynamically configure. If you are using a different location for dhclient, or if you wish to pass additional flags to dhclient, also include the following (editing as necessary): dhcp_program="/sbin/dhclient" dhcp_flags="" DHCP server The DHCP server, dhcpd, is included as part of the isc-dhcp2 port in the ports collection. This port contains the full ISC DHCP distribution, consisting of client, server, relay agent and documentation. Files DHCP configuration files /etc/dhclient.conf dhclient requires a configuration file, /etc/dhclient.conf. Typically the file contains only comments, the defaults being reasonably sane. This configuration file is described by the &man.dhclient.conf.5; man page. /sbin/dhclient dhclient is statically linked and resides in /sbin. The &man.dhclient.8; manual page gives more information about dhclient. /sbin/dhclient-script dhclient-script is the FreeBSD-specific DHCP client configuration script. It is described in &man.dhclient-script.8;, but should not need any user modification to function properly. /var/db/dhclient.leases The DHCP client keeps a database of valid leases in this file, which is written as a log. &man.dhclient.leases.5; gives a slightly longer description. Further Reading The DHCP protocol is fully described in RFC 2131. An informational resource has also been set up at dhcp.org. Chern Lee Contributed DNS Overview BIND FreeBSD utilizes, by default, a version of BIND (Berkeley Internet Name Domain), which is the most common implementation of the DNS protocol. DNS is the protocol through which names are mapped to IP addresses, and vice versa. For example, a query for www.freebsd.org will receive a reply with the IP address of The FreeBSD Project's webpage, whereas, a query for ftp.freebsd.org will return the IP address of the corresponding FTP machine. Likewise, the opposite can happen. A query for an IP address can resolve its hostname. It is not necessary to run a nameserver to perform DNS lookups on a system. DNS DNS is coordinated across the Internet through a somewhat complex system of authoritative root name servers, and other smaller-scale nameservers who host and cache individual domain information. This document refers to BIND 8.x, as it is the stable version used in FreeBSD. BIND 9.x in FreeBSD can be installed through the net/bind9 port. RFC1034 and RFC1035 dictates the DNS protocol. Currently, BIND is maintained by the Internet Software Consortium (www.isc.org) Terminology To understand this document, some terms related to DNS must be understood. Term Definition forward dns mapping of hostnames to IP addresses origin refers to the domain covered for the particular zone file named, bind, name server common names for the BIND name server package within FreeBSD resolver resolver a system process through which a machine queries a nameserver for zone information reverse dns reverse DNS the opposite of forward DNS, mapping of IP addresses to hostnames root zone root zone literally, a ., refers to the root, or beginning zone. All zones fall under this, as do all files in fall under the root directory. It is the beginning of the Internet zone hierarchy. zone Each individual domain, subdomain, or area dictated by DNS + zones examples Examples of zones: . is the root zone org. is a zone under the root zone foobardomain.org is a zone under the org. zone foo.foobardomain.org. is a subdomain, a zone under the foobardomain.org. zone 1.2.3.in-addr.arpa is a zone referencing all IP addresses which fall under the 3.2.1.* IP space. As one can see, the more specific part of a hostname appears to its left. For example, foobardomain.org. is more specific than org., as org. is more specific than the root zone. The layout of each part of a hostname is much like a filesystem: the /dev directory falls within the root, and so on. Reasons to run a name server Name servers usually come in two forms: an authoritative name server, and a caching nameserver. An authoritative name server is needed when: one wants to serve DNS information to the world, replying authoritatively to queries. a domain, such as foobardomain.org, is registered and IP addresses need to be assigned to hostnames under it. an IP address block requires reverse DNS entries (IP to hostname). a backup name server, called a slave, must reply to queries when the primary is down or inaccessible. A caching name server is needed when: a local DNS server may cache and respond more quickly then querying an outside name server. a reduction in overall network traffic is desired. (DNS traffic has been measured to account for 5% or more of total Internet traffic) When one queries for www.freebsd.org, the resolver usually queries the uplink ISP's name server, and retrieves the reply. With a local, caching DNS server, the query only has to be made once to the outside world by the caching DNS server. Every additional query will not have to look to the outside of the local network, since the information is cached locally. How it works In FreeBSD, the BIND daemon is called named for obvious reasons. File Description named the BIND daemon ndc name daemon control program /etc/namedb directory where BIND zone information resides /etc/namedb/named.conf daemon configuration file Zone files are usually contained within the /etc/namedb directory, and contain the DNS zone information served by the name server. Starting BIND BIND starting Since BIND is installed by default, configuring it all is relatively simple. To ensure the named daemon is started at boot, put the following modifications in /etc/rc.conf: named_enable="YES" To start the daemon manually (after configuring it) &prompt.root; ndc start Configuration files BIND configuration files make-localhost Be sure to: &prompt.root; cd /etc/namedb &prompt.root; sh make-localhost to properly create the local reverse dns zone file in /etc/namedb/localhost.rev. <filename>/etc/namedb/named.conf</filename> // $FreeBSD$ // // Refer to the named(8) man page for details. If you are ever going // to setup a primary server, make sure you've understood the hairy // details of how DNS is working. Even with simple mistakes, you can // break connectivity for affected parties, or cause huge amount of // useless Internet traffic. options { directory "/etc/namedb"; // In addition to the "forwarders" clause, you can force your name // server to never initiate queries of its own, but always ask its // forwarders only, by enabling the following line: // // forward only; // If you've got a DNS server around at your upstream provider, enter // its IP address here, and enable the line below. This will make you // benefit from its cache, thus reduce overall DNS traffic in the Internet. /* forwarders { 127.0.0.1; }; */ Just as the comment says, to benefit from an uplink's cache, forwarders can be enabled here. Under normal circumstances, a nameserver will recursively query the Internet looking at certain nameservers until it finds the answer it is looking for. Having this enabled will have it query the uplink's nameserver (or nameserver provided) first, taking advantage of its cache. If the uplink nameserver in question is a heavily trafficked, fast nameserver, enabling this may be worthwhile. 127.0.0.1 will not work here. Change this IP address to a nameserver at your uplink. /* * If there is a firewall between you and nameservers you want * to talk to, you might need to uncomment the query-source * directive below. Previous versions of BIND always asked * questions using port 53, but BIND 8.1 uses an unprivileged * port by default. */ // query-source address * port 53; /* * If running in a sandbox, you may have to specify a different * location for the dumpfile. */ // dump-file "s/named_dump.db"; }; // Note: the following will be supported in a future release. /* host { any; } { topology { 127.0.0.0/8; }; }; */ // Setting up secondaries is way easier and the rough picture for this // is explained below. // // If you enable a local name server, don't forget to enter 127.0.0.1 // into your /etc/resolv.conf so this server will be queried first. // Also, make sure to enable it in /etc/rc.conf. zone "." { type hint; file "named.root"; }; zone "0.0.127.IN-ADDR.ARPA" { type master; file "localhost.rev"; }; zone "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.INT" { type master; file "localhost.rev"; }; // NB: Do not use the IP addresses below, they are faked, and only // serve demonstration/documentation purposes! // // Example secondary config entries. It can be convenient to become // a secondary at least for the zone where your own domain is in. Ask // your network administrator for the IP address of the responsible // primary. // // Never forget to include the reverse lookup (IN-ADDR.ARPA) zone! // (This is the first bytes of the respective IP address, in reverse // order, with ".IN-ADDR.ARPA" appended.) // // Before starting to setup a primary zone, better make sure you fully // understand how DNS and BIND works, however. There are sometimes // unobvious pitfalls. Setting up a secondary is comparably simpler. // // NB: Don't blindly enable the examples below. :-) Use actual names // and addresses instead. // // NOTE!!! FreeBSD runs bind in a sandbox (see named_flags in rc.conf). // The directory containing the secondary zones must be write accessible // to bind. The following sequence is suggested: // // mkdir /etc/namedb/s // chown bind:bind /etc/namedb/s // chmod 750 /etc/namedb/s For more information on running BIND in a sandbox, see Running named in a sandbox. /* zone "domain.com" { type slave; file "s/domain.com.bak"; masters { 192.168.1.1; }; }; zone "0.168.192.in-addr.arpa" { type slave; file "s/0.168.192.in-addr.arpa.bak"; masters { 192.168.1.1; }; }; */ In named.conf, these are examples of slave entries for a forward and reverse zone. For each new zone served, a new zone entry must be added to named.conf For example, the simplest zone entry for foobardomain.org can look like: zone "foobardomain.org" { type master; file "foobardomain.org"; }; The zone is a master, as indicated by the statement, holding its zone information in /etc/namedb/foobardomain.org indicated by the statement. zone "foobardomain.org" { type slave; file "foobardomain.org"; }; In the slave case, the zone information is transferred from the master nameserver for the particular zone, and saved in the file specified. If and when the master server dies or is unreachable, the slave nameserver will have the transferred zone information and will be able to serve it. Zone files An example master zone file for foobardomain.org (existing within /etc/namedb/foobardomain.org) is as follows: $TTL 3600 foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. ( 5 ; Serial 10800 ; Refresh 3600 ; Retry 604800 ; Expire 86400 ) ; Minimum TTL ; DNS Servers @ IN NS ns1.foobardomain.org. @ IN NS ns2.foobardomain.org. ; Machine Names localhost IN A 127.0.0.1 ns1 IN A 3.2.1.2 ns2 IN A 3.2.1.3 mail IN A 3.2.1.10 @ IN A 3.2.1.30 ; Aliases www IN CNAME @ ; MX Record @ IN MX 10 mail.foobardomain.org. Note that every hostname ending in a . is an exact hostname, whereas everything without a trailing . is referenced to the origin. For example, www is translated into www + origin. In our fictitious zone file, our origin is foobardomain.org., so www would translate to www.foobardomain.org. The format of a zone file follows: recordname IN recordtype value DNS records The most commonly used DNS records: SOA start of zone authority NS an authoritative nameserver A A host address CNAME the canonical name for an alias MX mail exchange PTR a domain name pointer (used in reverse dns) foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. ( 5 ; Serial 10800 ; Refresh after 3 hours 3600 ; Retry after 1 hour 604800 ; Expire after 1 week 86400 ) ; Minimum TTL of 1 day foobardomain.org. the domain name, also the origin for this zone file. ns1.foobardomain.org. the primary/authoritative nameserver for this zone admin.foobardomain.org. the responsible person for this zone, email address with @ replaced. (admin@foobardomain.org becomes admin.foobardomain.org) - 5 + 5 the serial number of the file. this must be incremented each time the zone file is modified. Nowadays, many admins prefer a yyyymmddrr format for the serial number. 2001041002 would mean last modified 04/10/2001, the latter 02 being the second time the zone file has been modified this day. The serial number is important as it alerts slave nameservers for a zone when it is updated. @ IN NS ns1.foobardomain.org. This is an NS entry. Every nameserver that is going to reply authoritatively for the zone must have one of these entries. The @ as seen here could have been foobardomain.org. The @ translates to the origin. localhost IN A 127.0.0.1 ns1 IN A 3.2.1.2 ns2 IN A 3.2.1.3 mail IN A 3.2.1.10 @ IN A 3.2.1.30 The A record indicates machine names. As seen above, ns1.foobardomain.org would resolve to 3.2.1.2. Again, the origin symbol, @, is used here, thus meaning foobardomain.org would resolve to 3.2.1.30. www IN CNAME @ The canonical name record is usually used for giving aliases to a machine. In the example, www is aliased to the machine addressed to the origin, or foobardomain.org (3.2.1.30). CNAMEs can be used to provide alias hostnames, or round robin one hostname among multiple machines. @ IN MX 10 mail.foobardomain.org. The MX record indicates which mail servers are responsible for handling incoming mail for the zone. mail.foobardomain.org is the hostname of the mail server, and 10 being the priority of that mailserver. One can have several mailservers, with priorities of 3, 2, 1. A mail server attempting to deliver to foobardomain.org would first try the highest priority MX, then the second highest, etc, until the mail can be properly delivered. For in-addr.arpa zone files (reverse dns), the same format is used, except with PTR entries instead of A or CNAME. $TTL 3600 1.2.3.in-addr.arpa. IN SOA ns1.foobardomain.org. admin.foobardomain.org. ( 5 ; Serial 10800 ; Refresh 3600 ; Retry 604800 ; Expire 3600 ) ; Minimum @ IN NS ns1.foobardomain.org. @ IN NS ns2.foobardomain.org. 2 IN PTR ns1.foobardomain.org. 3 IN PTR ns2.foobardomain.org. 10 IN PTR mail.foobardomain.org. 30 IN PTR foobardomain.org. This file gives the proper IP address to hostname mappings of our above fictitious domain. Caching Name Server BIND caching name server A caching nameserver is a nameserver that is not authoritative for any zones. It simply asks queries of its own, and remembers them for later use. To set one up, just configure the name server as usual, omitting any inclusions of zones. Mike Makonnen Contributed Running named in a Sandbox BIND running in a sandbox chroot For added security you may want to run &man.named.8; in a sandbox. This will reduce the potential damage should it be compromised. If you include a sandbox directory in its command line, named will &man.chroot.8; into that directory immediately upon finishing processing its command line. It is also a good idea to have named run as a non-privileged user in the sandbox. The default FreeBSD install contains a user bind with group bind. If we wanted the sandbox in the /etc/namedb/sandbox directory the command line for named would look like this: &prompt.root; /usr/sbin/named -u bind -g bind -t /etc/namedb/sandbox <path_to_named.conf> The following steps should be taken in order to successfully run named in a sandbox. Throughout the following discussion we will assume the path to your sandbox is /etc/namedb/sandbox Create the sandbox directory: /etc/namedb/sandbox Create other necessary directories off of the sandbox directory: etc and var/run copy /etc/localtime to sandbox/etc make bind:bind the owner of all files and directories in the sandbox: &prompt.root; chown -R bind:bind /etc/namedb/sandbox &prompt.root; chmod -R 750 /etc/namedb/sandbox There are some issues you need to be aware of when running named in a sandbox. Your &man.named.conf.5; file and all your zone files must be in the sandbox sandbox/etc/localtime is needed in order to have the correct time for your time zone in log messages. &man.named.8; will write its process id to a file in sandbox/var/run The Unix socket used for communication by the &man.ndc.8; utility will be created in sandbox/var/run When using the &man.ndc.8; utility you need to specify the location of the Unix socket created in the sandbox, by &man.named.8;, by using the -c switch: &prompt.root; ndc -c /etc/namedb/sandbox/var/run/ndc If you enable logging to file, the log files must be in the sandbox &man.named.8; can be started in a sandbox properly, if the following is in /etc/rc.conf: named_flags="-u bind -g bind -t /etc/namedb/sandbox <path_to_named.conf>" How to use the nameserver If setup properly, the nameserver should be accessible through the network and locally. /etc/resolv.conf must contain a nameserver entry with the local IP address so it will query the local name server first. To access it over the network, the machine must have the nameserver's IP address set properly in its own nameserver configuration options. Security Although BIND is the most common implementation of DNS, there is always the issue of security. Possible and exploitable security holes are sometimes found. It is a good idea to subscribe to CERT and freebsd-announce to stay up to date with the current Internet and FreeBSD security issues. If a problem arises, keeping sources up to date and having a fresh build of named would not hurt. Further Reading BIND/named man pages: &man.ndc.8; &man.named.8; &man.named.conf.5; Official ISC Bind Page BIND FAQ O'Reilly DNS and BIND 4th Edition RFC1034 - Domain Names - Concepts and Facilities RFC1035 - Domain Names - Implementation and Specification Chern Lee Contributed Network Address Translation daemon (natd) 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. natd 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 in more and more 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 With this setup, the machine without Internet access can use the machine with access as a gateway to access the outside world. 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="" gateway_enable="YES" Sets up the machine to act as a gateway. Running sysctl -w net.inet.ip.forwarding=1 would have the same effect. firewall_enable="YES" Enables the firewall rules in /etc/rc.firewall at boot. firewall_type="OPEN" This specifies a predefined firewall ruleset that allows anything in. See /etc/rc.firewall for additional types. natd_interface="fxp0" Indicates which interface to forward packets through. (the interface connected to the Internet) natd_flags="" 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. 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 natd to work. Port Redirection The drawback with natd 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 -redirect_port 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 -redirect_port 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; or placed within the natd_flags="" option in /etc/rc.conf. 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 -redirect_address syntax is as follows: 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: Like -redirect_port, these arguments are also placed within natd_flags of /etc/rc.conf. 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. Chern Lee Contributed inetd <quote>Super-Server</quote> Overview &man.inetd.8; is referred to as the Internet Super-Server because it manages connections for several daemons. Programs that provide network service are commonly known as daemons. inetd serves as a managing server for other daemons. When a connection is received by inetd, it determines which daemon the connection is destined for, spawns the particular daemon and delegates the socket to it. Running one instance of inetd reduces the overall system load as compared to running each daemon individually in stand-alone mode. Primarily, inetd is used to spawn other daemons, but several trivial protocols are handled directly, such as chargen, auth, and daytime. This section will cover the basics in configuring inetd through its command-line options and it's configuration file, /etc/inetd.conf. Settings inetd is initialized through the /etc/rc.conf system. The inetd_enable option is set to NO by default, but is often times turned on by sysinstall with the medium security profile. Placing: inetd_enable="YES" or inetd_enable="NO" into /etc/rc.conf can enable or disable inetd starting at boot time. Additionally, different command-line options can be passed to inetd via the inetd_flags option. Command-Line Options inetd sypnosis: -d Turn on debugging. -l Turn on logging of successful connections. -w Turn on TCP Wrapping for external services. (on by default) -W Turn on TCP Wrapping for internal services which are built in to inetd. (on by default) -c maximum Specify the default maximum number of simultaneous invocations of each service; the default is unlimited. May be overridden on a per-service basis with the parameter. -C rate Specify the default maximum number of times a service can be invoked from a single IP address in one minute; the default is unlimited. May be overridden on a per-service basis with the parameter. -R rate Specify the maximum number of times a service can be invoked in one minute; the default is 256. A rate of 0 allows an unlimited number of invocations. -a Specify one specific IP address to bind to. Alternatively, a hostname can be specified, in which case the IPv4 or IPv6 address which corresponds to that hostname is used. Usually a hostname is specified when inetd is run inside a &man.jail.8;, in which case the hostname corresponds to the &man.jail.8; environment. When hostname specification is used and both IPv4 and IPv6 bindings are desired, one entry with the appropriate protocol type for each binding is required for each service in /etc/inetd.conf. For example, a TCP-based service would need two entries, one using ``tcp4'' for the protocol and the other using ``tcp6''. -p Specify an alternate file in which to store the process ID. These options can be passed to inetd using the inetd_flags option in /etc/rc.conf. By default, inetd_flags is set to -wW, which turns on TCP wrapping for inetd's internal and external services. For novice users, these parameters usually do not need to be modified or even entered in /etc/rc.conf An external service is a daemon outside of inetd, which is invoked when a connection is received for it. On the other hand, an internal service is one that inetd has the facility of offering within itself. <filename>inetd.conf</filename> Configuration of inetd is controlled through the /etc/inetd.conf file. When a modification is made to /etc/inetd.conf, inetd can be forced to re-read its configuration file by sending a HangUP signal to the inetd process as shown: Sending <application>inetd</application> a HangUP signal &prompt.root kill -HUP `cat /var/run/inetd.pid` Each line of the configuration file specifies an individual daemon. Comments in the file are preceded by a #. The format of /etc/inetd.conf is as follows: service-name socket-type protocol {wait|nowait}[/max-child[/max-connections-per-ip-per-minute]] user[:group][/login-class] server-program server-program-arguments An example entry for the ftpd daemon using IPv4: ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l service-name This is the service name of the particular daemon. It must correspond to a service listed in /etc/services. This determines which port inetd must listen to. If a new service is being created, it must be placed in /etc/services first. socket-type Either stream, dgram, raw, or seqpacket. stream must be used for connection-based, TCP daemons, while dgram is used for daemons utilizing the UDP transport protocol. protocol One of the following: Protocol Explanation tcp, tcp4 TCP IPv4 udp, udp4 UDP IPv4 tcp6 TCP IPv6 udp6 UDP IPv6 tcp46 Both TCP IPv4 and v6 udp46 Both UDP IPv4 and v6 + {wait|nowait}[/max-child[/max-connections-per-ip-per-minute]] indicates whether the daemon invoked from inetd is able to handle its own socket or not. socket types must use the wait option, while stream socket daemons, which are usually multi-threaded, should use . usually hands off multiple sockets to a single daemon, while spawns a child daemon for each new socket. The maximum number of child daemons inetd may spawn can be set using the option. If a limit of ten instances of a particular daemon is needed, a /10 would be placed after . In addition to another option limiting the maximum connections from a single place to a particular daemon can be enabled. does just this. A value of ten here would limit any particular IP address connecting to a particular service to ten attempts per minute. This is useful to prevent intentional or unintentional resource consumption and Denial of Service (DoS) attacks to a machine. In this field, or is mandatory. and are optional. A stream-type multi-threaded daemon without any or limits would simply be: nowait The same daemon with a maximum limit of ten daemons would read: nowait/10 Additionally, the same setup with a limit of twenty connections per IP address per minute and a maximum total limit of ten child daemons would read: nowait/10/20 These options are all utilized by the default settings of the fingerd daemon, as seen here: finger stream tcp nowait/3/10 nobody /usr/libexec/fingerd fingerd -s user The user is the username that the particular daemon should run as. Most commonly, daemons run as the root user. For security purposes, it is common to find some servers running as the daemon user, or the least privileged nobody user. server-program The full path of the daemon to be executed when a connection is received. If the daemon is a service provided by inetd internally, then should be used. server-program-arguments This works in conjunction with by specifying the arguments, starting with argv[0], passed to the daemon on invocation. If mydaemon -d is the command line, mydaemon -d would be the value of . Again, if the daemon is an internal service, use here. Security Depending on the security profile chosen at install, many of inetd's daemons may be enabled by default. If there is no apparent need for a particular daemon, disable it! Place a # in front of the daemon in question, and send a hangup signal to inetd. Some daemons, such as fingerd, may not be desired at all because they provide an attacker with too much information. Some daemons are not security-concious and have long, or non-existent timeouts for connection attempts. This allows an attacker to slowly send connections to a particular daemon, thus saturating available resources. It may be a good idea to place and limitations on certain daemons. By default, TCP wrapping is turned on. Consult the &man.hosts.access.5; man page for more information on placing TCP restrictions on various inetd - invoked daemons. + invoked daemons. Miscellaneous daytime, time, echo, discard, chargen, and auth are all internally provided services of inetd. The auth service provides identity (ident, identd) network services, and is configurable to a certain degree. Consult the &man.inetd.8; man page for more in-depth information. diff --git a/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml b/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml index 242d89f43c..e242a377f7 100644 --- a/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml @@ -1,368 +1,368 @@ Moses Moore Contributed Sound Synopsis FreeBSD supports a wide variety of sound cards, allowing you to enjoy high fidelity output from your computer. This includes the ability to record and playback audio in the MPEG Audio Layer 3 (MP3), WAV, and Ogg Vorbis formats as well as many other formats. The FreeBSD Ports Collection also contains applications allowing you to edit your recorded audio, add sound effects, and control attached MIDI devices. After reading this chapter you will know: How to locate your sound card. How to configure your system so that your sound card is recognized. Methods to test that your card is working using sample applications. How to troubleshoot your sound setup. - Before reading this chapter you should: + Before reading this chapter you should: Know how to configure and install a new kernel () Locating the Correct Device PCI ISA sound cards Before you begin, you should know the model of the card you have, the chip it uses, and whether it is a PCI or ISA card. FreeBSD supports a wide variety of both PCI and ISA cards. If you do not see your card in the following list, check the &man.pcm.4; manual page. This is not a complete list; however, it does list some of the most common cards. Crystal 4237, 4236, 4232, 4231 Yamaha OPL-SAx OPTi931 Ensoniq AudioPCI 1370/1371 ESS Solo-1/1E NeoMagic 256AV/ZX Sound Blaster Pro, 16, 32, AWE64, AWE128, Live Creative ViBRA16 Advanced Asound 100, 110, and Logic ALS120 ES 1868, 1869, 1879, 1888 Gravis UltraSound Aureal Vortex 1 or 2 kernel configuration The driver you use in your kernel depends on the kind of card you have. The sections below provide more information and what you will need to add to your kernel configuration. Creative, Advance, and ESS Sound Cards If you have one of the above cards, you will need to add device pcm to your kernel. If you have a PnP ISA card, you will also need to add device sbc to your kernel. For a non-PnP ISA card, add device pcm and device sbc0 at isa? port0x220 irq 5 drq 1 flags 0x15 to your kernel. Those are the default settings. You may need to change the IRQ, etc. See the &man.sbc.4; man page for more information. The Sound Blaster Live is not supported under FreeBSD 4.0 without a patch, which this document will not cover. It is recommended that you update to the latest -STABLE before trying to use this card. Gravis UltraSound Cards For a PnP ISA card, you will need to add device pcm and device gusc to your kernel. If you have a non-PnP ISA card, you will need to add device pcm and device gus0 at isa? port 0x220 irq 5 drq 1 flags 0x13 to your kernel. You may need to change the IRQ, etc. See the &man.gusc.4; man page for more information. Crystal Sound Cards For Crystal cards, you will need both device pcm and device csa in your kernel. Generic Support For PnP ISA or PCI cards, you will need to add device pcm to your kernel configuration. If you have a non-PnP ISA sound card that does not have a bridge driver, you will need to add device pcm0 at isa? irq 10 drq 1 flags 0x0 to your kernel configuration. You may need to change the IRQ, etc., to match your hardware configuration. Recompiling the Kernel After adding the driver(s) you need to your kernel configuration, you will need to recompile your kernel. Please see of the handbook for more information. Creating and Testing the Device Nodes device nodes After you reboot, log in and run cat /dev/sndstat. You should see output similar to the following: FreeBSD Audio Driver (newpcm) Sep 21 2000 18:29:53 Installed devices: pcm0: <Aureal Vortex 8830> at memory 0xfeb40000 irq 5 (4p/1r +channels duplex) If you see an error message, something went wrong earlier. If that happens, go through your kernel configuration file again and make sure you chose the correct device. If it reported no errors and returned pcm0, su to root and do the following: &prompt.root; cd /dev &prompt.root; sh MAKEDEV snd0 If it reported no errors and returned pcm1, su to root and do the following: &prompt.root; cd /dev &prompt.root; sh MAKEDEV snd1 Please note that either of the above commands will not create a /dev/snd device! Instead it creates a group of device nodes including: Device Description /dev/audio SPARC-compatible audio device /dev/dsp Digitized voice device /dev/dspW Like /dev/dsp, but 16 bits per sample /dev/midi Raw midi access device /dev/mixer Control port mixer device /dev/music Level 2 sequencer interface /dev/sequencer Sequencer device /dev/pss Programmable device interface If all goes well, you should now have a functioning sound card. If you do not, see the next section. Common Problems device node I get an unsupported subdevice XX error! One or more of the device nodes wasn't created correctly. Repeat the steps above. I/O port I get a sb_dspwr(XX) timed out error! The I/O port is not set correctly. IRQ I get a bad irq XX error! The IRQ is set incorrectly. Make sure that the set IRQ and the sound IRQ are the same. I get a xxx: gus pcm not attached, out of memory error. What causes that? If this happens, it is because there is not enough available memory to use the device. diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml index 7bb54e111a..39ed3aaae7 100644 --- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml @@ -1,2585 +1,2586 @@ Serial Communications Synopsis serial communications Unix has always had support for serial communications. In fact, the very first Unix machines relied on serial lines for user input and output. Things have changed a lot from the days when the average terminal consisted of a 10-character-per-second serial printer and a keyboard. This chapter will cover some of the ways in which FreeBSD uses serial communications. After reading this chapter you will know: How to connect terminals to your FreeBSD system. How to use a modem to dial out to remote hosts. How to allow remote users to login to your system with a modem. How to boot your system from a serial console. Before reading this chapter you should: Know how to configure and install a new kernel () Understand Unix permissions and processes () Have access to the technical manual for the serial hardware (modem or multi-port card) that you would like to use with FreeBSD. Introduction Terminology bits-per-second bps Bits per Second — the rate at which data is transmitted DTE DTE Data Terminal Equipment — for example, your computer DCE DCE Data Communications Equipment — your modem RS-232 RS-232C cables EIA standard for hardware serial communications When talking about communications data rates, the authors do not use the term baud. Baud refers to the number of electrical state transitions that may be made in a period of time, while bps (bits per second) is the correct term to use (at least it does not seem to bother the curmudgeons quite a much). Cables and Ports To connect a modem or terminal to your FreeBSD system, you will need a serial port on your computer and the proper cable to connect to your serial device. If you are already familiar with your hardware and the cable it requires, you can safely skip this section. Cables There are several different kinds of serial cables. The two most common types for our purposes are null-modem cables and standard ("straight") RS-232 cables. The documentation for your hardware should describe the type of cable required. Null-modem cables null-modem cable A null-modem cable passes some signals straight through, like signal ground, but switches other signals. For example, the send data pin on one end goes to the receive data pin on the other end. If you like making your own cables, you can construct a null-modem cable for use with terminals. This table shows the RS-232C signal names and the pin numbers on a DB-25 connector. Signal Pin # Pin # Signal TxD 2 connects to 3 RxD RxD 3 connects to 2 TxD DTR 20 connects to 6 DSR DSR 6 connects to 20 DTR SG 7 connects to 7 SG DCD 8 connects to 4 RTS RTS 4 5 CTS CTS 5 connects to 8 DCD For DCD to RTS, connect pins 4 to 5 internally in the connector hood, and then to pin 8 in the remote hood. Standard RS-232C Cables RS-232C cables A standard serial cable passes all the RS-232C signals straight-through. That is, the send data pin on one end of the cable goes to the send data pin on the other end. This is the type of cable to connect a modem to your FreeBSD system, and the type of cable needed for some terminals. Ports Serial ports are the devices through which data is transferred between the FreeBSD host computer and the terminal. This section describes the kinds of ports that exist and how they are addressed in FreeBSD. Kinds of Ports Several kinds of serial ports exist. Before you purchase or construct a cable, you need to make sure it will fit the ports on your terminal and on the FreeBSD system. Most terminals will have DB25 ports. Personal computers, including PCs running FreeBSD, will have DB25 or DB9 ports. If you have a multiport serial card for your PC, you may have RJ-12 or RJ-45 ports. See the documentation that accompanied the hardware for specifications on the kind of port in use. A visual inspection of the port often works, too. Port Names In FreeBSD, you access each serial port through an entry in the /dev directory. There are two different kinds of entries: Call-in ports are named /dev/ttydN where N is the port number, starting from zero. Generally, you use the call-in port for terminals. Call-in ports require that the serial line assert the data carrier detect (DCD) signal to work. Call-out ports are named /dev/cuaaN. You usually do not use the call-out port for terminals, just for modems. You may use the call-out port if the serial cable or the terminal does not support the carrier detect signal. If you have connected a terminal to the first serial port (COM1 in MS-DOS parlance), then you want to use /dev/ttyd0 to refer to the terminal. If it is on the second serial port (also known as COM2), it is /dev/ttyd1, and so forth. Kernel Configuration FreeBSD supports four serial ports by default. In the MS-DOS world, these are known as COM1:, COM2:, COM3:, and COM4:. FreeBSD currently supports dumb multiport serial interface cards, such as the BocaBoard 1008 and 2016, as well as more intelligent multi-port cards such as those made by Digiboard and Stallion Technologies. The default kernel only looks for the standard COM ports, though. To see if your kernel recognizes any of your serial ports, watch for messages while the kernel is booting, or use the /sbin/dmesg command to replay the kernel's boot messages. In particular, look for messages that start with the characters sio. To view just the messages that have the word sio, use the command: &prompt.root; /sbin/dmesg | grep 'sio' For example, on a system with four serial ports, these are the serial-port specific kernel boot messages: sio0 at 0x3f8-0x3ff irq 4 on isa sio0: type 16550A sio1 at 0x2f8-0x2ff irq 3 on isa sio1: type 16550A sio2 at 0x3e8-0x3ef irq 5 on isa sio2: type 16550A sio3 at 0x2e8-0x2ef irq 9 on isa sio3: type 16550A If your kernel does not recognize all of your serial ports, you will probably need to configure a custom FreeBSD kernel for your system. For detailed information on configuring your kernel, please see . The relevant device lines for your kernel configuration file would look like this: device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr device sio1 at isa? port "IO_COM2" tty irq 3 vector siointr device sio2 at isa? port "IO_COM3" tty irq 5 vector siointr device sio3 at isa? port "IO_COM4" tty irq 9 vector siointr You can comment-out or completely remove lines for devices you do not have. Please see the &man.sio.4; manual page for complete information on how to write configuration lines for multiport boards. Be careful if you are using a configuration file that was previously used for a different version of FreeBSD because the device flags have changed between versions. port "IO_COM1" is a substitution for port 0x3f8, IO_COM2 is 0x2f8, IO_COM3 is 0x3e8, and IO_COM4 is 0x2e8, which are fairly common port addresses for their respective serial ports; interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. Also note that regular serial ports cannot share interrupts on ISA-bus PCs (multiport boards have on-board electronics that allow all the 16550A's on the board to share one or two interrupt request lines). Device Special Files Most devices in the kernel are accessed through device special files, which are located in the /dev directory. The sio devices are accessed through the /dev/ttydN (dial-in) and /dev/cuaaN (call-out) devices. FreeBSD also provides initialization devices (/dev/ttyidN and /dev/cuai0N) and locking devices (/dev/ttyldN and /dev/cual0N). The initialization devices are used to initialize communications port parameters each time a port is opened, such as crtscts for modems which use CTS/RTS signaling for flow control. The locking devices are used to lock flags on ports to prevent users or programs changing certain parameters; see the manual pages &man.termios.4;, &man.sio.4;, and &man.stty.1; for information on the terminal settings, locking and initializing devices, and setting terminal options, respectively. Making Device Special Files FreeBSD 5.0 includes the devfs filesystem which automatically creates device nodes as needed. If you are running a version of FreeBSD with devfs enabled then you can safely skip this section. A shell script called MAKEDEV in the /dev directory manages the device special files. To use MAKEDEV to make dial-up device special files for COM1: (port 0), cd to /dev and issue the command MAKEDEV ttyd0. Likewise, to make dial-up device special files for COM2: (port 1), use MAKEDEV ttyd1. MAKEDEV not only creates the /dev/ttydN device special files, but also creates the /dev/cuaaN, /dev/cuaiaN, /dev/cualaN, /dev/ttyldN, and /dev/ttyidN nodes. After making new device special files, be sure to check the permissions on the files (especially the /dev/cua* files) to make sure that only users who should have access to those device special files can read and write on them — you probably do not want to allow your average user to use your modems to dial-out. The default permissions on the /dev/cua* files should be sufficient: crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cuaa1 crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuaia1 crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cuala1 These permissions allow the user uucp and users in the group dialer to use the call-out devices. Serial Port Configuration ttyd cuaa The ttydN (or cuaaN) device is the regular device you will want to open for your applications. When a process opens the device, it will have a default set of terminal I/O settings. You can see these settings with the command &prompt.root; stty -a -f /dev/ttyd1 When you change the settings to this device, the settings are in effect until the device is closed. When it is reopened, it goes back to the default set. To make changes to the default set, you can open and adjust the settings of the initial state device. For example, to turn on mode, 8 bit communication, and flow control by default for ttyd5, type: &prompt.root; stty -f /dev/ttyid5 clocal cs8 ixon ixoff rc files rc.serial System-wide initialization of the serial devices is controlled in /etc/rc.serial. This file affects the default settings of serial devices. To prevent certain settings from being changed by an application, make adjustments to the lock state device. For example, to lock the speed of ttyd5 to 57600 bps, type: &prompt.root; stty -f /dev/ttyld5 57600 Now, an application that opens ttyd5 and tries to change the speed of the port will be stuck with 57600 bps. MAKEDEV Naturally, you should make the initial state and lock state devices writable only by the root account. Sean Kelly Contributed Terminals terminals Terminals provide a convenient and low-cost way to access the power of your FreeBSD system when you are not at the computer's console or on a connected network. This section describes how to use terminals with FreeBSD. Uses and Types of Terminals The original Unix systems did not have consoles. Instead, people logged in and ran programs through terminals that were connected to the computer's serial ports. It is quite similar to using a modem and some terminal software to dial into a remote system to do text-only work. Today's PCs have consoles capable of high quality graphics, but the ability to establish a login session on a serial port still exists in nearly every Unix-style operating system today; FreeBSD is no exception. By using a terminal attached to a unused serial port, you can log in and run any text program that you would normally run on the console or in an xterm window in the X Window System. For the business user, you can attach many terminals to a FreeBSD system and place them on your employees' desktops. For a home user, a spare computer such as an older IBM PC or a Macintosh can be a terminal wired into a more powerful computer running FreeBSD. You can turn what might otherwise be a single-user computer into a powerful multiple user system. For FreeBSD, there are three kinds of terminals: Dumb terminals PCs acting as terminals X terminals The remaining subsections describe each kind. Dumb Terminals Dumb terminals are specialized pieces of hardware that let you connect to computers over serial lines. They are called dumb because they have only enough computational power to display, send, and receive text. You cannot run any programs on them. It is the computer to which you connect them that has all the power to run text editors, compilers, email, games, and so forth. There are hundreds of kinds of dumb terminals made by many manufacturers, including Digital Equipment Corporation's VT-100 and Wyse's WY-75. Just about any kind will work with FreeBSD. Some high-end terminals can even display graphics, but only certain software packages can take advantage of these advanced features. Dumb terminals are popular in work environments where workers do not need access to graphic applications such as those provided by the X Window System. PCs Acting As Terminals If a dumb terminal has just enough ability to display, send, and receive text, then certainly any spare personal computer can be a dumb terminal. All you need is the proper cable and some terminal emulation software to run on the computer. Such a configuration is popular in homes. For example, if your spouse is busy working on your FreeBSD system's console, you can do some text-only work at the same time from a less powerful personal computer hooked up as a terminal to the FreeBSD system. X Terminals X terminals are the most sophisticated kind of terminal available. Instead of connecting to a serial port, they usually connect to a network like Ethernet. Instead of being relegated to text-only applications, they can display any X application. We introduce X terminals just for the sake of completeness. However, this chapter does not cover setup, configuration, or use of X terminals. Configuration This section describes what you need to configure on your FreeBSD system to enable a login session on a terminal. It assumes you have already configured your kernel to support the serial port to which the terminal is connected—and that you have connected it. Recall from that the init process is responsible for all process control and initialization at system startup. One of the tasks performed by init is to read the /etc/ttys file and start a getty process on the available terminals. The getty process is responsible for reading a login name and starting the login program. Thus, to configure terminals for your FreeBSD system the following steps should be taken as root : Add a line to /etc/ttys for the entry in the /dev directory for the serial port if it is not already there. Specify that /usr/libexec/getty be run on the port, and specify the appropriate getty type from the /etc/gettytab file. Specify the default terminal type. Set the port to on. Specify whether the port should be secure. Force init to reread the /etc/ttys file. As an optional step, you may wish to create a custom getty type for use in step 2 by making an entry in /etc/gettytab. This chapter does not explain how to do so; you are encouraged to see the &man.gettytab.5; and the &man.getty.8; manual pages for more information. Adding an Entry to <filename>/etc/ttys</filename> The /etc/ttys file lists all of the ports on your FreeBSD system where you want to allow logins. For example, the first virtual console ttyv0 has an entry in this file. You can log in on the console using this entry. This file also contains entries for the other virtual consoles, serial ports, and pseudo-ttys. For a hardwired terminal, just list the serial port's /dev entry without the /dev part. A default FreeBSD install includes a /etc/ttys file with support for the first four serial ports: ttyd0 through ttyd3. If you are attaching a terminal to one of those ports, you do not need to add another entry. Adding Terminal Entries to <filename>/etc/ttys</filename> Suppose we would like to connect two terminals to the system: a Wyse-50 and an old 286 IBM PC running Procomm terminal software emulating a VT-100 terminal. We connect the Wyse to the second serial port and the 286 to the sixth serial port (a port on a multiport serial card). The corresponding entries in the /etc/ttys file would look like this: ttyd1 "/usr/libexec/getty std.38400" wy50 on insecure ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure The first field normally specifies the name of the terminal special file as it is found in /dev. The second field is the command to execute for this line, which is usually &man.getty.8;. getty initializes and opens the line, sets the speed, prompts for a user name and then executes the &man.login.1; program. The getty program accepts one (optional) parameter on its command line, the getty type. A getty type tells about characteristics on the terminal line, like bps rate and parity. The getty program reads these characteristics from the file /etc/gettytab. The file /etc/gettytab contains lots of entries for terminal lines both old and new. In almost all cases, the entries that start with the text std will work for hardwired terminals. These entries ignore parity. There is a std entry for each bps rate from 110 to 115200. Of course, you can add your own entries to this file. The &man.gettytab.5; manual page provides more information. When setting the getty type in the /etc/ttys file, make sure that the communications settings on the terminal match. For our example, the Wyse-50 uses no parity and connects at 38400 bps. The 286 PC uses no parity and connects at 19200 bps. The third field is the type of terminal usually connected to that tty line. For dial-up ports, unknown or dialup is typically used in this field since users may dial up with practically any type of terminal or software. For hardwired terminals, the terminal type does not change, so you can put a real terminal type from the &man.termcap.5; database file in this field. For our example, the Wyse-50 uses the real terminal type while the 286 PC running Procomm will be set to emulate at VT-100. The fourth field specifies if the port should be enabled. Putting on here will have the init process start the program in the second field, getty. If you put off in this field, there will be no getty, and hence no logins on the port. The final field is used to specify whether the port is secure. Marking a port as secure means that you trust it enough to allow the root account (or any account with a user ID of 0) to login from that port. Insecure ports do not allow root logins. On an insecure port, users must login from unprivileged accounts and then use &man.su.1; or a similar mechanism to gain superuser privileges. It is highly recommended that you use "insecure" even for terminals that are behind locked doors. It is quite easy to login and use su if you need superuser privileges. - + + Force <command>init</command> to Reread <filename>/etc/ttys</filename> After making the necessary changes to the /etc/ttys file you should send a SIGHUP (hangup) signal to the init process to force it to re-read its configuration file. For example : &prompt.root; kill -HUP 1 If everything is set up correctly, all cables are in place, and the terminals are powered up, then a getty process should be running on each terminal and you should see login prompts on your terminals at this point. Troubleshooting your connection Even with the most meticulous attention to detail, something could still go wrong while setting up a terminal. Here is a list of symptoms and some suggested fixes. No login prompt appears Make sure the terminal is plugged in and powered up. If it is a personal computer acting as a terminal, make sure it is running terminal emulation software on the correct serial port. Make sure the cable is connected firmly to both the terminal and the FreeBSD computer. Make sure it is the right kind of cable. Make sure the terminal and FreeBSD agree on the bps rate and parity settings. If you have a video display terminal, make sure the contrast and brightness controls are turned up. If it is a printing terminal, make sure paper and ink are in good supply. Make sure that a getty process is running and serving the terminal. For example, to get a list of running getty processes with ps, type: &prompt.root; ps -axww|grep getty You should see an entry for the terminal. For example, the following display shows that a getty is running on the second serial port ttyd1 and is using the std.38400 entry in /etc/gettytab: 22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1 If no getty process is running, make sure you have enabled the port in /etc/ttys. Also remember to run kill -HUP 1 after modifying the ttys file. Garbage appears instead of a login prompt Make sure the terminal and FreeBSD agree on the bps rate and parity settings. Check the getty processes to make sure the correct getty type is in use. If not, edit /etc/ttys and run kill -HUP 1. Characters appear doubled; the password appears when typed Switch the terminal (or the terminal emulation software) from half duplex or local echo to full duplex. Guy Helmer Contributed Sean Kelly Additions Dial-in Service dial-in service Configuring your FreeBSD system for dial-in service is very similar to connecting terminals except that you're dealing with modems instead of terminals. External v.s. Internal Modems External modems seem to be more convenient for dial-up, because external modems often can be semi-permanently configured via parameters stored in non-volatile RAM and they usually provide lighted indicators that display the state of important RS-232 signals. Blinking lights impress visitors, but lights are also very useful to see whether a modem is operating properly. Internal modems usually lack non-volatile RAM, so their configuration may be limited only to setting DIP switches. If your internal modem has any signal indicator lights, it is probably difficult to view the lights when the system's cover is in place. Modems and Cables modem If you are using an external modem, then you will of course need the proper cable. A standard RS-232C serial cable should suffice as long as all of the normal signals are wired : Transmitted Data (SD) Received Data (RD) Request to Send (RTS) Clear to Send (CTS) Data Set Ready (DSR) Data Terminal Ready (DTR) Carrier Detect (CD) Signal Ground (SG) FreeBSD needs the RTS and CTS signals for flow-control at speeds above 2400bps, the CD signal to detect when a call has been answered or the line has been hung up, and the DTR signal to reset the modem after a session is complete. Some cables are wired without all of the needed signals, so if you have problems, such as a login session not going away when the line hangs up, you may have a problem with your cable. Like other Unix-like operating systems, FreeBSD uses the hardware signals to find out when a call has been answered or a line has been hung up and to hangup and reset the modem after a call. FreeBSD avoids sending commands to the modem or watching for status reports from the modem. If you are familiar with connecting modems to PC-based bulletin board systems, this may seem awkward. Serial Interface Considerations FreeBSD supports NS8250-, NS16450-, NS16550-, and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 devices have single-character buffers. The 16550 device provides a 16-character buffer, which allows for better system performance. (Bugs in plain 16550's prevent the use of the 16-character buffer, so use 16550A's if possible). Because single-character-buffer devices require more work by the operating system than the 16-character-buffer devices, 16550A-based serial interface cards are much preferred. If the system has many active serial ports or will have a heavy load, 16550A-based cards are better for low-error-rate communications. Quick Overview getty As with terminals, init spawns a getty process for each configured serial port for dial-in connections. For example, if a modem is attached to /dev/ttyd0, the command ps ax might show this: 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0 When a user dials the modem's line and the modems connect, the CD line is asserted by the modem. The kernel notices that carrier has been detected and completes getty's open of the port. getty sends a login: prompt at the specified initial line speed. getty watches to see if legitimate characters are received, and, in a typical configuration, if it finds junk (probably due to the modem's connection speed being different than getty's speed), getty tries adjusting the line speeds until it receives reasonable characters. /usr/bin/login After the user enters his/her login name, getty executes /usr/bin/login, which completes the login by asking for the user's password and then starting the user's shell. Configuration Files There are three system configuration files in the /etc directory that you will probably need to edit to allow dial-up access to your FreeBSD system. The first, /etc/gettytab, contains configuration information for the /usr/libexec/getty daemon. Second, /etc/ttys holds information that tells /sbin/init what tty devices should have getty processes running on them. Lastly, you can place port initialization commands in the /etc/rc.serial script. There are two schools of thought regarding dial-up modems on Unix. One group likes to configure their modems and systems so that no matter at what speed a remote user dials in, the local computer-to-modem RS-232 interface runs at a locked speed. The benefit of this configuration is that the remote user always sees a system login prompt immediately. The downside is that the system does not know what a user's true data rate is, so full-screen programs like Emacs will not adjust their screen-painting methods to make their response better for slower connections. The other school configures their modems' RS-232 interface to vary its speed based on the remote user's connection speed. For example, V.32bis (14.4 Kbps) connections to the modem might make the modem run its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the modem's RS-232 interface run at 2400 bps. Because getty does not understand any particular modem's connection speed reporting, getty gives a login: message at an initial speed and watches the characters that come back in response. If the user sees junk, it is assumed that they know they should press the Enter key until they see a recognizable prompt. If the data rates do not match, getty sees anything the user types as junk, tries going to the next speed and gives the login: prompt again. This procedure can continue ad nauseam, but normally only takes a keystroke or two before the user sees a good prompt. Obviously, this login sequence does not look as clean as the former locked-speed method, but a user on a low-speed connection should receive better interactive response from full-screen programs. The authors will try to give balanced configuration information, but is biased towards having the modem's data rate follow the connection rate. <filename>/etc/gettytab</filename> /etc/gettytab /etc/gettytab is a &man.termcap.5;-style file of configuration information for &man.getty.8;. Please see the &man.gettytab.5; manual page for complete information on the format of the file and the list of capabilities. Locked-Speed Config If you are locking your modem's data communications rate at a particular speed, you probably will not need to make any changes to /etc/gettytab. Matching-Speed Config You will need to setup an entry in /etc/gettytab to give getty information about the speeds you wish to use for your modem. If you have a 2400 bps modem, you can probably use the existing D2400 entry. # # Fast dialup terminals, 2400/1200/300 rotary (can start either way) # D2400|d2400|Fast-Dial-2400:\ :nx=D1200:tc=2400-baud: 3|D1200|Fast-Dial-1200:\ :nx=D300:tc=1200-baud: 5|D300|Fast-Dial-300:\ :nx=D2400:tc=300-baud: If you have a higher speed modem, you will probably need to add an entry in /etc/gettytab; here is an entry you could use for a 14.4 Kbps modem with a top interface speed of 19.2 Kbps: # # Additions for a V.32bis Modem # um|V300|High Speed Modem at 300,8-bit:\ :nx=V19200:tc=std.300: un|V1200|High Speed Modem at 1200,8-bit:\ :nx=V300:tc=std.1200: uo|V2400|High Speed Modem at 2400,8-bit:\ :nx=V1200:tc=std.2400: up|V9600|High Speed Modem at 9600,8-bit:\ :nx=V2400:tc=std.9600: uq|V19200|High Speed Modem at 19200,8-bit:\ :nx=V9600:tc=std.19200: This will result in 8-bit, no parity connections. The example above starts the communications rate at 19.2 Kbps (for a V.32bis connection), then cycles through 9600 bps (for V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. Communications rate cycling is implemented with the nx= (next table) capability. Each of the lines uses a tc= (table continuation) entry to pick up the rest of the standard settings for a particular data rate. If you have a 28.8 Kbps modem and/or you want to take advantage of compression on a 14.4 Kbps modem, you need to use a higher communications rate than 19.2 Kbps. Here is an example of a gettytab entry starting a 57.6 Kbps: # # Additions for a V.32bis or V.34 Modem # Starting at 57.6 Kbps # vm|VH300|Very High Speed Modem at 300,8-bit:\ :nx=VH57600:tc=std.300: vn|VH1200|Very High Speed Modem at 1200,8-bit:\ :nx=VH300:tc=std.1200: vo|VH2400|Very High Speed Modem at 2400,8-bit:\ :nx=VH1200:tc=std.2400: vp|VH9600|Very High Speed Modem at 9600,8-bit:\ :nx=VH2400:tc=std.9600: vq|VH57600|Very High Speed Modem at 57600,8-bit:\ :nx=VH9600:tc=std.57600: If you have a slow CPU or a heavily loaded system and you do not have 16550A-based serial ports, you may receive sio silo errors at 57.6 Kbps. <filename>/etc/ttys</filename> /etc/ttys Configuration of the /etc/ttys file was covered in . Configuration for modems is similar but we must pass a different argument to getty and specify a different terminal type. The general format for both locked-speed and matching-speed configurations is: ttyd0 "/usr/libexec/getty xxx" dialup on The first item in the above line is the device special file for this entry — ttyd0 means /dev/ttyd0 is the file that this getty will be watching. The second item, "/usr/libexec/getty xxx" (xxx will be replaced by the initial gettytab capability) is the process init will run on the device. The third item, dialup, is the default terminal type. The fourth parameter, on, indicates to init that the line is operational. There can be a fifth parameter, secure, but it should only be used for terminals which are physically secure (such as the system console). The default terminal type (dialup in the example above) may depend on local preferences. dialup is the traditional default terminal type on dial-up lines so that users may customize their login scripts to notice when the terminal is dialup and automatically adjust their terminal type. However, the author finds it easier at his site to specify vt102 as the default terminal type, since the users just use VT102 emulation on their remote systems. After you have made changes to /etc/ttys, you may send the init process a HUP signal to re-read the file. You can use the command &prompt.root; kill -HUP 1 to send the signal. If this is your first time setting up the system, though, you may want to wait until your modem(s) are properly configured and connected before signaling init. Locked-Speed Config For a locked-speed configuration, your ttys entry needs to have a fixed-speed entry provided to getty. For a modem whose port speed is locked at 19.2 Kbps, the ttys entry might look like this: ttyd0 "/usr/libexec/getty std.19200" dialup on If your modem is locked at a different data rate, substitute the appropriate value for std.speed instead of std.19200. Make sure that you use a valid type listed in - /etc/gettytab. + /etc/gettytab. Matching-Speed Config In a matching-speed configuration, your ttys entry needs to reference the appropriate beginning auto-baud (sic) entry in /etc/gettytab. For example, if you added the above suggested entry for a matching-speed modem that starts at 19.2 Kbps (the gettytab entry containing the V19200 starting point), your ttys entry might look like this: ttyd0 "/usr/libexec/getty V19200" dialup on <filename>/etc/rc.serial</filename> rc files rc.serial High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware (RTS/CTS) flow control. You can add stty commands to /etc/rc.serial to set the hardware flow control flag in the FreeBSD kernel for the modem ports. For example to set the termios flag crtscts on serial port #1's (COM2:) dial-in and dial-out initialization devices, the following lines could be added to /etc/rc.serial : # Serial port initial configuration stty -f /dev/ttyid1 crtscts stty -f /dev/cuai01 crtscts Modem Settings If you have a modem whose parameters may be permanently set in non-volatile RAM, you will need to use a terminal program (such as Telix under MS-DOS or tip under FreeBSD) to set the parameters. Connect to the modem using the same communications speed as the initial speed getty will use and configure the modem's non-volatile RAM to match these requirements: CD asserted when connected DTR asserted for operation; dropping DTR hangs up line and resets modem CTS transmitted data flow control Disable XON/XOFF flow control RTS received data flow control Quiet mode (no result codes) No command echo Please read the documentation for your modem to find out what commands and/or DIP switch settings you need to give it. For example, to set the above parameters on a USRobotics Sportster 14,400 external modem, one could give these commands to the modem: ATZ AT&C1&D2&H1&I0&R2&W You might also want to take this opportunity to adjust other settings in the modem, such as whether it will use V.42bis and/or MNP5 compression. The USR Sportster 14,400 external modem also has some DIP switches that need to be set; for other modems, perhaps you can use these settings as an example: Switch 1: UP — DTR Normal Switch 2: Do not care (Verbal Result Codes/Numeric Result Codes) Switch 3: UP — Suppress Result Codes Switch 4: DOWN — No echo, offline commands Switch 5: UP — Auto Answer Switch 6: UP — Carrier Detect Normal Switch 7: UP — Load NVRAM Defaults Switch 8: Do not care (Smart Mode/Dumb Mode) Result codes should be disabled/suppressed for dial-up modems to avoid problems that can occur if getty mistakenly gives a login: prompt to a modem that is in command mode and the modem echoes the command or returns a result code. This sequence can result in a extended, silly conversation between getty and the modem. Locked-speed Config For a locked-speed configuration, you will need to configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a USR Sportster 14,400 external modem, these commands will lock the modem-to-computer data rate at the speed used to issue the commands: ATZ AT&B1&W Matching-speed Config For a variable-speed configuration, you will need to configure your modem to adjust its serial port data rate to match the incoming call rate. On a USR Sportster 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue the commands, but allow the serial port rate to vary for non-error-corrected connections: ATZ AT&B2&W Checking the Modem's Configuration Most high-speed modems provide commands to view the modem's current operating parameters in a somewhat human-readable fashion. On the USR Sportster 14,400 external modems, the command ATI5 displays the settings that are stored in the non-volatile RAM. To see the true operating parameters of the modem (as influenced by the USR's DIP switch settings), use the commands ATZ and then ATI4. If you have a different brand of modem, check your modem's manual to see how to double-check your modem's configuration parameters. Troubleshooting Here are a few steps you can follow to check out the dial-up modem on your system. Checking out the FreeBSD system Hook up your modem to your FreeBSD system, boot the system, and, if your modem has status indication lights, watch to see whether the modem's DTR indicator lights when the login: prompt appears on the system's console — if it lights up, that should mean that FreeBSD has started a getty process on the appropriate communications port and is waiting for the modem to accept a call. If the DTR indicator doesn't light, login to the FreeBSD system through the console and issue a ps ax to see if FreeBSD is trying to run a getty process on the correct port. You should see a lines like this among the processes displayed: 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1 If you see something different, like this: 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0 and the modem has not accepted a call yet, this means that getty has completed its open on the communications port. This could indicate a problem with the cabling or a mis-configured modem, because getty should not be able to open the communications port until CD (carrier detect) has been asserted by the modem. If you do not see any getty processes waiting to open the desired ttydN port, double-check your entries in /etc/ttys to see if there are any mistakes there. Also, check the log file /var/log/messages to see if there are any log messages from init or getty regarding any problems. If there are any messages, triple-check the configuration files /etc/ttys and /etc/gettytab, as well as the appropriate device special files /dev/ttydN, for any mistakes, missing entries, or missing device special files. Try Dialing In Try dialing into the system; be sure to use 8 bits, no parity, 1 stop bit on the remote system. If you do not get a prompt right away, or get garbage, try pressing Enter about once per second. If you still do not see a login: prompt after a while, try sending a BREAK. If you are using a high-speed modem to do the dialing, try dialing again after locking the dialing modem's interface speed (via AT&B1 on a USR Sportster, for example). If you still cannot get a login: prompt, check /etc/gettytab again and double-check that The initial capability name specified in /etc/ttys for the line matches a name of a capability in /etc/gettytab Each nx= entry matches another gettytab capability name Each tc= entry matches another gettytab capability name If you dial but the modem on the FreeBSD system will not answer, make sure that the modem is configured to answer the phone when DTR is asserted. If the modem seems to be configured correctly, verify that the DTR line is asserted by checking the modem's indicator lights (if it has any). If you have gone over everything several times and it still does not work, take a break and come back to it later. If it still does not work, perhaps you can send an electronic mail message to the &a.questions;describing your modem and your problem, and the good folks on the list will try to help. Dial-out Service dial-out service The following are tips to getting your host to be able to connect over the modem to another computer. This is appropriate for establishing a terminal session with a remote host. This is useful to log onto a BBS. This kind of connection can be extremely helpful to get a file on the Internet if you have problems with PPP. If you need to FTP something and PPP is broken, use the terminal session to FTP it. Then use zmodem to transfer it to your machine. My stock Hayes modem is not supported, what can I do? Actually, the man page for tip is out of date. There is a generic Hayes dialer already built in. Just use at=hayes in your /etc/remote file. The Hayes driver is not smart enough to recognize some of the advanced features of newer modems—messages like BUSY, NO DIALTONE, or CONNECT 115200 will just confuse it. You should turn those messages off when you use tip (using ATX0&W). Also, the dial timeout for tip is 60 seconds. Your modem should use something less, or else tip will think there is a communication problem. Try ATS7=45&W. Actually, as shipped tip does not yet support it fully. The solution is to edit the file tipconf.h in the directory /usr/src/usr.bin/tip/tip Obviously you need the source distribution to do this. Edit the line #define HAYES 0 to #define HAYES 1. Then make and make install. Everything works nicely after that. How am I expected to enter these AT commands? /etc/remote Make what is called a direct entry in your /etc/remote file. For example, if your modem is hooked up to the first serial port, /dev/cuaa0, then put in the following line: cuaa0:dv=/dev/cuaa0:br#19200:pa=none Use the highest bps rate your modem supports in the br capability. Then, type tip cuaa0 and you will be connected to your modem. If there is no /dev/cuaa0 on your system, do this: &prompt.root; cd /dev &prompt.root; MAKEDEV cuaa0 Or use cu as root with the following command: &prompt.root; cu -lline -sspeed line is the serial port (e.g./dev/cuaa0) and speed is the speed (e.g.57600). When you are done entering the AT commands hit ~. to exit. The <literal>@</literal> sign for the pn capability does not work! The @ sign in the phone number capability tells tip to look in /etc/phones for a phone number. But the @ sign is also a special character in capability files like /etc/remote. Escape it with a backslash: pn=\@ How can I dial a phone number on the command line? Put what is called a generic entry in your /etc/remote file. For example: tip115200|Dial any phone number at 115200 bps:\ :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du: tip57600|Dial any phone number at 57600 bps:\ :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du: Then you can things like: &prompt.root; tip -115200 5551234 If you prefer cu over tip, use a generic cu entry: cu115200|Use cu to dial any number at 115200bps:\ :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du: and type: &prompt.root; cu 5551234 -s 115200 Do I have to type in the bps rate every time I do that? Put in an entry for tip1200 or cu1200, but go ahead and use whatever bps rate is appropriate with the br capability. tip thinks a good default is 1200 bps which is why it looks for a tip1200 entry. You do not have to use 1200 bps, though. I access a number of hosts through a terminal server. Rather than waiting until you are connected and typing CONNECT <host> each time, use tip's cm capability. For example, these entries in /etc/remote: pain|pain.deep13.com|Forrester's machine:\ :cm=CONNECT pain\n:tc=deep13: muffin|muffin.deep13.com|Frank's machine:\ :cm=CONNECT muffin\n:tc=deep13: deep13:Gizmonics Institute terminal server:\ :dv=/dev/cuaa2:br#38400:at=hayes:du:pa=none:pn=5551234: will let you type tip pain or tip muffin to connect to the hosts pain or muffin; and tip deep13 to get to the terminal server. Can tip try more than one line for each site? This is often a problem where a university has several modem lines and several thousand students trying to use them... Make an entry for your university in /etc/remote and use @ for the pn capability: big-university:\ :pn=\@:tc=dialout dialout:\ :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none: Then, list the phone numbers for the university in /etc/phones: big-university 5551111 big-university 5551112 big-university 5551113 big-university 5551114 tip will try each one in the listed order, then give up. If you want to keep retrying, run tip in a while loop. Why do I have to hit <keycombo action="simul"> <keycap>Ctrl</keycap><keycap>P</keycap> </keycombo> twice to send <keycombo action="simul"> <keycap>Ctrl</keycap><keycap>P</keycap> </keycombo> once? CtrlP is the default force character, used to tell tip that the next character is literal data. You can set the force character to any other character with the ~s escape, which means set a variable. Type ~sforce=single-char followed by a newline. single-char is any single character. If you leave out single-char, then the force character is the nul character, which you can get by typing Ctrl2 or CtrlSPACE . A pretty good value for single-char is Shift Ctrl 6 , which is only used on some terminal servers. You can have the force character be whatever you want by specifying the following in your $HOME/.tiprc file: force=<single-char> Suddenly everything I type is in UPPER CASE?? You must have pressed Ctrl A , tip's raise character, specially designed for people with broken caps-lock keys. Use ~s as above and set the variable raisechar to something reasonable. In fact, you can set it to the same as the force character, if you never expect to use either of these features. Here is a sample .tiprc file perfect for Emacs users who need to type Ctrl2 and CtrlA a lot: force=^^ raisechar=^^ The ^^ is ShiftCtrl6 . How can I do file transfers with <command>tip</command>? If you are talking to another Unix system, you can send and receive files with ~p (put) and ~t (take). These commands run cat and echo on the remote system to accept and send files. The syntax is: ~p local-file remote-file ~t remote-file local-file There is no error checking, so you probably should use another protocol, like zmodem. How can I run zmodem with <command>tip</command>? To receive files, start the sending program on the remote end. Then, type ~C rz to begin receiving them locally. To send files, start the receiving program on the remote end. Then, type ~C sz files to send them to the remote system. Kazutaka YOKOTA Contributed Bill Paul Based on a document Setting Up the Serial Console serial console Introduction FreeBSD boot on a system with only a dumb terminal on a serial port as a console. Such a configuration should be useful for two classes of people: system administrators who wish to install FreeBSD on machines that have no keyboard or monitor attached, and developers who want to debug the kernel or device drivers. As described in , FreeBSD employs a three stage bootstrap. The first two stages are in the boot block code which is stored at the beginning of the FreeBSD slice on the boot disk. The boot block will then load and run the boot loader (/boot/loader) as the third stage code. In order to set up the serial console you must configure the boot block code, the boot loader code and the kernel. Serial Console Configuration Prepare a serial cable. null-modem cable You will need either a null-modem cable or a standard serial cable and a null-modem adapter. See for a discussion on serial cables. Unplug your keyboard. Most PC systems probe for the keyboard during the Power-On Self-Test (POST) and will generate an error if the keyboard is not detected. Some machines complain loudly about the lack of a keyboard and will not continue to boot until it is plugged in. If your computer complains about the error, but boots anyway, then you do not have to do anything special. (Some machines with Phoenix BIOS installed merely say Keyboard failed and continue to boot normally.) If your computer refuses to boot without a keyboard attached then you will have to configure the BIOS so that it ignores this error (if it can). Consult your motherboard's manual for details on how to do this. Setting the keyboard to Not installed in the BIOS setup does not mean that you will not be able to use your keyboard. All this does is tell the BIOS not to probe for a keyboard at power-on so that it will not complain if the keyboard is not plugged in. You can leave the keyboard plugged in even with this flag set to Not installed and the keyboard will still work. If your system has a PS/2 mouse, chances are very good that you may have to unplug your mouse as well as your keyboard. This is because PS/2 mice share some hardware with the keyboard, and leaving the mouse plugged in can fool the keyboard probe into thinking the keyboard is still there. It is said that a Gateway 2000 Pentium 90MHz system with an AMI BIOS that behaves this way. In general this is not a problem since the mouse is not much good without the keyboard anyway. Plug a dumb terminal into COM1: (sio0). If you do not have a dumb terminal, you can use an old PC/XT with a modem program, or the serial port on another Unix box. If you do not have a COM1: (sio0), get one. At this time, there is no way to select a port other than COM1: for the boot blocks without recompiling the boot blocks. If you are already using COM1: for another device, you will have to temporarily remove that device and install a new boot block and kernel once you get FreeBSD up and running. (It is assumed that COM1: will be available on a file/compute/terminal server anyway; if you really need COM1: for something else (and you cannot switch that something else to COM2: (sio1)), then you probably should not even be bothering with all this in the first place.) Make sure the configuration file of your kernel has appropriate flags set for COM1: (sio0). Relevant flags are: 0x10 Enables console support for this unit. The other console flags are ignored unless this is set. Currently, at most one unit can have console support; the first one (in config file order) with this flag set is preferred. This option alone will not make the serial port the console. Set the following flag or use the option described below, together with this flag. 0x20 Forces this unit to be the console (unless there is another higher priority console), regardless of the option discussed below. This flag replaces the COMCONSOLE option in FreeBSD versions 2.X. The flag 0x20 must be used together with the flag. 0x40 Reserves this unit (in conjunction with 0x10) and makes the unit unavailable for normal access. You should not set this flag to the serial port unit which you want to use as the serial console. The only use of this flag is to designate the unit for kernel remote debugging. See The Developer's Handbook for more information on remote debugging. In FreeBSD 4.0-CURRENT or later the semantics of the flag 0x40 are slightly different and there is another flag to specify a serial port for remote debugging. Example: device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4 See the &man.sio.4; manual page for more details. If the flags were not set, you need to run UserConfig (on a different console) or recompile the kernel. Create boot.config in the root directory of the a partition on the boot drive. This file will instruct the boot block code how you would like to boot the system. In order to activate the serial console, you need one or more of the following options—if you want multiple options, include them all on the same line: Toggles internal and serial consoles. You can use this to switch console devices. For instance, if you boot from the internal (video) console, you can use to direct the boot loader and the kernel to use the serial port as its console device. Alternatively, if you boot from the serial port, you can use the to tell the boot loader and the kernel to use the video display as the console instead. Toggles single and dual console configurations. In the single configuration the console will be either the internal console (video display) or the serial port, depending on the state of the option above. In the dual console configuration, both the video display and the serial port will become the console at the same time, regardless of the state of the option. However, that the dual console configuration takes effect only during the boot block is running. Once the boot loader gets control, the console specified by the option becomes the only console. Makes the boot block probe the keyboard. If no keyboard is found, the and options are automatically set. Due to space constraints in the current version of the boot blocks, the option is capable of detecting extended keyboards only. Keyboards with less than 101 keys (and without F11 and F12 keys) may not be detected. Keyboards on some laptop computers may not be properly found because of this limitation. If this is to be the case with your system, you have to abandon using the option. Unfortunately there is no workaround for this problem. Use either the option to select the console automatically, or the option to activate the serial console. You may include other options described in &man.boot.8; as well. The options, except for , will be passed to the boot loader (/boot/loader). The boot loader will determine which of the internal video or the serial port should become the console by examining the state of the option alone. This means that if you specify the option but not the option in /boot.config, you can use the serial port as the console only during the boot block; the boot loader will use the internal video display as the console. Boot the machine. When you start your FreeBSD box, the boot blocks will echo the contents of /boot.config to the console. For example; /boot.config: -P Keyboard: no The second line appears only if you put in /boot.config and indicates presence/absence of the keyboard. These messages go to either serial or internal console, or both, depending on the option in /boot.config. Options Message goes to none internal console serial console serial and internal consoles serial and internal consoles , keyboard present internal console , keyboard absent serial console After the above messages, there will be a small pause before the boot blocks continue loading the boot loader and before any further messages printed to the console. Under normal circumstances, you do not need to interrupt the boot blocks, but you may want to do so in order to make sure things are set up correctly. Hit any key, other than Enter, at the console to interrupt the boot process. The boot blocks will then prompt you for further action. You should now see something like: >> FreeBSD/i386 BOOT Default: 0:wd(0,a)/boot/loader boot: Verify the above message appears on either the serial or internal console or both, according to the options you put in /boot.config. If the message appears in the correct console, hit Enter to continue the boot process. If you want the serial console but you do not see the prompt on the serial terminal, something is wrong with your settings. In the meantime, you enter and hit Enter/Return (if possible) to tell the boot block (and then the boot loader and the kernel) to choose the serial port for the console. Once the system is up, go back and check what went wrong. After the boot loader is loaded and you are in the third stage of the boot process you can still switch between the internal console and the serial console by setting appropriate environment variables in the boot loader. See . Summary Here is the summary of various settings discussed in this section and the console eventually selected. Case 1: You set the flags to 0x10 for sio0 device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4 Options in /boot.config Console during boot blocks Console during boot loader Console in kernel nothing internal internal internal serial serial serial serial and internal internal internal serial and internal serial serial , keyboard present internal internal internal , keyboard absent serial and internal serial serial Case 2: You set the flags to 0x30 for sio0 device sio0 at isa? port "IO_COM1" tty flags 0x30 irq 4 Options in /boot.config Console during boot blocks Console during boot loader Console in kernel nothing internal internal serial serial serial serial serial and internal internal serial serial and internal serial serial , keyboard present internal internal serial , keyboard absent serial and internal serial serial Tips for the Serial Console Setting A Faster Serial Port Speed By default the serial port settings are set to 9600 baud, 8 bits, no parity, 1 stop bit. If you wish to change the speed, you need to recompile at least the boot blocks. Add the following line to /etc/make.conf and compile new boot blocks: BOOT_COMCONSOLE_SPEED=19200 If the serial console is configured in some other way than by booting with , or if the serial console used by the kernel is different from the one used by the boot blocks, then you must also add the following option to the kernel configuration file and compile a new kernel: options CONSPEED=19200 Using Serial Port Other Than <devicename>sio0</devicename> For The Console Using a port other than sio0 as the console requires some recompiling. If you want to use another serial port for whatever reasons, recompile the boot blocks, the boot loader and the kernel as follows. Get the kernel source. Edit /etc/make.conf and set BOOT_COMCONSOLE_PORT to the address of the port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only sio0 through sio3 (COM1: through COM4:) can be used; multiport serial cards will not work. No interrupt setting is needed. Create a custom kernel configuration file and add appropriate flags for the serial port you want to use. For example, if you want to make sio1 (COM2:) the console: device sio1 at isa? port "IO_COM2" tty flags 0x10 irq 3 or device sio1 at isa? port "IO_COM2" tty flags 0x30 irq 3 The console flags for the other serial ports should not be set. Recompile and install the boot blocks: &prompt.root; cd /sys/boot/i386/boot2 &prompt.root; make &prompt.root; make install Recompile and install the boot loader: &prompt.root; cd /sys/boot/i386/loader &prompt.root; make &prompt.root; make install Rebuild and install the kernel. Write the boot blocks to the boot disk with &man.disklabel.8; and boot from the new kernel. Entering the DDB Debugger from the Serial Line If you wish to drop into the kernel debugger from the serial console (useful for remote diagnostics, but also dangerous if you generate a spurious BREAK on the serial port!) then you should compile your kernel with the following options: options BREAK_TO_DEBUGGER options DDB Getting a Login Prompt on the Serial Console While this is not required, you may wish to get a login prompt over the serial line, now that you can see boot messages and can enter the kernel debugging session through the serial console. Here is how to do it. Open the file /etc/ttys with an editor and locate the lines: ttyd0 "/usr/libexec/getty std.9600" unknown off secure ttyd1 "/usr/libexec/getty std.9600" unknown off secure ttyd2 "/usr/libexec/getty std.9600" unknown off secure ttyd3 "/usr/libexec/getty std.9600" unknown off secure ttyd0 through ttyd3 corresponds to COM1 through COM4. Change off to on for the desired port. If you have changed the speed of the serial port, you need to change std.9600 to match the current setting, e.g. std.19200. You may also want to change the terminal type from unknown to the actual type of your serial terminal. After editing the file, you must kill -HUP 1 to make this change take effect. Changing Console from the Boot Loader Previous sections described how to set up the serial console by tweaking the boot block. This section shows that you can specify the console by entering some commands and environment variables in the boot loader. As the boot loader is invoked as the third stage of the boot process, after the boot block, the settings in the boot loader will override the settings in the boot block. Setting Up the Serial Console You can easily specify the boot loader and the kernel to use the serial console by writing just one line in /boot/loader.rc: set console=comconsole This will take effect regardless of the settings in the boot block discussed in the previous section. You had better put the above line as the first line of /boot/loader.rc so as to see boot messages on the serial console as early as possible. Likewise, you can specify the internal console as: set console=vidconsole If you do not set the boot loader environment variable console, the boot loader, and subsequently the kernel, will use whichever console indicated by the option in the boot block. In versions 3.2 or later, you may specify the console in /boot/loader.conf.local or /boot/loader.conf, rather than in /boot/loader.rc. In this method your /boot/loader.rc should look like: include /boot/loader.4th start Then, create /boot/loader.conf.local and put the following line there. console=comconsole or console=vidconsole See &man.loader.conf.5; for more information. At the moment, the boot loader has no option equivalent to the option in the boot block, and there is no provision to automatically select the internal console and the serial console based on the presence of the keyboard. Using Serial Port Other than <devicename>sio0</devicename> for the Console You need to recompile the boot loader to use a serial port other than sio0 for the serial console. Follow the procedure described in . Caveats The idea here is to allow people to set up dedicated servers that require no graphics hardware or attached keyboards. Unfortunately, while most systems will let you boot without a keyboard, there are quite a few that will not let you boot without a graphics adapter. Machines with AMI BIOSes can be configured to boot with no graphics adapter installed simply by changing the `graphics adapter' setting in the CMOS configuration to `Not installed.' However, many machines do not support this option and will refuse to boot if you have no display hardware in the system. With these machines, you'll have to leave some kind of graphics card plugged in, (even if it's just a junky mono board) although you will not have to attach a monitor into it. You might also try installing an AMI BIOS. diff --git a/en_US.ISO8859-1/books/handbook/sound/chapter.sgml b/en_US.ISO8859-1/books/handbook/sound/chapter.sgml index 242d89f43c..e242a377f7 100644 --- a/en_US.ISO8859-1/books/handbook/sound/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/sound/chapter.sgml @@ -1,368 +1,368 @@ Moses Moore Contributed Sound Synopsis FreeBSD supports a wide variety of sound cards, allowing you to enjoy high fidelity output from your computer. This includes the ability to record and playback audio in the MPEG Audio Layer 3 (MP3), WAV, and Ogg Vorbis formats as well as many other formats. The FreeBSD Ports Collection also contains applications allowing you to edit your recorded audio, add sound effects, and control attached MIDI devices. After reading this chapter you will know: How to locate your sound card. How to configure your system so that your sound card is recognized. Methods to test that your card is working using sample applications. How to troubleshoot your sound setup. - Before reading this chapter you should: + Before reading this chapter you should: Know how to configure and install a new kernel () Locating the Correct Device PCI ISA sound cards Before you begin, you should know the model of the card you have, the chip it uses, and whether it is a PCI or ISA card. FreeBSD supports a wide variety of both PCI and ISA cards. If you do not see your card in the following list, check the &man.pcm.4; manual page. This is not a complete list; however, it does list some of the most common cards. Crystal 4237, 4236, 4232, 4231 Yamaha OPL-SAx OPTi931 Ensoniq AudioPCI 1370/1371 ESS Solo-1/1E NeoMagic 256AV/ZX Sound Blaster Pro, 16, 32, AWE64, AWE128, Live Creative ViBRA16 Advanced Asound 100, 110, and Logic ALS120 ES 1868, 1869, 1879, 1888 Gravis UltraSound Aureal Vortex 1 or 2 kernel configuration The driver you use in your kernel depends on the kind of card you have. The sections below provide more information and what you will need to add to your kernel configuration. Creative, Advance, and ESS Sound Cards If you have one of the above cards, you will need to add device pcm to your kernel. If you have a PnP ISA card, you will also need to add device sbc to your kernel. For a non-PnP ISA card, add device pcm and device sbc0 at isa? port0x220 irq 5 drq 1 flags 0x15 to your kernel. Those are the default settings. You may need to change the IRQ, etc. See the &man.sbc.4; man page for more information. The Sound Blaster Live is not supported under FreeBSD 4.0 without a patch, which this document will not cover. It is recommended that you update to the latest -STABLE before trying to use this card. Gravis UltraSound Cards For a PnP ISA card, you will need to add device pcm and device gusc to your kernel. If you have a non-PnP ISA card, you will need to add device pcm and device gus0 at isa? port 0x220 irq 5 drq 1 flags 0x13 to your kernel. You may need to change the IRQ, etc. See the &man.gusc.4; man page for more information. Crystal Sound Cards For Crystal cards, you will need both device pcm and device csa in your kernel. Generic Support For PnP ISA or PCI cards, you will need to add device pcm to your kernel configuration. If you have a non-PnP ISA sound card that does not have a bridge driver, you will need to add device pcm0 at isa? irq 10 drq 1 flags 0x0 to your kernel configuration. You may need to change the IRQ, etc., to match your hardware configuration. Recompiling the Kernel After adding the driver(s) you need to your kernel configuration, you will need to recompile your kernel. Please see of the handbook for more information. Creating and Testing the Device Nodes device nodes After you reboot, log in and run cat /dev/sndstat. You should see output similar to the following: FreeBSD Audio Driver (newpcm) Sep 21 2000 18:29:53 Installed devices: pcm0: <Aureal Vortex 8830> at memory 0xfeb40000 irq 5 (4p/1r +channels duplex) If you see an error message, something went wrong earlier. If that happens, go through your kernel configuration file again and make sure you chose the correct device. If it reported no errors and returned pcm0, su to root and do the following: &prompt.root; cd /dev &prompt.root; sh MAKEDEV snd0 If it reported no errors and returned pcm1, su to root and do the following: &prompt.root; cd /dev &prompt.root; sh MAKEDEV snd1 Please note that either of the above commands will not create a /dev/snd device! Instead it creates a group of device nodes including: Device Description /dev/audio SPARC-compatible audio device /dev/dsp Digitized voice device /dev/dspW Like /dev/dsp, but 16 bits per sample /dev/midi Raw midi access device /dev/mixer Control port mixer device /dev/music Level 2 sequencer interface /dev/sequencer Sequencer device /dev/pss Programmable device interface If all goes well, you should now have a functioning sound card. If you do not, see the next section. Common Problems device node I get an unsupported subdevice XX error! One or more of the device nodes wasn't created correctly. Repeat the steps above. I/O port I get a sb_dspwr(XX) timed out error! The I/O port is not set correctly. IRQ I get a bad irq XX error! The IRQ is set incorrectly. Make sure that the set IRQ and the sound IRQ are the same. I get a xxx: gus pcm not attached, out of memory error. What causes that? If this happens, it is because there is not enough available memory to use the device. diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml index f056c18c12..069f1a356f 100644 --- a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml @@ -1,1139 +1,1139 @@ The X Window System Synopsis FreeBSD uses XFree86 to provide users with a powerful graphical user interface. XFree86 is a open-source implementation of the X Window System. The following chapter will cover installation and configuration of XFree86 on your FreeBSD system. For more information on X11 and to see whether your video card is supported, check the XFree86 web site. After reading this chapter you will know: How to install and configure XFree86. How to install and use different window managers How to use TrueType fonts in XFree86 How to setup your system for graphical logins (XDM). - Before reading this chapter you should: + Before reading this chapter you should: Know how to install additional third-party software () Installing XFree86 XFree86 is available as a port and as a package, making it easy to install. You can also download the binaries directly from the XFree86 organization and install them by hand, following the instructions provided by the XFree86 group. Your only decision is which version of XFree86 to run. XFree86 3.X is the maintenance branch of XFree86 development. It's very stable, and it supports a huge number of graphics cards. However, no new development is happening there. XFree86 4.X is a redesign of XFree86. As well as introducing many new features (including much better support for fonts and anti-aliasing), XFree86 4.X supports slightly fewer graphics cards. If your card is supported we recommend you run 4.X. If it is not then run 3.X. The rest of this chapter will explain how to configure XFree86, and suggest various programs for X that you might want to try. Christopher Shumway XFree86 Configuration Introduction This chapter will introduce the steps necessary to install and configure the XFree86 X Windows System under FreeBSD. Once the server is installed and configured properly. The user can read to setup their desktop environment. XFree86 4.X XFree86 Before You Start Before the user is to start configuration of XFree86-4, the the following information will need to be known about the target system: Monitor specifications Video Adapter chipset Video Adapter memory horizontal scan rate vertical scan rate The specifications for the target system's monitor are used by XFree86 to determine the resolution and refresh rate to run at. These specifications can usually be obtained from the documentation that came with the target system's 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 XFree86 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 doesn't work correctly. Video memory on the graphic adapter determines the resolution and color depth the target system can run at. This is important to know so the user knows the limitations of the target system. Installing XFree86 4.X software XFree86 4 can be installed using the FreeBSD ports system or using &man.pkg.add.1;. If the user is building XFree86-4 from source and has USA_RESIDENT set in /etc/make.conf, the user may first have to fetch Wraphelp.c if XDM-AUTHORIZATION-1 support is desired. This file is to be placed in the port's files/ sub-directory before the port is built. Configuring XFree86 4.X Configuration of XFree86 4.X is a several step process. The first step is to build an initial configuration file with the configure option to XFree86. As the super user, simply run: &prompt.root; XFree86 -configure This will generate a skeleton XFree86 configuration file in the current working directory called XF86Config.new. The XFree86 program will attempt to probe the graphics hardware on the system and will write a configuration file to load the proper drivers for the detected hardware on the target system. The next step is to test the currently existing configuration to verify that XFree86 can work with the graphics hardware on the target system. To preform this task, the user needs to run: &prompt.root; XFree86 -xf86config XF86Config.new If the user is presented with a black and grey grid and an X mouse cursor, then the configuration was successful. To exit the test, just press ctrl, alt and backspace simultaneously. XFree86 4 Tuning Next, the user needs to tune the XF86Config.new configuration file to their personal taste. Open up the file in a text editor such as &man.emacs.1; or &man.ee.1;. The first thing the user will want to do is 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 XF86Config.new file under the "Monitor" section as such: Section "Monitor" Identifier "Monitor0" VendorName "Monitor Vendor" ModelName "Monitor Model" Horizsync 30-107 VertRefresh 48-120 EndSection The Horizsync and VertRefresh keywords may not exist in the user's configuration file. If they do not, 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 where entered. XF86Config While the XF86Config.new configuration file is still open in an editor, next the user needs to select what the default resolution and color depth is desired. This is defined in the Screen section. Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" DefaultColorDepth 24 SubSection "Display" Depth 24 Modes "1024x768" EndSubSection EndSection The DefaultColorDepth keyword describes the color depth the user wishes to run at by default. This can be overridden with the -bpp command line switch to XFree86 1. The Modes keyword describes the resolution the user wishes to run at for the given color depth. In the example above, the default color depth is twenty four bits per pixel. At this color depth, the accepted resolution is one thousand twenty four pixels by seven hundred and sixty eight pixels. If a user wants to run at a resolution of one thousand twenty four pixels by seven hundred sixty eight pixels at twenty four bits per pixel, then the user needs to add the DefaultColorDepth keyword with the value of twenty four, and add to the "Display" subsection with the desired Depth the Modes keyword with the resolution the user wishes to run at. Note that only VESA standard modes are supported as defined by the target system's graphics hardware. Finally, the user can write out the configuration file and test it using the test mode given above. If all is well, then the configuration file needs to be installed in a common location where XFree86 1 can source it in the future. This is typically /etc/X11/XF86Config or /usr/X11R6/etc/X11/XF86Config. &prompt.root; cp XF86Config.new /etc/X11/XF86Config Once the configuration file has been placed in a common location, XFree86 can then be used through &man.xdm.1;. In order to use startx 1 the user will have to install the X11/wrapper port. 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 XFree86 to be able to drive the card. To enable the agpgart programming interface, the agp.ko kernel loadable module needs to be loaded into the kernel with &man.kldload.8;. This can be done automatically with the &man.loader.8;. Simply add this line to /boot/loader.conf to have the loader load agp.ko at boot time: agp_load="YES" Next, 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 as such: &prompt.root; cd /dev &prompt.root; sh MAKEDEV agpgart This will allow the user to configure the graphics hardware as any other graphics board. Murray Stokely Section on fonts Using Fonts in XFree86 Type1 Fonts The default fonts that ship with XFree86 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 XFree86, either version 3.X or version 4.X. For instance, the URW font collection (x11-fonts/urwfonts) includes high quality versions of standard type1 fonts (Times Roman, Helvetica, Palatino and others). The Freefont collection (x11-fonts/freefont) 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, XFree86 can be configured to use TrueType fonts with a minimum of effort: see the section on TrueType fonts later. To install the above Type1 font collections from the ports collection you can 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 tell the X server that these fonts exist, you can add an appropriate line to your XF86Config file (in /etc/ for XFree86 version 3, or in /etc/X11/ for version 4), which reads: FontPath "/usr/X11R6/lib/X11/fonts/URW/" Alternatively, at the command line in your X session you can write: &prompt.user; xset fp+ /usr/X11R6/lib/X11/fonts/URW &prompt.user; xset fp rehash This will work but will be lost when you log out from this session, unless you add it to your 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 XftConfig file: see the section on anti-aliasing, later. TrueType Fonts XFree86 4.0 has built in support for rendering TrueType fonts. There are two different modules that can enable this functionality. The "freetype" module is used in this example because it is more consistent with the other font rendering back-ends. To enable the freetype module just add the following line to the module section of your /etc/X11/XF86Config file. Load "freetype" For XFree86 3.3.X you will need to run a separate TrueType font server. Xfstt is commonly used for this purpose. To install x11-servers/Xfstt on your FreeBSD system simply install the port from /usr/ports/x11-servers/Xfstt You should now make a directory for your TrueType fonts (e.g. /usr/X11R6/lib/X11/fonts/TrueType) and copy all of your TrueType fonts into this directory. Keep in mind that you cannot take TrueType fonts directly from a Macintosh; they must be in Unix/DOS/Windows format for use by XFree86. Once you have copied the files into this directory you need to use ttmkfdir to create a fonts.dir file so that the X font renderer knows that you've installed these new files. There is a FreeBSD port for x11-fonts/ttmkfdir in /usr/ports/x11-fonts/ttmkfdir. &prompt.root; cd /usr/X11R6/lib/X11/fonts/TrueType &prompt.root; ttmkfdir > fonts.dir Now you need to add your TrueType directory to your fonts 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 line to the XF86Config file. That's it. Now Netscape, Gimp, StarOffice, and all of your other X applications should now recognize your installed TrueType fonts. Extremely small fonts (as with text in a high resolution display on a web page) and extremely large fonts (within StarOffice) will look much better now. Anti-Aliasing your fonts Starting with version 4.0.2, XFree86 supports anti-aliased fonts. Currently, most software has not been updated to take advantage of this new functionality. However, Qt (the toolkit for the KDE desktop) does; so if you are running XFree86 4.0.2 (or higher), Qt 2.3 (or higher) and KDE, all your KDE/Qt applications can be made to use anti-aliased fonts. To configure anti-aliasing, you need to create (or edit, if it already exists) the file /usr/X11R6/lib/X11/XftConfig. Several advanced things can be done with this file; this section describes only the simplest possibilities. First, you need to tell the X server about the fonts which you want anti-aliased. To do that, for each font directory you have a line, which looks like this: dir "/usr/X11R6/lib/X11/Type1" And likewise for the other font directories (URW, truetype, etc) containing fonts you'd like anti-aliased. Anti-aliasing makes sense only for scalable fonts (basically, Type1 and TrueType) so don't include bitmap font directories here. The directories which you included here can now be commented out of your XF86Config file. Next, you may not want to anti-alias normal-sized text. (Antialiasing 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 point sizes between 9 and 13 from anti-aliasing, include these lines: match any size > 8 any size < 14 edit antialias = false; You may also find that the spacing for some monospaced fonts gets messed up when you turn on 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 any family == "fixed" edit family =+ "mono"; match any family == "console" edit family =+ "mono"; (this aliases the other common names for fixed fonts as "mono"), and then add: match any family == "mono" edit spacing = 100; Supposing you want to use the Lucidux fonts whenever monospaced fonts are required (these look nice, and don't seem to suffer from the spacing problem), you could replace that last line with these: match any family == "mono" edit family += "LuciduxMono"; match any family == "Lucidux Mono" edit family += "LuciduxMono"; match any family == "LuciduxMono" edit family =+ "Lucidux Mono"; (the last lines alias different equivalent family names). Finally, you want to allow users to add commands to this file, via their personal .xftconfig files. To do this, add a last line: includeif "~/.xftconfig" That's all; anti-aliasing should be enabled the next time you start the X server. However, note that your programs must know how to take advantage of it. At the present time, the toolkit Qt does, so the entire KDE environment can use anti-aliased fonts (see on KDE for details); there are patches for gtk+ to do the same, so if compiled against such a patched gtk+, the GNOME environment and Mozilla can also use anti-aliased fonts. Anti-aliasing is still new to FreeBSD and XFree86; configuring it should get easier with time, and it will soon be supported by many more applications. Seth Kingsley Section on XDM The X Display Manager Overview 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 (see ), 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. You may 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. You can run this program at any time as root and it will start managing the X display on the local machine. If you want XDM to run in the background 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, and in order to enable it you will need to change field 5 from off to on and then 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 you will see several files used to change the behavior and appearance of XDM. Typically you will find these files: 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_* 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 setup the desktop when XDM is running. In the next few sections I will briefly describe the purpose of each of these files. 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 if you are planning to design your own look and feel for the XDM screens. Xaccess The protocol for connecting to XDM controlled displays is called the X Display Manager Connection Protocol (XDMCP). This file is basically just a ruleset for controlling XDMCP connections from remote machines. By default, it allows any client to connect, but you will see this will not matter because the default xdm-config file does not listen for remote connections. Xresources This is an application-defaults file for the display chooser and the login screens. This is where you can customize the appearance of the login program. The format is identical to the app-defaults file described in the XFree86 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 ~/.xsessionrc that overrides this script. Xsetup_* These files contain scripts that 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 file contains settings in the form of app-defaults that are applicable to every display that this installation manages. xdm-errors This file 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 your display server, you will need to edit the access control rules, and enable the connection listener. By default these are set to conservative values, which is a good decision security-wise. To get XDM to 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 a #. After this, you may need to put more strict access controls in place. Look at the example entries in Xaccess file, 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 in a later section. Apart from various visual improvements and cosmetic frills, it can be easily configured to let users choose their window manager of choice at the time they log in. Desktop Environments Written by &a.logo;, June 2001 This section describes the different desktop environments available for X-Windows on FreeBSD. For our purposes a "desktop environment" will mean anything ranging from a simple window manager, to a complete suite of desktop applications such as KDE or GNOME. GNOME About 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. Installing GNOME To install GNOME from the network, simply type: &prompt.root; pkg_add -r gnome If you would rather build GNOME from source, then use the ports tree: &prompt.root; cd /usr/ports/x11/gnome &prompt.root; make install clean Once GNOME is installed, we must have the X server start GNOME instead of a default window manager. If you have already customized your .xinitrc file then you should simply replace the line that starts your current window manager with one that starts /usr/X11R6/bin/gnome-wm instead. If you haven't added anything special to your configuration file, then it is enough to simply type: &prompt.root; echo "/usr/X11R6/bin/gnome-wm" > ~/.xinitrc That's it. Type startx and you will be in the GNOME desktop environment. If you're running a display manager like XDM, this will not work. Instead, you should create an executable .xsession file with the same command in it. To do this, edit your file (if you already have one) and replace the existing window manager command with /usr/X11R6/bin/gnome-wm; or else, &prompt.root; echo "#!/bin/sh" > ~/.xsession &prompt.root; echo "/usr/X11R6/bin/gnome-wm" >> ~/.xsession &prompt.root; chmod +x ~/.xsession Another option is to configure your display manager to allow choosing the window manager at login time; the section on KDE2 details explains how to do this for kdm, the display manager of KDE. KDE2 About KDE2 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 is also comes with a web browser called Konqeuror, which represents already a solid competitor to other existing web browsers on Unix systems. More information on KDE can be found on the KDE website Installing KDE2 At the time of writing, a package for kde2 doesn't exist yet. No problem! The ports tree hides all the complexity of building a package from source. To install KDE2, do this : &prompt.root; cd /usr/ports/x11/kde2 &prompt.root; make install clean This command will fetch all the necessary files from the Internet, configure and compile KDE2, install the applications, and then clean up after itself. Now you're going to have to tell the X server to launch KDE2 instead of a default window manager. Do this by typing this: &prompt.root; echo "/usr/X11R6/bin/startkde" > ~/.xinitrc Now, whenever you go into X-Windows, KDE2 will be your desktop. (Note: this will not work if you're logging in via a display manager like xdm. In that case you have two options: create an .xsession file as described in the section on GNOME, but with the /usr/X11R6/bin/startkde command instead of the gnome-wm command; or, configure your display manager to allow choosing a desktop at login time. Below it is explained how to do this for kdm, KDE's display manager.) More details on KDE2 Now that KDE2 is installed on your system, you'll find that you can learn a lot from its 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. This section only discusses somewhat technical things which are difficult to learn just by random exploration. The KDE display manager If you're an administrator on a multi-user system, you may like to have a graphical login screen to welcome users. You can use xdm, 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 (KDE2, GNOME, or something else) to run after logging on. If you're slightly adventurous and you want this added flexibility and visual appeal, read on. To begin with, run the KDE2 control panel, kcontrol, as root. Note: it is generally considered unsafe to run your entire X environment as root. Instead, run your window manager as a normal user, open a terminal window (such as xterm or KDE's konsole, become root with su (you need to 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 you'll see various configurable options, which the KDE manual will explain in greater detail. Click on "sessions" on the right. Depending on what window managers or desktop environments you have currently installed, you can type their names in "New type" and add them. (These are just labels so far, not commands, so you can write KDE and GNOME rather than startkde or gnome-wm.) Include a label failsafe. Play with the other menus as you like (those are mainly cosmetic and self-explanatory). When you're done, click on "Apply" at the bottom, and quit the control center. To make sure kdm understands what your above labels (KDE, GNOME etc) mean, you need to edit some more files: the same ones used by xdm. In your terminal window, as root, edit the file /usr/X11R6/lib/X11/xdm/Xsession. You will come across a section in the middle looking like this (by default): case $# in 1) case $1 in failsafe) exec xterm -geometry 80x24-0-0 ;; esac esac You will need to add a few lines to this section. Assuming the labels you gave earlier were KDE2 and GNOME, the following will do: case $# in 1) case $1 in KDE2) exec /usr/X11R6/bin/startkde ;; GNOME) exec /usr/X11R6/bin/gnome-wm ;; failsafe) exec xterm -geometry 80x24-0-0 ;; esac esac To make sure your KDE choice of a login-time desktop background is also honored, you will need to add the following line to /usr/X11R6/lib/X11/xdm/Xsetup_0: /usr/X11R6/bin/kdmdesktop Now, you need only to make sure kdm is started at the next bootup. To learn how to do this, read the section on xdm, and do the same thing replacing references to the xdm program by kdm. That's it. Your next login screen should have a pretty face and lots of menus. Anti-aliased fonts Tired of blocky staircase edges to your fonts under X11? Tired of unreadable text in web browsers? Well, no more. Starting with version 4.0.2, XFree86 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 if you're running up-to-date software, anti-aliasing is possible on your KDE2 desktop. Just go to your KDE2 menu, go to Preferences -> Look and Feel -> Style, and click on the checkbox "Use Anti-Aliasing for Fonts and Icons". That's all. If you're running a Qt application which is not part of KDE, you may need to set the environment variable QT_XFT to true before starting your program. XFCE About XFCE XFCE is 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 app 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 do this: &prompt.root; pkg_add -r xfce Alternatively, you may prefer to build from source. The ports tree comes to the rescue again: &prompt.root; cd /usr/ports/x11-wm/xfce &prompt.root; make install clean All necessary source packages (including dependencies) will be automagically fetched, built and installed, and the build areas cleaned up afterwards. Now you want to tell the X server to launch XFCE the next time you start X. Simply type this: &prompt.root; echo "/usr/X11R6/bin/startxfce" > ~/.xinitrc The next time you start X, XFCE will be your desktop. (Note, as before: if you're logging in via a display manager like xdm, you should either create an .xsession, as described in the section on GNOME, but with the /usr/X11R6/bin/startxfce command; or, configure your display manager to allow choosing a desktop at login time, as explained in the section on kdm.)