diff --git a/en_US.ISO8859-1/articles/explaining-bsd/article.sgml b/en_US.ISO8859-1/articles/explaining-bsd/article.sgml index 619658d112..27634dd7a4 100644 --- a/en_US.ISO8859-1/articles/explaining-bsd/article.sgml +++ b/en_US.ISO8859-1/articles/explaining-bsd/article.sgml @@ -1,542 +1,542 @@ %man; ]>
Explaining BSD Greg Lehey
grog@FreeBSD.org
 In the open source world, the word Linux is almost synonymous with Operating System, but it's not the only open source UNIX operating system. According to the Internet Operating System Counter, as of April 1999 31.3% of the world's network connected machines run Linux. 14.6% run BSD UNIX. Some of the world's largest web operations, such as Yahoo!, run BSD. The world's - busiest ftp server, ftp.cdrom.com, uses BSD to transfer 1.4 TB of data a day. Clearly this is not a niche market: BSD is a well-kept secret. So what's the secret? Why isn't BSD better known? This white paper addresses these and other questions. Throughout this paper, differences between BSD and Linux will be noted like this. What is BSD? BSD stands for Berkeley Software Distribution. It is the name of distributions of source code from the University of California, Berkeley, which were originally extensions to AT&T's Research UNIX operating system. Several open source operating system projects are based on a release of this source code known as 4.4BSD-Lite. In addition, they comprise a number of packages from other Open Source projects, including notably the GNU project. The overall operating system comprises: The BSD kernel, which handles process scheduling, memory management, symmetric multi-processing (SMP), device drivers, etc. Unlike the Linux kernel, there are several different BSD kernels with differing capabilities. The C library, the base API for the system. The BSD C library is based on code from Berkeley, not the GNU project. Utilities such as shells, file utilities, compilers and linkers. Some of the utilities are derived from the GNU project, others are not. The X Window system, which handles graphical display. The X Window system used in most versions of BSD is maintained by a separate project, the XFree86 project. This is the same code as Linux uses. BSD does not normally specify a graphical desktop such as GNOME or KDE, though these are available. Many other programs and utilities. What, a real UNIX? The BSD operating systems are not clones, but open source derivatives of AT&T's Research UNIX operating system, which is also the ancestor of the modern UNIX System V. This may surprise you. How could that happen when AT&T has never released its code as open source? It's true that AT&T UNIX is not open source, and in a copyright sense BSD is very definitely not UNIX, but on the other hand, AT&T has imported sources from other projects, noticeably the Computer Sciences Research Group of the University of California in Berkeley, CA. Starting in 1976, the CSRG started releasing tapes of their software, calling them Berkeley Software Distribution or BSD. Initial BSD releases consisted mainly of user programs, but that changed dramatically when the CSRG landed a contract with the Defense Advanced Projects Research Agency (DARPA) to upgrade the communications protocols on their network, ARPANET. The new protocols were known as the Internet Protocols, later TCP/IP after the most important protocols. The first widely distributed implementation was part of 4.2BSD, in 1982. In the course of the 1980s, a number of new workstation companies sprang up. Many preferred to license UNIX rather than developing operating systems for themselves. In particular, Sun Microsystems licensed UNIX and implemented a version of 4.2BSD, which they called SunOS. When AT&T themselves were allowed to sell UNIX commercially, they started with a somewhat bare-bones implementation called System III, to be quickly followed by System V. The System V code base did not include networking, so all implementations included additional software from the BSD, including the TCP/IP software, but also utilities such as the csh shell and the vi editor. Collectively, these enhancements were known as the Berkeley Extensions. The BSD tapes contained AT&T source code and thus required a UNIX source license. By 1990, the CSRG's funding was running out, and it faced closure. Some members of the group decided to release the BSD code, which was Open Source, without the AT&T proprietary code. This finally happened with the Networking Tape 2, usually known as Net/2. Net/2 was not a complete operating system: about 20% of the kernel code was missing. One of the CSRG members, William F. Jolitz, wrote the remaining code and released it in early 1992 as 386BSD. At the same time, another group of ex-CSRG members formed a commercial company called Berkeley Software Design Inc. and released a beta version of an operating system called BSD/386, which was based on the same sources. The name of the operating system has since changed to BSD/OS. 386BSD never became a stable operating system. Instead, two other projects split off from it in 1993: NetBSD and FreeBSD. The two projects originally diverged due to differences in patience waiting for improvements to 386BSD: the NetBSD people started early in the year, and the first version of FreeBSD wasn't ready until the end of the year. In the meantime, the code base had diverged sufficiently to make it difficult to merge. In addition, the projects had different aims, as we'll see below. In 1996, a further project, OpenBSD, split off from NetBSD. Why isn't BSD better known? For a number of reasons, BSD is relatively unknown: The BSD developers are often more interested in polishing their code than marketing it. Much of Linux's popularity is due to factors external to the Linux projects, such as the press, and to companies formed to provide Linux services. Until recently, the open source BSDs had no such proponents. BSD developers tend to be more experienced than Linux developers, and have less interest in making the system easy to use. Newcomers tend to feel more comfortable with Linux. In 1992, AT&T sued BSDI, the vendor of BSD/386, alleging that the product contained AT&T-copyrighted code. The case was settled out of court in 1994, but the spectre of the litigation continues to haunt people. As recently as March 2000 an article published on the web claimed that the court case had been recently settled. One detail that the lawsuit did clarify is the naming: in the 1980s, BSD was known as BSD UNIX. With the elimination of the last vestige of AT&T code from BSD, it also lost the right to the name UNIX. Thus you will see references in book titles to the 4.3BSD UNIX operating system and the 4.4BSD operating system. There is a perception that the BSD projects are fragmented and belligerent. The Wall Street Journal spoke of balkanization of the BSD projects. Like the law suit, this perception bases mainly on ancient history. Comparing BSD and Linux So what's really the difference between, say, Debian Linux and FreeBSD? For the average user, the difference is surprisingly small: Both are UNIX-like operating systems. Both are developed by non-commercial projects (this doesn't apply to many other Linux distributions, of course). In the following section, we'll look at BSD and compare it to Linux. The description applies most closely to FreeBSD, which accounts for an estimated 80% of the BSD installations, but the differences from NetBSD and OpenBSD are small. Who owns BSD? No one person or corporation owns BSD. It is created and distributed by a community of highly technical and committed contributors all over the world. Some of the components of BSD are Open Source projects managed by a different project maintainer. How is BSD developed and updated? The BSD kernels are developed and updated following the Open Source development model. Each project maintains a publicly accessible source tree under the Concurrent Versions System (CVS), which contains all source files for the project, including documentation and other incidental files. CVS allows users to check out (in other words, to extract a copy of) any desired version of the system. A large number of developers worldwide contribute to improvements to BSD. They are divided into three kinds: Contributors write code or documentation. They are not permitted to commit (add code) directly to the source tree. In order for their code to be included in the system, it must be reviewed and checked in by a registered developer, known as a committer. Committers are developers with write access to the source tree. In order to become a committer, an individual must show ability in the area in which he is active. It is at the individual committer's discretion whether he should obtain authority before committing changes to the source tree. In general, an experienced committer may make changes which are obviously correct without obtaining consensus. For example, a documentation project committer may correct typographical or grammatical errors without review. On the other hand, developers making far-reaching or complicated changes are expected to submit their changes for review before committing them. In extreme cases, a core team member with a function such as Principal Architect may order that changes be removed from the tree, a process known as backing out. All committers receive mail describing each individual commit, so it is not possible to commit secretly. Core team In addition, FreeBSD and NetBSD each have a core team which manages the project. The core teams developed in the course of the projects, and their role is not always well-defined. It is not necessary to be a developer in order to be a core team member, though it is normal. The rules for the core team vary from one project to the other, but in general they have more say in the direction of the project than non-core team members have. This arrangement differs from Linux in a number of ways: No one person controls the content of the system. In practice, this difference is overrated, since the Chief Architect can require that code be backed out, and even in the Linux project several people are permitted to make changes. On the other hand, there is a central repository, a single place where you can find the entire operating system sources, including all older versions. BSD projects maintain the entire Operating System, not only the kernel. This distinction is only marginally useful: neither BSD nor Linux is useful without applications. The applications used under BSD are frequently the same as the applications used under Linux. As a result of the formalized maintenance of a single CVS source tree, BSD development is clear, and it is possible to access any version of the system by release number or by date. CVS also allows incremental updates to the system: for example, the FreeBSD repository is updated about 100 times a day. Most of these changes are small. BSD releases Each BSD project provides the system in three different releases. As with Linux, releases are assigned a number such as 1.4.1 or 3.5. In addition, the version number has a suffix indicating its purpose: The development version of the system is called CURRENT. FreeBSD assigns a number to CURRENT, for example FreeBSD 5.0-CURRENT. NetBSD uses a slightly different naming scheme and appends a single-letter suffix which indicates changes in the internal interfaces, for example NetBSD 1.4.3G. OpenBSD does not assign a number ("OpenBSD-current"). All new development on the system goes into this branch. At regular intervals, between two and four times a year, the projects bring out a RELEASE version of the system, which is available on CD-ROM and for free download from - ftp sites, for example OpenBSD 2.6-RELEASE or NetBSD 1.4-RELEASE. + FTP sites, for example OpenBSD 2.6-RELEASE or NetBSD 1.4-RELEASE. The RELEASE version is intended for end users and is the normal version of the system. NetBSD also provides patch releases with a third digit, for example NetBSD 1.4.2. As bugs are found in a RELEASE version, they are fixed, and the fixes are added to the CVS tree. In FreeBSD, the resultant version is called the STABLE version, while in NetBSD and OpenBSD it continues to be called the RELEASE version. Smaller new features can also be added to this branch after a period of test in the CURRENT branch. By contrast, Linux maintains two separate code trees: the stable version and the development version. Stable versions have an even minor version number, such as 2.0, 2.2 or 2.4. Development versions have an odd minor version number, such as 2.1, 2.3 or 2.5. In each case, the number is followed by a further number designating the exact release. In addition, each vendor adds their own userland programs and utilities, so the name of the distribution is also important. Each distribution vendor also assigns version numbers to the distribution, so a complete description might be something like TurboLinux 6.0 with kernel 2.2.14 What versions of BSD are available? In contrast to the numerous Linux distributions, there are only three open source BSDs. Each BSD project maintains its own source tree and its own kernel. In practice, though, there appear to be fewer divergences between the userland code of the projects than there is in Linux. It's difficult to categorize the goals of each project: the differences are very subjective. Basically, FreeBSD aims for high performance and ease of use by end users, and is a favourite of web content providers. It runs on PCs and Compaq's Alpha processors. The FreeBSD project has significantly more users than the other projects. NetBSD aims for maximum portability: of course it runs NetBSD. It runs on machines from palmtops to large servers, and has even been used on NASA space missions. It is a particularly good choice for running on old non-Intel hardware. OpenBSD aims for security and code purity: it uses a combination of the open source concept and rigorous code reviews to create a system which is demonstrably correct, making it the choice of security-conscious organizations such as banks, stock exchanges and US Government departments. Like NetBSD, it runs on a number of platforms. There are also two additional BSD operating systems which are not open source, BSD/OS and Apple's Mac OS X: BSD/OS is the oldest of the 4.4BSD derivatives. It is not open source, though source code licenses are available at relatively low cost. It resembles FreeBSD in many ways. Mac OS X is the latest version of the operating system for Apple Computer Inc.'s Macintosh line. Unlike the rest of the operating system, the kernel is open source. As part of this development, key Apple developers have commit access to the FreeBSD source tree. How does the BSD license differ from the GNU Public license? Linux is available under the GNU General Public License (GPL), which is designed to eliminate closed source software. In particular, any derivative work of a product released under the GPL must also be supplied with source code if requested. By contrast, the BSD license is less restrictive: binary-only distributions are allowed. This is particularly attractive for embedded applications. What else should I know? Since fewer applications are available for BSD than Linux, the BSD developers created a Linux compatibility package, which allows Linux programs to run under BSD. The package includes both kernel modifications, in order to correctly perform Linux system calls, and Linux compatibility files such as the C library. There is no noticeable difference in execution speed between a Linux application running on a Linux machine and a Linux application running on a BSD machine of the same speed. The all from one supplier nature of BSD means that upgrades are much easier to handle than is frequently the case with Linux. BSD handles library version upgrades by providing compatibility modules for earlier library versions, so it is possible to run binaries which are several years old with no problems. Which should I use, BSD or Linux? What does this all mean in practice? Who should use BSD, who should use Linux? This is a very difficult question to answer. Here are some guidelines: If it ain't broke, don't fix it: If you already use an open source operating system, and you are happy with it, there's probably no good reason to change. BSD systems, in particular FreeBSD, can have notably higher performance than Linux. But this isn't across the board. In many cases, there is little or no difference in performance. In some cases, Linux may perform better than FreeBSD. In general, BSD systems have a better reputation for reliability, mainly as a result of the more mature code base. The BSD license may be more attractive than the GPL. BSD can execute Linux code, while Linux can't execute BSD code. As a result, more software is available for BSD than for Linux. Who provides support, service, and training for BSD? BSDi have always supported BSD/OS, and they have recently announced support contracts for FreeBSD. In addition, each of the projects has a list of consultants for hire: FreeBSD, NetBSD, and OpenBSD.
diff --git a/en_US.ISO8859-1/articles/new-users/article.sgml b/en_US.ISO8859-1/articles/new-users/article.sgml index dbff31d29d..b94ef29961 100644 --- a/en_US.ISO8859-1/articles/new-users/article.sgml +++ b/en_US.ISO8859-1/articles/new-users/article.sgml @@ -1,1034 +1,1034 @@ - +
For People New to Both FreeBSD and Unix Annelise Anderson
andrsn@andrsn.stanford.edu
 August 15, 1997 Congratulations on installing FreeBSD! This introduction is for people new to both FreeBSD and Un*x—so it starts with basics. It assumes you're using version 2.0.5 or later of FreeBSD as distributed by BSDi or FreeBSD.org, your system (for now) has a single user (you)—and you're probably pretty good with DOS/Windows or OS/2. Logging in and Getting Out Log in (when you see login:) as a user you created during installation or as root. (Your FreeBSD installation will already have an account for root; root can go anywhere and do anything, including deleting essential files, so be careful!) The symbols &prompt.user; and &prompt.root; in the following stand for the prompt (yours may be different), with &prompt.user; indicating an ordinary user and &prompt.root; indicating root. To log out (and get a new login: prompt) type &prompt.root; exit as often as necessary. Yes, press enter after commands, and remember that Unix is case-sensitive—exit, not EXIT. To shut down the machine type &prompt.root; /sbin/shutdown -h now Or to reboot type &prompt.root; /sbin/shutdown -r now or &prompt.root; /sbin/reboot You can also reboot with CtrlAltDelete. Give it a little time to do its work. This is equivalent to /sbin/reboot in recent releases of FreeBSD and is much, much better than hitting the reset button. You don't want to have to reinstall this thing, do you? Adding A User with Root Privileges If you didn't create any users when you installed the system and are thus logged in as root, you should probably create a user now with &prompt.root; adduser The first time you use adduser, it might ask for some defaults to save. You might want to make the default shell csh instead of sh, if it suggests sh as the default. Otherwise just press enter to accept each default. These defaults are saved in /etc/adduser.conf, an editable file. Suppose you create a user jack with full name Jack Benimble. Give jack a password if security (even kids around who might pound on the keyboard) is an issue. When it asks you if you want to invite jack into other groups, type wheel Login group is ``jack''. Invite jack into other groups: wheel This will make it possible to log in as jack and use the su command to become root. Then you won't get scolded any more for logging in as root. You can quit adduser any time by typing CtrlC, and at the end you'll have a chance to approve your new user or simply type n for no. You might want to create a second new user (jill?) so that when you edit jack's login files, you'll have a hot spare in case something goes wrong. Once you've done this, use exit to get back to a login prompt and log in as jack. In general, it's a good idea to do as much work as possible as an ordinary user who doesn't have the power—and risk—of root. If you already created a user and you want the user to be able to su to root, you can log in as root and edit the file /etc/group, adding jack to the first line (the group wheel). But first you need to practice vi, the text editor--or use the simpler text editor, ee, installed on recent version of FreeBSD. To delete a user, use the rmuser command. Looking Around Logged in as an ordinary user, look around and try out some commands that will access the sources of help and information within FreeBSD. Here are some commands and what they do: id Tells you who you are! pwd Shows you where you are—the current working directory. ls Lists the files in the current directory. ls Lists the files in the current directory with a * after executables, a / after directories, and an @ after symbolic links. ls Lists the files in long format—size, date, permissions. ls Lists hidden dot files with the others. If you're root, the dot files show up without the switch. cd Changes directories. cd .. backs up one level; note the space after cd. cd /usr/local goes there. cd ~ goes to the home directory of the person logged in—e.g., /usr/home/jack. Try cd /cdrom, and then ls, to find out if your CDROM is mounted and working. view filename Lets you look at a file (named filename) without changing it. Try view /etc/fstab. :q to quit. cat filename Displays filename on screen. If it's too long and you can see only the end of it, press ScrollLock and use the up-arrow to move backward; you can use ScrollLock with man pages too. Press ScrollLock again to quit scrolling. You might want to try cat on some of the dot files in your home directory—cat .cshrc, cat .login, cat .profile. You'll notice aliases in .cshrc for some of the ls commands (they're very convenient). You can create other aliases by editing .cshrc. You can make these aliases available to all users on the system by putting them in the system-wide csh configuration file, /etc/csh.cshrc. Getting Help and Information Here are some useful sources of help. Text stands for something of your choice that you type in—usually a command or filename. apropos text Everything containing string text in the whatis database. man text The man page for text. The major source of documentation for Un*x systems. man ls will tell you all the ways to use the ls command. Press Enter to move through text, Ctrlb to go back a page, Ctrlf to go forward, q or Ctrlc to quit. which text Tells you where in the user's path the command text is found. locate text All the paths where the string text is found. whatis text Tells you what the command text does and its man page. Typing whatis * will tell you about all the binaries in the current directory. whereis text Finds the file text, giving its full path. You might want to try using whatis on some common useful commands like cat, more, grep, mv, find, tar, chmod, chown, date, and script. more lets you read a page at a time as it does in DOS, e.g., ls -l | more or more filename. The * works as a wildcard—e.g., ls w* will show you files beginning with w. Are some of these not working very well? Both locate and whatis depend on a database that's rebuilt weekly. If your machine isn't going to be left on over the weekend (and running FreeBSD), you might want to run the commands for daily, weekly, and monthly maintenance now and then. Run them as root and give each one time to finish before you start the next one, for now. &prompt.root; periodic daily output omitted &prompt.root; periodic weekly output omitted &prompt.root; periodic monthly output omitted If you get tired of waiting, press AltF2 to get another virtual console, and log in again. After all, it's a multi-user, multi-tasking system. Nevertheless these commands will probably flash messages on your screen while they're running; you can type clear at the prompt to clear the screen. Once they've run, you might want to look at /var/mail/root and /var/log/messages. Running such commands is part of system administration—and as a single user of a Unix system, you're your own system administrator. Virtually everything you need to be root to do is system administration. Such responsibilities aren't covered very well even in those big fat books on Unix, which seem to devote a lot of space to pulling down menus in windows managers. You might want to get one of the two leading books on systems administration, either Evi Nemeth et.al.'s UNIX System Administration Handbook (Prentice-Hall, 1995, ISBN 0-13-15051-7)—the second edition with the red cover; or Æleen Frisch's Essential System Administration (O'Reilly & Associates, 1993, ISBN 0-937175-80-3). I used Nemeth. Editing Text To configure your system, you need to edit text files. Most of them will be in the /etc directory; and you'll need to su to root to be able to change them. You can use the easy ee, but in the long run the text editor vi is worth learning. There's an excellent tutorial on vi in /usr/src/contrib/nvi/docs/tutorial if you - have that installed; otherwise you can get it by ftp to + have that installed; otherwise you can get it by FTP to ftp.cdrom.com in the directory FreeBSD/FreeBSD-current/src/contrib/nvi/docs/tutorial. Before you edit a file, you should probably back it up. Suppose you want to edit /etc/rc.conf. You could just use cd /etc to get to the /etc directory and do: &prompt.root; cp rc.conf rc.conf.orig This would copy rc.conf to rc.conf.orig, and you could later copy rc.conf.orig to rc.conf to recover the original. But even better would be moving (renaming) and then copying back: &prompt.root; mv rc.conf rc.conf.orig &prompt.root; cp rc.conf.orig rc.conf because the mv command preserves the original date and owner of the file. You can now edit rc.conf. If you want the original back, you'd then mv rc.conf rc.conf.myedit (assuming you want to preserve your edited version) and then &prompt.root; mv rc.conf.orig rc.conf to put things back the way they were. To edit a file, type &prompt.root; vi filename Move through the text with the arrow keys. Esc (the escape key) puts vi in command mode. Here are some commands: x delete letter the cursor is on dd delete the entire line (even if it wraps on the screen) i insert text at the cursor a insert text after the cursor Once you type i or a, you can enter text. Esc puts you back in command mode where you can type :w to write your changes to disk and continue editing :wq to write and quit :q! to quit without saving changes /text to move the cursor to text; /Enter (the enter key) to find the next instance of text. G to go to the end of the file nG to go to line n in the file, where n is a number CtrlL to redraw the screen Ctrlb and Ctrlf go back and forward a screen, as they do with more and view. Practice with vi in your home directory by creating a new file with vi filename and adding and deleting text, saving the file, and calling it up again. vi delivers some surprises because it's really quite complex, and sometimes you'll inadvertently issue a command that will do something you don't expect. (Some people actually like vi—it's more powerful than DOS EDIT—find out about the :r command.) Use Esc one or more times to be sure you're in command mode and proceed from there when it gives you trouble, save often with :w, and use :q! to get out and start over (from your last :w) when you need to. Now you can cd to /etc, su to root, use vi to edit the file /etc/group, and add a user to wheel so the user has root privileges. Just add a comma and the user's login name to the end of the first line in the file, press Esc, and use :wq to write the file to disk and quit. Instantly effective. (You didn't put a space after the comma, did you?) Printing Files from DOS At this point you probably don't have the printer working, so here's a way to create a file from a man page, move it to a floppy, and then print it from DOS. Suppose you want to read carefully about changing permissions on files (pretty important). You can use the command man chmod to read about it. The command &prompt.user; man chmod | col -b > chmod.txt will remove formatting codes and send the man page to the chmod.txt file instead of showing it on your screen. Now put a dos-formatted diskette in your floppy drive a, su to root, and type &prompt.root; /sbin/mount -t msdos /dev/fd0 /mnt to mount the floppy drive on /mnt. Now (you no longer need to be root, and you can type exit to get back to being user jack) you can go to the directory where you created chmod.txt and copy the file to the floppy with: &prompt.user; cp chmod.txt /mnt and use ls /mnt to get a directory listing of /mnt, which should show the file chmod.txt. You might especially want to make a file from /sbin/dmesg by typing &prompt.user; /sbin/dmesg > dmesg.txt and copying dmesg.txt to the floppy. /sbin/dmesg is the boot log record, and it's useful to understand it because it shows what FreeBSD found when it booted up. If you ask questions on freebsd-questions@FreeBSD.org or on a USENET group—like FreeBSD isn't finding my tape drive, what do I do?—people will want to know what dmesg has to say. You can now dismount the floppy drive (as root) to get the disk out with &prompt.root; /sbin/umount /mnt and reboot to go to DOS. Copy these files to a DOS directory, call them up with DOS EDIT, Windows Notepad or Wordpad, or a word processor, make a minor change so the file has to be saved, and print as you normally would from DOS or Windows. Hope it works! man pages come out best if printed with the dos print command. (Copying files from FreeBSD to a mounted dos partition is in some cases still a little risky.) Getting the printer printing from FreeBSD involves creating an appropriate entry in /etc/printcap and creating a matching spool directory in /var/spool/output. If your printer is on lpt0 (what dos calls LPT1), you may only need to go to /var/spool/output and (as root) create the directory lpd by typing: mkdir lpd, if it doesn't already exist. Then the printer should respond if it's turned on when the system is booted, and lp or lpr should send a file to the printer. Whether or not the file actually prints depends on configuring it, which is covered in the FreeBSD handbook. Other Useful Commands df shows file space and mounted systems. ps aux shows processes running. ps ax is a narrower form. rm filename remove filename. rm -R dir removes a directory dir and all subdirectories—careful! ls -R lists files in the current directory and all subdirectories; I used a variant, ls -AFR > where.txt, to get a list of all the files in / and (separately) /usr before I found better ways to find files. passwd to change user's password (or root's password) man hier man page on the Unix file system Use find to locate filename in /usr or any of its subdirectories with &prompt.user; find /usr -name "filename" You can use * as a wildcard in "filename" (which should be in quotes). If you tell find to search in / instead of /usr it will look for the file(s) on all mounted file systems, including the CDROM and the dos partition. An excellent book that explains Unix commands and utilities is Abrahams & Larson, Unix for the Impatient (2nd ed., Addison-Wesley, 1996). There's also a lot of Unix information on the Internet. Try the Unix Reference Desk. Next Steps You should now have the tools you need to get around and edit files, so you can get everything up and running. There is a great deal of information in the FreeBSD handbook (which is probably on your hard drive) and FreeBSD's web site. A wide variety of packages and ports are on the CDROM as well as the web site. The handbook tells you more about how to use them (get the package if it exists, with pkg_add /cdrom/packages/All/packagename, where packagename is the filename of the package). The CDROM has lists of the packages and ports with brief descriptions in cdrom/packages/index, cdrom/packages/index.txt, and cdrom/ports/index, with fuller descriptions in /cdrom/ports/*/*/pkg/DESCR, where the *s represent subdirectories of kinds of programs and program names respectively. If you find the handbook too sophisticated (what with lndir and all) on installing ports from the CDROM, here's what usually works: Find the port you want, say kermit. There will be a directory for it on the CDROM. Copy the subdirectory to /usr/local (a good place for software you add that should be available to all users) with: &prompt.root; cp -R /cdrom/ports/comm/kermit /usr/local This should result in a /usr/local/kermit subdirectory that has all the files that the kermit subdirectory on the CDROM has. Next, create the directory /usr/ports/distfiles if it doesn't already exist using mkdir. Now check check /cdrom/ports/distfiles for a file with a name that indicates it's the port you want. Copy that file to /usr/ports/distfiles; in recent versions you can skip this step, as FreeBSD will do it for you. In the case of kermit, there is no distfile. Then cd to the subdirectory of /usr/local/kermit that has the file Makefile. Type &prompt.root; make all install - During this process the port will ftp to get any compressed + During this process the port will FTP to get any compressed files it needs that it didn't find on the CDROM or in /usr/ports/distfiles. If you don't have your network running yet and there was no file for the port in /cdrom/ports/distfiles, you will have to get the distfile using another machine and copy it to /usr/ports/distfiles from a floppy or your dos partition. Read Makefile (with cat or more or view) to find out where to go (the master distribution site) to get the file and what its name is. Its name will be truncated when downloaded to DOS, and after you get it into /usr/ports/distfiles you'll have to rename it (with the mv command) to its original name so it can be found. (Use binary file transfers!) Then go back to /usr/local/kermit, find the directory with Makefile, and type make all install. The other thing that happens when installing ports or packages is that some other program is needed. If the installation stops with a message can't find unzip or whatever, you might need to install the package or port for unzip before you continue. Once it's installed type rehash to make FreeBSD reread the files in the path so it knows what's there. (If you get a lot of path not found messages when you use whereis or which, you might want to make additions to the list of directories in the path statement in .cshrc in your home directory. The path statement in Unix does the same kind of work it does in DOS, except the current directory is not (by default) in the path for security reasons; if the command you want is in the directory you're in, you need to type ./ before the command to make it work; no space after the slash.) You might want to get the most recent version of Netscape - from their ftp site. + from their FTP site. (Netscape requires the X Window System.) There's now a FreeBSD version, so look around carefully. Just use gunzip filename and tar xvf filename on it, move the binary to /usr/local/bin or some other place binaries are kept, rehash, and then put the following lines in .cshrc in each user's home directory or (easier) in /etc/csh.cshrc, the system-wide csh start-up file: setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB setenv XNLSPATH /usr/X11R6/lib/X11/nls This assumes that the file XKeysymDB and the directory nls are in /usr/X11R6/lib/X11; if they're not, find them and put them there. If you originally got Netscape as a port using the CDROM (or - ftp), don't replace /usr/local/bin/netscape + FTP), don't replace /usr/local/bin/netscape with the new netscape binary; this is just a shell script that sets up the environment variables for you. Instead rename the new binary to netscape.bin and replace the old binary, which is /usr/local/netscape/netscape. Your Working Environment Your shell is the most important part of your working environment. In DOS, the usual shell is command.com. The shell is what interprets the commands you type on the command line, and thus communicates with the rest of the operating system. You can also write shell scripts, which are like DOS batch files: a series of commands to be run without your intervention. Two shells come installed with FreeBSD: csh and sh. csh is good for command-line work, but scripts should be written with sh (or bash). You can find out what shell you have by typing echo $SHELL. The csh shell is okay, but tcsh does everything csh does and more. It allows you to recall commands with the arrow keys and edit them. It has tab-key completion of filenames (csh uses the escape key), and it lets you switch to the directory you were last in with cd -. It's also much easier to alter your prompt with tcsh. It makes life a lot easier. Here are the three steps for installing a new shell: Install the shell as a port or a package, just as you would any other port or package. Use rehash and which tcsh (assuming you're installing tcsh) to make sure it got installed. As root, edit /etc/shells, adding a line in the file for the new shell, in this case /usr/local/bin/tcsh, and save the file. (Some ports may do this for you.) Use the chsh command to change your shell to tcsh permanently, or type tcsh at the prompt to change your shell without logging in again. It can be dangerous to change root's shell to something other than sh or csh on early versions of FreeBSD and many other versions of Unix; you may not have a working shell when the system puts you into single user mode. The solution is to use su -m to become root, which will give you the tcsh as root, because the shell is part of the environment. You can make this permanent by adding it to your .tcshrc file as an alias with alias su su -m. When tcsh starts up, it will read the /etc/csh.cshrc and /etc/csh.login files, as does csh. It will also read the .login file in your home directory and the .cshrc file as well, unless you provide a .tcshrc file. This you can do by simply copying .cshrc to .tcshrc. Now that you've installed tcsh, you can adjust your prompt. You can find the details in the manual page for tcsh, but here is a line to put in your .tcshrc that will tell you how many commands you have typed, what time it is, and what directory you are in. It also produces a > if you're an ordinary user and a # if you're root, but tsch will do that in any case: set prompt = "%h %t %~ %# " This should go in the same place as the existing set prompt line if there is one, or under "if($?prompt) then" if not. Comment out the old line; you can always switch back to it if you prefer it. Don't forget the spaces and quotes. You can get the .tcshrc reread by typing source .tcshrc. You can get a listing of other environmental variables that have been set by typing env at the prompt. The result will show you your default editor, pager, and terminal type, among possibly many others. A useful command if you log in from a remote location and can't run a program because the terminal isn't capable is setenv TERM vt100. Other As root, you can dismount the CDROM with /sbin/umount /cdrom, take it out of the drive, insert another one, and mount it with /sbin/mount_cd9660 /dev/cd0a /cdrom assuming cd0a is the device name for your CDROM drive. The most recent versions of FreeBSD let you mount the CDROM with just /sbin/mount /cdrom. Using the live file system—the second of FreeBSD's CDROM disks—is useful if you've got limited space. What is on the live file system varies from release to release. You might try playing games from the CDROM. This involves using lndir, which gets installed with the X Window System, to tell the program(s) where to find the necessary files, because they're in the /cdrom file system instead of in /usr and its subdirectories, which is where they're expected to be. Read man lndir. Comments Welcome If you use this guide I'd be interested in knowing where it was unclear and what was left out that you think should be included, and if it was helpful. My thanks to Eugene W. Stark, professor of computer science at SUNY-Stony Brook, and John Fieber for helpful comments. Annelise Anderson, andrsn@andrsn.stanford.edu
diff --git a/en_US.ISO8859-1/articles/pxe/article.sgml b/en_US.ISO8859-1/articles/pxe/article.sgml index 988de065a5..a27529accd 100644 --- a/en_US.ISO8859-1/articles/pxe/article.sgml +++ b/en_US.ISO8859-1/articles/pxe/article.sgml @@ -1,283 +1,283 @@ %man %authors; ]>
FreeBSD Jumpstart Guide Alfred Perlstein
alfred@FreeBSD.org
 - $FreeBSD: doc/en_US.ISO8859-1/articles/pxe/article.sgml,v 1.1 2001/06/25 14:51:37 nik Exp $ + $FreeBSD: doc/en_US.ISO8859-1/articles/pxe/article.sgml,v 1.2 2001/07/13 22:03:55 billf Exp $ This article details the method used to allow machines to install FreeBSD using the Intel PXE method of booting a machine over a network. Introduction This procedure will make the 'Server' both insecure and dangerous, it's best to just keep the 'Server' on it's own hub and not in any way accessable by any machines other than the 'Clients'. Terminology : Server The machine offering netboot and install options. Client The machine that will have FreeBSD installed on it. Requires: - Clients supporting the Intel PXE netboot option, an ethernet connection. + Clients supporting the Intel PXE netboot option, an Ethernet connection. Please let me know if you come across anything you have problems with or suggestions for additional documentation. If you'd like someone to train/implement a specific netinstall system for you, please send email so that we can discuss terms. I'd also like to thank &a.ps; and &a.jhb; for doing most of the programming work on pxeboot, the interface to Intel's PXE (netboot) system. Server Configuration Install DHCP : Install isc-dhcp-2.0 you can use this config file dhcpd.conf, stick it in /usr/local/etc/ Enable tftp: Make a directory /usr/tftpboot Add this line to your /etc/inetd.conf: tftp dgram udp wait nobody /usr/libexec/tftpd &prompt.root; tftpd /usr/tftpboot Enable NFS: Add this to /etc/rc.conf: nfs_server_enable="YES" Add this to /etc/exports: /usr -alldirs -ro Reboot to enable the new services or start them manually. Bootstrap Setup Download bootfiles : Download the kern.flp and mfsroot.flp floppy images. Setup tftp/pxe-boot directory: Put pxeboot in the boot directory: &prompt.root; rm -rf /usr/obj/* &prompt.root; cd /usr/src/sys/boot &prompt.root; make &prompt.root; cp /usr/src/sys/boot/i386/pxeldr/pxeboot /usr/tftpboot Using the vndevice mount the kern.flp file and copy its contents to /usr/tftpboot: &prompt.root; vnconfig vn0 kern.flp # associate a vndevice with the file &prompt.root; mount /dev/vn0 /mnt # mount it &prompt.root; cp -R /mnt /usr/tftpboot # copy the contents to /usr/tftpboot &prompt.root; umount /mnt # unmount it &prompt.root; vnconfig -u vn0 # disassociate the vndevice from the file Compile a custom kernel for the clients(particularly to avoid the device config screen at boot) and stick it in /usr/tftpboot. Make a special loader.rc to and install it in /usr/tftpboot/boot/loader.rc so that it doesn't prompt for the second disk, here's mine. Extract the installer and helper utilities from the mfsroot disk and uncompress them, put them in /usr/tftpboot as well: &prompt.root; vnconfig vn0 mfsroot.flp # associate a vndevice with the file &prompt.root; mount /dev/vn0 /mnt # mount it &prompt.root; cp /mnt/mfsroot.gz /usr/tftpboot # copy the contents to /usr/tftpboot &prompt.root; umount /mnt # unmount it &prompt.root; vnconfig -u vn0 # disassociate the vndevice from the file &prompt.root; cd /usr/tftpboot # get into the pxeboot directory &prompt.root; gunzip mfsroot.gz # uncompress the mfsroot Make your sysinstall script install.cfg, you can use mine as a template, but you must edit it. Copy the sysinstall script into the extracted and uncompressed mfsroot image: &prompt.root; cd /usr/tftpboot &prompt.root; vnconfig vn0 mfsroot &prompt.root; mount /dev/vn0 /mnt &prompt.root; cp install.cfg /mnt &prompt.root; umount /mnt &prompt.root; vnconfig -u vn0 Install Setup Put the install files in an NFS accessable location on the Server. Make a directory corresponding the 'nfs' directive in the install.cfg file and mirror the FreeBSD install files there, you'll want it to look somewhat like this: ABOUT.TXT TROUBLE.TXT compat20 floppies ports ERRATA.TXT UPGRADE.TXT compat21 games proflibs HARDWARE.TXT XF86336 compat22 info src INSTALL.TXT bin compat3x kern.flp LAYOUT.TXT catpages crypto manpages README.TXT cdrom.inf dict mfsroot.flp RELNOTES.TXT compat1x doc packages Copy the compressed packages into the packages/All directory under nfs. Make sure you have an INDEX file prepared in the packages directory. You can make your own INDEX entries like so: alfred-1.0||/|Alfred install bootstrap||alfred@FreeBSD.org|||| Then you can install custom packages, particularly your own custom post-install package. Custom Post-Install Package You can use the script pkgmaker.sh to create a custom package for post install, the idea is to have it install and configure any special things you may need done. pkgmaker is run in the directory above the package you wish to create with the single argument of the package (ie mypkg) which will then create a mypkg.tgz for you to include in your sysinstall package. Inside your custom package dir you'll want a file called PLIST which contains all the files that you wish to install and be incorperated into your package. You'll also want files called 'pre' and 'post' in the directory, these are shell scripts that you want to execute before and after your package is installed. Since this package is in your install.cfg file it should be run and do the final configuration for you.
diff --git a/en_US.ISO8859-1/articles/solid-state/article.sgml b/en_US.ISO8859-1/articles/solid-state/article.sgml index 841d7e1645..00d5ee11d1 100644 --- a/en_US.ISO8859-1/articles/solid-state/article.sgml +++ b/en_US.ISO8859-1/articles/solid-state/article.sgml @@ -1,630 +1,630 @@ %man; ]>
FreeBSD and Solid State Devices John Kozubik
john@kozubik.com
 - $FreeBSD: doc/en_US.ISO8859-1/articles/solid-state/article.sgml,v 1.3 2001/07/10 14:00:14 dd Exp $ + $FreeBSD: doc/en_US.ISO8859-1/articles/solid-state/article.sgml,v 1.4 2001/07/11 11:08:47 nik Exp $ 2001 The FreeBSD Documentation Project &legalnotice; This article covers the use of solid state disk devices in FreeBSD to create embedded systems. Embedded systems have the advantage of increased stability due to the lack of integral moving parts (hard drives). Account must be taken, however, for the generally low disk space available in the system and the durability of the storage medium. Specific topics to be covered include the types and attributes of solid state media suitable for disk use in FreeBSD, kernel options that are of interest in such an environment, the rc.diskless mechanisms that automate the initialization of such systems and the need for read-only filesystems, and building file systems from scratch. The article will conclude with some general strategies for small and read-only FreeBSD environments. Solid State Disk Devices The scope of this article will be limited to solid state disk devices made from flash memory. Flash memory is a solid state memory (no moving parts) that is non-volatile (the memory maintains data even after all power sources have been disconnected). Flash memory can withstand tremendous physical shock and is reasonably fast (the flash memory solutions covered in this article are slightly slower than a EIDE hard disk for write operations, and much faster for read operations). One very important aspect of flash memory, the ramifications of which will be discussed later in this article, is that each sector has a limited rewrite capacity. You can only write, erase, and write again to a sector of flash memory a certain number of times before the sector becomes permanently unusable. Although many flash memory products automatically map bad blocks, and although some even distribute write operations evenly throughout the unit, the fact remains that there exists a limit to the amount of writing that can be done to the device. Competitive units have between 1,000,000 and 10,000,000 writes per sector in their specification. This figure varies due to the temperature of the environment. Specifically, we will be discussing ATA compatible compact-flash units and the M-Systems Disk-On-Chip flash memory unit. ATA compatible compact-flash cards are quite popular as storage media for digital cameras. Of particular interest is the fact that they pin out directly to the IDE bus and are compatible with the ATA command set. Therefore, with a very simple and low-cost adaptor, these devices can be attached directly to an IDE bus in a computer. Once implemented in this manner, operating systems such as FreeBSD see the device as a normal hard disk (albeit small). The M-Systems Disk-On-Chip product is based on the same underlying flash memory technology as ATA compatible compact-flash cards, but resides in a DIP form factor and is not ATA compatible. To use such a device, not only must you install it on a motherboard that has a Disk-On-Chip socket, you must also build the `fla` driver into any FreeBSD kernel you wish to use it with. Further, there is critical, manufacturer-specific data residing in the boot sector of this device, so you must take care not to install the FreeBSD (or any other) boot loader when using this. Other solid state disk solutions do exist, but their expense, obscurity, and relative unease of use places them beyond the scope of this article. Kernel Options A few kernel options are of specific interest to those creating an embedded FreeBSD system. First, all embedded FreeBSD systems that use flash memory as system disk will be interested in memory disks and memory filesystems. Because of the limited number of writes that can be done to flash memory, the disk and the filesystems no the disk will most likely be mounted read-only. In this environment, filesystems such as /tmp and /var are mounted as memory filesystems to allow the system to create logs and update counters and temporary files. Memory filesystems are a critical component to a successful solid state FreeBSD implementation. You should make sure the following lines exist in your kernel configuration file: options MFS # Memory Filesystem options MD_ROOT # md device usable as a potential root device pseudo-device md # memory disk Second, if you will be using the M-Systems Disk-On-Chip product, you must also include this line: device fla0 at isa? <filename>rc.diskless</filename> and Read-Only Filesystems The post-boot initialization of an embedded FreeBSD system is controlled by /etc/rc.diskless2 (/etc/rc.diskless1 is for BOOTP diskless boot). This initialization script is invoked by placing a line in /etc/rc.conf as follows: diskless_mount=/etc/rc.diskless2 rc.diskless2 mounts /var as a memory filesystem, makes a configurable list of directories in /var with the &man.mkdir.1; command, changes modes on some of those directories, and extracts a list of device entries to copy to a writable (again, a memory filesystem) /dev partition. In the execution of /etc/rc.diskless2, one other rc.conf variable comes into play - varsize. The /etc/rc.diskless2 file creates a /var partition based on the value of this variable in rc.conf: varsize=8192 Remember that this value is in sectors. The creation of the /dev partition by /etc/rc.diskless2, however, is governed by a hard-coded value of 4096 sectors. It is trivial to change this entry in the /etc/rc.diskless2 file itself, although you shouldn't need more space than that for /dev. It is important to remember that the /etc/rc.diskless2 script assumes that you have already removed your conventional /tmp partition and replaced it with a symbolic link to /var/tmp. Because tmp is one of the directories created in /var by the /etc/rc.diskless2 script, and because /var is a memory file system (which is mounted read-write), /tmp will now be a directory that is read-write as well. The fact that /var and /dev are read-write filesystems is an important distinction, as the / partition (and any other partitions you may have on your flash media) should be mounted read-only. Remember that in we detailed the limitations of flash memory - specifically the limited write capability. The importance of not mounting filesystems on flash media read-write, and the importance of not using a swap file cannot be overstated. A swap file on a busy system can burn through a piece of flash media in less than one year. Heavy logging or temporary file creation and destruction can do the same. Therefore, in addition to removing the swap and /proc entries from your /etc/fstab file, you should also change the Options field for each filesystem to ro as follows: # Device Mountpoint FStype Options Dump Pass# /dev/ad0s1a / ufs ro 1 1 A few applications in the average system will immediately begin to fail as a result of this change. For instance, ports will not install from the ports tree because the /var/db/port.mkversion file does not exist. cron will not run properly as a result of missing cron tabs in the /var created by /etc/rc.diskless2, and syslog and dhcp will encounter problems as well as a result of the read-only filesystem and missing items in the /var that /etc/rc.diskless2 has created. These are only temporary problems though, and are addressed, along with solutions to the execution of other common software packages in . An important thing to remember is that a filesystem that was mounted read-only with /etc/fstab can be made read-write at any time by issuing the command: &prompt.root; /sbin/mount -uw partition and can be toggled back to read-only with the command: &prompt.root; /sbin/mount -ur partition Building a File System From Scratch Because ATA compatible compact-flash cards are seen by FreeBSD as normal IDE hard drives, as is a M-Systems Disk-On-Chip product (when you are running a kernel with the fla driver built in) you could theoretically install FreeBSD from the network using the kern and mfsroot floppies or from a CD. Other than the fact that you should not write a boot-loader of any kind to the M-Systems device, no special instructions are needed. However, even a small installation of FreeBSD using normal installation procedures can produce a system in size of greater than 200 megabytes. Because most people will be using smaller flash memory devices (128 megabytes is considered fairly large - 32 or even 16 megabytes is common) an installation using normal mechanisms is not possible—there is simply not enough disk space for even the smallest of conventional installations. The easiest way to overcome this space limitation is to install FreeBSD using conventional means to a normal hard disk. After the installation is complete, pare down the operating system to a size that will fit onto your flash media, then tar the entire filesystem. The following steps will guide you through the process of preparing a piece of flash memory for your tarred filesystem. Remember, because a normal installation is not being performed, operations such as partitioning, labeling, file-system creation, etc. need to be performed by hand. In addition to the kern and mfsroot floppy disks, you will also need to use the fixit floppy. If you are using a M-Systems Disk-On-Chip, the kernel on your kern floppy must have the fla option detailed in compiled into it. Please see for instructions on creating a new kernel for kern.flp. Partitioning your flash media device After booting with the kern and mfsroot floppies, choose custom from the installation menu. In the custom installation menu, choose partition. In the partition menu, you should delete all existing partitions using the d key. After deleting all existing partitions, create a partition using the c key and accept the default value for the size of the partition. When asked for the type of the partition, make sure the value is set to 165. Now write this partition table to the disk by pressing the w key (this is a hidden option on this screen). When presented with a menu to choose a boot manager, take care to select None if you are using an M-Systems Disk-On-Chip. If you are using a ATA compatible compact flash card, you should choose the FreeBSD Boot Manager. Now press the q key to quit the partition menu. You will be shown the boot manager menu once more - repeat the choice you made earlier. Creating file systems on your flash memory device Exit the custom installation menu, and from the main installation menu choose the fixit option. After entering the fixit environment, enter the following commands: ATA compatible Disk-On-Chip &prompt.root; mknod /dev/ad0a c 116 0 &prompt.root; mknod /dev/ad0c c 116 2 &prompt.root; disklabel -e /dev/ad0c &prompt.root; mknod /dev/fla0a c 102 0 &prompt.root; mknod /dev/fla0c c 102 2 &prompt.root; disklabel -e /dev/fla0c At this point you will have entered the vi editor under the auspices of the disklabel command. If you are using Disk-On-Chip, the first step will be to change the type value near the beginning of the file from ESDI to DOC2K. Next, regardless of whether you are using Disk-On-Chip or ATA compatible compact flash media, you need to add an a: line at the end of the file. This a: line should look like: a: 123456 0 4.2BSD 0 0 Where 123456 is a number that is exactly the same as the number in the existing c: entry for size. Basically you are duplicating the existing c: line as an a: line, making sure that fstype is 4.2BSD. Save the file and exit. ATA compatible Disk-On-Chip &prompt.root; disklabel -B -r /dev/ad0c &prompt.root; newfs /dev/ad0a &prompt.root; disklabel -B -r /dev/fla0c &prompt.root; newfs /dev/fla0a Placing your filesystem on the flash media Mount the newly prepared flash media: ATA compatible Disk-On-Chip &prompt.root; mount /dev/ad0a /flash &prompt.root; mount /dev/fla0a /flash Bring this machine up on the network so we may transfer our tar file and explode it onto our flash media filesystem. One example of how to do this is: &prompt.root; ifconfig xl0 192.168.0.10 netmask 255.255.255.0 &prompt.root; route add default 192.168.0.1 Now that the machine is on the network, transfer your tar file. You may be faced with a bit of a dilemma at this point - if your flash memory part is 128 megabytes, for instance, and your tar file is larger than 64 megabytes, you cannot have your tar file on the flash media at the same time as you explode it - you will run out of - space. One solution to this problem, if you are using ftp, is to - untar the file while it is transferred over ftp. If you perform + space. One solution to this problem, if you are using FTP, is to + untar the file while it is transferred over FTP. If you perform your transfer in this manner, you will never have the tar file and the tar contents on your disk at the same time: ftp> get tarfile.tar "| tar xvf -" If your tarfile is gzipped, you can accomplish this as well: ftp> get tarfile.tar "| zcat | tar xvf -" After the contents of your tarred filesystem are on your flash memory file system, you can unmount the flash memory and reboot: &prompt.root; cd / &prompt.root; umount /flash &prompt.root; exit Assuming that you configured your filesystem correctly when it was built on the normal hard disk (with your filesystems mounted read-only, and with the necessary options compiled into the kernel) you should now be successfully booting your FreeBSD embedded system. Building a <filename>kern.flp</filename> Installation Floppy with the fla Driver This section of the article is relevant only to those using M-Systems Disk-On-Chip flash media. It is possible that your kern.flp boot floppy does not have a kernel with the fla driver compiled into it necessary for the system to recognize the Disk-On-Chip. If you have booted off of the installation floppies and are told that no disks are present, then you are probably lacking the fla driver in your kernel. After you have built a kernel with fla support that is smaller than 1.4 megabytes, you can create a custom kern.flp floppy image with it by following these instructions: Obtain an existing kern.flp image file &prompt.root; vnconfig vn0c kern.flp &prompt.root; mount /dev/vn0c /mnt Place your kernel file into /mnt, replacing the existing one &prompt.root; vnconfig -d vn0c Your kern.flp file now has your new kernel on it. System Strategies for Small and Read Only Environments In , it was pointed out that the /var filesystem constructed by /etc/rc.diskless2 and the presence of a read-only root filesystem causes problems with many common software packages used with FreeBSD. In this article, suggestions for successfully running cron, syslog, ports installations, and the Apache web server will be provided. cron In /etc/rc.diskless2 there is a variable named var_dirs. This variable consists of a space-delimited list of directories that will be created inside of /var after it is mounted as a memory filesystem. cron and cron/tabs are not in that list, and without those directories, cron will complain. By inserting cron, cron/tabs, and perhaps even at, and at/jobs as elements of that variable, you will facilitate the running of the &man.cron.8; and &man.at.1; daemons. However, this still does not solve the problem of maintaining cron tabs across reboots. When the system reboots, the /var filesystem that is in memory will disappear and any cron tabs you may have had in it will also disappear. Therefore, one solution would be to create cron tabs for the users that need them, mount your / filesystem as read-write and copy those cron tabs to somewhere safe, like /etc/tabs, then add a line to the end of /etc/rc.diskless2 that copies those crontabs into /var/cron/tabs after that directory has been created during system initialization. You may also need to add a line that changes modes and permissions on the directories you create and the files you copy with /etc/rc.diskless2. syslog syslog.conf specifies the locations of certain log files that exist in /var/log. These files are not created by /etc/rc.diskless2 upon system initialization. Therefore, somewhere in /etc/rc.diskless2, after the section that creates the directories in /var, you will need to add something like this: &prompt.root; touch /var/log/security /var/log/maillog /var/log/cron /var/log/messages &prompt.root; chmod 0644 /var/log/* You will also need to add the log directory to the list of directories that /etc/rc.diskless2 creates. ports installation Before discussing the changes necessary to successfully use the ports tree, a reminder is necessary regarding the read-only nature of your filesystems on the flash media. Since they are read-only, you will need to temporarily mount them read-write using the mount syntax shown in . You should always remount those filesystems read-only when you are done with any maintenance - it is dangerous to leave them in read-write mode lest a process begin logging or otherwise writing regularly to the flash media and wearing it out over time. To make it possible to enter a ports directory and successfully run make install, it is necessary for the file /var/db/port.mkversion to exist, and that it have a correct date in it. Further, we must create a packages directory on a non-memory filesystem that will keep track of our packages across reboots. Because it is necessary to mount your filesystems as read-write for the installation of a package anyway, it is sensible to assume that an area on the flash media can also be used for package information to be written to. First, create a package database directory. This is normally in /var/db/pkg, but we cannot place it there as it will disappear every time the system is booted. &prompt.root; mkdir /etc/pkg Now, add a line to /etc/rc.diskless2 that links the /etc/pkg directory to /var/db/pkg. An example: &prompt.root; ln -s /etc/pkg /var/db/pkg Add another line in /etc/rc.diskless2 that creates and populates /var/db/port.mkversion &prompt.root; touch /var/db/port.mkversion &prompt.root; chmod 0644 /var/db/port.mkversion &prompt.root; echo 20010412 >> /var/db/port.mkversion where 20010412 is a date that is appropriate for your particular release of FreeBSD Now, any time that you mount your file systems as read-write and install a package, the make install will work because it finds a suitable /var/db/port.mkversion, and package information will be written successfully to /etc/pkg (because the filesystem will, at that time, be mounted read-write) which will always be available to the operating system as /var/db/pkg. Apache Web Server Apache keeps pid files and logs in apache_install/logs. Since this directory no doubt exists on a read-only file system, this will not work. It is necessary to add a new directory to the /etc/rc.diskless2 list of directories to create in /var, to link apache_install/logs to /var/log/apache. It is also necessary to set permissions and ownership on this new directory. First, add the directory log/apache to the list of directories to be created in /etc/rc.diskless2. Second, add these commands to /etc/rc.diskless2 after the directory creation section: &prompt.root; chmod 0774 /var/log/apache &prompt.root; chown nobody:nobody /var/log/apache Finally, remove the existing apache_install/logs directory, and replace it with a link: &prompt.root; rm -rf (apache_install)/logs &prompt.root; ln -s /var/log/apache (apache_install)/logs
diff --git a/en_US.ISO8859-1/articles/storage-devices/article.sgml b/en_US.ISO8859-1/articles/storage-devices/article.sgml index a1335b3b37..b3778f8ebb 100644 --- a/en_US.ISO8859-1/articles/storage-devices/article.sgml +++ b/en_US.ISO8859-1/articles/storage-devices/article.sgml @@ -1,2627 +1,2627 @@ %man; %authors; ]>
Storage Devices Wilko Bulte
wilko@FreeBSD.org
 - $FreeBSD$ + $FreeBSD: doc/en_US.ISO8859-1/articles/storage-devices/article.sgml,v 1.1 2001/07/13 22:30:40 murray Exp $ This article talks about storage devices with FreeBSD. Using ESDI hard disks Copyright © 1995, &a.wilko;. 24 September 1995. ESDI is an acronym that means Enhanced Small Device Interface. It is loosely based on the good old ST506/412 interface originally devised by Seagate Technology, the makers of the first affordable 5.25" winchester disk. The acronym says Enhanced, and rightly so. In the first place the speed of the interface is higher, 10 or 15 Mbits/second instead of the 5 Mbits/second of ST412 interfaced drives. Secondly some higher level commands are added, making the ESDI interface somewhat 'smarter' to the operating system driver writers. It is by no means as smart as SCSI by the way. ESDI is standardized by ANSI. Capacities of the drives are boosted by putting more sectors on each track. Typical is 35 sectors per track, high capacity drives I have seen were up to 54 sectors/track. Although ESDI has been largely obsoleted by IDE and SCSI interfaces, the availability of free or cheap surplus drives makes them ideal for low (or now) budget systems. Concepts of ESDI Physical connections The ESDI interface uses two cables connected to each drive. One cable is a 34 pin flat cable edge connector that carries the command and status signals from the controller to the drive and vice-versa. The command cable is daisy chained between all the drives. So, it forms a bus onto which all drives are connected. The second cable is a 20 pin flat cable edge connector that carries the data to and from the drive. This cable is radially connected, so each drive has its own direct connection to the controller. To the best of my knowledge PC ESDI controllers are limited to using a maximum of 2 drives per controller. This is compatibility feature(?) left over from the WD1003 standard that reserves only a single bit for device addressing. Device addressing On each command cable a maximum of 7 devices and 1 controller can be present. To enable the controller to uniquely identify which drive it addresses, each ESDI device is equipped with jumpers or switches to select the devices address. On PC type controllers the first drive is set to address 0, the second disk to address 1. Always make sure you set each disk to an unique address! So, on a PC with its two drives/controller maximum the first drive is drive 0, the second is drive 1. Termination The daisy chained command cable (the 34 pin cable remember?) needs to be terminated at the last drive on the chain. For this purpose ESDI drives come with a termination resistor network that can be removed or disabled by a jumper when it is not used. So, one and only one drive, the one at the farthest end of the command cable has its terminator installed/enabled. The controller automatically terminates the other end of the cable. Please note that this implies that the controller must be at one end of the cable and not in the middle. Using ESDI disks with FreeBSD Why is ESDI such a pain to get working in the first place? People who tried ESDI disks with FreeBSD are known to have developed a profound sense of frustration. A combination of factors works against you to produce effects that are hard to understand when you have never seen them before. This has also led to the popular legend ESDI and FreeBSD is a plain NO-GO. The following sections try to list all the pitfalls and solutions. ESDI speed variants As briefly mentioned before, ESDI comes in two speed flavors. The older drives and controllers use a 10 Mbits/second data transfer rate. Newer stuff uses 15 Mbits/second. It is not hard to imagine that 15 Mbits/second drive cause problems on controllers laid out for 10 Mbits/second. As always, consult your controller and drive documentation to see if things match. Stay on track Mainstream ESDI drives use 34 to 36 sectors per track. Most (older) controllers cannot handle more than this number of sectors. Newer, higher capacity, drives use higher numbers of sectors per track. For instance, I own a 670 MB drive that has 54 sectors per track. In my case, the controller could not handle this number of sectors. It proved to work well except that it only used 35 sectors on each track. This meant losing a lot of disk space. Once again, check the documentation of your hardware for more info. Going out-of-spec like in the example might or might not work. Give it a try or get another more capable controller. Hard or soft sectoring Most ESDI drives allow hard or soft sectoring to be selected using a jumper. Hard sectoring means that the drive will produce a sector pulse on the start of each new sector. The controller uses this pulse to tell when it should start to write or read. Hard sectoring allows a selection of sector size (normally 256, 512 or 1024 bytes per formatted sector). FreeBSD uses 512 byte sectors. The number of sectors per track also varies while still using the same number of bytes per formatted sector. The number of unformatted bytes per sector varies, dependent on your controller it needs more or less overhead bytes to work correctly. Pushing more sectors on a track of course gives you more usable space, but might give problems if your controller needs more bytes than the drive offers. In case of soft sectoring, the controller itself determines where to start/stop reading or writing. For ESDI hard sectoring is the default (at least on everything I came across). I never felt the urge to try soft sectoring. In general, experiment with sector settings before you install FreeBSD because you need to re-run the low-level format after each change. Low level formatting ESDI drives need to be low level formatted before they are usable. A reformat is needed whenever you figgle with the number of sectors/track jumpers or the physical orientation of the drive (horizontal, vertical). So, first think, then format. The format time must not be underestimated, for big disks it can take hours. After a low level format, a surface scan is done to find and flag bad sectors. Most disks have a manufacturer bad block list listed on a piece of paper or adhesive sticker. In addition, on most disks the list is also written onto the disk. Please use the manufacturer's list. It is much easier to remap a defect now than after FreeBSD is installed. Stay away from low-level formatters that mark all sectors of a track as bad as soon as they find one bad sector. Not only does this waste space, it also and more importantly causes you grief with bad144 (see the section on bad144). Translations Translations, although not exclusively a ESDI-only problem, might give you real trouble. Translations come in multiple flavors. Most of them have in common that they attempt to work around the limitations posed upon disk geometries by the original IBM PC/AT design (thanks IBM!). First of all there is the (in)famous 1024 cylinder limit. For a system to be able to boot, the stuff (whatever operating system) must be in the first 1024 cylinders of a disk. Only 10 bits are available to encode the cylinder number. For the number of sectors the limit is 64 (0-63). When you combine the 1024 cylinder limit with the 16 head limit (also a design feature) you max out at fairly limited disk sizes. To work around this problem, the manufacturers of ESDI PC controllers added a BIOS prom extension on their boards. This BIOS extension handles disk I/O for booting (and for some operating systems all disk I/O) by using translation. For instance, a big drive might be presented to the system as having 32 heads and 64 sectors/track. The result is that the number of cylinders is reduced to something below 1024 and is therefore usable by the system without problems. It is noteworthy to know that FreeBSD does not use the BIOS after its kernel has started. More on this later. A second reason for translations is the fact that most older system BIOSes could only handle drives with 17 sectors per track (the old ST412 standard). Newer system BIOSes usually have a user-defined drive type (in most cases this is drive type 47). Whatever you do to translations after reading this document, keep in mind that if you have multiple operating systems on the same disk, all must use the same translation While on the subject of translations, I have seen one controller type (but there are probably more like this) offer the option to logically split a drive in multiple partitions as a BIOS option. I had select 1 drive == 1 partition because this controller wrote this info onto the disk. On power-up it read the info and presented itself to the system based on the info from the disk. Spare sectoring Most ESDI controllers offer the possibility to remap bad sectors. During/after the low-level format of the disk bad sectors are marked as such, and a replacement sector is put in place (logically of course) of the bad one. In most cases the remapping is done by using N-1 sectors on each track for actual data storage, and sector N itself is the spare sector. N is the total number of sectors physically available on the track. The idea behind this is that the operating system sees a 'perfect' disk without bad sectors. In the case of FreeBSD this concept is not usable. The problem is that the translation from bad to good is performed by the BIOS of the ESDI controller. FreeBSD, being a true 32 bit operating system, does not use the BIOS after it has been booted. Instead, it has device drivers that talk directly to the hardware. So: don't use spare sectoring, bad block remapping or whatever it may be called by the controller manufacturer when you want to use the disk for FreeBSD. Bad block handling The preceding section leaves us with a problem. The controller's bad block handling is not usable and still FreeBSD's filesystems assume perfect media without any flaws. To solve this problem, FreeBSD use the bad144 tool. Bad144 (named after a Digital Equipment standard for bad block handling) scans a FreeBSD slice for bad blocks. Having found these bad blocks, it writes a table with the offending block numbers to the end of the FreeBSD slice. When the disk is in operation, the disk accesses are checked against the table read from the disk. Whenever a block number is requested that is in the bad144 list, a replacement block (also from the end of the FreeBSD slice) is used. In this way, the bad144 replacement scheme presents 'perfect' media to the FreeBSD filesystems. There are a number of potential pitfalls associated with the use of bad144. First of all, the slice cannot have more than 126 bad sectors. If your drive has a high number of bad sectors, you might need to divide it into multiple FreeBSD slices each containing less than 126 bad sectors. Stay away from low-level format programs that mark every sector of a track as bad when they find a flaw on the track. As you can imagine, the 126 limit is quickly reached when the low-level format is done this way. Second, if the slice contains the root filesystem, the slice should be within the 1024 cylinder BIOS limit. During the boot process the bad144 list is read using the BIOS and this only succeeds when the list is within the 1024 cylinder limit. The restriction is not that only the root filesystem must be within the 1024 cylinder limit, but rather the entire slice that contains the root filesystem. Kernel configuration ESDI disks are handled by the same wddriver as IDE and ST412 MFM disks. The wd driver should work for all WD1003 compatible interfaces. Most hardware is jumperable for one of two different I/O address ranges and IRQ lines. This allows you to have two wd type controllers in one system. When your hardware allows non-standard strappings, you can use these with FreeBSD as long as you enter the correct info into the kernel config file. An example from the kernel config file (they live in /sys/i386/conf BTW). # First WD compatible controller controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr disk wd0 at wdc0 drive 0 disk wd1 at wdc0 drive 1 # Second WD compatible controller controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr disk wd2 at wdc1 drive 0 disk wd3 at wdc1 drive 1 Particulars on ESDI hardware Adaptec 2320 controllers I successfully installed FreeBSD onto a ESDI disk controlled by a ACB-2320. No other operating system was present on the disk. To do so I low level formatted the disk using NEFMT.EXE (ftpable from www.adaptec.com) and answered NO to the question whether the disk should be formatted with a spare sector on each track. The BIOS on the ACD-2320 was disabled. I used the free configurable option in the system BIOS to allow the BIOS to boot it. Before using NEFMT.EXE I tried to format the disk using the ACB-2320 BIOS built-in formatter. This proved to be a show stopper, because it did not give me an option to disable spare sectoring. With spare sectoring enabled the FreeBSD installation process broke down on the bad144 run. Please check carefully which ACB-232xy variant you have. The x is either 0 or 2, indicating a controller without or with a floppy controller on board. The y is more interesting. It can either be a blank, a A-8 or a D. A blank indicates a plain 10 Mbits/second controller. An A-8 indicates a 15 Mbits/second controller capable of handling 52 sectors/track. A D means a 15 Mbits/second controller that can also handle drives with > 36 sectors/track (also 52 ?). All variations should be capable of using 1:1 interleaving. Use 1:1, FreeBSD is fast enough to handle it. Western Digital WD1007 controllers I successfully installed FreeBSD onto a ESDI disk controlled by a WD1007 controller. To be precise, it was a WD1007-WA2. Other variations of the WD1007 do exist. To get it to work, I had to disable the sector translation and the WD1007's onboard BIOS. This implied I could not use the low-level formatter built into this BIOS. Instead, I grabbed WDFMT.EXE from www.wdc.com Running this formatted my drive just fine. Ultrastor U14F controllers According to multiple reports from the net, Ultrastor ESDI boards work OK with FreeBSD. I lack any further info on particular settings. Further reading If you intend to do some serious ESDI hacking, you might want to have the official standard at hand: The latest ANSI X3T10 committee document is: Enhanced Small Device Interface (ESDI) [X3.170-1990/X3.170a-1991] [X3T10/792D Rev 11] On Usenet the newsgroup comp.periphs is a noteworthy place to look for more info. The World Wide Web (WWW) also proves to be a very handy info source: For info on Adaptec ESDI controllers see http://www.adaptec.com/. For info on Western Digital controllers see http://www.wdc.com/. Thanks to... Andrew Gordon for sending me an Adaptec 2320 controller and ESDI disk for testing. What is SCSI? Copyright © 1995, &a.wilko;. July 6, 1996. SCSI is an acronym for Small Computer Systems Interface. It is an ANSI standard that has become one of the leading I/O buses in the computer industry. The foundation of the SCSI standard was laid by Shugart Associates (the same guys that gave the world the first mini floppy disks) when they introduced the SASI bus (Shugart Associates Standard Interface). After some time an industry effort was started to come to a more strict standard allowing devices from different vendors to work together. This effort was recognized in the ANSI SCSI-1 standard. The SCSI-1 standard (approximately 1985) is rapidly becoming obsolete. The current standard is SCSI-2 (see Further reading), with SCSI-3 on the drawing boards. In addition to a physical interconnection standard, SCSI defines a logical (command set) standard to which disk devices must adhere. This standard is called the Common Command Set (CCS) and was developed more or less in parallel with ANSI SCSI-1. SCSI-2 includes the (revised) CCS as part of the standard itself. The commands are dependent on the type of device at hand. It does not make much sense of course to define a Write command for a scanner. The SCSI bus is a parallel bus, which comes in a number of variants. The oldest and most used is an 8 bit wide bus, with single-ended signals, carried on 50 wires. (If you do not know what single-ended means, do not worry, that is what this document is all about.) Modern designs also use 16 bit wide buses, with differential signals. This allows transfer speeds of 20Mbytes/second, on cables lengths of up to 25 meters. SCSI-2 allows a maximum bus width of 32 bits, using an additional cable. Quickly emerging are Ultra SCSI (also called Fast-20) and Ultra2 (also called Fast-40). Fast-20 is 20 million transfers per second (20 Mbytes/sec on a 8 bit bus), Fast-40 is 40 million transfers per second (40 Mbytes/sec on a 8 bit bus). Most hard drives sold today are single-ended Ultra SCSI (8 or 16 bits). Of course the SCSI bus not only has data lines, but also a number of control signals. A very elaborate protocol is part of the standard to allow multiple devices to share the bus in an efficient manner. In SCSI-2, the data is always checked using a separate parity line. In pre-SCSI-2 designs parity was optional. In SCSI-3 even faster bus types are introduced, along with a serial SCSI busses that reduces the cabling overhead and allows a higher maximum bus length. You might see names like SSA and fibre channel in this context. None of the serial buses are currently in widespread use (especially not in the typical FreeBSD environment). For this reason the serial bus types are not discussed any further. As you could have guessed from the description above, SCSI devices are intelligent. They have to be to adhere to the SCSI standard (which is over 2 inches thick BTW). So, for a hard disk drive for instance you do not specify a head/cylinder/sector to address a particular block, but simply the number of the block you want. Elaborate caching schemes, automatic bad block replacement etc are all made possible by this 'intelligent device' approach. On a SCSI bus, each possible pair of devices can communicate. Whether their function allows this is another matter, but the standard does not restrict it. To avoid signal contention, the 2 devices have to arbitrate for the bus before using it. The philosophy of SCSI is to have a standard that allows older-standard devices to work with newer-standard ones. So, an old SCSI-1 device should normally work on a SCSI-2 bus. I say Normally, because it is not absolutely sure that the implementation of an old device follows the (old) standard closely enough to be acceptable on a new bus. Modern devices are usually more well-behaved, because the standardization has become more strict and is better adhered to by the device manufacturers. Generally speaking, the chances of getting a working set of devices on a single bus is better when all the devices are SCSI-2 or newer. This implies that you do not have to dump all your old stuff when you get that shiny 2GB disk: I own a system on which a pre-SCSI-1 disk, a SCSI-2 QIC tape unit, a SCSI-1 helical scan tape unit and 2 SCSI-1 disks work together quite happily. From a performance standpoint you might want to separate your older and newer (=faster) devices however. Components of SCSI As said before, SCSI devices are smart. The idea is to put the knowledge about intimate hardware details onto the SCSI device itself. In this way, the host system does not have to worry about things like how many heads a hard disks has, or how many tracks there are on a specific tape device. If you are curious, the standard specifies commands with which you can query your devices on their hardware particulars. FreeBSD uses this capability during boot to check out what devices are connected and whether they need any special treatment. The advantage of intelligent devices is obvious: the device drivers on the host can be made in a much more generic fashion, there is no longer a need to change (and qualify!) drivers for every odd new device that is introduced. For cabling and connectors there is a golden rule: get good stuff. With bus speeds going up all the time you will save yourself a lot of grief by using good material. So, gold plated connectors, shielded cabling, sturdy connector hoods with strain reliefs etc are the way to go. Second golden rule: do no use cables longer than necessary. I once spent 3 days hunting down a problem with a flaky machine only to discover that shortening the SCSI bus by 1 meter solved the problem. And the original bus length was well within the SCSI specification. SCSI bus types From an electrical point of view, there are two incompatible bus types: single-ended and differential. This means that there are two different main groups of SCSI devices and controllers, which cannot be mixed on the same bus. It is possible however to use special converter hardware to transform a single-ended bus into a differential one (and vice versa). The differences between the bus types are explained in the next sections. In lots of SCSI related documentation there is a sort of jargon in use to abbreviate the different bus types. A small list: FWD: Fast Wide Differential FND: Fast Narrow Differential SE: Single Ended FN: Fast Narrow etc. With a minor amount of imagination one can usually imagine what is meant. Wide is a bit ambiguous, it can indicate 16 or 32 bit buses. As far as I know, the 32 bit variant is not (yet) in use, so wide normally means 16 bit. Fast means that the timing on the bus is somewhat different, so that on a narrow (8 bit) bus 10 Mbytes/sec are possible instead of 5 Mbytes/sec for 'slow' SCSI. As discussed before, bus speeds of 20 and 40 million transfers/second are also emerging (Fast-20 == Ultra SCSI and Fast-40 == Ultra2 SCSI). The data lines > 8 are only used for data transfers and device addressing. The transfers of commands and status messages etc are only performed on the lowest 8 data lines. The standard allows narrow devices to operate on a wide bus. The usable bus width is negotiated between the devices. You have to watch your device addressing closely when mixing wide and narrow. Single ended buses A single-ended SCSI bus uses signals that are either 5 Volts or 0 Volts (indeed, TTL levels) and are relative to a COMMON ground reference. A singled ended 8 bit SCSI bus has approximately 25 ground lines, who are all tied to a single `rail' on all devices. A standard single ended bus has a maximum length of 6 meters. If the same bus is used with fast-SCSI devices, the maximum length allowed drops to 3 meters. Fast-SCSI means that instead of 5Mbytes/sec the bus allows 10Mbytes/sec transfers. Fast-20 (Ultra SCSI) and Fast-40 allow for 20 and 40 million transfers/second respectively. So, F20 is 20 Mbytes/second on a 8 bit bus, 40 Mbytes/second on a 16 bit bus etc. For F20 the max bus length is 1.5 meters, for F40 it becomes 0.75 meters. Be aware that F20 is pushing the limits quite a bit, so you will quickly find out if your SCSI bus is electrically sound. If some devices on your bus use 'fast' to communicate your bus must adhere to the length restrictions for fast buses! It is obvious that with the newer fast-SCSI devices the bus length can become a real bottleneck. This is why the differential SCSI bus was introduced in the SCSI-2 standard. For connector pinning and connector types please refer to the SCSI-2 standard (see Further reading) itself, connectors etc are listed there in painstaking detail. Beware of devices using non-standard cabling. For instance Apple uses a 25pin D-type connecter (like the one on serial ports and parallel printers). Considering that the official SCSI bus needs 50 pins you can imagine the use of this connector needs some 'creative cabling'. The reduction of the number of ground wires they used is a bad idea, you better stick to 50 pins cabling in accordance with the SCSI standard. For Fast-20 and 40 do not even think about buses like this. Differential buses A differential SCSI bus has a maximum length of 25 meters. Quite a difference from the 3 meters for a single-ended fast-SCSI bus. The idea behind differential signals is that each bus signal has its own return wire. So, each signal is carried on a (preferably twisted) pair of wires. The voltage difference between these two wires determines whether the signal is asserted or de-asserted. To a certain extent the voltage difference between ground and the signal wire pair is not relevant (do not try 10 kVolts though). It is beyond the scope of this document to explain why this differential idea is so much better. Just accept that electrically seen the use of differential signals gives a much better noise margin. You will normally find differential buses in use for inter-cabinet connections. Because of the lower cost single ended is mostly used for shorter buses like inside cabinets. There is nothing that stops you from using differential stuff with FreeBSD, as long as you use a controller that has device driver support in FreeBSD. As an example, Adaptec marketed the AHA1740 as a single ended board, whereas the AHA1744 was differential. The software interface to the host is identical for both. Terminators Terminators in SCSI terminology are resistor networks that are used to get a correct impedance matching. Impedance matching is important to get clean signals on the bus, without reflections or ringing. If you once made a long distance telephone call on a bad line you probably know what reflections are. With 20Mbytes/sec traveling over your SCSI bus, you do not want signals echoing back. Terminators come in various incarnations, with more or less sophisticated designs. Of course, there are internal and external variants. Many SCSI devices come with a number of sockets in which a number of resistor networks can (must be!) installed. If you remove terminators from a device, carefully store them. You will need them when you ever decide to reconfigure your SCSI bus. There is enough variation in even these simple tiny things to make finding the exact replacement a frustrating business. There are also SCSI devices that have a single jumper to enable or disable a built-in terminator. There are special terminators you can stick onto a flat cable bus. Others look like external connectors, or a connector hood without a cable. So, lots of choice as you can see. There is much debate going on if and when you should switch from simple resistor (passive) terminators to active terminators. Active terminators contain slightly more elaborate circuit to give cleaner bus signals. The general consensus seems to be that the usefulness of active termination increases when you have long buses and/or fast devices. If you ever have problems with your SCSI buses you might consider trying an active terminator. Try to borrow one first, they reputedly are quite expensive. Please keep in mind that terminators for differential and single-ended buses are not identical. You should not mix the two variants. OK, and now where should you install your terminators? This is by far the most misunderstood part of SCSI. And it is by far the simplest. The rule is: every single line on the SCSI bus has 2 (two) terminators, one at each end of the bus. So, two and not one or three or whatever. Do yourself a favor and stick to this rule. It will save you endless grief, because wrong termination has the potential to introduce highly mysterious bugs. (Note the potential here; the nastiest part is that it may or may not work.) A common pitfall is to have an internal (flat) cable in a machine and also an external cable attached to the controller. It seems almost everybody forgets to remove the terminators from the controller. The terminator must now be on the last external device, and not on the controller! In general, every reconfiguration of a SCSI bus must pay attention to this. Termination is to be done on a per-line basis. This means if you have both narrow and wide buses connected to the same host adapter, you need to enable termination on the higher 8 bits of the bus on the adapter (as well as the last devices on each bus, of course). What I did myself is remove all terminators from my SCSI devices and controllers. I own a couple of external terminators, for both the Centronics-type external cabling and for the internal flat cable connectors. This makes reconfiguration much easier. On modern devices, sometimes integrated terminators are used. These things are special purpose integrated circuits that can be enabled or disabled with a control pin. It is not necessary to physically remove them from a device. You may find them on newer host adapters, sometimes they are software configurable, using some sort of setup tool. Some will even auto-detect the cables attached to the connectors and automatically set up the termination as necessary. At any rate, consult your documentation! Terminator power The terminators discussed in the previous chapter need power to operate properly. On the SCSI bus, a line is dedicated to this purpose. So, simple huh? Not so. Each device can provide its own terminator power to the terminator sockets it has on-device. But if you have external terminators, or when the device supplying the terminator power to the SCSI bus line is switched off you are in trouble. The idea is that initiators (these are devices that initiate actions on the bus, a discussion follows) must supply terminator power. All SCSI devices are allowed (but not required) to supply terminator power. To allow for un-powered devices on a bus, the terminator power must be supplied to the bus via a diode. This prevents the backflow of current to un-powered devices. To prevent all kinds of nastiness, the terminator power is usually fused. As you can imagine, fuses might blow. This can, but does not have to, lead to a non functional bus. If multiple devices supply terminator power, a single blown fuse will not put you out of business. A single supplier with a blown fuse certainly will. Clever external terminators sometimes have a LED indication that shows whether terminator power is present. In newer designs auto-restoring fuses that 'reset' themselves after some time are sometimes used. Device addressing Because the SCSI bus is, ehh, a bus there must be a way to distinguish or address the different devices connected to it. This is done by means of the SCSI or target ID. Each device has a unique target ID. You can select the ID to which a device must respond using a set of jumpers, or a dip switch, or something similar. Some SCSI host adapters let you change the target ID from the boot menu. (Yet some others will not let you change the ID from 7.) Consult the documentation of your device for more information. Beware of multiple devices configured to use the same ID. Chaos normally reigns in this case. A pitfall is that one of the devices sharing the same ID sometimes even manages to answer to I/O requests! For an 8 bit bus, a maximum of 8 targets is possible. The maximum is 8 because the selection is done bitwise using the 8 data lines on the bus. For wide buses this increases to the number of data lines (usually 16). A narrow SCSI device can not communicate with a SCSI device with a target ID larger than 7. This means it is generally not a good idea to move your SCSI host adapter's target ID to something higher than 7 (or your CDROM will stop working). The higher the SCSI target ID, the higher the priority the devices has. When it comes to arbitration between devices that want to use the bus at the same time, the device that has the highest SCSI ID will win. This also means that the SCSI host adapter usually uses target ID 7. Note however that the lower 8 IDs have higher priorities than the higher 8 IDs on a wide-SCSI bus. Thus, the order of target IDs is: [7 6 .. 1 0 15 14 .. 9 8] on a wide-SCSI system. (If you are wondering why the lower 8 have higher priority, read the previous paragraph for a hint.) For a further subdivision, the standard allows for Logical Units or LUNs for short. A single target ID may have multiple LUNs. For example, a tape device including a tape changer may have LUN 0 for the tape device itself, and LUN 1 for the tape changer. In this way, the host system can address each of the functional units of the tape changer as desired. Bus layout SCSI buses are linear. So, not shaped like Y-junctions, star topologies, rings, cobwebs or whatever else people might want to invent. One of the most common mistakes is for people with wide-SCSI host adapters to connect devices on all three connecters (external connector, internal wide connector, internal narrow connector). Don't do that. It may appear to work if you are really lucky, but I can almost guarantee that your system will stop functioning at the most unfortunate moment (this is also known as Murphy's law). You might notice that the terminator issue discussed earlier becomes rather hairy if your bus is not linear. Also, if you have more connectors than devices on your internal SCSI cable, make sure you attach devices on connectors on both ends instead of using the connectors in the middle and let one or both ends dangle. This will screw up the termination of the bus. The electrical characteristics, its noise margins and ultimately the reliability of it all are tightly related to linear bus rule. Stick to the linear bus rule! Using SCSI with FreeBSD About translations, BIOSes and magic... As stated before, you should first make sure that you have a electrically sound bus. When you want to use a SCSI disk on your PC as boot disk, you must aware of some quirks related to PC BIOSes. The PC BIOS in its first incarnation used a low level physical interface to the hard disk. So, you had to tell the BIOS (using a setup tool or a BIOS built-in setup) how your disk physically looked like. This involved stating number of heads, number of cylinders, number of sectors per track, obscure things like precompensation and reduced write current cylinder etc. One might be inclined to think that since SCSI disks are smart you can forget about this. Alas, the arcane setup issue is still present today. The system BIOS needs to know how to access your SCSI disk with the head/cyl/sector method in order to load the FreeBSD kernel during boot. The SCSI host adapter or SCSI controller you have put in your AT/EISA/PCI/whatever bus to connect your disk therefore has its own on-board BIOS. During system startup, the SCSI BIOS takes over the hard disk interface routines from the system BIOS. To fool the system BIOS, the system setup is normally set to No hard disk present. Obvious, isn't it? The SCSI BIOS itself presents to the system a so called translated drive. This means that a fake drive table is constructed that allows the PC to boot the drive. This translation is often (but not always) done using a pseudo drive with 64 heads and 32 sectors per track. By varying the number of cylinders, the SCSI BIOS adapts to the actual drive size. It is useful to note that 32 * 64 / 2 = the size of your drive in megabytes. The division by 2 is to get from disk blocks that are normally 512 bytes in size to Kbytes. Right. All is well now?! No, it is not. The system BIOS has another quirk you might run into. The number of cylinders of a bootable hard disk cannot be greater than 1024. Using the translation above, this is a show-stopper for disks greater than 1 GB. With disk capacities going up all the time this is causing problems. Fortunately, the solution is simple: just use another translation, e.g. with 128 heads instead of 32. In most cases new SCSI BIOS versions are available to upgrade older SCSI host adapters. Some newer adapters have an option, in the form of a jumper or software setup selection, to switch the translation the SCSI BIOS uses. It is very important that all operating systems on the disk use the same translation to get the right idea about where to find the relevant partitions. So, when installing FreeBSD you must answer any questions about heads/cylinders etc using the translated values your host adapter uses. Failing to observe the translation issue might lead to un-bootable systems or operating systems overwriting each others partitions. Using fdisk you should be able to see all partitions. You might have heard some talk of lying devices? Older FreeBSD kernels used to report the geometry of SCSI disks when booting. An example from one of my systems: aha0 targ 0 lun 0: <MICROP 1588-15MB1057404HSP4> sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, 53 sec, bytes/sec 512 Newer kernels usually do not report this information. e.g. (bt0:0:0): "SEAGATE ST41651 7574" type 0 fixed SCSI 2 sd0(bt0:0:0): Direct-Access 1350MB (2766300 512 byte sectors) Why has this changed? This info is retrieved from the SCSI disk itself. Newer disks often use a technique called zone bit recording. The idea is that on the outer cylinders of the drive there is more space so more sectors per track can be put on them. This results in disks that have more tracks on outer cylinders than on the inner cylinders and, last but not least, have more capacity. You can imagine that the value reported by the drive when inquiring about the geometry now becomes suspect at best, and nearly always misleading. When asked for a geometry , it is nearly always better to supply the geometry used by the BIOS, or if the BIOS is never going to know about this disk, (e.g. it is not a booting disk) to supply a fictitious geometry that is convenient. SCSI subsystem design FreeBSD uses a layered SCSI subsystem. For each different controller card a device driver is written. This driver knows all the intimate details about the hardware it controls. The driver has a interface to the upper layers of the SCSI subsystem through which it receives its commands and reports back any status. On top of the card drivers there are a number of more generic drivers for a class of devices. More specific: a driver for tape devices (abbreviation: st), magnetic disks (sd), CDROMs (cd) etc. In case you are wondering where you can find this stuff, it all lives in /sys/scsi. See the man pages in section 4 for more details. The multi level design allows a decoupling of low-level bit banging and more high level stuff. Adding support for another piece of hardware is a much more manageable problem. Kernel configuration Dependent on your hardware, the kernel configuration file must contain one or more lines describing your host adapter(s). This includes I/O addresses, interrupts etc. Consult the man page for your adapter driver to get more info. Apart from that, check out /sys/i386/conf/LINT for an overview of a kernel config file. LINT contains every possible option you can dream of. It does not imply LINT will actually get you to a working kernel at all. Although it is probably stating the obvious: the kernel config file should reflect your actual hardware setup. So, interrupts, I/O addresses etc must match the kernel config file. During system boot messages will be displayed to indicate whether the configured hardware was actually found. Note that most of the EISA/PCI drivers (namely ahb, ahc, ncr and amd will automatically obtain the correct parameters from the host adapters themselves at boot time; thus, you just need to write, for instance, controller ahc0. An example loosely based on the FreeBSD 2.2.5-Release kernel config file LINT with some added comments (between []): # SCSI host adapters: `aha', `ahb', `aic', `bt', `nca' # # aha: Adaptec 154x # ahb: Adaptec 174x # ahc: Adaptec 274x/284x/294x # aic: Adaptec 152x and sound cards using the Adaptec AIC-6360 (slow!) # amd: AMD 53c974 based SCSI cards (e.g., Tekram DC-390 and 390T) # bt: Most Buslogic controllers # nca: ProAudioSpectrum cards using the NCR 5380 or Trantor T130 # ncr: NCR/Symbios 53c810/815/825/875 etc based SCSI cards # uha: UltraStore 14F and 34F # sea: Seagate ST01/02 8 bit controller (slow!) # wds: Western Digital WD7000 controller (no scatter/gather!). # [For an Adaptec AHA274x/284x/294x/394x etc controller] controller ahc0 [For an NCR/Symbios 53c875 based controller] controller ncr0 [For an Ultrastor adapter] controller uha0 at isa? port "IO_UHA0" bio irq ? drq 5 vector uhaintr # Map SCSI buses to specific SCSI adapters controller scbus0 at ahc0 controller scbus2 at ncr0 controller scbus1 at uha0 # The actual SCSI devices disk sd0 at scbus0 target 0 unit 0 [SCSI disk 0 is at scbus 0, LUN 0] disk sd1 at scbus0 target 1 [implicit LUN 0 if omitted] disk sd2 at scbus1 target 3 [SCSI disk on the uha0] disk sd3 at scbus2 target 4 [SCSI disk on the ncr0] tape st1 at scbus0 target 6 [SCSI tape at target 6] device cd0 at scbus? [the first ever CDROM found, no wiring] The example above tells the kernel to look for a ahc (Adaptec 274x) controller, then for an NCR/Symbios board, and so on. The lines following the controller specifications tell the kernel to configure specific devices but only attach them when they match the target ID and LUN specified on the corresponding bus. Wired down devices get first shot at the unit numbers so the first non wired down device, is allocated the unit number one greater than the highest wired down unit number for that kind of device. So, if you had a SCSI tape at target ID 2 it would be configured as st2, as the tape at target ID 6 is wired down to unit number 1. Wired down devices need not be found to get their unit number. The unit number for a wired down device is reserved for that device, even if it is turned off at boot time. This allows the device to be turned on and brought on-line at a later time, without rebooting. Notice that a device's unit number has no relationship with its target ID on the SCSI bus. Below is another example of a kernel config file as used by FreeBSD version < 2.0.5. The difference with the first example is that devices are not wired down. Wired down means that you specify which SCSI target belongs to which device. A kernel built to the config file below will attach the first SCSI disk it finds to sd0, the second disk to sd1 etc. If you ever removed or added a disk, all other devices of the same type (disk in this case) would 'move around'. This implies you have to change /etc/fstab each time. Although the old style still works, you are strongly recommended to use this new feature. It will save you a lot of grief whenever you shift your hardware around on the SCSI buses. So, when you re-use your old trusty config file after upgrading from a pre-FreeBSD2.0.5.R system check this out. [driver for Adaptec 174x] controller ahb0 at isa? bio irq 11 vector ahbintr [for Adaptec 154x] controller aha0 at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr [for Seagate ST01/02] controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr controller scbus0 device sd0 [support for 4 SCSI harddisks, sd0 up sd3] device st0 [support for 2 SCSI tapes] [for the CDROM] device cd0 #Only need one of these, the code dynamically grows Both examples support SCSI disks. If during boot more devices of a specific type (e.g. sd disks) are found than are configured in the booting kernel, the system will simply allocate more devices, incrementing the unit number starting at the last number wired down. If there are no wired down devices then counting starts at unit 0. Use man 4 scsi to check for the latest info on the SCSI subsystem. For more detailed info on host adapter drivers use e.g., man 4 ahc for info on the Adaptec 294x driver. Tuning your SCSI kernel setup Experience has shown that some devices are slow to respond to INQUIRY commands after a SCSI bus reset (which happens at boot time). An INQUIRY command is sent by the kernel on boot to see what kind of device (disk, tape, CDROM etc.) is connected to a specific target ID. This process is called device probing by the way. To work around the 'slow response' problem, FreeBSD allows a tunable delay time before the SCSI devices are probed following a SCSI bus reset. You can set this delay time in your kernel configuration file using a line like: options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device This line sets the delay time to 15 seconds. On my own system I had to use 3 seconds minimum to get my trusty old CDROM drive to be recognized. Start with a high value (say 30 seconds or so) when you have problems with device recognition. If this helps, tune it back until it just stays working. Rogue SCSI devices Although the SCSI standard tries to be complete and concise, it is a complex standard and implementing things correctly is no easy task. Some vendors do a better job then others. This is exactly where the rogue devices come into view. Rogues are devices that are recognized by the FreeBSD kernel as behaving slightly (...) non-standard. Rogue devices are reported by the kernel when booting. An example for two of my cartridge tape units: Feb 25 21:03:34 yedi /kernel: ahb0 targ 5 lun 0: <TANDBERG TDC 3600 -06:> Feb 25 21:03:34 yedi /kernel: st0: Tandberg tdc3600 is a known rogue Mar 29 21:16:37 yedi /kernel: aha0 targ 5 lun 0: <ARCHIVE VIPER 150 21247-005> Mar 29 21:16:37 yedi /kernel: st1: Archive Viper 150 is a known rogue For instance, there are devices that respond to all LUNs on a certain target ID, even if they are actually only one device. It is easy to see that the kernel might be fooled into believing that there are 8 LUNs at that particular target ID. The confusion this causes is left as an exercise to the reader. The SCSI subsystem of FreeBSD recognizes devices with bad habits by looking at the INQUIRY response they send when probed. Because the INQUIRY response also includes the version number of the device firmware, it is even possible that for different firmware versions different workarounds are used. See e.g. /sys/scsi/st.c and /sys/scsi/scsiconf.c for more info on how this is done. This scheme works fine, but keep in mind that it of course only works for devices that are known to be weird. If you are the first to connect your bogus Mumbletech SCSI CDROM you might be the one that has to define which workaround is needed. After you got your Mumbletech working, please send the required workaround to the FreeBSD development team for inclusion in the next release of FreeBSD. Other Mumbletech owners will be grateful to you. Multiple LUN devices In some cases you come across devices that use multiple logical units (LUNs) on a single SCSI ID. In most cases FreeBSD only probes devices for LUN 0. An example are so called bridge boards that connect 2 non-SCSI harddisks to a SCSI bus (e.g. an Emulex MD21 found in old Sun systems). This means that any devices with LUNs != 0 are not normally found during device probe on system boot. To work around this problem you must add an appropriate entry in /sys/scsi/scsiconf.c and rebuild your kernel. Look for a struct that is initialized like below: { T_DIRECT, T_FIXED, "MAXTOR", "XT-4170S", "B5A", "mx1", SC_ONE_LU } For you Mumbletech BRIDGE2000 that has more than one LUN, acts as a SCSI disk and has firmware revision 123 you would add something like: { T_DIRECT, T_FIXED, "MUMBLETECH", "BRIDGE2000", "123", "sd", SC_MORE_LUS } The kernel on boot scans the inquiry data it receives against the table and acts accordingly. See the source for more info. Tagged command queuing Modern SCSI devices, particularly magnetic disks, support what is called tagged command queuing (TCQ). In a nutshell, TCQ allows the device to have multiple I/O requests outstanding at the same time. Because the device is intelligent, it can optimize its operations (like head positioning) based on its own request queue. On SCSI devices like RAID (Redundant Array of Independent Disks) arrays the TCQ function is indispensable to take advantage of the device's inherent parallelism. Each I/O request is uniquely identified by a tag (hence the name tagged command queuing) and this tag is used by FreeBSD to see which I/O in the device drivers queue is reported as complete by the device. It should be noted however that TCQ requires device driver support and that some devices implemented it not quite right in their firmware. This problem bit me once, and it leads to highly mysterious problems. In such cases, try to disable TCQ. Busmaster host adapters Most, but not all, SCSI host adapters are bus mastering controllers. This means that they can do I/O on their own without putting load onto the host CPU for data movement. This is of course an advantage for a multitasking operating system like FreeBSD. It must be noted however that there might be some rough edges. For instance an Adaptec 1542 controller can be set to use different transfer speeds on the host bus (ISA or AT in this case). The controller is settable to different rates because not all motherboards can handle the higher speeds. Problems like hang-ups, bad data etc might be the result of using a higher data transfer rate then your motherboard can stomach. The solution is of course obvious: switch to a lower data transfer rate and try if that works better. In the case of a Adaptec 1542, there is an option that can be put into the kernel config file to allow dynamic determination of the right, read: fastest feasible, transfer rate. This option is disabled by default: options "TUNE_1542" #dynamic tune of bus DMA speed Check the man pages for the host adapter that you use. Or better still, use the ultimate documentation (read: driver source). Tracking down problems The following list is an attempt to give a guideline for the most common SCSI problems and their solutions. It is by no means complete. Check for loose connectors and cables. Check and double check the location and number of your terminators. Check if your bus has at least one supplier of terminator power (especially with external terminators. Check if no double target IDs are used. Check if all devices to be used are powered up. Make a minimal bus config with as little devices as possible. If possible, configure your host adapter to use slow bus speeds. Disable tagged command queuing to make things as simple as possible (for a NCR host adapter based system see man ncrcontrol) If you can compile a kernel, make one with the SCSIDEBUG option, and try accessing the device with debugging turned on for that device. If your device does not even probe at startup, you may have to define the address of the device that is failing, and the desired debug level in /sys/scsi/scsidebug.h. If it probes but just does not work, you can use the &man.scsi.8; command to dynamically set a debug level to it in a running kernel (if SCSIDEBUG is defined). This will give you copious debugging output with which to confuse the gurus. See man 4 scsi for more exact information. Also look at man 8 scsi. Further reading If you intend to do some serious SCSI hacking, you might want to have the official standard at hand: Approved American National Standards can be purchased from ANSI at
13th Floor 11 West 42nd Street New York NY 10036 Sales Dept: (212) 642-4900
You can also buy many ANSI standards and most committee draft documents from Global Engineering Documents,
15 Inverness Way East Englewood CO, 80112-5704 Phone: (800) 854-7179 Outside USA and Canada: (303) 792-2181 Fax: (303) 792- 2192
Many X3T10 draft documents are available electronically on the SCSI BBS (719-574-0424) and on the ncrinfo.ncr.com anonymous ftp site. + role="fqdn">ncrinfo.ncr.com anonymous FTP site. Latest X3T10 committee documents are: AT Attachment (ATA or IDE) [X3.221-1994] (Approved) ATA Extensions (ATA-2) [X3T10/948D Rev 2i] Enhanced Small Device Interface (ESDI) [X3.170-1990/X3.170a-1991] (Approved) Small Computer System Interface — 2 (SCSI-2) [X3.131-1994] (Approved) SCSI-2 Common Access Method Transport and SCSI Interface Module (CAM) [X3T10/792D Rev 11] Other publications that might provide you with additional information are: SCSI: Understanding the Small Computer System Interface, written by NCR Corporation. Available from: Prentice Hall, Englewood Cliffs, NJ, 07632 Phone: (201) 767-5937 ISBN 0-13-796855-8 Basics of SCSI, a SCSI tutorial written by Ancot Corporation Contact Ancot for availability information at: Phone: (415) 322-5322 Fax: (415) 322-0455 SCSI Interconnection Guide Book, an AMP publication (dated 4/93, Catalog 65237) that lists the various SCSI connectors and suggests cabling schemes. Available from AMP at (800) 522-6752 or (717) 564-0100 Fast Track to SCSI, A Product Guide written by Fujitsu. Available from: Prentice Hall, Englewood Cliffs, NJ, 07632 Phone: (201) 767-5937 ISBN 0-13-307000-X The SCSI Bench Reference, The SCSI Encyclopedia, and the SCSI Tutor, ENDL Publications, 14426 Black Walnut Court, Saratoga CA, 95070 Phone: (408) 867-6642 Zadian SCSI Navigator (quick ref. book) and Discover the Power of SCSI (First book along with a one-hour video and tutorial book), Zadian Software, Suite 214, 1210 S. Bascom Ave., San Jose, CA 92128, (408) 293-0800 On Usenet the newsgroups comp.periphs.scsi and comp.periphs are noteworthy places to look for more info. You can also find the SCSI-Faq there, which is posted periodically. - Most major SCSI device and host adapter suppliers operate ftp + Most major SCSI device and host adapter suppliers operate FTP sites and/or BBS systems. They may be valuable sources of information about the devices you own. * Disk/tape controllers * SCSI * IDE * Floppy Hard drives SCSI hard drives Contributed by &a.asami;. 17 February 1998. As mentioned in the SCSI section, virtually all SCSI hard drives sold today are SCSI-2 compliant and thus will work fine as long as you connect them to a supported SCSI host adapter. Most problems people encounter are either due to badly designed cabling (cable too long, star topology, etc.), insufficient termination, or defective parts. Please refer to the SCSI section first if your SCSI hard drive is not working. However, there are a couple of things you may want to take into account before you purchase SCSI hard drives for your system. Rotational speed Rotational speeds of SCSI drives sold today range from around 4,500RPM to 10,000RPM. Most of them are either 5,400RPM or 7,200RPM. Even though the 7,200RPM drives can generally transfer data faster, they run considerably hotter than their 5,400RPM counterparts. A large fraction of today's disk drive malfunctions are heat-related. If you do not have very good cooling in your PC case, you may want to stick with 5,400RPM or slower drives. Note that newer drives, with higher areal recording densities, can deliver much more bits per rotation than older ones. Today's top-of-line 5,400RPM drives can sustain a throughput comparable to 7,200RPM drives of one or two model generations ago. The number to find on the spec sheet for bandwidth is internal data (or transfer) rate. It is usually in megabits/sec so divide it by 8 and you'll get the rough approximation of how much megabytes/sec you can get out of the drive. (If you are a speed maniac and want a 10,000RPM drive for your cute little PC, be my guest; however, those drives become extremely hot. Don't even think about it if you don't have a fan blowing air directly at the drive or a properly ventilated disk enclosure.) Obviously, the latest 10,000RPM drives and 7,200RPM drives can deliver more data than the latest 5,400RPM drives, so if absolute bandwidth is the necessity for your applications, you have little choice but to get the faster drives. Also, if you need low latency, faster drives are better; not only do they usually have lower average seek times, but also the rotational delay is one place where slow-spinning drives can never beat a faster one. (The average rotational latency is half the time it takes to rotate the drive once; thus, it's 3 milliseconds for 10,000RPM drives, 4.2ms for 7,200RPM drives and 5.6ms for 5,400RPM drives.) Latency is seek time plus rotational delay. Make sure you understand whether you need low latency or more accesses per second, though; in the latter case (e.g., news servers), it may not be optimal to purchase one big fast drive. You can achieve similar or even better results by using the ccd (concatenated disk) driver to create a striped disk array out of multiple slower drives for comparable overall cost. Make sure you have adequate air flow around the drive, especially if you are going to use a fast-spinning drive. You generally need at least 1/2" (1.25cm) of spacing above and below a drive. Understand how the air flows through your PC case. Most cases have the power supply suck the air out of the back. See where the air flows in, and put the drive where it will have the largest volume of cool air flowing around it. You may need to seal some unwanted holes or add a new fan for effective cooling. Another consideration is noise. Many 7,200 or faster drives generate a high-pitched whine which is quite unpleasant to most people. That, plus the extra fans often required for cooling, may make 7,200 or faster drives unsuitable for some office and home environments. Form factor Most SCSI drives sold today are of 3.5" form factor. They come in two different heights; 1.6" (half-height) or 1" (low-profile). The half-height drive is the same height as a CDROM drive. However, don't forget the spacing rule mentioned in the previous section. If you have three standard 3.5" drive bays, you will not be able to put three half-height drives in there (without frying them, that is). Interface The majority of SCSI hard drives sold today are Ultra or Ultra-wide SCSI. The maximum bandwidth of Ultra SCSI is 20MB/sec, and Ultra-wide SCSI is 40MB/sec. There is no difference in max cable length between Ultra and Ultra-wide; however, the more devices you have on the same bus, the sooner you will start having bus integrity problems. Unless you have a well-designed disk enclosure, it is not easy to make more than 5 or 6 Ultra SCSI drives work on a single bus. On the other hand, if you need to connect many drives, going for Fast-wide SCSI may not be a bad idea. That will have the same max bandwidth as Ultra (narrow) SCSI, while electronically it's much easier to get it right. My advice would be: if you want to connect many disks, get wide SCSI drives; they usually cost a little more but it may save you down the road. (Besides, if you can't afford the cost difference, you shouldn't be building a disk array.) There are two variant of wide SCSI drives; 68-pin and 80-pin SCA (Single Connector Attach). The SCA drives don't have a separate 4-pin power connector, and also read the SCSI ID settings through the 80-pin connector. If you are really serious about building a large storage system, get SCA drives and a good SCA enclosure (dual power supply with at least one extra fan). They are more electronically sound than 68-pin counterparts because there is no stub of the SCSI bus inside the disk canister as in arrays built from 68-pin drives. They are easier to install too (you just need to screw the drive in the canister, instead of trying to squeeze in your fingers in a tight place to hook up all the little cables (like the SCSI ID and disk activity LED lines). * IDE hard drives Tape drives Contributed by &a.jmb;. 2 July 1996. General tape access commands &man.mt.1; provides generic access to the tape drives. Some of the more common commands are rewind, erase, and status. See the &man.mt.1; manual page for a detailed description. Controller Interfaces There are several different interfaces that support tape drives. The interfaces are SCSI, IDE, Floppy and Parallel Port. A wide variety of tape drives are available for these interfaces. Controllers are discussed in Disk/tape controllers. SCSI drives The &man.st.4; driver provides support for 8mm (Exabyte), 4mm (DAT: Digital Audio Tape), QIC (Quarter-Inch Cartridge), DLT (Digital Linear Tape), QIC Mini cartridge and 9-track (remember the big reels that you see spinning in Hollywood computer rooms) tape drives. See the &man.st.4; manual page for a detailed description. The drives listed below are currently being used by members of the FreeBSD community. They are not the only drives that will work with FreeBSD. They just happen to be the ones that we use. 4mm (DAT: Digital Audio Tape) Archive Python 28454 Archive Python 04687 HP C1533A HP C1534A HP 35450A HP 35470A HP 35480A SDT-5000 Wangtek 6200 8mm (Exabyte) EXB-8200 EXB-8500 EXB-8505 QIC (Quarter-Inch Cartridge) Archive Anaconda 2750 Archive Viper 60 Archive Viper 150 Archive Viper 2525 Tandberg TDC 3600 Tandberg TDC 3620 Tandberg TDC 3800 Tandberg TDC 4222 Wangtek 5525ES DLT (Digital Linear Tape) Digital TZ87 Mini-Cartridge Conner CTMS 3200 Exabyte 2501 Autoloaders/Changers Hewlett-Packard HP C1553A Autoloading DDS2 * IDE drives Floppy drives Conner 420R * Parallel port drives Detailed Information Archive Anaconda 2750 The boot message identifier for this drive is ARCHIVE ANCDA 2750 28077 -003 type 1 removable SCSI 2 This is a QIC tape drive. Native capacity is 1.35GB when using QIC-1350 tapes. This drive will read and write QIC-150 (DC6150), QIC-250 (DC6250), and QIC-525 (DC6525) tapes as well. Data transfer rate is 350kB/s using &man.dump.8;. Rates of 530kB/s have been reported when using Amanda Production of this drive has been discontinued. The SCSI bus connector on this tape drive is reversed from that on most other SCSI devices. Make sure that you have enough SCSI cable to twist the cable one-half turn before and after the Archive Anaconda tape drive, or turn your other SCSI devices upside-down. Two kernel code changes are required to use this drive. This drive will not work as delivered. If you have a SCSI-2 controller, short jumper 6. Otherwise, the drive behaves are a SCSI-1 device. When operating as a SCSI-1 device, this drive, locks the SCSI bus during some tape operations, including: fsf, rewind, and rewoffl. If you are using the NCR SCSI controllers, patch the file /usr/src/sys/pci/ncr.c (as shown below). Build and install a new kernel. *** 4831,4835 **** }; ! if (np->latetime>4) { /* ** Although we tried to wake it up, --- 4831,4836 ---- }; ! if (np->latetime>1200) { /* ** Although we tried to wake it up, Reported by: &a.jmb; Archive Python 28454 The boot message identifier for this drive is ARCHIVE Python 28454-XXX4ASB type 1 removable SCSI 2 density code 0x8c, 512-byte blocks This is a DDS-1 tape drive. Native capacity is 2.5GB on 90m tapes. Data transfer rate is XXX. This drive was repackaged by Sun Microsystems as model 595-3067. Reported by: Bob Bishop rb@gid.co.uk Throughput is in the 1.5 MByte/sec range, however this will drop if the disks and tape drive are on the same SCSI controller. Reported by: Robert E. Seastrom rs@seastrom.com Archive Python 04687 The boot message identifier for this drive is ARCHIVE Python 04687-XXX 6580 Removable Sequential Access SCSI-2 device This is a DAT-DDS-2 drive. Native capacity is 4GB when using 120m tapes. This drive supports hardware data compression. Switch 4 controls MRS (Media Recognition System). MRS tapes have stripes on the transparent leader. Switch 4 off enables MRS, on disables MRS. Parity is controlled by switch 5. Switch 5 on to enable parity control. Compression is enabled with Switch 6 off. It is possible to override compression with the SCSI MODE SELECT command (see &man.mt.1;). Data transfer rate is 800kB/s. Archive Viper 60 The boot message identifier for this drive is ARCHIVE VIPER 60 21116 -007 type 1 removable SCSI 1 This is a QIC tape drive. Native capacity is 60MB. Data transfer rate is XXX. Production of this drive has been discontinued. Reported by: Philippe Regnauld regnauld@hsc.fr Archive Viper 150 The boot message identifier for this drive is ARCHIVE VIPER 150 21531 -004 Archive Viper 150 is a known rogue type 1 removable SCSI 1. A multitude of firmware revisions exist for this drive. Your drive may report different numbers (e.g 21247 -005. This is a QIC tape drive. Native capacity is 150/250MB. Both 150MB (DC6150) and 250MB (DC6250) tapes have the recording format. The 250MB tapes are approximately 67% longer than the 150MB tapes. This drive can read 120MB tapes as well. It can not write 120MB tapes. Data transfer rate is 100kB/s This drive reads and writes DC6150 (150MB) and DC6250 (250MB) tapes. This drives quirks are known and pre-compiled into the scsi tape device driver (&man.st.4;). Under FreeBSD 2.2-CURRENT, use mt blocksize 512 to set the blocksize. (The particular drive had firmware revision 21247 -005. Other firmware revisions may behave differently) Previous versions of FreeBSD did not have this problem. Production of this drive has been discontinued. Reported by: Pedro A M Vazquez vazquez@IQM.Unicamp.BR &a.msmith; Archive Viper 2525 The boot message identifier for this drive is ARCHIVE VIPER 2525 25462 -011 type 1 removable SCSI 1 This is a QIC tape drive. Native capacity is 525MB. Data transfer rate is 180kB/s at 90 inches/sec. The drive reads QIC-525, QIC-150, QIC-120 and QIC-24 tapes. Writes QIC-525, QIC-150, and QIC-120. Firmware revisions prior to 25462 -011 are bug ridden and will not function properly. Production of this drive has been discontinued. Conner 420R The boot message identifier for this drive is Conner tape. This is a floppy controller, mini cartridge tape drive. Native capacity is XXXX Data transfer rate is XXX The drive uses QIC-80 tape cartridges. Reported by: Mark Hannon mark@seeware.DIALix.oz.au Conner CTMS 3200 The boot message identifier for this drive is CONNER CTMS 3200 7.00 type 1 removable SCSI 2. This is a mini cartridge tape drive. Native capacity is XXXX Data transfer rate is XXX The drive uses QIC-3080 tape cartridges. Reported by: Thomas S. Traylor tst@titan.cs.mci.com <ulink url="http://www.digital.com/info/Customer-Update/931206004.txt.html">DEC TZ87</ulink> The boot message identifier for this drive is DEC TZ87 (C) DEC 9206 type 1 removable SCSI 2 density code 0x19 This is a DLT tape drive. Native capacity is 10GB. This drive supports hardware data compression. Data transfer rate is 1.2MB/s. This drive is identical to the Quantum DLT2000. The drive firmware can be set to emulate several well-known drives, including an Exabyte 8mm drive. Reported by: &a.wilko; <ulink url="http://www.Exabyte.COM:80/Products/Minicartridge/2501/Rfeatures.html">Exabyte EXB-2501</ulink> The boot message identifier for this drive is EXABYTE EXB-2501 This is a mini-cartridge tape drive. Native capacity is 1GB when using MC3000XL mini cartridges. Data transfer rate is XXX This drive can read and write DC2300 (550MB), DC2750 (750MB), MC3000 (750MB), and MC3000XL (1GB) mini cartridges. WARNING: This drive does not meet the SCSI-2 specifications. The drive locks up completely in response to a SCSI MODE_SELECT command unless there is a formatted tape in the drive. Before using this drive, set the tape blocksize with &prompt.root; mt -f /dev/st0ctl.0 blocksize 1024 Before using a mini cartridge for the first time, the mini cartridge must be formated. FreeBSD 2.1.0-RELEASE and earlier: &prompt.root; /sbin/scsi -f /dev/rst0.ctl -s 600 -c "4 0 0 0 0 0" (Alternatively, fetch a copy of the scsiformat shell script from FreeBSD 2.1.5/2.2.) FreeBSD 2.1.5 and later: &prompt.root; /sbin/scsiformat -q -w /dev/rst0.ctl Right now, this drive cannot really be recommended for FreeBSD. Reported by: Bob Beaulieu ez@eztravel.com Exabyte EXB-8200 The boot message identifier for this drive is EXABYTE EXB-8200 252X type 1 removable SCSI 1 This is an 8mm tape drive. Native capacity is 2.3GB. Data transfer rate is 270kB/s. This drive is fairly slow in responding to the SCSI bus during boot. A custom kernel may be required (set SCSI_DELAY to 10 seconds). There are a large number of firmware configurations for this drive, some have been customized to a particular vendor's hardware. The firmware can be changed via EPROM replacement. Production of this drive has been discontinued. Reported by: &a.msmith; Exabyte EXB-8500 The boot message identifier for this drive is EXABYTE EXB-8500-85Qanx0 0415 type 1 removable SCSI 2 This is an 8mm tape drive. Native capacity is 5GB. Data transfer rate is 300kB/s. Reported by: Greg Lehey grog@lemis.de <ulink url="http://www.Exabyte.COM:80/Products/8mm/8505XL/Rfeatures.html">Exabyte EXB-8505</ulink> The boot message identifier for this drive is EXABYTE EXB-85058SQANXR1 05B0 type 1 removable SCSI 2 This is an 8mm tape drive which supports compression, and is upward compatible with the EXB-5200 and EXB-8500. Native capacity is 5GB. The drive supports hardware data compression. Data transfer rate is 300kB/s. Reported by: Glen Foster gfoster@gfoster.com Hewlett-Packard HP C1533A The boot message identifier for this drive is HP C1533A 9503 type 1 removable SCSI 2. This is a DDS-2 tape drive. DDS-2 means hardware data compression and narrower tracks for increased data capacity. Native capacity is 4GB when using 120m tapes. This drive supports hardware data compression. Data transfer rate is 510kB/s. This drive is used in Hewlett-Packard's SureStore 6000eU and 6000i tape drives and C1533A DDS-2 DAT drive. The drive has a block of 8 dip switches. The proper settings for FreeBSD are: 1 ON; 2 ON; 3 OFF; 4 ON; 5 ON; 6 ON; 7 ON; 8 ON. switch 1 switch 2 Result On On Compression enabled at power-on, with host control On Off Compression enabled at power-on, no host control Off On Compression disabled at power-on, with host control Off Off Compression disabled at power-on, no host control Switch 3 controls MRS (Media Recognition System). MRS tapes have stripes on the transparent leader. These identify the tape as DDS (Digital Data Storage) grade media. Tapes that do not have the stripes will be treated as write-protected. Switch 3 OFF enables MRS. Switch 3 ON disables MRS. See HP SureStore Tape Products and Hewlett-Packard Disk and Tape Technical Information for more information on configuring this drive. Warning: Quality control on these drives varies greatly. One FreeBSD core-team member has returned 2 of these drives. Neither lasted more than 5 months. Reported by: &a.se; Hewlett-Packard HP 1534A The boot message identifier for this drive is HP HP35470A T503 type 1 removable SCSI 2 Sequential-Access density code 0x13, variable blocks. This is a DDS-1 tape drive. DDS-1 is the original DAT tape format. Native capacity is 2GB when using 90m tapes. Data transfer rate is 183kB/s. The same mechanism is used in Hewlett-Packard's SureStore 2000i tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT drive and HP C1536A DDS format DAT drive. The HP C1534A DDS format DAT drive has two indicator lights, one green and one amber. The green one indicates tape action: slow flash during load, steady when loaded, fast flash during read/write operations. The amber one indicates warnings: slow flash when cleaning is required or tape is nearing the end of its useful life, steady indicates an hard fault. (factory service required?) Reported by Gary Crutcher gcrutchr@nightflight.com Hewlett-Packard HP C1553A Autoloading DDS2 The boot message identifier for this drive is "". This is a DDS-2 tape drive with a tape changer. DDS-2 means hardware data compression and narrower tracks for increased data capacity. Native capacity is 24GB when using 120m tapes. This drive supports hardware data compression. Data transfer rate is 510kB/s (native). This drive is used in Hewlett-Packard's SureStore 12000e tape drive. The drive has two selectors on the rear panel. The selector closer to the fan is SCSI id. The other selector should be set to 7. There are four internal switches. These should be set: 1 ON; 2 ON; 3 ON; 4 OFF. At present the kernel drivers do not automatically change tapes at the end of a volume. This shell script can be used to change tapes: #!/bin/sh PATH="/sbin:/usr/sbin:/bin:/usr/bin"; export PATH usage() { echo "Usage: dds_changer [123456ne] raw-device-name echo "1..6 = Select cartridge" echo "next cartridge" echo "eject magazine" exit 2 } if [ $# -ne 2 ] ; then usage fi cdb3=0 cdb4=0 cdb5=0 case $1 in [123456]) cdb3=$1 cdb4=1 ;; n) ;; e) cdb5=0x80 ;; ?) usage ;; esac scsi -f $2 -s 100 -c "1b 0 0 $cdb3 $cdb4 $cdb5" Hewlett-Packard HP 35450A The boot message identifier for this drive is HP HP35450A -A C620 type 1 removable SCSI 2 Sequential-Access density code 0x13 This is a DDS-1 tape drive. DDS-1 is the original DAT tape format. Native capacity is 1.2GB. Data transfer rate is 160kB/s. Reported by: Mark Thompson mark.a.thompson@pobox.com Hewlett-Packard HP 35470A The boot message identifier for this drive is HP HP35470A 9 09 type 1 removable SCSI 2 This is a DDS-1 tape drive. DDS-1 is the original DAT tape format. Native capacity is 2GB when using 90m tapes. Data transfer rate is 183kB/s. The same mechanism is used in Hewlett-Packard's SureStore 2000i tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT drive, and HP C1536A DDS format DAT drive. Warning: Quality control on these drives varies greatly. One FreeBSD core-team member has returned 5 of these drives. None lasted more than 9 months. Reported by: David Dawes dawes@rf900.physics.usyd.edu.au (9 09) Hewlett-Packard HP 35480A The boot message identifier for this drive is HP HP35480A 1009 type 1 removable SCSI 2 Sequential-Access density code 0x13. This is a DDS-DC tape drive. DDS-DC is DDS-1 with hardware data compression. DDS-1 is the original DAT tape format. Native capacity is 2GB when using 90m tapes. It cannot handle 120m tapes. This drive supports hardware data compression. Please refer to the section on HP C1533A for the proper switch settings. Data transfer rate is 183kB/s. This drive is used in Hewlett-Packard's SureStore 5000eU and 5000i tape drives and C35480A DDS format DAT drive.. This drive will occasionally hang during a tape eject operation (mt offline). Pressing the front panel button will eject the tape and bring the tape drive back to life. WARNING: HP 35480-03110 only. On at least two occasions this tape drive when used with FreeBSD 2.1.0, an IBM Server 320 and an 2940W SCSI controller resulted in all SCSI disk partitions being lost. The problem has not be analyzed or resolved at this time. <ulink url="http://www.sel.sony.com/SEL/ccpg/storage/tape/t5000.html">Sony SDT-5000</ulink> There are at least two significantly different models: one is a DDS-1 and the other DDS-2. The DDS-1 version is SDT-5000 3.02. The DDS-2 version is SONY SDT-5000 327M. The DDS-2 version has a 1MB cache. This cache is able to keep the tape streaming in almost any circumstances. The boot message identifier for this drive is SONY SDT-5000 3.02 type 1 removable SCSI 2 Sequential-Access density code 0x13 Native capacity is 4GB when using 120m tapes. This drive supports hardware data compression. Data transfer rate is depends upon the model or the drive. The rate is 630kB/s for the SONY SDT-5000 327M while compressing the data. For the SONY SDT-5000 3.02, the data transfer rate is 225kB/s. In order to get this drive to stream, set the blocksize to 512 bytes (mt blocksize 512) reported by Kenneth Merry ken@ulc199.residence.gatech.edu. SONY SDT-5000 327M information reported by Charles Henrich henrich@msu.edu. Reported by: &a.jmz; Tandberg TDC 3600 The boot message identifier for this drive is TANDBERG TDC 3600 =08: type 1 removable SCSI 2 This is a QIC tape drive. Native capacity is 150/250MB. This drive has quirks which are known and work around code is present in the scsi tape device driver (&man.st.4;). Upgrading the firmware to XXX version will fix the quirks and provide SCSI 2 capabilities. Data transfer rate is 80kB/s. IBM and Emerald units will not work. Replacing the firmware EPROM of these units will solve the problem. Reported by: &a.msmith; Tandberg TDC 3620 This is very similar to the Tandberg TDC 3600 drive. Reported by: &a.joerg; Tandberg TDC 3800 The boot message identifier for this drive is TANDBERG TDC 3800 =04Y Removable Sequential Access SCSI-2 device This is a QIC tape drive. Native capacity is 525MB. Reported by: &a.jhs; Tandberg TDC 4222 The boot message identifier for this drive is TANDBERG TDC 4222 =07 type 1 removable SCSI 2 This is a QIC tape drive. Native capacity is 2.5GB. The drive will read all cartridges from the 60 MB (DC600A) upwards, and write 150 MB (DC6150) upwards. Hardware compression is optionally supported for the 2.5 GB cartridges. This drives quirks are known and pre-compiled into the scsi tape device driver (&man.st.4;) beginning with FreeBSD 2.2-CURRENT. For previous versions of FreeBSD, use mt to read one block from the tape, rewind the tape, and then execute the backup program (mt fsr 1; mt rewind; dump ...) Data transfer rate is 600kB/s (vendor claim with compression), 350 KB/s can even be reached in start/stop mode. The rate decreases for smaller cartridges. Reported by: &a.joerg; Wangtek 5525ES The boot message identifier for this drive is WANGTEK 5525ES SCSI REV7 3R1 type 1 removable SCSI 1 density code 0x11, 1024-byte blocks This is a QIC tape drive. Native capacity is 525MB. Data transfer rate is 180kB/s. The drive reads 60, 120, 150, and 525MB tapes. The drive will not write 60MB (DC600 cartridge) tapes. In order to overwrite 120 and 150 tapes reliably, first erase (mt erase) the tape. 120 and 150 tapes used a wider track (fewer tracks per tape) than 525MB tapes. The extra width of the previous tracks is not overwritten, as a result the new data lies in a band surrounded on both sides by the previous data unless the tape have been erased. This drives quirks are known and pre-compiled into the scsi tape device driver (&man.st.4;). Other firmware revisions that are known to work are: M75D Reported by: Marc van Kempen marc@bowtie.nl REV73R1 Andrew Gordon Andrew.Gordon@net-tel.co.uk M75D Wangtek 6200 The boot message identifier for this drive is WANGTEK 6200-HS 4B18 type 1 removable SCSI 2 Sequential-Access density code 0x13 This is a DDS-1 tape drive. Native capacity is 2GB using 90m tapes. Data transfer rate is 150kB/s. Reported by: Tony Kimball alk@Think.COM * Problem drives CDROM drives Contributed by &a.obrien;. 23 November 1997. Generally speaking those in The FreeBSD Project prefer SCSI CDROM drives over IDE CDROM drives. However not all SCSI CDROM drives are equal. Some feel the quality of some SCSI CDROM drives have been deteriorating to that of IDE CDROM drives. Toshiba used to be the favored stand-by, but many on the SCSI mailing list have found displeasure with the 12x speed XM-5701TA as its volume (when playing audio CDROMs) is not controllable by the various audio player software. Another area where SCSI CDROM manufacturers are cutting corners is adherence to the SCSI specification. Many SCSI CDROMs will respond to multiple LUNs for its target address. Known violators include the 6x Teac CD-56S 1.0D.
\ No newline at end of file diff --git a/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml index b7a44cc989..0210d7ab45 100644 --- a/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml +++ b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.sgml @@ -1,1587 +1,1587 @@ IPv6 Internals IPv6/IPsec Implementation Contributed by &a.shin;, 5 March 2000. This section should explain IPv6 and IPsec related implementation internals. These functionalities are derived from KAME project IPv6 Conformance The IPv6 related functions conforms, or tries to conform to the latest set of IPv6 specifications. For future reference we list some of the relevant documents below (NOTE: this is not a complete list - this is too hard to maintain...). For details please refer to specific chapter in the document, RFCs, manpages, or comments in the source code. Conformance tests have been performed on the KAME STABLE kit at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/ . We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/) in the past, with our past snapshots. RFC1639: FTP Operation Over Big Address Records (FOOBAR) RFC2428 is preferred over RFC1639. FTP clients will first try RFC2428, then RFC1639 if failed. RFC1886: DNS Extensions to support IPv6 RFC1933: Transition Mechanisms for IPv6 Hosts and Routers IPv4 compatible address is not supported. automatic tunneling (described in 4.3 of this RFC) is not supported. &man.gif.4; interface implements IPv[46]-over-IPv[46] tunnel in a generic way, and it covers "configured tunnel" described in the spec. See 23.5.1.5 in this document for details. RFC1981: Path MTU Discovery for IPv6 RFC2080: RIPng for IPv6 usr.sbin/route6d support this. RFC2292: Advanced Sockets API for IPv6 For supported library functions/kernel APIs, see sys/netinet6/ADVAPI. RFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM) RFC2362 defines packet formats for PIM-SM. draft-ietf-pim-ipv6-01.txt is written based on this. RFC2373: IPv6 Addressing Architecture supports node required addresses, and conforms to the scope requirement. RFC2374: An IPv6 Aggregatable Global Unicast Address Format supports 64-bit length of Interface ID. RFC2375: IPv6 Multicast Address Assignments Userland applications use the well-known addresses assigned in the RFC. RFC2428: FTP Extensions for IPv6 and NATs RFC2428 is preferred over RFC1639. FTP clients will first try RFC2428, then RFC1639 if failed. RFC2460: IPv6 specification RFC2461: Neighbor discovery for IPv6 See 23.5.1.2 in this document for details. RFC2462: IPv6 Stateless Address Autoconfiguration See 23.5.1.4 in this document for details. RFC2463: ICMPv6 for IPv6 specification See 23.5.1.9 in this document for details. RFC2464: Transmission of IPv6 Packets over Ethernet Networks RFC2465: MIB for IPv6: Textual Conventions and General Group Necessary statistics are gathered by the kernel. Actual IPv6 MIB support is provided as a patchkit for ucd-snmp. RFC2466: MIB for IPv6: ICMPv6 group Necessary statistics are gathered by the kernel. Actual IPv6 MIB support is provided as patchkit for ucd-snmp. RFC2467: Transmission of IPv6 Packets over FDDI Networks RFC2497: Transmission of IPv6 packet over ARCnet Networks RFC2553: Basic Socket Interface Extensions for IPv6 IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind socket (3.8) are supported. See 23.5.1.12 in this document for details. RFC2675: IPv6 Jumbograms See 23.5.1.7 in this document for details. RFC2710: Multicast Listener Discovery for IPv6 RFC2711: IPv6 router alert option draft-ietf-ipngwg-router-renum-08: Router renumbering for IPv6 draft-ietf-ipngwg-icmp-namelookups-02: IPv6 Name Lookups Through ICMP draft-ietf-ipngwg-icmp-name-lookups-03: IPv6 Name Lookups Through ICMP draft-ietf-pim-ipv6-01.txt: PIM for IPv6 &man.pim6dd.8; implements dense mode. &man.pim6sd.8; implements sparse mode. draft-itojun-ipv6-tcp-to-anycast-00: Disconnecting TCP connection toward IPv6 anycast address draft-yamamoto-wideipv6-comm-model-00 See 23.5.1.6 in this document for details. draft-ietf-ipngwg-scopedaddr-format-00.txt : An Extension of Format for IPv6 Scoped Addresses Neighbor Discovery Neighbor Discovery is fairly stable. Currently Address Resolution, Duplicated Address Detection, and Neighbor Unreachability Detection are supported. In the near future we will be adding Proxy Neighbor Advertisement support in the kernel and Unsolicited Neighbor Advertisement transmission command as admin tool. If DAD fails, the address will be marked "duplicated" and message will be generated to syslog (and usually to console). The "duplicated" mark can be checked with &man.ifconfig.8;. It is administrators' responsibility to check for and recover from DAD failures. The behavior should be improved in the near future. Some of the network driver loops multicast packets back to itself, even if instructed not to do so (especially in promiscuous mode). In such cases DAD may fail, because DAD engine sees inbound NS packet (actually from the node itself) and considers it as a sign of duplicate. You may want to look at #if condition marked "heuristics" in sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code fragment in "heuristics" section is not spec conformant). Neighbor Discovery specification (RFC2461) does not talk about neighbor cache handling in the following cases: when there was no neighbor cache entry, node received unsolicited RS/NS/NA/redirect packet without link-layer address neighbor cache handling on medium without link-layer address (we need a neighbor cache entry for IsRouter bit) For first case, we implemented workaround based on discussions on IETF ipngwg mailing list. For more details, see the comments in the source code and email thread started from (IPng 7155), dated Feb 6 1999. IPv6 on-link determination rule (RFC2461) is quite different from assumptions in BSD network code. At this moment, no on-link determination rule is supported where default router list is empty (RFC2461, section 5.2, last sentence in 2nd paragraph - note that the spec misuse the word "host" and "node" in several places in the section). To avoid possible DoS attacks and infinite loops, only 10 options on ND packet is accepted now. Therefore, if you have 20 prefix options attached to RA, only the first 10 prefixes will be recognized. If this troubles you, please ask it on FREEBSD-CURRENT mailing list and/or modify nd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may provide sysctl knob for the variable. Scope Index IPv6 uses scoped addresses. Therefore, it is very important to specify scope index (interface index for link-local address, or site index for site-local address) with an IPv6 address. Without scope index, scoped IPv6 address is ambiguous to the kernel, and kernel will not be able to determine the outbound interface for a packet. Ordinary userland applications should use advanced API (RFC2292) to specify scope index, or interface index. For similar purpose, sin6_scope_id member in sockaddr_in6 structure is defined in RFC2553. However, the semantics for sin6_scope_id is rather vague. If you care about portability of your application, we suggest you to use advanced API rather than sin6_scope_id. In the kernel, an interface index for link-local scoped address is embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address. For example, you may see something like: fe80:1::200:f8ff:fe01:6317 in the routing table and interface address structure (struct in6_ifaddr). The address above is a link-local unicast address which belongs to a network interface whose interface identifier is 1. The embedded index enables us to identify IPv6 link local addresses over multiple interfaces effectively and with only a little code change. Routing daemons and configuration programs, like &man.route6d.8; and &man.ifconfig.8;, will need to manipulate the "embedded" scope index. These programs use routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API will return IPv6 addresses with 2nd 16bit-word filled in. The APIs are for manipulating kernel internal structure. Programs that use these APIs have to be prepared about differences in kernels anyway. When you specify scoped address to the command line, NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc). This is not supposed to work. Always use standard form, like ff02::1 or fe80::fedc, with command line option for specifying interface (like ping6 -I ne0 ff02::1). In general, if a command does not have command line option to specify outgoing interface, that command is not ready to accept scoped address. This may seem to be opposite from IPv6's premise to support "dentist office" situation. We believe that specifications need some improvements for this. Some of the userland tools support extended numeric IPv6 syntax, as documented in draft-ietf-ipngwg-scopedaddr-format-00.txt. You can specify outgoing link, by using name of the outgoing interface like "fe80::1%ne0". This way you will be able to specify link-local scoped address without much trouble. To use this extension in your program, you'll need to use &man.getaddrinfo.3;, and &man.getnameinfo.3; with NI_WITHSCOPEID. The implementation currently assumes 1-to-1 relationship between a link and an interface, which is stronger than what specs say. Plug and Play Most of the IPv6 stateless address autoconfiguration is implemented in the kernel. Neighbor Discovery functions are implemented in the kernel as a whole. Router Advertisement (RA) input for hosts is implemented in the kernel. Router Solicitation (RS) output for endhosts, RS input for routers, and RA output for routers are implemented in the userland. Assignment of link-local, and special addresses IPv6 link-local address is generated from IEEE802 address - (ethernet MAC address). Each of interface is assigned an IPv6 + (Ethernet MAC address). Each of interface is assigned an IPv6 link-local address automatically, when the interface becomes up (IFF_UP). Also, direct route for the link-local address is added to routing table. Here is an output of netstat command: Internet6: Destination Gateway Flags Netif Expire fe80:1::%ed0/64 link#1 UC ed0 fe80:2::%ep0/64 link#2 UC ep0 Interfaces that has no IEEE802 address (pseudo interfaces like tunnel interfaces, or ppp interfaces) will borrow IEEE802 - address from other interfaces, such as ethernet interfaces, + address from other interfaces, such as Ethernet interfaces, whenever possible. If there is no IEEE802 hardware attached, last-resort pseudorandom value, which is from MD5(hostname), will be used as source of link-local address. If it is not suitable for your usage, you will need to configure the link-local address manually. If an interface is not capable of handling IPv6 (such as lack of multicast support), link-local address will not be assigned to that interface. See section 2 for details. Each interface joins the solicited multicast address and the link-local all-nodes multicast addresses (e.g. fe80::1:ff01:6317 and ff02::1, respectively, on the link the interface is attached). In addition to a link-local address, the loopback address (::1) will be assigned to the loopback interface. Also, ::1/128 and ff01::/32 are automatically added to routing table, and loopback interface joins node-local multicast group ff01::1. Stateless address autoconfiguration on hosts In IPv6 specification, nodes are separated into two categories: routers and hosts. Routers forward packets addressed to others, hosts does not forward the packets. net.inet6.ip6.forwarding defines whether this node is router or host (router if it is 1, host if it is 0). When a host hears Router Advertisement from the router, a host may autoconfigure itself by stateless address autoconfiguration. This behavior can be controlled by net.inet6.ip6.accept_rtadv (host autoconfigures itself if it is set to 1). By autoconfiguration, network address prefix for the receiving interface (usually global address prefix) is added. Default route is also configured. Routers periodically generate Router Advertisement packets. To request an adjacent router to generate RA packet, a host can transmit Router Solicitation. To generate a RS packet at any time, use the rtsol command. &man.rtsold.8; daemon is also available. &man.rtsold.8; generates Router Solicitation whenever necessary, and it works great for nomadic usage (notebooks/laptops). If one wishes to ignore Router Advertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0. To generate Router Advertisement from a router, use the &man.rtadvd.8 daemon. Note that, IPv6 specification assumes the following items, and nonconforming cases are left unspecified: Only hosts will listen to router advertisements Hosts have single network interface (except loopback) Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv on routers, or multi-interface host. A misconfigured node can behave strange (nonconforming configuration allowed for those who would like to do some experiments). To summarize the sysctl knob: accept_rtadv forwarding role of the node --- --- --- 0 0 host (to be manually configured) 0 1 router 1 0 autoconfigured host (spec assumes that host has single interface only, autoconfigured host with multiple interface is out-of-scope) 1 1 invalid, or experimental (out-of-scope of spec) RFC2462 has validation rule against incoming RA prefix information option, in 5.5.3 (e). This is to protect hosts from malicious (or misconfigured) routers that advertise very short prefix lifetime. There was an update from Jim Bound to ipngwg mailing list (look for "(ipng 6712)" in the archive) and it is implemented Jim's update. See 23.5.1.2 in the document for relationship between DAD and autoconfiguration. Generic tunnel interface GIF (Generic InterFace) is a pseudo interface for configured tunnel. Details are described in &man.gif.4;. Currently v6 in v6 v6 in v4 v4 in v6 v4 in v4 are available. Use &man.gifconfig.8; to assign physical (outer) source and destination address to gif interfaces. Configuration that uses same address family for inner and outer IP header (v4 in v4, or v6 in v6) is dangerous. It is very easy to configure interfaces and routing tables to perform infinite level of tunneling. Please be warned. gif can be configured to be ECN-friendly. See 23.5.4.5 for ECN-friendliness of tunnels, and &man.gif.4; for how to configure. If you would like to configure an IPv4-in-IPv6 tunnel with gif interface, read &man.gif.4; carefully. You will need to remove IPv6 link-local address automatically assigned to the gif interface. Source Address Selection Current source selection rule is scope oriented (there are some exceptions - see below). For a given destination, a source IPv6 address is selected by the following rule: If the source address is explicitly specified by the user (e.g. via the advanced API), the specified address is used. If there is an address assigned to the outgoing interface (which is usually determined by looking up the routing table) that has the same scope as the destination address, the address is used. This is the most typical case. If there is no address that satisfies the above condition, choose a global address assigned to one of the interfaces on the sending node. If there is no address that satisfies the above condition, and destination address is site local scope, choose a site local address assigned to one of the interfaces on the sending node. If there is no address that satisfies the above condition, choose the address associated with the routing table entry for the destination. This is the last resort, which may cause scope violation. For instance, ::1 is selected for ff01::1, fe80:1::200:f8ff:fe01:6317 for fe80:1::2a0:24ff:feab:839b (note that embedded interface index - described in 23.5.1.3 - helps us choose the right source address. Those embedded indices will not be on the wire). If the outgoing interface has multiple address for the scope, a source is selected longest match basis (rule 3). Suppose 3ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317 are given to the outgoing interface. 3ffe:501:808:1:200:f8ff:fe01:6317 is chosen as the source for the destination 3ffe:501:800::1. Note that the above rule is not documented in the IPv6 spec. It is considered "up to implementation" item. There are some cases where we do not use the above rule. One example is connected TCP session, and we use the address kept in tcb as the source. Another example is source address for Neighbor Advertisement. Under the spec (RFC2461 7.2.2) NA's source should be the target address of the corresponding NS's target. In this case we follow the spec rather than the above longest-match rule. For new connections (when rule 1 does not apply), deprecated addresses (addresses with preferred lifetime = 0) will not be chosen as source address if other choices are available. If no other choices are available, deprecated address will be used as a last resort. If there are multiple choice of deprecated addresses, the above scope rule will be used to choose from those deprecated addresses. If you would like to prohibit the use of deprecated address for some reason, configure net.inet6.ip6.use_deprecated to 0. The issue related to deprecated address is described in RFC2462 5.5.4 (NOTE: there is some debate underway in IETF ipngwg on how to use "deprecated" address). Jumbo Payload The Jumbo Payload hop-by-hop option is implemented and can be used to send IPv6 packets with payloads longer than 65,535 octets. But currently no physical interface whose MTU is more than 65,535 is supported, so such payloads can be seen only on the loopback interface (i.e. lo0). If you want to try jumbo payloads, you first have to reconfigure the kernel so that the MTU of the loopback interface is more than 65,535 bytes; add the following to the kernel configuration file: options "LARGE_LOMTU" #To test jumbo payload and recompile the new kernel. Then you can test jumbo payloads by the &man.ping6.8; command with -b and -s options. The -b option must be specified to enlarge the size of the socket buffer and the -s option specifies the length of the packet, which should be more than 65,535. For example, type as follows: &prompt.user; ping6 -b 70000 -s 68000 ::1 The IPv6 specification requires that the Jumbo Payload option must not be used in a packet that carries a fragment header. If this condition is broken, an ICMPv6 Parameter Problem message must be sent to the sender. specification is followed, but you cannot usually see an ICMPv6 error caused by this requirement. When an IPv6 packet is received, the frame length is checked and compared to the length specified in the payload length field of the IPv6 header or in the value of the Jumbo Payload option, if any. If the former is shorter than the latter, the packet is discarded and statistics are incremented. You can see the statistics as output of &man.netstat.8; command with `-s -p ip6' option: &prompt.user; netstat -s -p ip6 ip6: (snip) 1 with data size < data length So, kernel does not send an ICMPv6 error unless the erroneous packet is an actual Jumbo Payload, that is, its packet size is more than 65,535 bytes. As described above, currently no physical interface with such a huge MTU is supported, so it rarely returns an ICMPv6 error. TCP/UDP over jumbogram is not supported at this moment. This is because we have no medium (other than loopback) to test this. Contact us if you need this. IPsec does not work on jumbograms. This is due to some specification twists in supporting AH with jumbograms (AH header size influences payload length, and this makes it real hard to authenticate inbound packet with jumbo payload option as well as AH). There are fundamental issues in *BSD support for jumbograms. We would like to address those, but we need more time to finalize these. To name a few: mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it will not hold jumbogram with len > 2G on 32bit architecture CPUs. If we would like to support jumbogram properly, the field must be expanded to hold 4G + IPv6 header + link-layer header. Therefore, it must be expanded to at least int64_t (u_int32_t is NOT enough). We mistakingly use "int" to hold packet length in many places. We need to convert them into larger integral type. It needs a great care, as we may experience overflow during packet length computation. We mistakingly check for ip6_plen field of IPv6 header for packet payload length in various places. We should be checking mbuf pkthdr.len instead. ip6_input() will perform sanity check on jumbo payload option on input, and we can safely use mbuf pkthdr.len afterwards. TCP code needs a careful update in bunch of places, of course. Loop prevention in header processing IPv6 specification allows arbitrary number of extension headers to be placed onto packets. If we implement IPv6 packet processing code in the way BSD IPv4 code is implemented, kernel stack may overflow due to long function call chain. sys/netinet6 code is carefully designed to avoid kernel stack overflow. Because of this, sys/netinet6 code defines its own protocol switch structure, as "struct ip6protosw" (see netinet6/ip6protosw.h). There is no such update to IPv4 part (sys/netinet) for compatibility, but small change is added to its pr_input() prototype. So "struct ipprotosw" is also defined. Because of this, if you receive IPsec-over-IPv4 packet with massive number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay. (Off-course, for those all IPsec headers to be processed, each such IPsec header must pass each IPsec check. So an anonymous attacker won't be able to do such an attack.) ICMPv6 After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium. This is already implemented into the kernel. Applications For userland programming, we support IPv6 socket API as specified in RFC2553, RFC2292 and upcoming Internet drafts. TCP/UDP over IPv6 is available and quite stable. You can enjoy &man.telnet.1;, &man.ftp.1;, &man.rlogin.1;, &man.rsh.1;, &man.ssh.1, etc. These applications are protocol independent. That is, they automatically chooses IPv4 or IPv6 according to DNS. Kernel Internals While ip_forward() calls ip_output(), ip6_forward() directly calls if_output() since routers must not divide IPv6 packets into fragments. ICMPv6 should contain the original packet as long as possible up to 1280. UDP6/IP6 port unreach, for instance, should contain all extension headers and the *unchanged* UDP6 and IP6 headers. So, all IP6 functions except TCP never convert network byte order into host byte order, to save the original packet. tcp_input(), udp6_input() and icmp6_input() can't assume that IP6 header is preceding the transport headers due to extension headers. So, in6_cksum() was implemented to handle packets whose IP6 header and transport header is not continuous. TCP/IP6 nor UDP6/IP6 header structure don't exist for checksum calculation. To process IP6 header, extension headers and transport headers easily, network drivers are now required to store packets in one internal mbuf or one or more external mbufs. A typical old driver prepares two internal mbufs for 96 - 204 bytes data, however, now such packet data is stored in one external mbuf. netstat -s -p ip6 tells you whether or not your driver conforms such requirement. In the following example, "cce0" violates the requirement. (For more information, refer to Section 2.) Mbuf statistics: 317 one mbuf two or more mbuf:: lo0 = 8 cce0 = 10 3282 one ext mbuf 0 two or more ext mbuf Each input function calls IP6_EXTHDR_CHECK in the beginning to check if the region between IP6 and its header is continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has M_LOOP flag, that is, the packet comes from the loopback interface. m_pullup() is never called for packets coming from physical network interfaces. Both IP and IP6 reassemble functions never call m_pullup(). IPv4 mapped address and IPv6 wildcard socket RFC2553 describes IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind socket (3.8). The spec allows you to: Accept IPv4 connections by AF_INET6 wildcard bind socket. Transmit IPv4 packet over AF_INET6 socket by using special form of the address like ::ffff:10.1.1.1. but the spec itself is very complicated and does not specify how the socket layer should behave. Here we call the former one "listening side" and the latter one "initiating side", for reference purposes. You can perform wildcard bind on both of the address families, on the same port. The following table show the behavior of FreeBSD 4.x. listening side initiating side (AF_INET6 wildcard (connection to ::ffff:10.1.1.1) socket gets IPv4 conn.) --- --- FreeBSD 4.x configurable supported default: enabled The following sections will give you more details, and how you can configure the behavior. Comments on listening side: It looks that RFC2553 talks too little on wildcard bind issue, especially on the port space issue, failure mode and relationship between AF_INET/INET6 wildcard bind. There can be several separate interpretation for this RFC which conform to it but behaves differently. So, to implement portable application you should assume nothing about the behavior in the kernel. Using &man.getaddrinfo.3; is the safest way. Port number space and wildcard bind issues were discussed in detail on ipv6imp mailing list, in mid March 1999 and it looks that there's no concrete consensus (means, up to implementers). You may want to check the mailing list archives. If a server application would like to accept IPv4 and IPv6 connections, there will be two alternatives. One is using AF_INET and AF_INET6 socket (you'll need two sockets). Use &man.getaddrinfo.3; with AI_PASSIVE into ai_flags, and &man.socket.2; and &man.bind.2; to all the addresses returned. By opening multiple sockets, you can accept connections onto the socket with proper address family. IPv4 connections will be accepted by AF_INET socket, and IPv6 connections will be accepted by AF_INET6 socket. Another way is using one AF_INET6 wildcard bind socket. Use &man.getaddrinfo.3; with AI_PASSIVE into ai_flags and with AF_INET6 into ai_family, and set the 1st argument hostname to NULL. And &man.socket.2; and &man.bind.2; to the address returned. (should be IPv6 unspecified addr). You can accept either of IPv4 and IPv6 packet via this one socket. To support only IPv6 traffic on AF_INET6 wildcard binded socket portably, always check the peer address when a connection is made toward AF_INET6 listening socket. If the address is IPv4 mapped address, you may want to reject the connection. You can check the condition by using IN6_IS_ADDR_V4MAPPED() macro. To resolve this issue more easily, there is system dependent &man.setsockopt.2; option, IPV6_BINDV6ONLY, used like below. int on; setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY, (char *)&on, sizeof (on)) < 0)); When this call succeed, then this socket only receive IPv6 packets. Comments on initiating side: Advise to application implementers: to implement a portable IPv6 application (which works on multiple IPv6 kernels), we believe that the following is the key to the success: NEVER hardcode AF_INET nor AF_INET6. Use &man.getaddrinfo.3; and &man.getnameinfo.3; throughout the system. Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*(). (To update existing applications to be IPv6 aware easily, sometime getipnodeby*() will be useful. But if possible, try to rewrite the code to use &man.getaddrinfo.3; and &man.getnameinfo.3;.) If you would like to connect to destination, use &man.getaddrinfo.3; and try all the destination returned, like &man.telnet.1; does. Some of the IPv6 stack is shipped with buggy &man.getaddrinfo.3;. Ship a minimal working version with your application and use that as last resort. If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing connection, you will need to use &man.getipnodebyname.3;. When you would like to update your existing application to be IPv6 aware with minimal effort, this approach might be chosen. But please note that it is a temporal solution, because &man.getipnodebyname.3; itself is not recommended as it does not handle scoped IPv6 addresses at all. For IPv6 name resolution, &man.getaddrinfo.3; is the preferred API. So you should rewrite your application to use &man.getaddrinfo.3;, when you get the time to do it. When writing applications that make outgoing connections, story goes much simpler if you treat AF_INET and AF_INET6 as totally separate address family. {set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do not recommend you to rely upon IPv4 mapped address. unified tcp and inpcb code FreeBSD 4.x uses shared tcp code between IPv4 and IPv6 (from sys/netinet/tcp*) and separate udp4/6 code. It uses unified inpcb structure. The platform can be configured to support IPv4 mapped address. Kernel configuration is summarized as follows: By default, AF_INET6 socket will grab IPv4 connections in certain condition, and can initiate connection to IPv4 destination embedded in IPv4 mapped IPv6 address. You can disable it on entire system with sysctl like below. sysctl -w net.inet6.ip6.mapped_addr=0 listening side Each socket can be configured to support special AF_INET6 wildcard bind (enabled by default). You can disable it on each socket basis with &man.setsockopt.2; like below. int on; setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY, (char *)&on, sizeof (on)) < 0)); Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following conditions are satisfied: there's no AF_INET socket that matches the IPv4 connection the AF_INET6 socket is configured to accept IPv4 traffic, i.e. getsockopt(IPV6_BINDV6ONLY) returns 0. There's no problem with open/close ordering. initiating side FreeBSD 4.x supports outgoing connection to IPv4 mapped address (::ffff:10.1.1.1), if the node is configured to support IPv4 mapped address. sockaddr_storage When RFC2553 was about to be finalized, there was discussion on how struct sockaddr_storage members are named. One proposal is to prepend "__" to the members (like "__ss_len") as they should not be touched. The other proposal was that don't prepend it (like "ss_len") as we need to touch those members directly. There was no clear consensus on it. As a result, RFC2553 defines struct sockaddr_storage as follows: struct sockaddr_storage { u_char __ss_len; /* address length */ u_char __ss_family; /* address family */ /* and bunch of padding */ }; On the contrary, XNET draft defines as follows: struct sockaddr_storage { u_char ss_len; /* address length */ u_char ss_family; /* address family */ /* and bunch of padding */ }; In December 1999, it was agreed that RFC2553bis should pick the latter (XNET) definition. Current implementation conforms to XNET definition, based on RFC2553bis discussion. If you look at multiple IPv6 implementations, you will be able to see both definitions. As an userland programmer, the most portable way of dealing with it is to: ensure ss_family and/or ss_len are available on the platform, by using GNU autoconf, have -Dss_family=__ss_family to unify all occurrences (including header file) into __ss_family, or never touch __ss_family. cast to sockaddr * and use sa_family like: struct sockaddr_storage ss; family = ((struct sockaddr *)&ss)->sa_family Network Drivers Now following two items are required to be supported by standard drivers: mbuf clustering requirement. In this stable release, we changed MINCLSIZE into MHLEN+1 for all the operating systems in order to make all the drivers behave as we expect. multicast. If &man.ifmcstat.8; yields no multicast group for a interface, that interface has to be patched. If any of the driver don't support the requirements, then the driver can't be used for IPv6 and/or IPsec communication. If you find any problem with your card using IPv6/IPsec, then, please report it to freebsd-bugs@FreeBSD.org. (NOTE: In the past we required all PCMCIA drivers to have a call to in6_ifattach(). We have no such requirement any more) Translator We categorize IPv4/IPv6 translator into 4 types: Translator A --- It is used in the early stage of transition to make it possible to establish a connection from an IPv6 host in an IPv6 island to an IPv4 host in the IPv4 ocean. Translator B --- It is used in the early stage of transition to make it possible to establish a connection from an IPv4 host in the IPv4 ocean to an IPv6 host in an IPv6 island. Translator C --- It is used in the late stage of transition to make it possible to establish a connection from an IPv4 host in an IPv4 island to an IPv6 host in the IPv6 ocean. Translator D --- It is used in the late stage of transition to make it possible to establish a connection from an IPv6 host in the IPv6 ocean to an IPv4 host in an IPv4 island. TCP relay translator for category A is supported. This is called "FAITH". We also provide IP header translator for category A. (The latter is not yet put into FreeBSD 4.x yet.) FAITH TCP relay translator FAITH system uses TCP relay daemon called &man.faithd.8; helped by the kernel. FAITH will reserve an IPv6 address prefix, and relay TCP connection toward that prefix to IPv4 destination. For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and the IPv6 destination for TCP connection is 3ffe:0501:0200:ffff::163.221.202.12, the connection will be relayed toward IPv4 destination 163.221.202.12. destination IPv4 node (163.221.202.12) ^ | IPv4 tcp toward 163.221.202.12 FAITH-relay dual stack node ^ | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12 source IPv6 node &man.faithd.8; must be invoked on FAITH-relay dual stack node. For more details, consult src/usr.sbin/faithd/README IPsec IPsec is mainly organized by three components. Policy Management Key Management AH and ESP handling Policy Management The kernel implements experimental policy management code. There are two way to manage security policy. One is to configure per-socket policy using &man.setsockopt.2;. In this cases, policy configuration is described in &man.ipsec.set.policy.3;. The other is to configure kernel packet filter-based policy using PF_KEY interface, via &man.setkey.8;. The policy entry is not re-ordered with its indexes, so the order of entry when you add is very significant. Key Management The key management code implemented in this kit (sys/netkey) is a home-brew PFKEY v2 implementation. This conforms to RFC2367. The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon). Basically you'll need to run racoon as daemon, then setup a policy to require keys (like ping -P 'out ipsec esp/transport//use'). The kernel will contact racoon daemon as necessary to exchange keys. AH and ESP handling IPsec module is implemented as "hooks" to the standard IPv4/IPv6 processing. When sending a packet, ip{,6}_output() checks if ESP/AH processing is required by checking if a matching SPD (Security Policy Database) is found. If ESP/AH is needed, {esp,ah}{4,6}_output() will be called and mbuf will be updated accordingly. When a packet is received, {esp,ah}4_input() will be called based on protocol number, i.e. (*inetsw[proto])(). {esp,ah}4_input() will decrypt/check authenticity of the packet, and strips off daisy-chained header and padding for ESP/AH. It is safe to strip off the ESP/AH header on packet reception, since we will never use the received packet in "as is" form. By using ESP/AH, TCP4/6 effective data segment size will be affected by extra daisy-chained headers inserted by ESP/AH. Our code takes care of the case. Basic crypto functions can be found in directory "sys/crypto". ESP/AH transform are listed in {esp,ah}_core.c with wrapper functions. If you wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and add your crypto algorithm code into sys/crypto. Tunnel mode is partially supported in this release, with the following restrictions: IPsec tunnel is not combined with GIF generic tunneling interface. It needs a great care because we may create an infinite loop between ip_output() and tunnelifp->if_output(). Opinion varies if it is better to unify them, or not. MTU and Don't Fragment bit (IPv4) considerations need more checking, but basically works fine. Authentication model for AH tunnel must be revisited. We'll need to improve the policy management engine, eventually. Conformance to RFCs and IDs The IPsec code in the kernel conforms (or, tries to conform) to the following standards: "old IPsec" specification documented in rfc182[5-9].txt "new IPsec" specification documented in rfc240[1-6].txt, rfc241[01].txt, rfc2451.txt and draft-mcdonald-simple-ipsec-api-01.txt (draft expired, but you can take from ftp://ftp.kame.net/pub/internet-drafts/). (NOTE: IKE specifications, rfc241[7-9].txt are implemented in userland, as "racoon" IKE daemon) Currently supported algorithms are: old IPsec AH null crypto checksum (no document, just for debugging) keyed MD5 with 128bit crypto checksum (rfc1828.txt) keyed SHA1 with 128bit crypto checksum (no document) HMAC MD5 with 128bit crypto checksum (rfc2085.txt) HMAC SHA1 with 128bit crypto checksum (no document) old IPsec ESP null encryption (no document, similar to rfc2410.txt) DES-CBC mode (rfc1829.txt) new IPsec AH null crypto checksum (no document, just for debugging) keyed MD5 with 96bit crypto checksum (no document) keyed SHA1 with 96bit crypto checksum (no document) HMAC MD5 with 96bit crypto checksum (rfc2403.txt) HMAC SHA1 with 96bit crypto checksum (rfc2404.txt) new IPsec ESP null encryption (rfc2410.txt) DES-CBC with derived IV (draft-ietf-ipsec-ciph-des-derived-01.txt, draft expired) DES-CBC with explicit IV (rfc2405.txt) 3DES-CBC with explicit IV (rfc2451.txt) BLOWFISH CBC (rfc2451.txt) CAST128 CBC (rfc2451.txt) RC5 CBC (rfc2451.txt) each of the above can be combined with: ESP authentication with HMAC-MD5(96bit) ESP authentication with HMAC-SHA1(96bit) The following algorithms are NOT supported: old IPsec AH HMAC MD5 with 128bit crypto checksum + 64bit replay prevention (rfc2085.txt) keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt) IPsec (in kernel) and IKE (in userland as "racoon") has been tested at several interoperability test events, and it is known to interoperate with many other implementations well. Also, current IPsec implementation as quite wide coverage for IPsec crypto algorithms documented in RFC (we cover algorithms without intellectual property issues only). ECN consideration on IPsec tunnels ECN-friendly IPsec tunnel is supported as described in draft-ipsec-ecn-00.txt. Normal IPsec tunnel is described in RFC2401. On encapsulation, IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner IP header to outer IP header. On decapsulation outer IP header will be simply dropped. The decapsulation rule is not compatible with ECN, since ECN bit on the outer IP TOS/traffic class field will be lost. To make IPsec tunnel ECN-friendly, we should modify encapsulation and decapsulation procedure. This is described in http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt, chapter 3. IPsec tunnel implementation can give you three behaviors, by setting net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value: RFC2401: no consideration for ECN (sysctl value -1) ECN forbidden (sysctl value 0) ECN allowed (sysctl value 1) Note that the behavior is configurable in per-node manner, not per-SA manner (draft-ipsec-ecn-00 wants per-SA configuration, but it looks too much for me). The behavior is summarized as follows (see source code for more detail): encapsulate decapsulate --- --- RFC2401 copy all TOS bits drop TOS bits on outer from inner to outer. (use inner TOS bits as is) ECN forbidden copy TOS bits except for ECN drop TOS bits on outer (masked with 0xfc) from inner (use inner TOS bits as is) to outer. set ECN bits to 0. ECN allowed copy TOS bits except for ECN use inner TOS bits with some CE (masked with 0xfe) from change. if outer ECN CE bit inner to outer. is 1, enable ECN CE bit on set ECN CE bit to 0. the inner. General strategy for configuration is as follows: if both IPsec tunnel endpoint are capable of ECN-friendly behavior, you'd better configure both end to "ECN allowed" (sysctl value 1). if the other end is very strict about TOS bit, use "RFC2401" (sysctl value -1). in other cases, use "ECN forbidden" (sysctl value 0). The default behavior is "ECN forbidden" (sysctl value 0). For more information, please refer to: http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt, RFC2481 (Explicit Congestion Notification), src/sys/netinet6/{ah,esp}_input.c (Thanks goes to Kenjiro Cho kjc@csl.sony.co.jp for detailed analysis) Interoperability Here are (some of) platforms that KAME code have tested IPsec/IKE interoperability in the past. Note that both ends may have modified their implementation, so use the following list just for reference purposes. Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure), Ericsson ACC, FreeS/WAN, HITACHI, IBM AIX, IIJ, Intel, Microsoft WinNT, NIST (linux IPsec + plutoplus), Netscreen, OpenBSD, RedCreek, Routerware, SSH, Secure Computing, Soliton, Toshiba, VPNet, Yamaha RT100i diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml index 360a37c5db..69d33b26be 100644 --- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml +++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml @@ -1,400 +1,400 @@ Source Tree Guidelines and Policies Contributed by &a.phk;. This chapter documents various guidelines and policies in force for the FreeBSD source tree. <makevar>MAINTAINER</makevar> on Makefiles ports maintainer June 1996. If a particular portion of the FreeBSD distribution is being maintained by a person or group of persons, they can communicate this fact to the world by adding a MAINTAINER= email-addresses line to the Makefiles covering this portion of the source tree. The semantics of this are as follows: The maintainer owns and is responsible for that code. This means that he is responsible for fixing bugs and answer problem reports pertaining to that piece of the code, and in the case of contributed software, for tracking new versions, as appropriate. Changes to directories which have a maintainer defined shall be sent to the maintainer for review before being committed. Only if the maintainer does not respond for an unacceptable period of time, to several emails, will it be acceptable to commit changes without review by the maintainer. However, it is suggested that you try and have the changes reviewed by someone else if at all possible. It is of course not acceptable to add a person or group as maintainer unless they agree to assume this duty. On the other hand it doesn't have to be a committer and it can easily be a group of people. Contributed Software contributed software Contributed by &a.phk; and &a.obrien;. June 1996. Some parts of the FreeBSD distribution consist of software that is actively being maintained outside the FreeBSD project. For historical reasons, we call this contributed software. Some examples are perl, gcc and patch. Over the last couple of years, various methods have been used in dealing with this type of software and all have some number of advantages and drawbacks. No clear winner has emerged. Since this is the case, after some debate one of these methods has been selected as the official method and will be required for future imports of software of this kind. Furthermore, it is strongly suggested that existing contributed software converge on this model over time, as it has significant advantages over the old method, including the ability to easily obtain diffs relative to the official versions of the source by everyone (even without cvs access). This will make it significantly easier to return changes to the primary developers of the contributed software. Ultimately, however, it comes down to the people actually doing the work. If using this model is particularly unsuited to the package being dealt with, exceptions to these rules may be granted only with the approval of the core team and with the general consensus of the other developers. The ability to maintain the package in the future will be a key issue in the decisions. Because of some unfortunate design limitations with the RCS file format and CVS's use of vendor branches, minor, trivial and/or cosmetic changes are strongly discouraged on files that are still tracking the vendor branch. Spelling fixes are explicitly included here under the cosmetic category and are to be avoided for files with revision 1.1.x.x. The repository bloat impact from a single character change can be rather dramatic. - The TCL embedded programming + The Tcl embedded programming language will be used as example of how this model works: src/contrib/tcl contains the source as distributed by the maintainers of this package. Parts that are entirely not applicable for FreeBSD can be removed. In the case of Tcl, the mac, win and compat subdirectories were eliminated before the import src/lib/libtcl contains only a "bmake style" Makefile that uses the standard bsd.lib.mk makefile rules to produce the library and install the documentation. src/usr.bin/tclsh contains only a bmake style Makefile which will produce and install the tclsh program and its associated man-pages using the standard bsd.prog.mk rules. src/tools/tools/tcl_bmake contains a couple of shell-scripts that can be of help when the tcl software needs updating. These are not part of the built or installed software. The important thing here is that the src/contrib/tcl directory is created according to the rules: It is supposed to contain the sources as distributed (on a proper CVS vendor-branch and without RCS keyword expansion) with as few FreeBSD-specific changes as possible. The 'easy-import' tool on freefall will assist in doing the import, but if there are any doubts on how to go about it, it is imperative that you ask first and not blunder ahead and hope it works out. CVS is not forgiving of import accidents and a fair amount of effort is required to back out major mistakes. Because of the previously mentioned design limitations with CVS's vendor branches, it is required that official patches from the vendor be applied to the original distributed sources and the result re-imported onto the vendor branch again. Official patches should never be patched into the FreeBSD checked out version and "committed", as this destroys the vendor branch coherency and makes importing future versions rather difficult as there will be conflicts. Since many packages contain files that are meant for compatibility with other architectures and environments that FreeBSD, it is permissible to remove parts of the distribution tree that are of no interest to FreeBSD in order to save space. Files containing copyright notices and release-note kind of information applicable to the remaining files shall not be removed. If it seems easier, the bmake Makefiles can be produced from the dist tree automatically by some utility, something which would hopefully make it even easier to upgrade to a new version. If this is done, be sure to check in such utilities (as necessary) in the src/tools directory along with the port itself so that it is available to future maintainers. In the src/contrib/tcl level directory, a file called FREEBSD-upgrade should be added and it should states things like: Which files have been left out Where the original distribution was obtained from and/or the official master site. Where to send patches back to the original authors Perhaps an overview of the FreeBSD-specific changes that have been made. However, please do not import FREEBSD-upgrade with the contributed source. Rather you should cvs add FREEBSD-upgrade ; cvs ci after the initial import. Example wording from src/contrib/cpio is below: This directory contains virgin sources of the original distribution files on a "vendor" branch. Do not, under any circumstances, attempt to upgrade the files in this directory via patches and a cvs commit. New versions or official-patch versions must be imported. Please remember to import with "-ko" to prevent CVS from corrupting any vendor RCS Ids. For the import of GNU cpio 2.4.2, the following files were removed: INSTALL cpio.info mkdir.c Makefile.in cpio.texi mkinstalldirs To upgrade to a newer version of cpio, when it is available: 1. Unpack the new version into an empty directory. [Do not make ANY changes to the files.] 2. Remove the files listed above and any others that don't apply to FreeBSD. 3. Use the command: cvs import -ko -m 'Virgin import of GNU cpio v<version>' \ src/contrib/cpio GNU cpio_<version> For example, to do the import of version 2.4.2, I typed: cvs import -ko -m 'Virgin import of GNU v2.4.2' \ src/contrib/cpio GNU cpio_2_4_2 4. Follow the instructions printed out in step 3 to resolve any conflicts between local FreeBSD changes and the newer version. Do not, under any circumstances, deviate from this procedure. To make local changes to cpio, simply patch and commit to the main branch (aka HEAD). Never make local changes on the GNU branch. All local changes should be submitted to "cpio@gnu.ai.mit.edu" for inclusion in the next vendor release. obrien@FreeBSD.org - 30 March 1997 Encumbered Files It might occasionally be necessary to include an encumbered file in the FreeBSD source tree. For example, if a device requires a small piece of binary code to be loaded to it before the device will operate, and we do not have the source to that code, then the binary file is said to be encumbered. The following policies apply to including encumbered files in the FreeBSD source tree. Any file which is interpreted or executed by the system CPU(s) and not in source format is encumbered. Any file with a license more restrictive than BSD or GNU is encumbered. A file which contains downloadable binary data for use by the hardware is not encumbered, unless (1) or (2) apply to it. It must be stored in an architecture neutral ASCII format (file2c or uuencoding is recommended). Any encumbered file requires specific approval from the Core team before it is added to the CVS repository. Encumbered files go in src/contrib or src/sys/contrib. The entire module should be kept together. There is no point in splitting it, unless there is code-sharing with non-encumbered code. Object files are named arch/filename.o.uu>. Kernel files; Should always be referenced in conf/files.* (for build simplicity). Should always be in LINT, but the Core team decides per case if it should be commented out or not. The Core team can, of course, change their minds later on. The Release Engineer decides whether or not it goes in to the release. User-land files; core team The Core team decides if the code should be part of make world. release engineer The Release Engineer decides if it goes in to the release. Shared Libraries Contributed by &a.asami;, &a.peter;, and &a.obrien; 9 December 1996. If you are adding shared library support to a port or other piece of software that doesn't have one, the version numbers should follow these rules. Generally, the resulting numbers will have nothing to do with the release version of the software. The three principles of shared library building are: Start from 1.0 If there is a change that is backwards compatible, bump minor number (note that ELF systems ignore the minor number) If there is an incompatible change, bump major number For instance, added functions and bugfixes result in the minor version number being bumped, while deleted functions, changed function call syntax etc. will force the major version number to change. Stick to version numbers of the form major.minor (x.y). Our a.out dynamic linker does not handle version numbers of the form x.y.z well. Any version number after the y (ie. the third digit) is totally ignored when comparing shared lib version numbers to decide which library to link with. Given two shared libraries that differ only in the micro revision, ld.so will link with the higher one. Ie: if you link with libfoo.so.3.3.3, the linker only records 3.3 in the headers, and will link with anything starting with libfoo.so.3.(anything >= 3).(highest available). ld.so will always use the highest minor revision. Ie: it will use libc.so.2.2 in preference to libc.so.2.0, even if the program was initially linked with libc.so.2.0. In addition, our ELF dynamic linker does not handle minor version numbers at all. However, one should still specify a major and minor version number as our Makefiles "do the right thing" based on the type of system. For non-port libraries, it is also our policy to change the shared library version number only once between releases. In addition, it is our policy to change the major shared library version number only once between major OS releases. Ie: X.0 to (X+1).0. When you make a change to a system library that requires the version number to be bumped, check the Makefile's commit logs. It is the responsibility of the committer to ensure that the first such change since the release will result in the shared library version number in the Makefile to be updated, and any subsequent changes will not. diff --git a/en_US.ISO8859-1/books/faq/book.sgml b/en_US.ISO8859-1/books/faq/book.sgml index 76487ff398..5eed00be1c 100644 --- a/en_US.ISO8859-1/books/faq/book.sgml +++ b/en_US.ISO8859-1/books/faq/book.sgml @@ -1,12487 +1,12487 @@ %man; %authors; %bookinfo; %mailing-lists; ]> Frequently Asked Questions for FreeBSD 2.X, 3.X and 4.X The FreeBSD Documentation Project - $FreeBSD: doc/en_US.ISO8859-1/books/faq/book.sgml,v 1.244 2001/07/10 14:39:25 nik Exp $ + $FreeBSD: doc/en_US.ISO8859-1/books/faq/book.sgml,v 1.245 2001/07/17 20:51:50 chern Exp $ 1995 1996 1997 1998 1999 2000 2001 The FreeBSD Documentation Project &bookinfo.legalnotice; This is the FAQ for FreeBSD versions 2.X, 3.X, and 4.X. All entries are assumed to be relevant to FreeBSD 2.0.5 and later, unless otherwise noted. Any entries with a <XXX> are under construction. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the FreeBSD World Wide Web server. It may also be downloaded as one large HTML file with HTTP or as plain text, postscript, PDF, etc. from the FreeBSD FTP server. You may also want to Search the FAQ. Introduction Welcome to the FreeBSD 2.X-4.X FAQ! As is usual with Usenet FAQs, this document aims to cover the most frequently asked questions concerning the FreeBSD operating system (and of course answer them!). Although originally intended to reduce bandwidth and avoid the same old questions being asked over and over again, FAQs have become recognized as valuable information resources. Every effort has been made to make this FAQ as informative as possible; if you have any suggestions as to how it may be improved, please feel free to mail them to the &a.faq;. What is FreeBSD? Briefly, FreeBSD is a UN*X-like operating system for the i386 and Alpha/AXP platforms based on U.C. Berkeley's 4.4BSD-Lite release, with some 4.4BSD-Lite2 enhancements. It is also based indirectly on William Jolitz's port of U.C. Berkeley's Net/2 to the i386, known as 386BSD, though very little of the 386BSD code remains. A fuller description of what FreeBSD is and how it can work for you may be found on the FreeBSD home page. FreeBSD is used by companies, Internet Service Providers, researchers, computer professionals, students and home users all over the world in their work, education and recreation. See some of them in the FreeBSD Gallery. For more detailed information on FreeBSD, please see the FreeBSD Handbook. What are the goals of FreeBSD? The goals of the FreeBSD Project are to provide software that may be used for any purpose and without strings attached. Many of us have a significant investment in the code (and project) and would certainly not mind a little financial compensation now and then, but we are definitely not prepared to insist on it. We believe that our first and foremost mission is to provide code to any and all comers, and for whatever purpose, so that the code gets the widest possible use and provides the widest possible benefit. This is, we believe, one of the most fundamental goals of Free Software and one that we enthusiastically support. That code in our source tree which falls under the GNU General Public License (GPL) or GNU Library General Public License (LGPL) comes with slightly more strings attached, though at least on the side of enforced access rather than the usual opposite. Due to the additional complexities that can evolve in the commercial use of GPL software, we do, however, endeavor to replace such software with submissions under the more relaxed FreeBSD copyright whenever possible. Why is it called FreeBSD? It may be used free of charge, even by commercial users. Full source for the operating system is freely available, and the minimum possible restrictions have been placed upon its use, distribution and incorporation into other work (commercial or non-commercial). Anyone who has an improvement and/or bug fix is free to submit their code and have it added to the source tree (subject to one or two obvious provisions). For those of our readers whose first language is not English, it may be worth pointing out that the word free is being used in two ways here, one meaning at no cost, the other meaning you can do whatever you like. Apart from one or two things you cannot do with the FreeBSD code, for example pretending you wrote it, you really can do whatever you like with it. What is the latest version of FreeBSD? Version 4.3 is the latest STABLE version; it was released in April, 2001. This is also the latest RELEASE version. Briefly explained, -STABLE is aimed at the ISP or other corporate user who wants stability and a low change count over the wizzy new features of the latest -CURRENT snapshot. Releases can come from either branch, but you should only use -CURRENT if you are sure that you are prepared for its increased volatility (relative to -STABLE, that is). Releases are only made every few months. While many people stay more up-to-date with the FreeBSD sources (see the questions on FreeBSD-CURRENT and FreeBSD-STABLE) than that, doing so is more of a commitment, as the sources are a moving target. What is FreeBSD-CURRENT? FreeBSD-CURRENT is the development version of the operating system, which will in due course become 5.0-RELEASE. As such, it is really only of interest to developers working on the system and die-hard hobbyists. See the relevant section in the handbook for details on running -CURRENT. If you are not familiar with the operating system or are not capable of identifying the difference between a real problem and a temporary problem, you should not use FreeBSD-CURRENT. This branch sometimes evolves quite quickly and can be un-buildable for a number of days at a time. People that use FreeBSD-CURRENT are expected to be able to analyze any problems and only report them if they are deemed to be mistakes rather than glitches. Questions such as make world produces some error about groups on the -CURRENT mailing list are sometimes treated with contempt. Every day, snapshot releases are made based on the current state of the -CURRENT and -STABLE branches. Nowadays, distributions of the occasional snapshot are now being made available. The goals behind each snapshot release are: To test the latest version of the installation software. To give people who would like to run -CURRENT or -STABLE but who do not have the time and/or bandwidth to follow it on a day-to-day basis an easy way of bootstrapping it onto their systems. To preserve a fixed reference point for the code in question, just in case we break something really badly later. (Although CVS normally prevents anything horrible like this happening :) To ensure that any new features in need of testing have the greatest possible number of potential testers. No claims are made that any -CURRENT snapshot can be considered production quality for any purpose. If you want to run a stable and fully tested system, you will have to stick to full releases, or use the -STABLE snaphosts. Snapshot releases are directly available from ftp://current.FreeBSD.org/pub/FreeBSD/ for 5.0-CURRENT and releng4.FreeBSD.org for 4-STABLE snapshots. 3-STABLE snapshots are not being produced at the time of this writing (May 2000). Snapshots are generated, on the average, once a day for all actively developed branches. What is the FreeBSD-STABLE concept? Back when FreeBSD 2.0.5 was released, we decided to branch FreeBSD development into two parts. One branch was named -STABLE, with the intention that only well-tested bug fixes and small incremental enhancements would be made to it (for Internet Service Providers and other commercial enterprises for whom sudden shifts or experimental features are quite undesirable). The other branch was -CURRENT, which essentially has been one unbroken line leading towards 5.0-RELEASE (and beyond) since 2.0 was released. If a little ASCII art would help, this is how it looks: 2.0 | | | [2.1-STABLE] *BRANCH* 2.0.5 -> 2.1 -> 2.1.5 -> 2.1.6 -> 2.1.7.1 [2.1-STABLE ends] | (Mar 1997) | | | [2.2-STABLE] *BRANCH* 2.2.1 -> 2.2.2-RELEASE -> 2.2.5 -> 2.2.6 -> 2.2.7 -> 2.2.8 [end] | (Mar 1997) (Oct 97) (Apr 98) (Jul 98) (Dec 98) | | 3.0-SNAPs (started Q1 1997) | | 3.0-RELEASE (Oct 1998) | | [3.0-STABLE] *BRANCH* 3.1-RELEASE (Feb 1999) -> 3.2 -> 3.3 -> 3.4 -> 3.5 -> 3.5.1 | (May 1999) (Sep 1999) (Dec 1999) (June 2000) (July 2000) | | [4.0-STABLE] *BRANCH* 4.0 (Mar 2000) -> 4.1 -> 4.1.1 -> 4.2 -> 4.3 -> ... future 4.x releases ... | | (July 2000) (Sep 2000) (Nov 2000) \|/ + [5.0-CURRENT continues] The 2.2-STABLE branch was retired with the release of 2.2.8. The 3-STABLE branch has ended with the release of 3.5.1, the final 3.X release. The only changes made to either of these branches will be, for the most part, security-related bug fixes. 4-STABLE is the actively developed -STABLE branch. The latest release on the 4-STABLE is 4.3-RELEASE, which was released in April 2001. The 5-CURRENT branch is slowly progressing toward 5.0-RELEASE and beyond. See What is FreeBSD-CURRENT? for more information on this branch. When are FreeBSD releases made? As a general principle, the FreeBSD core team only release a new version of FreeBSD when they believe that there are sufficient new features and/or bug fixes to justify one, and are satisfied that the changes made have settled down sufficiently to avoid compromising the stability of the release. Many users regard this caution as one of the best things about FreeBSD, although it can be a little frustrating when waiting for all the latest goodies to become available... Releases are made about every 4 months on average. For people needing (or wanting) a little more excitement, binary snapshots are made every day... see above. Who is responsible for FreeBSD? The key decisions concerning the FreeBSD project, such as the overall direction of the project and who is allowed to add code to the source tree, are made by a core team of 9 people. There is a much larger team of more than 200 committers who are authorized to make changes directly to the FreeBSD source tree. However, most non-trivial changes are discussed in advance in the mailing lists, and there are no restrictions on who may take part in the discussion. Where can I get FreeBSD? Every significant release of FreeBSD is available via - anonymous ftp from the FreeBSD FTP site: For the current 3.X-STABLE release, 3.5.1-RELEASE, see the 3.5.1-RELEASE directory. The current 4-STABLE release, 4.3-RELEASE can be found in the 4.3-RELEASE directory. 4.X snapshots are usually made once a day. 5.0 Snapshot releases are made once a day for the -CURRENT branch, these being of service purely to bleeding-edge testers and developers. Information about obtaining FreeBSD on CD, DVD, and other media can be found in the Handbook. Where do I find info on the FreeBSD mailing lists? You can find full information in the Handbook entry on mailing-lists. Where do I find the FreeBSD Y2K info? You can find full information in the FreeBSD Y2K page. What FreeBSD news groups are available? You can find full information in the Handbook entry on newsgroups. Are there FreeBSD IRC (Internet Relay Chat) channels? Yes, most major IRC networks host a FreeBSD chat channel: Channel #FreeBSD on EFNet is a FreeBSD forum, but do not go there for tech support or to try and get folks there to help you avoid the pain of reading man pages or doing your own research. It is a chat channel, first and foremost, and topics there are just as likely to involve sex, sports or nuclear weapons as they are FreeBSD. You Have Been Warned! Available at server irc.chat.org. Channel #FreeBSDhelp on EFNet is a channel dedicated to helping FreeBSD users. They are much more sympathetic to questions then #FreeBSD is. Channel #FreeBSD on DALNET is available at irc.dal.net in the US and irc.eu.dal.net in Europe. Channel #FreeBSD on UNDERNET is available at us.undernet.org in the US and eu.undernet.org in Europe. Since it is a help channel, be prepared to read the documents you are referred to. Channel #FreeBSD on HybNet. This channel is a help channel. A list of servers can be found on the HybNet web site. Each of these channels are distinct and are not connected to each other. Their chat styles also differ, so you may need to try each to find one suited to your chat style. As with *all* types of IRC traffic, if you are easily offended or cannot deal with lots of young people (and more than a few older ones) doing the verbal equivalent of jello wrestling, do not even bother with it. How do I access the Problem Report database? The Problem Report database of all user change requests may be queried (or submitted to) by using our web-based PR submission and query interfaces. The &man.send-pr.1; command can also be used to submit problem reports and change requests via electronic mail. Is the documentation available in other formats, such as plain text (ASCII), or Postscript? Yes. The documentation is available in a number of different formats and compression schemes on the FreeBSD FTP site, in the /pub/FreeBSD/doc/ directory. The documentation is categorised in a number of different ways. These include: The document's name, such as faq, or handbook. The document's language and encoding. These are based on the locale names you will find under /usr/share/locale on your FreeBSD system. The current languages and encodings that we have for documentation are as follows: Name Meaning en_US.ISO8859-1 US English de_DE.ISO8859-1 German es_ES.ISO8859-1 Spanish fr_FR.ISO8859-1 French ja_JP.eucJP Japanese (EUC encoding) ru_RU.KOI8-R Russian (KOI8-R encoding) zh_TW.Big5 Chinese (Big5 encoding) Some documents may not be available in all languages. The document's format. We produce the documentation in a number of different output formats to try and make it as flexible as possible. The current formats are; Format Meaning html-split A collection of small, linked, HTML files. html One large HTML file containing the entire document pdb Palm Pilot database format, for use with the iSilo reader. pdf Adobe's Portable Document Format ps Postscript rtf Microsoft's Rich Text Format Page numbers are not automatically updated when loading this format in to Word. Press CTRL+A, CTRL+END, F9 after loading the document, to update the page numbers. txt Plain text The compression and packaging scheme. There are three of these currently in use. Where the format is html-split, the files are bundled up using &man.tar.1;. The resulting .tar file is then compressed using the compression schemes detailed in the next point. All the other formats generate one file, called book.format (i.e., book.pdb, book.html, and so on). These files are then compressed using three compression schemes. Scheme Description zip The Zip format. If you want to uncompress this on FreeBSD you will need to install the archivers/unzip port first. gz The GNU Zip format. Use &man.gunzip.1; to uncompress these files, which is part of FreeBSD. bz2 The BZip2 format. Less widespread than the others, but generally gives smaller files. Install the archivers/bzip2 port to uncompress these files. So the Postscript version of the Handbook, compressed using BZip2 will be stored in a file called book.ps.bz2 in the handbook/ directory. The formatted documentation is also available as a FreeBSD package, of which more later. After choosing the format and compression mechanism that you want to download, you must then decide whether or not you want to download the document as a FreeBSD package. The advantage of downloading and installing the package is that the documentation can then be managed using the normal FreeBSD package management comments, such as &man.pkg.add.1; and &man.pkg.delete.1;. If you decide to download and install the package then you must know the filename to download. The documentation-as-packages files are stored in a directory called packages. Each package file looks like document-name.lang.encoding.format.tgz. For example, the FAQ, in English, formatted as PDF, is in the package called faq.en_US.ISO8859-1.pdf.tgz. Knowing this, you can use the following command to install the English PDF FAQ package. &prompt.root; pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/packages/faq.en_US.ISO8859-1.pdf.tgz Having done that, you can use &man.pkg.info.1; to determine where the file has been installed. &prompt.root; pkg_info -f faq.en_US.ISO8859-1.pdf Information for faq.en_US.ISO8859-1.pdf: Packing list: Package name: faq.en_US.ISO8859-1.pdf CWD to /usr/share/doc/en_US.ISO8859-1/books/faq File: book.pdf CWD to . File: +COMMENT (ignored) File: +DESC (ignored) As you can see, book.pdf will have been installed in to /usr/share/doc/en_US.ISO8859-1/books/faq. If you do not want to use the packages then you will have to download the compressed files yourself, uncompress them, and then copy the appropriate documents in to place. For example, the split HTML version of the FAQ, compressed using &man.gzip.1;, can be found in the en_US.ISO8859-1/books/faq/book.html-split.tar.gz file. To download and uncompress that file you would have to do this. &prompt.root; fetch ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/faq/book.html-split.tar.gz &prompt.root; gzip -d book.html-split.tar.gz &prompt.root; tar xvf book.html-split.tar You will be left with a collection of .html files. The main one is called index.html, which will contain the table of contents, introductory material, and links to the other parts of the document. You can then copy or move these to their final location as necessary. How do I become a FreeBSD Web mirror? Certainly! There are multiple ways to mirror the Web pages. Using CVSup: You can retrieve the formatted files using CVSup, and connecting to a CVSup server. To retrieve the webpages, please look at the example supfile, which can be found in /usr/share/examples/cvsup/www-supfile. - Using ftp mirror: You can download the FTP server's + Using FTP mirror: You can download the FTP server's copy of the web site sources using your favorite ftp mirror tool. Keep in mind that you have to build these sources before publishing them. Simply start at ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/www. What other sources of information are there? The following newsgroups contain pertinent discussion for FreeBSD users: comp.unix.bsd.freebsd.announce (moderated) comp.unix.bsd.freebsd.misc comp.unix.bsd.misc Web resources: The FreeBSD Home Page. If you have a laptop, be sure and see Tatsumi Hosokawa's Mobile Computing page in Japan. For information on SMP (Symmetric MultiProcessing), please see the SMP support page. For information on FreeBSD multimedia applications, please see the multimedia page. If you are interested specifically in the Bt848 video capture chip, then follow that link. The FreeBSD handbook also has a fairly complete bibliography section which is worth reading if you are looking for actual books to buy. Nik Clayton
nik@freebsd.org
 Installation Which file do I download to get FreeBSD? Prior to release 3.1, you only needed one floppy image to install FreeBSD, namely floppies/boot.flp. However, since release 3.1 the Project has added base support for a wide variety of hardware which needed more space, and thus for 3.x and 4.x we now use two floppy images, namely floppies/kernel.flp and floppies/mfsroot.flp. These images need to be copied onto floppies by tools like fdimage or &man.dd.1;. If you need to download the distributions yourself (for a DOS filesystem install, for instance), below are some recommendations for distributions to grab: bin/ manpages/ compat*/ doc/ src/ssys.* Full instructions on this procedure and a little bit more about installation issues in general can be found in the Handbook entry on installing FreeBSD. What do I do if the floppy images does not fit on a single floppy? A 3.5 inch (1.44MB) floppy can accomodate 1474560 bytes of data. The boot image is exactly 1474560 bytes in size. Common mistakes when preparing the boot floppy are: Not downloading the floppy image in binary mode when using FTP. Some FTP clients default their transfer mode to ascii and attempt to change any end-of-line characters received to match the conventions used by the client's system. This will almost invariably corrupt the boot image. Check the size of the downloaded boot image: if it is not exactly that on the server, then the download process is suspect. To workaround: type binary at the FTP command prompt after getting connected to the server and before starting the download of the image. Using the DOS copy command (or equivalent GUI tool) to transfer the boot image to floppy. Programs like copy will not work as the boot image has been created to be booted into directly. The image has the complete content of the floppy, track for track, and is not meant to be placed on the floppy as a regular file. You have to transfer it to the floppy raw, using the low-level tools (e.g. fdimage or rawrite) described in the installation guide to FreeBSD. Where are the instructions for installing FreeBSD? Installation instructions can be found in the Handbook entry on installing FreeBSD. What do I need in order to run FreeBSD? You will need a 386 or better PC, with 5 MB or more of RAM and at least 60 MB of hard disk space. It can run with a low end MDA graphics card but to run X11R6, a VGA or better video card is needed. See also the section on I have only 4 MB of RAM. Can I install FreeBSD? FreeBSD 2.1.7 was the last version of FreeBSD that could be installed on a 4MB system. Newer versions of FreeBSD, like 2.2, need at least 5MB to install on a new system. All versions of FreeBSD, including 3.0, will run in 4MB of RAM, they just cannot run the installation program in 4MB. You can add extra memory for the install process, if you like, and then after the system is up and running, go back to 4MB. Or you could always just swap your disk into a system which has >4MB, install onto it and then swap it back. There are also situations in which FreeBSD 2.1.7 will not install in 4 MB. To be exact: it does not install with 640 kB base + 3 MB extended memory. If your motherboard can remap some of the lost memory out of the 640kB to 1MB region, then you may still be able to get FreeBSD 2.1.7 up. Try to go into your BIOS setup and look for a remap option. Enable it. You may also have to disable ROM shadowing. It may be easier to get 4 more MB just for the install. Build a custom kernel with only the options you need and then get the 4MB out again. You may also install 2.0.5 and then upgrade your system to 2.1.7 with the upgrade option of the 2.1.7 installation program. After the installation, if you build a custom kernel, it will run in 4 MB. Someone has even succeeded in booting with 2 MB (the system was almost unusable though :-)) How can I make my own custom install floppy? Currently there is no way to just make a custom install floppy. You have to cut a whole new release, which will include your install floppy. To make a custom release, follow the instructions here. Can I have more than one operating system on my PC? Have a look at The multi-OS page. Can Windows 95/98 co-exist with FreeBSD? Install Windows 95/98 first, after that FreeBSD. FreeBSD's boot manager will then manage to boot Win95/98 and FreeBSD. If you install Windows 95/98 second, it will boorishly overwrite your boot manager without even asking. If that happens, see the next section. Windows 95/98 killed my boot manager! How do I get it back? You can reinstall the boot manager FreeBSD comes with in one of three ways: Running DOS, go into the tools/ directory of your FreeBSD distribution and look for bootinst.exe. You run it like so: ...\TOOLS> bootinst.exe boot.bin and the boot manager will be reinstalled. Boot the FreeBSD boot floppy again and go to the Custom installation menu item. Choose Partition. Select the drive which used to contain your boot manager (likely the first one) and when you come to the partition editor for it, as the very first thing (e.g. do not make any changes) select (W)rite. This will ask for confirmation, say yes, and when you get the Boot Manager selection prompt, be sure to select Boot Manager. This will re-write the boot manager to disk. Now quit out of the installation menu and reboot off the hard disk as normal. Boot the FreeBSD boot floppy (or CDROM) and choose the Fixit menu item. Select either the Fixit floppy or CDROM #2 (the live file system option) as appropriate and enter the fixit shell. Then execute the following command: Fixit# fdisk -B -b /boot/boot0 bootdevice substituting bootdevice for your real boot device such as ad0 (first IDE disk), ad4 (first IDE disk on auxiliary controller), da0 (first SCSI disk), etc. My A, T, or X series IBM Thinkpad locks up when I first booted up my FreeBSD installation. How can I solve this? A bug in early revisions of IBM's BIOS on these machines mistakenly identifies the FreeBSD partition as a potential FAT suspend-to-disk partition. When the BIOS tries to parse the FreeBSD partition it hangs. According to IBMIn an e-mail from Keith Frechette kfrechet@us.ibm.com., the following model/BIOS release numbers incorporate the fix. Model BIOS revision T20 IYET49WW or later T21 KZET22WW or later A20p IVET62WW or later A20m IWET54WW or later A21p KYET27WW or later A21m KXET24WW or later A21e KUET30WW It has been reported that later IBM BIOS revisions may have reintroduced the bug. This message from Jacques Vidrine to the &a.mobile; describes a procedure which may work if your newer IBM laptop does not boot FreeBSD properly, and you can upgrade or downgrade the BIOS.. If you have an earlier BIOS, and upgrading is not an option a workaround is to install FreeBSD, change the partition ID FreeBSD uses, and install new boot blocks that can handle the different partition ID. First, you will need to restore the machine to a state where it can get through its self-test screen. Doing this requires powering up the machine without letting it find a FreeBSD partition on its primary disk. One way is to remove the hard disk and temporarily move it to an older ThinkPad (such as a ThinkPad 600) or a desktop PC with an appropriate conversion cable. Once it is there, you can delete the FreeBSD partition and move the hard disk back. The ThinkPad should now be in a bootable state again. With the machine functional again, you can use the workaround procedure described here to get a working FreeBSD installation. Download boot1 and boot2 from http://people.freebsd.org/~bmah/ThinkPad/. Put these files somewhere you will be able to retrieve them later. Install FreeBSD as normal on to the ThinkPad. Do not use Dangerously Dedicated mode. Do not reboot when the install has finished. Either switch to the Emergency Holographic Shell (ALT F4) or start a fixit shell. Use &man.fdisk.8; to change the FreeBSD partition ID from 165 to 166 (this is the type used by OpenBSD). Bring the boot1 and boot2 files to the local filesystem. Use &man.disklabel.8; to write boot1 and boot2 to your FreeBSD slice. &prompt.root; disklabel -B -b boot1 -s boot2 ad0sn n is the number of the slice where you installed FreeBSD. Reboot. At the boot prompt you will be given the option of booting OpenBSD. This will actually boot FreeBSD. Getting this to work in the case where you want to dual boot OpenBSD and FreeBSD on the same laptop is left as an exercise for the reader. Can I install on a disk with bad blocks? Prior to 3.0, FreeBSD included a utility known as bad144, which automatically remapped bad blocks. Because modern IDE drives perform this function themselves, bad144 has been removed from the FreeBSD source tree. If you wish to install FreeBSD 3.0 or later, we strongly suggest you purchase a newer disk drive. If you do not wish to do this, you must run FreeBSD 2.x. If you are seeing bad block errors with a modern IDE drive, chances are the drive is going to die very soon (the drive's internal remapping functions are no longer sufficient to fix the bad blocks, which means the disk is heavily corrupted); we suggest you by a new hard drive. If you have a SCSI drive with bad blocks, see this answer. Strange things happen when I boot the install floppy! What is happening? If you are seeing things like the machine grinding to a halt or spontaneously rebooting when you try to boot the install floppy, here are three questions to ask yourself:- Did you use a new, freshly-formatted, error-free floppy (preferably a brand-new one straight out of the box, as opposed to the magazine coverdisk that has been lying under the bed for the last three years)? Did you download the floppy image in binary (or image) mode? (do not be embarrassed, even the best of us have accidentally downloaded a binary file in ASCII mode at least once!) If you are using Windows95 or Win98 did you run fdimage or rawrite in pure DOS mode? These OS's can interfere with programs that write directly to hardware, which the disk creation program does; even running it inside a DOS shell in the GUI can cause this problem. There have also been reports of Netscape causing problems when downloading the boot floppy, so it is probably best to use a different FTP client if you can. I booted from my ATAPI CDROM, but the install program says no CDROM is found. Where did it go? The usual cause of this problem is a mis-configured CDROM drive. Many PCs now ship with the CDROM as the slave device on the secondary IDE controller, with no master device on that controller. This is illegal according to the ATAPI specification, but Windows plays fast and loose with the specification, and the BIOS ignores it when booting. This is why the BIOS was able to see the CDROM to boot from it, but why FreeBSD cannot see it to complete the install. Reconfigure your system so that the CDROM is either the master device on the IDE controller it is attached to, or make sure that it is the slave on an IDE controller that also has a master device. Why can I not install from tape? If you are installing 2.1.7R from tape, you must create the tape using a tar blocksize of 10 (5120 bytes). The default tar blocksize is 20 (10240 bytes), and tapes created using this default size cannot be used to install 2.1.7R; with these tapes, you will get an error that complains about the record size being too big. Can I install on my laptop over PLIP (Parallel Line IP)? Connect the two computers using a Laplink parallel cable to use this feature: Wiring a parallel cable for networking A-name A-End B-End Descr. Post/Bit DATA0 -ERROR 2 15 15 2 Data 0/0x01 1/0x08 DATA1 +SLCT 3 13 13 3 Data 0/0x02 1/0x10 DATA2 +PE 4 12 12 4 Data 0/0x04 1/0x20 DATA3 -ACK 5 10 10 5 Strobe 0/0x08 1/0x40 DATA4 BUSY 6 11 11 6 Data 0/0x10 1/0x80 GND 18-25 18-25 GND -
See also this note on the Mobile Computing page. Which geometry should I use for a disk drive? By the geometry of a disk, we mean the number of cylinders, heads and sectors/track on a disk - I will refer to this as C/H/S for convenience. This is how the PC's BIOS works out which area on a disk to read/write from. This seems to cause a lot of confusion for some reason. First of all, the physical geometry of a SCSI drive is totally irrelevant, as FreeBSD works in term of disk blocks. In fact, there is no such thing as the physical geometry, as the sector density varies across the disk - what manufacturers claim is the quote physical geometry is usually the geometry that they have worked out results in the least wasted space. For IDE disks, FreeBSD does work in terms of C/H/S, but all modern drives will convert this into block references internally as well. All that matters is the logical geometry - the answer that the BIOS gets when it asks what is your geometry? and then uses to access the disk. As FreeBSD uses the BIOS when booting, it is very important to get this right. In particular, if you have more than one operating system on a disk, they must all agree on the geometry, otherwise you will have serious problems booting! For SCSI disks, the geometry to use depends on whether extended translation support is turned on in your controller (this is often referred to as support for DOS disks >1GB or something similar). If it is turned off, then use N cylinders, 64 heads and 32 sectors/track, where N is the capacity of the disk in MB. For example, a 2GB disk should pretend to have 2048 cylinders, 64 heads and 32 sectors/track. If it is turned on (it is often supplied this way to get around certain limitations in MSDOS) and the disk capacity is more than 1GB, use M cylinders, 63 sectors per track (*not* 64), and 255 heads, where 'M' is the disk capacity in MB divided by 7.844238 (!). So our example 2GB drive would have 261 cylinders, 63 sectors per track and 255 heads. If you are not sure about this, or FreeBSD fails to detect the geometry correctly during installation, the simplest way around this is usually to create a small DOS partition on the disk. The correct geometry should then be detected (and you can always remove the DOS partition in the partition editor if you do not want to keep it, or leave it around for programming network cards and the like). Alternatively, there is a freely available utility distributed with FreeBSD called pfdisk.exe (located in the tools subdirectory on the - FreeBSD CDROM or on the various FreeBSD ftp sites) which can be + FreeBSD CDROM or on the various FreeBSD FTP sites) which can be used to work out what geometry the other operating systems on the disk are using. You can then enter this geometry in the partition editor. Are there any restrictions on how I divide the disk up? Yes. You must make sure that your root partition is below 1024 cylinders so the BIOS can boot the kernel from it. (Note that this is a limitation in the PC's BIOS, not FreeBSD). For a SCSI drive, this will normally imply that the root partition will be in the first 1024MB (or in the first 4096MB if extended translation is turned on - see previous question). For IDE, the corresponding figure is 504MB. Is FreeBSD compatible with any disk managers? FreeBSD recognizes the Ontrack Disk Manager and makes allowances for it. Other disk managers are not supported. If you just want to use the disk with FreeBSD you do not need a disk manager. Just configure the disk for as much space as the BIOS can deal with (usually 504 megabytes), and FreeBSD should figure out how much space you really have. If you are using an old disk with an MFM controller, you may need to explicitly tell FreeBSD how many cylinders to use. If you want to use the disk with FreeBSD and another operating system, you may be able to do without a disk manager: just make sure the FreeBSD boot partition and the slice for the other operating system are in the first 1024 cylinders. If you are reasonably careful, a 20 megabyte boot partition should be plenty. When I boot FreeBSD I get Missing Operating System. What is happening? This is classically a case of FreeBSD and DOS or some other OS conflicting over their ideas of disk geometry. You will have to reinstall FreeBSD, but obeying the instructions given above will almost always get you going. Why can I not get past the boot manager's F? prompt? This is another symptom of the problem described in the preceding question. Your BIOS geometry and FreeBSD geometry settings do not agree! If your controller or BIOS supports cylinder translation (often marked as >1GB drive support), try toggling its setting and reinstalling FreeBSD. Do I need to install the complete sources? In general, no. However, we would strongly recommend that you install, at a minimum, the base source kit, which includes several of the files mentioned here, and the sys (kernel) source kit, which includes sources for the kernel. There is nothing in the system which requires the presence of the sources to operate, however, except for the kernel-configuration program &man.config.8;. With the exception of the kernel sources, our build structure is set up so that you can read-only mount the sources from elsewhere via NFS and still be able to make new binaries. (Because of the kernel-source restriction, we recommend that you not mount this on /usr/src directly, but rather in some other location with appropriate symbolic links to duplicate the top-level structure of the source tree.) Having the sources on-line and knowing how to build a system with them will make it much easier for you to upgrade to future releases of FreeBSD. To actually select a subset of the sources, use the Custom menu item when you are in the Distributions menu of the system installation tool. Do I need to build a kernel? Building a new kernel was originally pretty much a required step in a FreeBSD installation, but more recent releases have benefited from the introduction of a much friendlier kernel configuration tool. When at the FreeBSD boot prompt (boot:), use the flag and you will be dropped into a visual configuration screen which allows you to configure the kernel's settings for most common ISA cards. It is still recommended that you eventually build a new kernel containing just the drivers that you need, just to save a bit of RAM, but it is no longer a strict requirement for most systems. Should I use DES passwords, or MD5, and how do I specify which form my users receive? The default password format on FreeBSD is to use MD5-based passwords. These are believed to be more secure than the traditional Unix password format, which used a scheme based on the DES algorithm. DES passwords are still available if you need to share your password file with legacy operating systems which still use the less secure password format (they are available if you choose to install the crypto distribution in sysinstall, or by installing the crypto sources if building from source). Which password format to use for new passwords is controlled by the passwd_format login capability in /etc/login.conf, which takes values of either des (if available) or md5. See the &man.login.conf.5; manpage for more information about login capabilities. Why does the boot floppy start, but hang at the Probing Devices... screen? If you have a IDE Zip or Jaz drive installed, remove it and try again. The boot floppy can get confused by the drives. After the system is installed you can reconnect the drive. Hopefully this will be fixed in a later release. Why do I get a panic: can't mount root error when rebooting the system after installation? This error comes from confusion between the boot block's and the kernel's understanding of the disk devices. The error usually manifests on two-disk IDE systems, with the hard disks arranged as the master or single device on separate IDE controllers, with FreeBSD installed on the secondary IDE controller. The boot blocks think the system is installed on wd1 (the second BIOS disk) while the kernel assigns the first disk on the secondary controller device wd2. After the device probing, the kernel tries to mount what the boot blocks think is the boot disk, wd1, while it is really wd2, and fails. To fix the problem, do one of the following: For FreeBSD 3.3 and later, reboot the system and hit Enter at the Booting kernel in 10 seconds; hit [Enter] to interrupt prompt. This will drop you into the boot loader. Then type set root_disk_unit="disk_number" . disk_number will be 0 if FreeBSD is installed on the master drive on the first IDE controller, 1 if it is installed on the slave on the first IDE controller, 2 if it is installed on the master of the second IDE controller, and 3 if it is installed on the slave of the second IDE controller. Then type boot, and your system should boot correctly. To make this change permanent (ie so you do not have to do this every time you reboot or turn on your FreeBSD machine), put the line root_disk_unit="disk_number" in /boot/loader.conf.local . If using FreeBSD 3.2 or earlier, at the Boot: prompt, enter 1:wd(2,a)kernel and press Enter. If the system starts, then run the command echo "1:wd(2,a)kernel" > /boot.config to make it the default boot string. Move the FreeBSD disk onto the primary IDE controller, so the hard disks are consecutive. Rebuild your kernel, modify the wd configuration lines to read: controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr disk wd0 at wdc0 drive 0 # disk wd1 at wdc0 drive 1 # comment out this line controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr disk wd1 at wdc1 drive 0 # change from wd2 to wd1 disk wd2 at wdc1 drive 1 # change from wd3 to wd2 Install the new kernel. If you moved your disks and wish to restore the previous configuration, replace the disks in the desired configuration and reboot. Your system should boot successfully. What are the limits for memory? For memory, the limit is 4 gigabytes. This configuration has been tested, see wcarchive's configuration for more details. If you plan to install this much memory into a machine, you need to be careful. You will probably want to use ECC memory and to reduce capacitive loading use 9 chip memory modules vice 18 chip memory modules. What are the limits for ffs filesystems? For ffs filesystems, the maximum theoretical limit is 8 terabytes (2G blocks), or 16TB for the default block size of 8K. In practice, there is a soft limit of 1 terabyte, but with modifications filesystems with 4 terabytes are possible (and exist). The maximum size of a single ffs file is approximately 1G blocks (4TB) if the block size is 4K. Maximum file sizes fs block size 2.2.7-stable 3.0-current works should work 4K 4T-1 4T-1 4T-1 >4T 8K >32G 8T-1 >32G 32T-1 16K >128G 16T-1 >128G 32T-1 32K >512G 32T-1 >512G 64T-1 64K >2048G 64T-1 >2048G 128T-1
When the fs block size is 4K, triple indirect blocks work and everything should be limited by the maximum fs block number that can be represented using triple indirect blocks (approx. 1K^3 + 1K^2 + 1K), but everything is limited by a (wrong) limit of 1G-1 on fs block numbers. The limit on fs block numbers should be 2G-1. There are some bugs for fs block numbers near 2G-1, but such block numbers are unreachable when the fs block size is 4K. For block sizes of 8K and larger, everything should be limited by the 2G-1 limit on fs block numbers, but is actually limited by the 1G-1 limit on fs block numbers, except under -STABLE triple indirect blocks are unreachable, so the limit is the maxiumum fs block number that can be represented using double indirect blocks (approx. (blocksize/4)^2 + (blocksize/4)), and under -CURRENT exceeding this limit may cause problems. Using the correct limit of 2G-1 blocks does cause problems. How can I put 1TB files on my floppy? I keep several virtual ones on floppies :-). The maxiumum file size is not closely related to the maximum disk size. The maximum disk size is 1TB. It is a feature that the file size can be larger than the disk size. The following example creates a file of size 8T-1 using a whole 32K of disk space (3 indirect blocks and 1 data block) on a small root partition. The dd command requires a dd that works with large files. &prompt.user; cat foo df . dd if=/dev/zero of=z bs=1 seek=`echo 2^43 - 2 | bc` count=1 ls -l z du z df . &prompt.user; sh foo Filesystem 1024-blocks Used Avail Capacity Mounted on /dev/da0a 64479 27702 31619 47% / 1+0 records in 1+0 records out 1 bytes transferred in 0.000187 secs (5346 bytes/sec) -rw-r--r-- 1 bde bin 8796093022207 Sep 7 16:04 z 32 z Filesystem 1024-blocks Used Avail Capacity Mounted on /dev/da0a 64479 27734 31587 47% / Bruce Evans, September 1998 Why do I get an error message, archsw.readin.failed after compiling and booting a new kernel? You can boot by specifying the kernel directly at the second stage, pressing any key when the | shows up before loader is started. More specifically, you have upgraded the source for your kernel, and installed a new kernel builtin from them without making world. This is not supported. Make world. How do I upgrade from 3.X -> 4.X? We strongly recommend that you use binary snapshots to do this. 4-STABLE snapshots are available at releng4.FreeBSD.org. If you wish to upgrade using source, please see the FreeBSD Handbook for more information. Upgrading via source is never recommended for new users, and upgrading from 3.X to 4.X is even less so; make sure you have read the instructions carefully before attempting to upgrade via source. What are these security profiles? A security profile is a set of configuration options that attempts to achieve the desired ratio of security to convenience by enabling and disabling certain programs and other settings. The more severe the security profile, the less programs will be enabled by default; this is one of the basic principles of security: do not run anything except what you must. Please note that the security profile is just a default setting. All programs can be enabled and disabled after you have installed FreeBSD by editing or adding the appropriate line(s) to /etc/rc.conf. For more information on the latter, please see the &man.rc.conf.5; manual page. Following is a table that describes what each security profile does. The columns are the choices you have for a security profile, and the rows are the program or feature that is enabled or disabled. Possible security profiles Extreme High Moderate Low &man.inetd.8; NO NO YES YES &man.sendmail.8; NO YES YES YES &man.sshd.8; NO YES YES YES &man.portmap.8; NO NO MAYBE The portmapper is enabled if the machine has been configured as an NFS client or server earlier in the installation. YES NFS server NO NO YES YES &man.securelevel.8; YES (2) If you choose a security profile that sets the securelevel (Extreme or High), you must be aware of the implications. Please read the &man.init.8; manual page and pay particular attention to the meanings of the security levels, or you may have significant trouble later! YES (1) NO NO
The security profile is not a silver bullet! Setting it high does not mean you do not have to keep up with security issues by reading an appropriate mailing list, using good passwords and passphrases, and generally adhering to good security practices. It simply sets up the desired security to convenience ratio out of the box. The security profile mechanism is meant to be used when you first install FreeBSD. If you already have FreeBSD installed, it would probably be more beneficial to simply enable or disable the desired functionality. If you really want to use a security profile, you can re-run &man.sysinstall.8; to set it. Hardware compatibility Does FreeBSD support architectures other than the x86? Yes. FreeBSD currently runs on both Intel x86 and DEC (now Compaq) Alpha architectures. Interest has also been expressed in a port of FreeBSD to the SPARC architecture, join the freebsd-sparc@FreeBSD.org mailing list if you are interested in joining that project. Most recent additions to the list of upcoming platforms are IA-64 and PowerPC, join the freebsd-ia64@FreeBSD.org and/or freebsd-ppc@FreeBSD.org mailing lists for more information. For general discussion on new architectures, join the freebsd-platforms@FreeBSD.org mailing list. If your machine has a different architecture and you need something right now, we suggest you look at NetBSD or OpenBSD. What kind of hard drives does FreeBSD support? FreeBSD supports EIDE and SCSI drives (with a compatible controller; see the next section), and all drives using the original Western Digital interface (MFM, RLL, ESDI, and of course IDE). A few ESDI controllers that use proprietary interfaces may not work: stick to WD1002/3/6/7 interfaces and clones. Which SCSI controllers are supported? See the complete list in the Handbook. Which CDROM drives are supported by FreeBSD? Any SCSI drive connected to a supported controller is supported. The following proprietary CDROM interfaces are also supported: Mitsumi LU002 (8bit), LU005 (16bit) and FX001D (16bit 2x Speed). Sony CDU 31/33A Sound Blaster Non-SCSI CDROM Matsushita/Panasonic CDROM ATAPI compatible IDE CDROMs All non-SCSI cards are known to be extremely slow compared to SCSI drives, and some ATAPI CDROMs may not work. As of 2.2 the FreeBSD CDROM from the FreeBSD Mall supports booting directly from the CD. Which CD-RW drives are supported by FreeBSD? FreeBSD supports any ATAPI-compatible IDE CD-R or CD-RW drive. For FreeBSD versions 4.0 and later, see the man page for &man.burncd.8;. For earlier FreeBSD versions, see the examples in /usr/share/examples/atapi. FreeBSD also supports any SCSI CD-R or CD-RW drives. Install and use the cdrecord command from the ports or packages system, and make sure that you have the pass device compiled in your kernel. Does FreeBSD support ZIP drives? FreeBSD supports the SCSI ZIP drive out of the box, of course. The ZIP drive can only be set to run at SCSI target IDs 5 or 6, but if your SCSI host adapter's BIOS supports it you can even boot from it. It is not clear which host adapters support booting from targets other than 0 or 1, so you will have to consult your adapter's documentation if you would like to use this feature. ATAPI (IDE) Zip drives are supported in FreeBSD 2.2.6 and later releases. FreeBSD has contained support for Parallel Port Zip Drives since version 3.0. If you are using a sufficiently up to date version, then you should check that your kernel contains the scbus0, da0, ppbus0, and vp0 drivers (the GENERIC kernel contains everything except vp0). With all these drivers present, the Parallel Port drive should be available as /dev/da0s4. Disks can be mounted using mount /dev/da0s4 /mnt OR (for dos disks) mount_msdos /dev/da0s4 /mnt as appropriate. Also check out this note on removable drives, and this note on formatting. Does FreeBSD support JAZ, EZ and other removable drives? Apart from the IDE version of the EZ drive, these are all SCSI devices, so the should all look like SCSI disks to FreeBSD, and the IDE EZ should look like an IDE drive. I am not sure how well FreeBSD supports changing the media out while running. You will of course need to dismount the drive before swapping media, and make sure that any external units are powered on when you boot the system so FreeBSD can see them. See this note on formatting. Which multi-port serial cards are supported by FreeBSD? There is a list of these in the Miscellaneous devices section of the handbook. Some unnamed clone cards have also been known to work, especially those that claim to be AST compatible. Check the &man.sio.4; man page to get more information on configuring such cards. Does FreeBSD support my USB keyboard? USB device support was added to FreeBSD 3.1. However, it is still in preliminary state and may not always work as of version 3.2. If you want to experiment with the USB keyboard support, follow the procedure described below. Use FreeBSD 3.2 or later. Add the following lines to your kernel configuration file, and rebuild the kernel. device uhci device ohci device usb device ukbd options KBD_INSTALL_CDEV In versions of FreeBSD before 4.0, use this instead: controller uhci0 controller ohci0 controller usb0 controller ukbd0 options KBD_INSTALL_CDEV Go to the /dev directory and create device nodes as follows: &prompt.root; cd /dev &prompt.root; ./MAKEDEV kbd0 kbd1 Edit /etc/rc.conf and add the following lines: usbd_enable="YES" usbd_flags="" After the system is rebooted, the AT keyboard becomes /dev/kbd0 and the USB keyboard becomes /dev/kbd1, if both are connected to the system. If there is the USB keyboard only, it will be /dev/ukbd0. If you want to use the USB keyboard in the console, you have to explicitly tell the console driver to use the existence of the USB keyboard. This can be done by running the following command as a part of system initialization. &prompt.root; kbdcontrol -k /dev/kbd1 < /dev/ttyv0 > /dev/null Note that if the USB keyboard is the only keyboard, it is accessed as /dev/kbd0, thus, the command should look like: &prompt.root; kbdcontrol -k /dev/kbd0 < /dev/ttyv0 > /dev/null /etc/rc.i386 is a good place to add the above command. Once this is done, the USB keyboard should work in the X environment as well without any special settings. Hot-plugging and unplugging of the USB keyboard may not work quite right yet. It is a good idea to connect the keyboard before you start the system and leave it connected until the system is shutdown to avoid troubles. See the &man.ukbd.4; man page for more information. I have an unusual bus mouse. How do I set it up? FreeBSD supports the bus mouse and the InPort bus mouse from such manufactures as Microsoft, Logitech and ATI. The bus device driver is compiled in the GENERIC kernel by default in FreeBSD versions 2.X, but not included in version 3.0 or later. If you are building a custom kernel with the bus mouse driver, make sure to add the following line to the kernel config file In FreeBSD 3.0 or before, add: device mse0 at isa? port 0x23c tty irq5 vector mseintr In FreeBSD 3.X, the line should be: device mse0 at isa? port 0x23c tty irq5 And in FreeBSD 4.X and later, the line should read: device mse0 at isa? port 0x23c irq5 Bus mice usually comes with dedicated interface cards. These cards may allow you to set the port address and the IRQ number other than shown above. Refer to the manual of your mouse and the &man.mse.4; man page for more information. How do I use my PS/2 (mouse port or keyboard) mouse? If you are running a post-2.2.5 version of FreeBSD, the necessary driver, psm, is included and enabled in the kernel. The kernel should detect your PS/2 mouse at boot time. If you are running a previous but relatively recent version of FreeBSD (2.1.x or better) then you can simply enable it in the kernel configuration menu at installation time, otherwise later with at the boot: prompt. It is disabled by default, so you will need to enable it explicitly. If you are running an older version of FreeBSD then you will have to add the following lines to your kernel configuration file and compile a new kernel. In FreeBSD 3.0 or earlier, the line should be: device psm0 at isa? port "IO_KBD" conflicts tty irq 12 vector psmintr In FreeBSD 3.1 or later, the line should be: device psm0 at isa? tty irq 12 In FreeBSD 4.0 or later, the line should be: device psm0 at atkbdc? irq 12 See the Handbook entry on configuring the kernel if you have no experience with building kernels. Once you have a kernel detecting psm0 correctly at boot time, make sure that an entry for psm0 exists in /dev. You can do this by typing: &prompt.root; cd /dev; sh MAKEDEV psm0 when logged in as root. Is it possible to make use of a mouse in any way outside the X Window system? If you are using the default console driver, syscons, you can use a mouse pointer in text consoles to cut & paste text. Run the mouse daemon, moused, and turn on the mouse pointer in the virtual console: &prompt.root; moused -p /dev/xxxx -t yyyy &prompt.root; vidcontrol -m on Where xxxx is the mouse device name and yyyy is a protocol type for the mouse. See the &man.moused.8; man page for supported protocol types. You may wish to run the mouse daemon automatically when the system starts. In version 2.2.1, set the following variables in /etc/sysconfig. mousedtype="yyyy" mousedport="xxxx" mousedflags="" In versions 2.2.2 to 3.0, set the following variables in /etc/rc.conf. moused_type="yyyy" moused_port="xxxx" moused_flags="" In 3.1 and later, assuming you have a PS/2 mouse, all you need to is add moused_enable="YES" to /etc/rc.conf. In addition, if you would like to be able to use the mouse daemon on all virtual terminals instead of just console at boot-time, add the following to /etc/rc.conf. allscreens_flags="-m on" Staring from FreeBSD 2.2.6, the mouse daemon is capable of determining the correct protocol type automatically unless the mouse is a relatively old serial mouse model. Specify auto the protocol to invoke automatic detection. When the mouse daemon is running, access to the mouse needs to be coordinated between the mouse daemon and other programs such as the X Window. Refer to another section on this issue. How do I cut and paste text with mouse in the text console? Once you get the mouse daemon running (see previous section), hold down the button 1 (left button) and move the mouse to select a region of text. Then, press the button 2 (middle button) or the button 3 (right button) to paste it at the text cursor. In versions 2.2.6 and later, pressing the button 2 will paste the text. Pressing the button 3 will extend the selected region of text. If your mouse does not have the middle button, you may wish to emulate it or remap buttons using moused options. See the &man.moused.8; man page for details. Does FreeBSD support any USB mice? USB device support was added to FreeBSD 3.1. However, it is still in a preliminary state and may not always work as of version 3.2. If you want to experiment with the USB mouse support, follow the procedure described below. Use FreeBSD 3.2 or later. Add the following lines to your kernel configuration file, and rebuild the kernel. device uhci device ohci device usb device ums In versions of FreeBSD before 4.0, use this instead: controller uhci0 controller ohci0 controller usb0 device ums0 Go to the /dev directory and create a device node as follows: &prompt.root; cd /dev &prompt.root; ./MAKEDEV ums0 Edit /etc/rc.conf and add the following lines: moused_enable="YES" moused_type="auto" moused_port="/dev/ums0" moused_flags="" usbd_enable="YES" usbd_flags="" See the previous section for more detailed discussion on moused. In order to use the USB mouse in the X session, edit XF86Config. If you are using XFree86 3.3.2 or later, be sure to have the following lines in the Pointer section: Device "/dev/sysmouse" Protocol "Auto" If you are using earlier versions of XFree86, be sure to have the following lines in the Pointer section: Device "/dev/sysmouse" Protocol "SysMouse" Refer to another section on the mouse support in the X environment. Hot-plugging and unplugging of the USB mouse may not work quite right yet. It is a good idea connect the mouse before you start the system and leave it connected until the system is shutdown to avoid trouble. My mouse has a fancy wheel and buttons. Can I use them in FreeBSD? The answer is, unfortunately, It depends. These mice with additional features require specialized driver in most cases. Unless the mouse device driver or the user program has specific support for the mouse, it will act just like a standard two, or three button mouse. For the possible usage of wheels in the X Window environment, refer to that section. Why does my wheel-equipped PS/2 mouse cause my mouse cursor to jump around the screen? The PS/2 mouse driver psm in FreeBSD versions 3.2 or earlier has difficulty with some wheel mice, including Logitech model M-S48 and its OEM siblings. Apply the following patch to /sys/i386/isa/psm.c and rebuild the kernel. Index: psm.c =================================================================== RCS file: /src/CVS/src/sys/i386/isa/Attic/psm.c,v retrieving revision 1.60.2.1 retrieving revision 1.60.2.2 diff -u -r1.60.2.1 -r1.60.2.2 --- psm.c 1999/06/03 12:41:13 1.60.2.1 +++ psm.c 1999/07/12 13:40:52 1.60.2.2 @@ -959,14 +959,28 @@ sc->mode.packetsize = vendortype[i].packetsize; /* set mouse parameters */ +#if 0 + /* + * A version of Logitech FirstMouse+ won't report wheel movement, + * if SET_DEFAULTS is sent... Don't use this command. + * This fix was found by Takashi Nishida. + */ i = send_aux_command(sc->kbdc, PSMC_SET_DEFAULTS); if (verbose >= 2) printf("psm%d: SET_DEFAULTS return code:%04x\n", unit, i); +#endif if (sc->config & PSM_CONFIG_RESOLUTION) { sc->mode.resolution = set_mouse_resolution(sc->kbdc, - (sc->config & PSM_CONFIG_RESOLUTION) - 1); + (sc->config & PSM_CONFIG_RESOLUTION) - 1); + } else if (sc->mode.resolution >= 0) { + sc->mode.resolution + = set_mouse_resolution(sc->kbdc, sc->dflt_mode.resolution); + } + if (sc->mode.rate > 0) { + sc->mode.rate = set_mouse_sampling_rate(sc->kbdc, sc->dflt_mode.rate); } + set_mouse_scaling(sc->kbdc, 1); /* request a data packet and extract sync. bits */ if (get_mouse_status(sc->kbdc, stat, 1, 3) < 3) { Versions later than 3.2 should be all right. How do I use the mouse/trackball/touchpad on my laptop? Please refer to the answer to the previous question. And check out this note on the Mobile Computing page. What types of tape drives are supported? FreeBSD supports SCSI and QIC-36 (with a QIC-02 interface). This includes 8-mm (aka Exabyte) and DAT drives. Some of the early 8-mm drives are not quite compatible with SCSI-2, and may not work well with FreeBSD. Does FreeBSD support tape changers? FreeBSD 2.2 supports SCSI changers using the &man.ch.4; device and the &man.chio.1; command. The details of how you actually control the changer can be found in the &man.chio.1; man page. If you are not using AMANDA or some other product that already understands changers, remember that they only know how to move a tape from one point to another, so you need to keep track of which slot a tape is in, and which slot the tape currently in the drive needs to go back to. Which sound cards are supported by FreeBSD? FreeBSD supports the SoundBlaster, SoundBlaster Pro, SoundBlaster 16, Pro Audio Spectrum 16, AdLib and Gravis UltraSound sound cards. There is also limited support for MPU-401 and compatible MIDI cards. Cards conforming to the Microsoft Sound System specification are also supported through the pcm driver. This is only for sound! This driver does not support CDROMs, SCSI or joysticks on these cards, except for the SoundBlaster. The SoundBlaster SCSI interface and some non-SCSI CDROMS are supported, but you cannot boot off this device. Workarounds for no sound from es1370 with pcm driver? You can run the following command every time the machine booted up: &prompt.root; mixer pcm 100 vol 100 cd 100 Which network cards does FreeBSD support? See the Ethernet cards section of the handbook for a more complete list. I do not have a math co-processor - is that bad? This will only affect 386/486SX/486SLC owners - other machines will have one built into the CPU. In general this will not cause any problems, but there are circumstances where you will take a hit, either in performance or accuracy of the math emulation code (see the section on FP emulation). In particular, drawing arcs in X will be VERY slow. It is highly recommended that you buy a math co-processor; it is well worth it. Some math co-processors are better than others. It pains us to say it, but nobody ever got fired for buying Intel. Unless you are sure it works with FreeBSD, beware of clones. What other devices does FreeBSD support? See the Handbook for the list of other devices supported. Does FreeBSD support power management on my laptop? FreeBSD supports APM on certain machines. Please look in the LINT kernel config file, searching for the APM keyword. Further information can be found in &man.apm.4;. Why does my Micron system hang at boot time? Certain Micron motherboards have a non-conforming PCI BIOS implementation that causes grief when FreeBSD boots because PCI devices do not get configured at their reported addresses. Disable the Plug and Play Operating System flag in the BIOS to work around this problem. More information can be found at http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron Why does FreeBSD not recognize my Adaptec SCSI controller card? The newer AIC789x series Adaptec chips are supported under the CAM SCSI framework which made it's debut in 3.0. Patches against 2.2-STABLE are in ftp://ftp.FreeBSD.org/pub/FreeBSD/development/cam/. A CAM-enhanced boot floppy is available at http://people.FreeBSD.org/~abial/cam-boot/. In both cases read the README before beginning. How come FreeBSD cannot find my internal Plug & Play modem? You will need to add the modem's PnP ID to the PnP ID list in the serial driver. To enable Plug & Play support, compile a new kernel with controller pnp0 in the configuration file, then reboot the system. The kernel will print the PnP IDs of all the devices it finds. Copy the PnP ID from the modem to the table in /sys/i386/isa/sio.c, at about line 2777. Look for the string SUP1310 in the structure siopnp_ids[] to find the table. Build the kernel again, install, reboot, and your modem should be found. You may have to manually configure the PnP devices using the pnp command in the boot-time configuration with a command like pnp 1 0 enable os irq0 3 drq0 0 port0 0x2f8 to make the modem show. How do I get the boot: prompt to show on the serial console? Build a kernel with options COMCONSOLE. Create /boot.config and place as the only text in the file. Unplug the keyboard from the system. See /usr/src/sys/i386/boot/biosboot/README.serial for information. Why doesn't my 3Com PCI network card work with my Micron computer? Certain Micron motherboards have a non-conforming PCI BIOS implementation that does not configure PCI devices at the addresses reported. This causes grief when FreeBSD boots. To work around this problem, disable the Plug and Play Operating System flag in the BIOS. More information on this problem is available at URL: http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron Does FreeBSD support Symmetric Multiprocessing (SMP)? SMP is supported in 3.0-STABLE and later releases only. SMP is not enabled in the GENERIC kernel, so you will have to recompile your kernel to enable SMP. Take a look at /sys/i386/conf/LINT to figure out what options to put in your kernel config file. The boot floppy hangs on a system with an ASUS K7V motherboard. How do I fix this? Go in to the BIOS setup and disable the boot virus protection. Troubleshooting What do I do when I have bad blocks on my hard drive? With SCSI drives, the drive should be capable of re-mapping these automatically. However, many drives are shipped with this feature disabled, for some mysterious reason... To enable this, you will need to edit the first device page mode, which can be done on FreeBSD by giving the command (as root) &prompt.root; scsi -f /dev/rsd0c -m 1 -e -P 3 and changing the values of AWRE and ARRE from 0 to 1:- AWRE (Auto Write Reallocation Enbld): 1 ARRE (Auto Read Reallocation Enbld): 1 The following paragraphs were submitted by Ted Mittelstaedt tedm@toybox.placo.com: For IDE drives, any bad block is usually a sign of potential trouble. All modern IDE drives come with internal bad-block remapping turned on. All IDE hard drive manufacturers today offer extensive warranties and will replace drives with bad blocks on them. If you still want to attempt to rescue an IDE drive with bad blocks, you can attempt to download the IDE drive manufacturer's IDE diagnostic program, and run this against the drive. Sometimes these programs can be set to force the drive electronics to rescan the drive for bad blocks and lock them out. For ESDI, RLL and MFM drives, bad blocks are a normal part of the drive and are no sign of trouble, generally. With a PC, the disk drive controller card and BIOS handle the task of locking out bad sectors. This is fine for operating systems like DOS that use BIOS code to access the disk. However, FreeBSD's disk driver does not go through BIOS, therefore a mechanism, bad144, exists that replaces this functionality. bad144 only works with the wd driver (which means it is not supported in FreeBSD 4.0), it is NOT able to be used with SCSI. bad144 works by entering all bad sectors found into a special file. One caveat with bad144 - the bad block special file is placed on the last track of the disk. As this file may possibly contain a listing for a bad sector that would occur near the beginning of the disk, where the /kernel file might be located, it therefore must be accessible to the bootstrap program that uses BIOS calls to read the kernel file. This means that the disk with bad144 used on it must not exceed 1024 cylinders, 16 heads, and 63 sectors. This places an effective limit of 500MB on a disk that is mapped with bad144. To use bad144, simply set the Bad Block scanning to ON in the FreeBSD fdisk screen during the initial install. This works up through FreeBSD 2.2.7. The disk must have less than 1024 cylinders. It is generally recommended that the disk drive has been in operation for at least 4 hours prior to this to allow for thermal expansion and track wandering. If the disk has more than 1024 cylinders (such as a large ESDI drive) the ESDI controller uses a special translation mode to make it work under DOS. The wd driver understands about these translation modes, IF you enter the translated geometry with the set geometry command in fdisk. You must also NOT use the dangerously dedicated mode of creating the FreeBSD partition, as this ignores the geometry. Also, even though fdisk will use your overridden geometry, it still knows the true size of the disk, and will attempt to create a too large FreeBSD partition. If the disk geometry is changed to the translated geometry, the partition MUST be manually created with the number of blocks. A quick trick to use is to set up the large ESDI disk with the ESDI controller, boot it with a DOS disk and format it with a DOS partition. Then, boot the FreeBSD install and in the fdisk screen, read off and write down the blocksize and block numbers for the DOS partition. Then, reset the geometry to the same that DOS uses, delete the DOS partition, and create a cooperative FreeBSD partition using the blocksize you recorded earlier. Then, set the partition bootable and turn on bad block scanning. During the actual install, bad144 will run first, before any filesystems are created. (you can view this with an Alt-F2) If it has any trouble creating the badsector file, you have set too large a disk geometry - reboot the system and start all over again (including repartitioning and reformatting with DOS). If remapping is enabled and you are seeing bad blocks, consider replacing the drive. The bad blocks will only get worse as time goes on. How come FreeBSD does not recognize my Bustek 742a EISA SCSI controller? This info is specific to the 742a but may also cover other Buslogic cards. (Bustek = Buslogic) There are 2 general versions of the 742a card. They are hardware revisions A-G, and revisions H - onwards. The revision letter is located after the Assembly number on the edge of the card. The 742a has 2 ROM chips on it, one is the BIOS chip and the other is the Firmware chip. FreeBSD does not care what version of BIOS chip you have but it does care about what version of firmware chip. Buslogic will send upgrade ROMS out if you call their tech support dept. The BIOS and Firmware chips are shipped as a matched pair. You must have the most current Firmware ROM in your adapter card for your hardware revision. The REV A-G cards can only accept BIOS/Firmware sets up to 2.41/2.21. The REV H- up cards can accept the most current BIOS/Firmware sets of 4.70/3.37. The difference between the firmware sets is that the 3.37 firmware supports round robin The Buslogic cards also have a serial number on them. If you have a old hardware revision card you can call the Buslogic RMA department and give them the serial number and attempt to exchange the card for a newer hardware revision. If the card is young enough they will do so. FreeBSD 2.1 only supports Firmware revisions 2.21 onward. If you have a Firmware revision older than this your card will not be recognized as a Buslogic card. It may be recognized as an Adaptec 1540, however. The early Buslogic firmware contains an AHA1540 emulation mode. This is not a good thing for an EISA card, however. If you have an old hardware revision card and you obtain the 2.21 firmware for it, you will need to check the position of jumper W1 to B-C, the default is A-B. How come FreeBSD does not detect my HP Netserver's SCSI controller? This is basically a known problem. The EISA on-board SCSI controller in the HP Netserver machines occupies EISA slot number 11, so all the true EISA slots are in front of it. Alas, the address space for EISA slots >= 10 collides with the address space assigned to PCI, and FreeBSD's auto-configuration currently cannot handle this situation very well. So now, the best you can do is to pretend there is no address range clash :), by bumping the kernel option EISA_SLOTS to a value of 12. Configure and compile a kernel, as described in the Handbook entry on configuring the kernel. Of course, this does present you with a chicken-and-egg problem when installing on such a machine. In order to work around this problem, a special hack is available inside UserConfig. Do not use the visual interface, but the plain command-line interface there. Simply type eisa 12 quit at the prompt, and install your system as usual. While it is recommended you compile and install a custom kernel anyway. Hopefully, future versions will have a proper fix for this problem. You cannot use a dangerously dedicated disk with an HP Netserver. See this note for more info. What is going on with my CMD640 IDE controller? It is broken. It cannot handle commands on both channels simultaneously. There's a workaround available now and it is enabled automatically if your system uses this chip. For the details refer to the manual page of the disk driver (man 4 wd). If you are already running FreeBSD 2.2.1 or 2.2.2 with a CMD640 IDE controller and you want to use the second channel, build a new kernel with options "CMD640" enabled. This is the default for 2.2.5 and later. I keep seeing messages like ed1: timeout. What do these messages mean? This is usually caused by an interrupt conflict (e.g., two boards using the same IRQ). FreeBSD prior to 2.0.5R used to be tolerant of this, and the network driver would still function in the presence of IRQ conflicts. However, with 2.0.5R and later, IRQ conflicts are no longer tolerated. Boot with the -c option and change the ed0/de0/... entry to match your board. If you are using the BNC connector on your network card, you may also see device timeouts because of bad termination. To check this, attach a terminator directly to the NIC (with no cable) and see if the error messages go away. Some NE2000 compatible cards will give this error if there is no link on the UTP port or if the cable is disconnected. Why do I get Incorrect super block when mounting a CDROM? You have to tell &man.mount.8; the type of the device that you want to mount. By default, &man.mount.8; will assume the filesystem is of type ufs. You want to mount a CDROM filesystem, and you do this by specifying the option to &man.mount.8;. This does, of course, assume that the CDROM contains an ISO 9660 filesystem, which is what most CDROMs have. As of 1.1R, FreeBSD automatically understands the Rock Ridge (long filename) extensions as well. As an example, if you want to mount the CDROM device, /dev/cd0c, under /mnt, you would execute: &prompt.root; mount -t cd9660 /dev/cd0c /mnt Note that your device name (/dev/cd0c in this example) could be different, depending on the CDROM interface. Note that the option just causes the &man.mount.cd9660.8; command to be executed, and so the above example could be shortened to: &prompt.root; mount_cd9660 /dev/cd0c /mnt Why do I get Device not configured when mounting a CDROM? This generally means that there is no CDROM in the CDROM drive, or the drive is not visible on the bus. Feed the drive something, and/or check its master/slave status if it is IDE (ATAPI). It can take a couple of seconds for a CDROM drive to notice that it has been fed, so be patient. Sometimes a SCSI CDROM may be missed because it had not enough time to answer the bus reset. If you have a SCSI CDROM please try to add the following symbol into your kernel configuration file and recompile. options "SCSI_DELAY=15" Why do all non-English characters in filenames show up as ? on my CDs when mounted in FreeBSD? Most likely your CDROM uses the Joliet extension for storing information about files and directories. This extension specifies that all filenames are stored using Unicode two-byte characters. Currently, efforts are under way to introduce a generic Unicode interface into the FreeBSD kernel, but since that is not ready yet, the CD9660 driver does not have the ability to decode the characters in the filenames. As a temporary solution, starting with FreeBSD 4.3, a special hook has been added into the CD9660 driver to allow the user to load an appropriate conversion table on the fly. Modules for some of the common encodings are available via the sysutils/cd9660_unicode port. My printer is ridiculously slow. What can I do? If it is parallel, and the only problem is that it is terribly slow, try setting your printer port into polled mode: &prompt.root; lptcontrol -p Some newer HP printers are claimed not to work correctly in interrupt mode, apparently due to some (not yet exactly understood) timing problem. Why do my programs occasionally die with Signal 11 errors? Signal 11 errors are caused when your process has attempted to access memory which the operating system has not granted it access to. If something like this is happening at seemingly random intervals then you need to start investigating things very carefully. These problems can usually be attributed to either: If the problem is occurring only in a specific application that you are developing yourself it is probably a bug in your code. If it is a problem with part of the base FreeBSD system, it may also be buggy code, but more often than not these problems are found and fixed long before us general FAQ readers get to use these bits of code (that is what -current is for). In particular, a dead giveaway that this is *not* a FreeBSD bug is if you see the problem when you are compiling a program, but the activity that the compiler is carrying out changes each time. For example, suppose you are running make buildworld, and the compile fails while trying to compile ls.c in to ls.o. If you next run make buildworld again, and the compile fails in the same place then this is a broken build -- try updating your sources and try again. If the compile fails elsewhere then this is almost certainly hardware. What you should do: In the first case you can use a debugger e.g. gdb to find the point in the program which is attempting to access a bogus address and then fix it. In the second case you need to verify that it is not your hardware at fault. Common causes of this include: Your hard disks might be overheating: Check the fans in your case are still working, as your disk (and perhaps other hardware might be overheating). The processor running is overheating: This might be because the processor has been overclocked, or the fan on the processor might have died. In either case you need to ensure that you have hardware running at what it is specified to run at, at least while trying to solve this problem. i.e. Clock it back to the default settings. If you are overclocking then note that it is far cheaper to have a slow system than a fried system that needs replacing! Also the wider community is not often sympathetic to problems on overclocked systems, whether you believe it is safe or not. Dodgy memory: If you have multiple memory SIMMS/DIMMS installed then pull them all out and try running the machine with each SIMM or DIMM individually and narrow the problem down to either the problematic DIMM/SIMM or perhaps even a combination. Over-optimistic Motherboard settings: In your BIOS settings, and some motherboard jumpers you have options to set various timings, mostly the defaults will be sufficient, but sometimes, setting the wait states on RAM too low, or setting the RAM Speed: Turbo option, or similar in the BIOS will cause strange behaviour. A possible idea is to set to BIOS defaults, but it might be worth noting down your settings first! Unclean or insufficient power to the motherboard. If you have any unused I/O boards, hard disks, or CDROMs in your system, try temporarily removing them or disconnecting the power cable from them, to see if your power supply can manage a smaller load. Or try another power supply, preferably one with a little more power (for instance, if your current power supply is rated at 250 Watts try one rated at 300 Watts). You should also read the SIG11 FAQ (listed below) which has excellent explanations of all these problems, albeit from a Linux viewpoint. It also discusses how memory testing software or hardware can still pass faulty memory. Finally, if none of this has helped it is possible that you have just found a bug in FreeBSD, and you should follow the instructions to send a problem report. There is an extensive FAQ on this at the SIG11 problem FAQ Why does the screen go black and lose sync when I boot? This is a known problem with the ATI Mach 64 video card. The problem is that this card uses address 2e8, and the fourth serial port does too. Due to a bug (feature?) in the &man.sio.4; driver it will touch this port even if you do not have the fourth serial port, and even if you disable sio3 (the fourth port) which normally uses this address. Until the bug has been fixed, you can use this workaround: Enter at the boot prompt. (This will put the kernel into configuration mode). Disable sio0, sio1, sio2 and sio3 (all of them). This way the sio driver does not get activated -> no problems. Type exit to continue booting. If you want to be able to use your serial ports, you will have to build a new kernel with the following modification: in /usr/src/sys/i386/isa/sio.c find the one occurrence of the string 0x2e8 and remove that string and the preceding comma (keep the trailing comma). Now follow the normal procedure of building a new kernel. Even after applying these workarounds, you may still find that the X Window System does not work properly. If this is the case, make sure that the XFree86 version you are using is at least XFree86 3.3.3 or higher. This version and upwards has built-in support for the Mach64 cards and even a dedicated X server for those cards. How come FreeBSD uses only 64 MB of RAM when my system has 128 MB of RAM installed? Due to the manner in which FreeBSD gets the memory size from the BIOS, it can only detect 16 bits worth of Kbytes in size (65535 Kbytes = 64MB) (or less... some BIOSes peg the memory size to 16M). If you have more than 64MB, FreeBSD will attempt to detect it; however, the attempt may fail. To work around this problem, you need to use the kernel option specified below. There is a way to get complete memory information from the BIOS, but we do not have room in the bootblocks to do it. Someday when lack of room in the bootblocks is fixed, we will use the extended BIOS functions to get the full memory information...but for now we are stuck with the kernel option. options "MAXMEM=n" Where n is your memory in Kilobytes. For a 128 MB machine, you would want to use 131072. Why does FreeBSD 2.0 panic with kmem_map too small!? The message may also be mb_map too small! The panic indicates that the system ran out of virtual memory for network buffers (specifically, mbuf clusters). You can increase the amount of VM available for mbuf clusters by adding: options "NMBCLUSTERS=n" to your kernel config file, where n is a number in the range 512-4096, depending on the number of concurrent TCP connections you need to support. I would recommend trying 2048 - this should get rid of the panic completely. You can monitor the number of mbuf clusters allocated/in use on the system with netstat -m (see &man.netstat.1;). The default value for NMBCLUSTERS is 512 + MAXUSERS * 16. Why do I get an error reading CMAP busy when rebooting with a new kernel? The logic that attempts to detect an out of date /var/db/kvm_*.db files sometimes fails and using a mismatched file can sometimes lead to panics. If this happens, reboot single-user and do: &prompt.root; rm /var/db/kvm_*.db What does the message ahc0: brkadrint, Illegal Host Access at seqaddr 0x0 mean? This is a conflict with an Ultrastor SCSI Host Adapter. During the boot process enter the kernel configuration menu and disable uha0, which is causing the problem. Why does Sendmail give me an error reading mail loops back to myself? This is answered in the sendmail FAQ as follows:- * I'm getting "Local configuration error" messages, such as: 553 relay.domain.net config error: mail loops back to myself 554 <user@domain.net>... Local configuration error How can I solve this problem? You have asked mail to the domain (e.g., domain.net) to be forwarded to a specific host (in this case, relay.domain.net) by using an MX record, but the relay machine doesn't recognize itself as domain.net. Add domain.net to /etc/sendmail.cw (if you are using FEATURE(use_cw_file)) or add "Cw domain.net" to /etc/sendmail.cf. The current version of the sendmail FAQ is no longer maintained with the sendmail release. It is however regularly posted to comp.mail.sendmail, comp.mail.misc, comp.mail.smail, comp.answers, and news.answers. You can also receive a copy via email by sending a message to mail-server@rtfm.mit.edu with the command send usenet/news.answers/mail/sendmail-faq as the body of the message. Why do full screen applications on remote machines misbehave? The remote machine may be setting your terminal type to something other than the cons25 terminal type required by the FreeBSD console. There are a number of possible work-arounds for this problem: After logging on to the remote machine, set your TERM shell variable to ansi or sco if the remote machine knows about these terminal types. Use a VT100 emulator like screen at the FreeBSD console. screen offers you the ability to run multiple concurrent sessions from one terminal, and is a neat program in its own right. Each screen window behaves like a VT100 terminal, so the TERM variable at the remote end should be set to vt100. Install the cons25 terminal database entry on the remote machine. The way to do this depends on the operating system on the remote machine. The system administration manuals for the remote system should be able to help you here. Fire up an X server at the FreeBSD end and login to the remote machine using an X based terminal emulator such as xterm or rxvt. The TERM variable at the remote host should be set to xterm or vt100. Why does my machine print calcru: negative time...? This can be caused by various hardware and/or software ailments relating to interrupts. It may be due to bugs but can also happen by nature of certain devices. Running TCP/IP over the parallel port using a large MTU is one good way to provoke this problem. Graphics accelerators can also get you here, in which case you should check the interrupt setting of the card first. A side effect of this problem are dying processes with the message SIGXCPU exceeded cpu time limit. For FreeBSD 3.0 and later from Nov 29, 1998 forward: If the problem cannot be fixed otherwise the solution is to set this sysctl variable: &prompt.root; sysctl -w kern.timecounter.method=1 This means a performance impact, but considering the cause of this problem, you probably will not notice. If the problem persists, keep the sysctl set to one and set the NTIMECOUNTER option in your kernel to increasingly large values. If by the time you have reached NTIMECOUNTER=20 the problem is not solved, interrupts are too hosed on your machine for reliable timekeeping. I see pcm0 not found or my sound card is found as pcm1 but I have device pcm0 in my kernel config file. What is going on? This occurs in FreeBSD 3.x with PCI sound cards. The pcm0 device is reserved exclusively for ISA-based cards so, if you have a PCI card, then you will see this error, and your card will appear as pcm1. You cannot remove the warning by simply changing the line in the kernel config file to device pcm1 as this will result in pcm1 being reserved for ISA cards and your PCI card being found as pcm2 (along with the warning pcm1 not found). If you have a PCI sound card you will also have to make the snd1 device rather than snd0: &prompt.root; cd /dev &prompt.root; ./MAKEDEV snd1 This situation does not arise in FreeBSD 4.x as has a lot of work has been done to make the it more PnP-centric and the pcm0 device is no longer reserved exclusively for ISA cards Why is my PnP card no longer found (or found as unknown) since upgrading to FreeBSD 4.x? FreeBSD 4.x is now much more PnP-centric and this has had the side effect of some PnP devices (e.g. sound cards and internal modems) not working even though they worked under FreeBSD 3.x. The reasons for this behaviour are explained by the following e-mail, posted to the freebsd-questions mailing list by Peter Wemm, in answer to a question about an internal modem that was no longer found after an upgrade to FreeBSD 4.x (the comments in [] have been added to clarify the context.
The PNP bios preconfigured it [the modem] and left it laying around in port space, so [in 3.x] the old-style ISA probes found it there. Under 4.0, the ISA code is much more PnP-centric. It was possible [in 3.x] for an ISA probe to find a stray device and then for the PNP device id to match and then fail due to resource conflicts. So, it disables the programmable cards first so this double probing cannot happen. It also means that it needs to know the PnP id's for supported PnP hardware. Making this more user tweakable is on the TODO list.
To get the device working again requires finding its PnP id and adding it to the list that the ISA probes use to identify PnP devices. This is obtained using &man.pnpinfo.8; to probe the device, for example this is the output from &man.pnpinfo.8; for an internal modem: &prompt.root; pnpinfo Checking for Plug-n-Play devices... Card assigned CSN #1 Vendor ID PMC2430 (0x3024a341), Serial Number 0xffffffff PnP Version 1.0, Vendor Version 0 Device Description: Pace 56 Voice Internal Plug & Play Modem Logical Device ID: PMC2430 0x3024a341 #0 Device supports I/O Range Check TAG Start DF I/O Range 0x3f8 .. 0x3f8, alignment 0x8, len 0x8 [16-bit addr] IRQ: 4 - only one type (true/edge) [more TAG lines elided] TAG End DF End Tag Successfully got 31 resources, 1 logical fdevs -- card select # 0x0001 CSN PMC2430 (0x3024a341), Serial Number 0xffffffff Logical device #0 IO: 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 IRQ 5 0 DMA 4 0 IO range check 0x00 activate 0x01 The information you require is in the Vendor ID line at the start of the output. The hexadecimal number in parentheses (0x3024a341 in this example) is the PnP id and the string immediately before this (PMC2430) is a unique ASCII id. This information needs adding to the file /usr/src/sys/isa/sio.c. You should first make a backup of sio.c just in case things go wrong. You will also need it to make the patch to submit with your PR (you are going to submit a PR, aren't you?) then edit sio.c and search for the line static struct isa_pnp_id sio_ids[] = { then scroll down to find the correct place to add the entry for your device. The entries look like this, and are sorted on the ASCII Vendor ID string which should be included in the comment to the right of the line of code along with all (if it will fit) or part of the Device Description from the output of &man.pnpinfo.8;: {0x0f804f3f, NULL}, /* OZO800f - Zoom 2812 (56k Modem) */ {0x39804f3f, NULL}, /* OZO8039 - Zoom 56k flex */ {0x3024a341, NULL}, /* PMC2430 - Pace 56 Voice Internal Modem */ {0x1000eb49, NULL}, /* ROK0010 - Rockwell ? */ {0x5002734a, NULL}, /* RSS0250 - 5614Jx3(G) Internal Modem */ Add the hexadecimal Vendor ID for your device in the correct place, save the file, rebuild your kernel, and reboot. Your device should now be found as an sio device as it was under FreeBSD 3.x Why do I get the error nlist failed when running, for example, top or systat? The problem is that the application you are trying to run is looking for a specific kernel symbol, but, for whatever reason, cannot find it; this error stems from one of two problems: Your kernel and userland are not synchronized (i.e., you built a new kernel but did not do an installworld, or vice versa), and thus the symbol table is different from what the user application thinks it is. If this is the case, simply complete the upgrade process (see /usr/src/UPDATING for the correct sequence). You are not using /boot/loader to load your kernel, but doing it directly from boot2 (see &man.boot.8;). While there is nothing wrong with bypassing /boot/loader, it generally does a better job of making the kernel symbols available to user applications. Why does it take so long to connect to my computer via ssh or telnet? The symptom: there is a long delay between the time the TCP connection is established and the time when the client software asks for a password (or, in &man.telnet.1;'s case, when a login prompt appears). The problem: more likely than not, the delay is caused by the server software trying to resolve the client's IP address into a hostname. Many servers, including the Telnet and SSH servers that come with FreeBSD, do this in order to, among other things, store the hostname in a log file for future reference by the administrator. The remedy: if the problem occurs whenever you connect from your computer (the client) to any server, the problem is with the client; likewise, if the problem only occurs when someone connects to your computer (the server) the problem is with the server. If the problem is with the client, the only remedy is to fix the DNS so the server can resolve it. If this is on a local network, consider it a server problem and keep reading; conversely, if this is on the global Internet, you will most likely need to contact your ISP and ask them to fix it for you. If the problem is with the server, and this is on a local network, you need to configure the server to be able to resolve address-to-hostname queries for your local address range. See the &man.hosts.5; and &man.named.8; manual pages for more information. If this is on the global Internet, the problem may be that your server's resolver is not functioning correctly. To check, try to look up another host--say, www.yahoo.com. If it does not work, that is your problem. Why does file: table is full show up repeatedly in dmesg? This error is caused when you have exhausted the number of available file descriptors on your system. The file table in memory is full. The solution: Manually adjust the kern.maxfiles kernel limit setting. &prompt.root; sysctl -w kern.maxfiles=n Adjust n according to your system needs. Each open file, socket, or fifo uses one file descriptor. A large-scale server may easily require tens of thousands of file descriptors (10,000+), depending on the kind and number of services running concurrently. The number of default file descriptors set in the kernel is dictated by the maxusers 32 maxusers line in your kernel config file. Increasing this will proportionally increase kern.maxfiles. You can see what kern.maxfiles is currently set to by: &prompt.root; sysctl kern.maxfiles kern.maxfiles: 1064 Why does the clock on my laptop keep incorrect time? Your laptop has two or more clocks, and FreeBSD has chosen to use the wrong one. Run &man.dmesg.8;, and check for lines that contain Timecounter. The last line printed is the one that FreeBSD chose, and will almost certainly be TSC. &prompt.root; dmesg | grep Timecounter Timecounter "i8254" frequency 1193182 Hz Timecounter "TSC" frequency 595573479 Hz You can confirm this by checking the kern.timecounter.hardware &man.sysctl.3;. &prompt.root; sysctl kern.timecounter.hardware kern.timecounter.hardware: TSC The BIOS may modify the TSC clock—perhaps to change the speed of the processor when running from batteries, or going in to a power saving mode, but FreeBSD is unaware of these adjustments, and appears to gain or lose time. In this example, the i8254 clock is also available, and can be selected by writing its name to the kern.timecounter.hardware &man.sysctl.3;. &prompt.root; sysctl -w kern.timecounter.hardware=i8254 kern.timecounter.hardware: TSC -> i8254 Your laptop should now start keeping more accurate time. To have this change automatically run at boot time, add the following line to /etc/sysctl.conf. kern.timecounter.hardware=i8254 Why does FreeBSD's boot loader display Read error and stop after the BIOS screen? FreeBSD's boot loader is incorrectly recognizing the hard drive's geometry. This must be manually set within fdisk when creating or modifying FreeBSD's slice. The correct drive geometry values can be found within the machine's BIOS. Look for the number of cylinders, heads and sectors for the particular drive. Within &man.sysinstall.8;'s fdisk, hit G to set the drive geometry. A dialog will pop up requesting the number of cylinders, heads and sectors. Type the numbers found from the BIOS separates by forward slashes. 5000 cylinders, 250 sectors and 60 sectors would be entered as 5000/250/60 Press enter to set the values, and hit W to write the new partition table to the drive. Another operating system destroyed my Boot Manager. How do I get it back? Enter &man.sysinstall.8; and choose Configure, then Fdisk. Select the disk the Boot Manager resided on with the space key. Press W to write changes to the drive. A prompt will appear asking which boot loader to install. Select this, and it will be restored. Commercial Applications This section is still very sparse, though we are hoping, of course, that companies will add to it! :) The FreeBSD group has no financial interest in any of the companies listed here but simply lists them as a public service (and feels that commercial interest in FreeBSD can have very positive effects on FreeBSD's long-term viability). We encourage commercial software vendors to send their entries here for inclusion. See the Vendors page for a longer list. Where can I get an Office Suite for FreeBSD? The FreeBSD Mall offers a FreeBSD native version of VistaSource ApplixWare 5. ApplixWare is a rich full-featured, commercial Office Suite for FreeBSD containing a word processor, spreadsheet, presentation program, vector drawing package, and other applications. You can purchase ApplixWare for FreeBSD here. The Linux version of StarOffice works flawlessly on FreeBSD. The easiest way to install the Linux version of StarOffice is through the FreeBSD Ports collection. Future versions of the open-source OpenOffice suite should work as well. Where can I get Motif for FreeBSD? The Open Group has released the source code to Motif 2.1.30. You can install the open-motif package, or compile it from ports. Refer to the ports section of the Handbook for more information on how to do this. The Open Motif distribution only allows redistribution if it is running on an open source operating system. In addition, there are commercial distributions of the Motif software available. These, however, are not for free, but their license allows them to be used in closed-source software. Contact Apps2go for the least expensive ELF Motif 2.1.20 distribution for FreeBSD (either i386 or Alpha). There are two distributions, the developement edition and the runtime edition (for much less). These distributions includes: OSF/Motif manager, xmbind, panner, wsm. Development kit with uil, mrm, xm, xmcxx, include and Imake files. Static and dynamic ELF libraries (for use with FreeBSD 3.0 and above). Demonstration applets. Be sure to specify that you want the FreeBSD version of Motif when ordering (do not forget to mention the architecture you want too)! Versions for NetBSD and OpenBSD are also sold by Apps2go. This is currently a FTP only download. More info Apps2go WWW page or sales@apps2go.com or support@apps2go.com or phone (817) 431 8775 or +1 817 431-8775 Contact Metro Link for an either ELF or a.out Motif 2.1 distribution for FreeBSD. This distribution includes: OSF/Motif manager, xmbind, panner, wsm. Development kit with uil, mrm, xm, xmcxx, include and Imake files. Static and dynamic libraries (specify ELF for use with FreeBSD 3.0 and later; or a.out for use with FreeBSD 2.2.8 and earlier). Demonstration applets. Preformatted man pages. Be sure to specify that you want the FreeBSD version of Motif when ordering! Versions for Linux are also sold by Metro Link. This is available on either a CDROM or for FTP download. Contact Xi Graphics for an a.out Motif 2.0 distribution for FreeBSD. This distribution includes: OSF/Motif manager, xmbind, panner, wsm. Development kit with uil, mrm, xm, xmcxx, include and Imake files. Static and dynamic libraries (for use with FreeBSD 2.2.8 and earlier). Demonstration applets. Preformatted man pages. Be sure to specify that you want the FreeBSD version of Motif when ordering! Versions for BSDI and Linux are also sold by Xi Graphics. This is currently a 4 diskette set... in the future this will change to a unified CD distribution like their CDE. Where can I get CDE for FreeBSD? Xi Graphics used to sell CDE for FreeBSD, but no longer do. KDE is an open source X11 desktop which is similar to CDE in many respects. You might also like the look and feel of xfce. KDE and xfce are both in the ports system. Are there any commercial high-performance X servers? Yes, Xi Graphics and Metro Link sells Accelerated-X product for FreeBSD and other Intel based systems. The Metro Link offering is a high performance X Server that offers easy configuration using the FreeBSD Package suite of tools, support for multiple concurrent video boards and is distributed in binary form only, in a convenient FTP download. Not to mention the Metro Link offering is available at the very reasonable price of $39. Metro Link also sells both ELF and a.out Motif for FreeBSD (see above). More info Metro Link WWW page or sales@metrolink.com or tech@metrolink.com or phone (954) 938-0283 or +1 954 938-0283 The Xi Graphics offering is a high performance X Server that offers easy configuration, support for multiple concurrent video boards and is distributed in binary form only, in a unified diskette distribution for FreeBSD and Linux. Xi Graphics also offers a high performance X Server tailored for laptop support. There is a free compatibility demo of version 5.0 available. Xi Graphics also sells Motif and CDE for FreeBSD (see above). More info Xi Graphics WWW page or sales@xig.com or support@xig.com or phone (800) 946 7433 or +1 303 298-7478. Are there any Database systems for FreeBSD? Yes! See the Commercial Vendors section of FreeBSD's Web site. Also see the Databases section of the Ports collection. Can I run Oracle on FreeBSD? Yes. The following pages tell you exactly how to setup Linux-Oracle on FreeBSD: http://www.scc.nl/~marcel/howto-oracle.html http://www.lf.net/lf/pi/oracle/install-linux-oracle-on-freebsd User Applications So, where are all the user applications? Please take a look at the ports page for info on software packages ported to FreeBSD. The list currently tops 3400 and is growing daily, so come back to check often or subscribe to the freebsd-announce mailing list for periodic updates on new entries. Most ports should be available for the 2.2, 3.x and 4.x branches, and many of them should work on 2.1.x systems as well. Each time a FreeBSD release is made, a snapshot of the ports tree at the time of release in also included in the ports/ directory. We also support the concept of a package, essentially no more than a gzipped binary distribution with a little extra intelligence embedded in it for doing whatever custom installation work is required. A package can be installed and uninstalled again easily without having to know the gory details of which files it includes. Use the package installation menu in /stand/sysinstall (under the post-configuration menu item) or invoke the &man.pkg.add.1; command on the specific package files you are interested in installing. Package files can usually be identified by their .tgz suffix and CDROM distribution people will have a packages/All directory on their CD which contains such files. They can also be downloaded over the net for various versions of FreeBSD at the following locations: for 2.2.8-RELEASE/2.2.8-STABLE ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-2.2.8/ for 3.X-RELEASE/3.X-STABLE ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-3-stable/ for 4.X-RELEASE/4-STABLE ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-4-stable/ for 5.X-CURRENT ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-5-current or your nearest local mirror site. Note that all ports may not be available as packages since new ones are constantly being added. It is always a good idea to check back periodically to see which packages are available at the ftp.FreeBSD.org master site. Why is /bin/sh so minimal? Why doesn't FreeBSD use bash or another shell? Because POSIX says that there shall be such a shell. The more complicated answer: many people need to write shell scripts which will be portable across many systems. That is why POSIX specifies the shell and utility commands in great detail. Most scripts are written in Bourne shell, and because several important programming interfaces (&man.make.1;, &man.system.3;, &man.popen.3;, and analogues in higher-level scripting languages like Perl and Tcl) are specified to use the Bourne shell to interpret commands. Because the Bourne shell is so often and widely used, it is important for it to be quick to start, be deterministic in its behavior, and have a small memory footprint. The existing implementation is our best effort at meeting as many of these requirements simultaneously as we can. In order to keep /bin/sh small, we have not provided many of the convenience features that other shells have. That is why the Ports Collection includes more featureful shells like bash, scsh, tcsh, and zsh. (You can compare for yourself the memory utilization of all these shells by looking at the VSZ and RSS columns in a ps -u listing.) Where do I find libc.so.3.0? You are trying to run a package built on 2.2 and later on a 2.1.x system. Please take a look at the previous section and get the correct port/package for your system. Why do I get a message reading Error: can't find libc.so.4.0? You accidently downloaded packages meant for 4.X and 5.X systems and attempted to install them on your 2.X or 3.X FreeBSD system. Please download the correct version of the packages. Why does ghostscript give lots of errors with my 386/486SX? You do not have a math co-processor, right? You will need to add the alternative math emulator to your kernel; you do this by adding the following to your kernel config file and it will be compiled in. options GPL_MATH_EMULATE You will need to remove the MATH_EMULATE option when you do this. Why do SCO/iBCS2 applications bomb on socksys? (FreeBSD 3.0 and older only). You first need to edit the /etc/sysconfig (or /etc/rc.conf, see &man.rc.conf.5;) file in the last section to change the following variable to YES: # Set to YES if you want ibcs2 (SCO) emulation loaded at startup ibcs2=NO It will load the ibcs2 kernel module at startup. You will then need to set up /compat/ibcs2/dev to look like: lrwxr-xr-x 1 root wheel 9 Oct 15 22:20 X0R@ -> /dev/null lrwxr-xr-x 1 root wheel 7 Oct 15 22:20 nfsd@ -> socksys -rw-rw-r-- 1 root wheel 0 Oct 28 12:02 null lrwxr-xr-x 1 root wheel 9 Oct 15 22:20 socksys@ -> /dev/null crw-rw-rw- 1 root wheel 41, 1 Oct 15 22:14 spx You just need socksys to go to /dev/null (see &man.null.4;) to fake the open & close. The code in -CURRENT will handle the rest. This is much cleaner than the way it was done before. If you want the spx driver for a local socket X connection, define SPX_HACK when you compile the system. How do I configure INN (Internet News) for my machine? After installing the inn package or port, an excellent place to start is Dave Barr's INN Page where you will find the INN FAQ. What version of Microsoft FrontPage should I get? Use the Port, Luke! A pre-patched version of Apache is available in the ports tree. Does FreeBSD support Java? Yes. Please see http://www.FreeBSD.org/java/. Why can't I build this port on my 3.X-STABLE machine? If you are running a FreeBSD version that lags significantly behind -CURRENT or -STABLE, you may need a ports upgrade kit from http://www.FreeBSD.org/ports/. If you are up to date, then someone might have committed a change to the port which works for -CURRENT but which broke the port for -STABLE. Please submit a bug report on this with the &man.send-pr.1; command, since the ports collection is supposed to work for both the -CURRENT and -STABLE branches. Where do I find ld.so? If you want to run some aout applications like Netscape Navigator on an Elf'ened machine such as 3.1-R or later, it would need /usr/libexec/ld.so and some aout libs. They are included in the compat22 distribution. Use /stand/sysinstall or install.sh in the compat22 subdirectory and install it. Also read ERRATAs for 3.1-R and 3.2-R. I updated the sources, now how do I update my installed ports? Unfortunately, there is no easy way to update installed ports. The &man.pkg.version.1; command can be used to generate a script that will update the installed ports with a newer version in the ports tree: &prompt.root; pkg_version > /tmp/myscript The output script must be edited by hand before you use it. Current versions of &man.pkg.version.1; force this by inserting an &man.exit.1; at the beginning of the script. You should save the output of the script, as it will note packages that depend on the one that has been updated. These may or may not need to be updated as well. The usual case where they need to be updated is that a shared library has changed version numbers, so the ports that used that library need to be rebuilt to use the new version. If your system is up full time, the &man.periodic.8 system can be used to generate a weekly list of ports that might need updating by setting weekly_status_pkg_enable="YES" in /etc/periodic.conf. Kernel Configuration I would like to customize my kernel. Is it difficult? Not at all! Check out the kernel config section of the Handbook. It is recommended that you make a dated snapshot of your kernel in kernel.YYMMDD after you get it all working, that way if you do something dire the next time you play with your configuration you can boot that kernel instead of having to go all the way back to kernel.GENERIC. This is particularly important if you are now booting off a controller that is not supported in the GENERIC kernel. My kernel compiles fail because _hw_float is missing. How do I solve this problem? Let me guess. You removed npx0 (see &man.npx.4;) from your kernel configuration file because you do not have a math co-processor, right? Wrong! :-) The npx0 is MANDATORY. Even if you do not have a mathematic co-processor, you must include the npx0 device. Why is my kernel so big (over 10MB)? Chances are, you compiled your kernel in debug mode. Kernels built in debug mode contain many symbols that are used for debugging, thus greatly increasing the size of the kernel. Note that if you running a FreeBSD 3.0 or later system, there will be little or no performance decrease from running a debug kernel, and it is useful to keep one around in case of a system panic. However, if you are running low on disk space, or you simply do not want to run a debug kernel, make sure that both of the following are true: You do not have a line in your kernel configuration file that reads: makeoptions DEBUG=-g You are not running &man.config.8; with the option. Both of the above situations will cause your kernel to be built in debug mode. As long as you make sure you follow the steps above, you can build your kernel normally, and you should notice a fairly large size decrease; most kernels tend to be around 1.5MB to 2MB. Why do I get interrupt conflicts with multi-port serial code? When I compile a kernel with multi-port serial code, it tells me that only the first port is probed and the rest skipped due to interrupt conflicts. How do I fix this? The problem here is that FreeBSD has code built-in to keep the kernel from getting trashed due to hardware or software conflicts. The way to fix this is to leave out the IRQ settings on all but one port. Here is a example: # # Multiport high-speed serial line - 16550 UARTS # device sio2 at isa? port 0x2a0 tty irq 5 flags 0x501 vector siointr device sio3 at isa? port 0x2a8 tty flags 0x501 vector siointr device sio4 at isa? port 0x2b0 tty flags 0x501 vector siointr device sio5 at isa? port 0x2b8 tty flags 0x501 vector siointr Why does every kernel I try to build fail to compile, even GENERIC? There are a number of possible causes for this problem. They are, in no particular order: You are not using the new make buildkernel and make installkernel targets, and your source tree is different from the one used to build the currently running system (e.g., you are compiling 4.3-RELEASE on a 4.0-RELEASE system). If you are attempting an upgrade, please read the /usr/src/UPDATING file, paying particular attention to the COMMON ITEMS section at the end. You are using the new make buildkernel and make installkernel targets, but you failed to assert the completion of the make buildworld target. The make buildkernel target relies on files generated by the make buildworld target to complete its job correctly. Even if you are trying to build FreeBSD-STABLE, it is possible that you fetched the source tree at a time when it was either being modified, or broken for other reasons; only releases are absolutely guaranteed to be buildable, although FreeBSD-STABLE builds fine the majority of the time. If you have not already done so, try re-fetching the source tree and see if the problem goes away. Try using a different server in case the one you are using is having problems. System Administration Where are the system start-up configuration files? From 2.0.5R to 2.2.1R, the primary configuration file is /etc/sysconfig. All the options are to be specified in this file and other files such as /etc/rc (see &man.rc.8;) and /etc/netstart just include it. Look in the /etc/sysconfig file and change the value to match your system. This file is filled with comments to show what to put in there. In post-2.2.1 and 3.0, /etc/sysconfig was renamed to a more self-describing &man.rc.conf.5; file and the syntax cleaned up a bit in the process. /etc/netstart was also renamed to /etc/rc.network so that all files could be copied with a cp /usr/src/etc/rc* /etc command. And, in 3.1 and later, /etc/rc.conf has been moved to /etc/defaults/rc.conf. Do not edit this file! Instead, if there is any entry in /etc/defaults/rc.conf that you want to change, you should copy the line into /etc/rc.conf and change it there. For example, if you wish to start named, the DNS server included with FreeBSD in FreeBSD 3.1 or later, all you need to do is: &prompt.root; echo named_enable="YES" >> /etc/rc.conf To start up local services in FreeBSD 3.1 or later, place shell scripts in the /usr/local/etc/rc.d directory. These shell scripts should be set executable, and end with a .sh. In FreeBSD 3.0 and earlier releases, you should edit the /etc/rc.local file. The /etc/rc.serial is for serial port initialization (e.g. locking the port characteristics, and so on.). The /etc/rc.i386 is for Intel-specifics settings, such as iBCS2 emulation or the PC system console configuration. How do I add a user easily? Use the &man.adduser.8; command. For more complicated usage, the &man.pw.8; command. To remove the user again, use the &man.rmuser.8; command. Once again, &man.pw.8; will work as well. How can I add my new hard disk to my FreeBSD system? See the Disk Formatting Tutorial at www.FreeBSD.org. I have a new removable drive, how do I use it? Whether it is a removable drive like a ZIP or an EZ drive (or even a floppy, if you want to use it that way), or a new hard disk, once it is installed and recognized by the system, and you have your cartridge/floppy/whatever slotted in, things are pretty much the same for all devices. (this section is based on Mark Mayo's ZIP FAQ) If it is a ZIP drive or a floppy , you have already got a DOS filesystem on it, you can use a command like this: &prompt.root; mount -t msdos /dev/fd0c /floppy if it is a floppy, or this: &prompt.root; mount -t msdos /dev/da2s4 /zip for a ZIP disk with the factory configuration. For other disks, see how they are laid out using &man.fdisk.8; or &man.sysinstall.8;. The rest of the examples will be for a ZIP drive on da2, the third SCSI disk. Unless it is a floppy, or a removable you plan on sharing with other people, it is probably a better idea to stick a BSD file system on it. You will get long filename support, at least a 2X improvement in performance, and a lot more stability. First, you need to redo the DOS-level partitions/filesystems. You can either use &man.fdisk.8; or /stand/sysinstall, or for a small drive that you do not want to bother with multiple operating system support on, just blow away the whole FAT partition table (slices) and just use the BSD partitioning: &prompt.root; dd if=/dev/zero of=/dev/rda2 count=2 &prompt.root; disklabel -Brw da2 auto You can use disklabel or /stand/sysinstall to create multiple BSD partitions. You will certainly want to do this if you are adding swap space on a fixed disk, but it is probably irrelevant on a removable drive like a ZIP. Finally, create a new file system, this one is on our ZIP drive using the whole disk: &prompt.root; newfs /dev/rda2c and mount it: &prompt.root; mount /dev/da2c /zip and it is probably a good idea to add a line like this to /etc/fstab (see &man.fstab.5;) so you can just type mount /zip in the future: /dev/da2c /zip ffs rw,noauto 0 0 Why do I keep getting messages like root: not found after editing my crontab file? This is normally caused by editing the system crontab (/etc/crontab) and then using &man.crontab.1; to install it: &prompt.root; crontab /etc/crontab This is not the correct way to do things. The system crontab has a different format to the per-user crontabs which &man.crontab.1; updates (the &man.crontab.5; manual page explains the differences in more detail). If this is what you did, the extra crontab is simply a copy of /etc/crontab in the wrong format it. Delete it with the command: &prompt.root; crontab -r Next time, when you edit /etc/crontab, you should not do anything to inform &man.cron.8; of the changes, since it will notice them automatically. If you want something to be run once per day, week, or month, it is probably better to add shell scripts /usr/local/etc/periodic, and let the &man.periodic.8; command run from the system cron schedule it with the other periodic system tasks. The actual reason for the error is that the system crontab has an extra field, specifying which user to run the command as. In the default system crontab provided with FreeBSD, this is root for all entries. When this crontab is used as the root user's crontab (which is not the same as the system crontab), &man.cron.8; assumes the string root is the first word of the command to execute, but no such command exists. Why do I get the error, you are not in the correct group to su root when I try to su to root? This is a security feature. In order to su to root (or any other account with superuser privileges), you must be in the wheel group. If this feature were not there, anybody with an account on a system who also found out root's password would be able to gain superuser level access to the system. With this feature, this is not strictly true; &man.su.1; will prevent them from even trying to enter the password if they are not in wheel. To allow someone to su to root, simply put them in the wheel group. I made a mistake in rc.conf, or another startup file, and now I cannot edit it because the filesystem is read-only. What should I do? When you get the prompt to enter the shell pathname, simply press ENTER, and run mount / to re-mount the root filesystem in read/write mode. You may also need to run mount -a -t ufs to mount the filesystem where your favourite editor is defined. If your favourite editor is on a network filesystem, you will need to either configure the network manually before you can mount network filesystems, or use an editor which resides on a local filesystem, such as &man.ed.1;. If you intend to use a full screen editor such as &man.vi.1; or &man.emacs.1;, you may also need to run export TERM=cons25 so that these editors can load the correct data from the &man.termcap.5; database. Once you have performed these steps, you can edit /etc/rc.conf as you usually would to fix the syntax error. The error message displayed immediately after the kernel boot messages should tell you the number of the line in the file which is at fault. How do I mount a secondary DOS partition? The secondary DOS partitions are found after ALL the primary partitions. For example, if you have an E partition as the second DOS partition on the second SCSI drive, you need to create the special files for slice 5 in /dev, then mount /dev/da1s5: &prompt.root; cd /dev &prompt.root; sh MAKEDEV da1s5 &prompt.root; mount -t msdos /dev/da1s5 /dos/e Can I mount other foreign filesystems under FreeBSD? Digital UNIX UFS CDROMs can be mounted directly on FreeBSD. Mounting disk partitions from Digital UNIX and other systems that support UFS may be more complex, depending on the details of the disk partitioning for the operating system in question. Linux As of 2.2, FreeBSD supports ext2fs partitions. See &man.mount.ext2fs.8; for more information. NT A read-only NTFS driver exists for FreeBSD. For more information, see this tutorial by Mark Ovens at http://ukug.uk.freebsd.org/~mark/ntfs_install.html. Any other information on this subject would be appreciated. How can I use the NT loader to boot FreeBSD? This procedure is slightly different for 2.2.x and 3.x (with the 3-stage boot) systems. The general idea is that you copy the first sector of your native root FreeBSD partition into a file in the DOS/NT partition. Assuming you name that file something like c:\bootsect.bsd (inspired by c:\bootsect.dos), you can then edit the c:\boot.ini file to come up with something like this: [boot loader] timeout=30 default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS [operating systems] multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT" C:\BOOTSECT.BSD="FreeBSD" C:\="DOS" For 2.2.x systems this procedure assumes that DOS, NT, FreeBSD, or whatever have been installed into their respective fdisk partitions on the same disk. This example was tested on a system where DOS & NT were on the first fdisk partition, and FreeBSD on the second. FreeBSD was also set up to boot from its native partition, not the disk's MBR. Mount a DOS-formatted floppy (if you have converted to NTFS) or the FAT partition, under, say, /mnt. &prompt.root; dd if=/dev/rda0a of=/mnt/bootsect.bsd bs=512 count=1 Reboot into DOS or NT. NTFS users copy the bootsect.bsd and/or the bootsect.lnx file from the floppy to C:\. Modify the attributes (permissions) on boot.ini with: C:\> attrib -s -r c:\boot.ini Edit to add the appropriate entries from the example boot.ini above, and restore the attributes: C:\> attrib +s +r c:\boot.ini If FreeBSD is booting from the MBR, restore it with the DOS fdisk command after you reconfigure them to boot from their native partitions. For FreeBSD 3.x systems the procedure is somewhat simpler. If FreeBSD is installed on the same disk as the NT boot partition simply copy /boot/boot1 to C:\BOOTSECT.BSD However, if FreeBSD is installed on a different disk /boot/boot1 will not work, /boot/boot0 is needed. DO NOT SIMPLY COPY /boot/boot0 INSTEAD OF /boot/boot1, YOU WILL OVERWRITE YOUR PARTITION TABLE AND RENDER YOUR COMPUTER UN-BOOTABLE! /boot/boot0 needs to be installed using sysinstall by selecting the FreeBSD boot manager on the screen which asks if you wish to use a boot manager. This is because /boot/boot0 has the partition table area filled with NULL characters but sysinstall copies the partition table before copying /boot/boot0 to the MBR. When the FreeBSD boot manager runs it records the last OS booted by setting the active flag on the partition table entry for that OS and then writes the whole 512-bytes of itself back to the MBR so if you just copy /boot/boot0 to C:\BOOTSECT.BSD then it writes an empty partition table, with the active flag set on one entry, to the MBR. How do I boot FreeBSD and Linux from LILO? If you have FreeBSD and Linux on the same disk, just follow LILO's installation instructions for booting a non-Linux operating system. Very briefly, these are: Boot Linux, and add the following lines to /etc/lilo.conf: other=/dev/hda2 table=/dev/hda label=FreeBSD (the above assumes that your FreeBSD slice is known to Linux as /dev/hda2; tailor to suit your setup). Then, run lilo as root and you should be done. If FreeBSD resides on another disk, you need to add loader=/boot/chain.b to the LILO entry. For example: other=/dev/dab4 table=/dev/dab loader=/boot/chain.b label=FreeBSD In some cases you may need to specify the BIOS drive number to the FreeBSD boot loader to successfully boot off the second disk. For example, if your FreeBSD SCSI disk is probed by BIOS as BIOS disk 1, at the FreeBSD boot loader prompt you need to specify: Boot: 1:da(0,a)/kernel On FreeBSD 2.2.5 and later, you can configure &man.boot.8; to automatically do this for you at boot time. The Linux+FreeBSD mini-HOWTO is a good reference for FreeBSD and Linux interoperability issues. How do I boot FreeBSD and Linux using BootEasy? Install LILO at the start of your Linux boot partition instead of in the Master Boot Record. You can then boot LILO from BootEasy. If you are running Windows-95 and Linux this is recommended anyway, to make it simpler to get Linux booting again if you should need to reinstall Windows95 (which is a Jealous Operating System, and will bear no other Operating Systems in the Master Boot Record). Will a dangerously dedicated disk endanger my health? The installation procedure allows you to chose two different methods in partitioning your harddisk(s). The default way makes it compatible with other operating systems on the same machine, by using fdisk table entries (called slices in FreeBSD), with a FreeBSD slice that employs partitions of its own. Optionally, one can chose to install a boot-selector to switch between the possible operating systems on the disk(s). The alternative uses the entire disk for FreeBSD, and makes no attempt to be compatible with other operating systems. So why it is called dangerous? A disk in this mode does not contain what normal PC utilities would consider a valid fdisk table. Depending on how well they have been designed, they might complain at you once they are getting in contact with such a disk, or even worse, they might damage the BSD bootstrap without even asking or notifying you. In addition, the dangerously dedicated disk's layout is known to confuse many BIOSsen, including those from AWARD (eg. as found in HP Netserver and Micronics systems as well as many others) and Symbios/NCR (for the popular 53C8xx range of SCSI controllers). This is not a complete list, there are more. Symptoms of this confusion include the read error message printed by the FreeBSD bootstrap when it cannot find itself, as well as system lockups when booting. Why have this mode at all then? It only saves a few kbytes of disk space, and it can cause real problems for a new installation. Dangerously dedicated mode's origins lie in a desire to avoid one of the most common problems plaguing new FreeBSD installers - matching the BIOS geometry numbers for a disk to the disk itself. Geometry is an outdated concept, but one still at the heart of the PC's BIOS and its interaction with disks. When the FreeBSD installer creates slices, it has to record the location of these slices on the disk in a fashion that corresponds with the way the BIOS expects to find them. If it gets it wrong, you will not be able to boot. Dangerously dedicated mode tries to work around this by making the problem simpler. In some cases, it gets it right. But it is meant to be used as a last-ditch alternative - there are better ways to solve the problem 99 times out of 100. So, how do you avoid the need for DD mode when you are installing? Start by making a note of the geometry that your BIOS claims to be using for your disks. You can arrange to have the kernel print this as it boots by specifying at the boot: prompt, or using boot -v in the loader. Just before the installer starts, the kernel will print a list of BIOS geometries. Do not panic - wait for the installer to start and then use scrollback to read the numbers. Typically the BIOS disk units will be in the same order that FreeBSD lists your disks, first IDE, then SCSI. When you are slicing up your disk, check that the disk geometry displayed in the FDISK screen is correct (ie. it matches the BIOS numbers); if it is wrong, use the g key to fix it. You may have to do this if there is absolutely nothing on the disk, or if the disk has been moved from another system. Note that this is only an issue with the disk that you are going to boot from; FreeBSD will sort itself out just fine with any other disks you may have. Once you have got the BIOS and FreeBSD agreeing about the geometry of the disk, your problems are almost guaranteed to be over, and with no need for DD mode at all. If, however, you are still greeted with the dreaded read error message when you try to boot, it is time to cross your fingers and go for it - there's nothing left to lose. To return a dangerously dedicated disk for normal PC use, there are basically two options. The first is, you write enough NULL bytes over the MBR to make any subsequent installation believe this to be a blank disk. You can do this for example with &prompt.root; dd if=/dev/zero of=/dev/rda0 count=15 Alternatively, the undocumented DOS feature C:\> fdisk /mbr will to install a new master boot record as well, thus clobbering the BSD bootstrap. How can I add more swap space? The best way is to increase the size of your swap partition, or take advantage of this convenient excuse to add another disk. The general rule of thumb is to have around 2x the swap space as you have main memory. However, if you have a very small amount of main memory you may want to configure swap beyond that. It is also a good idea to configure sufficient swap relative to anticipated future memory upgrades so you do not have to futz with your swap configuration later. Adding swap onto a separate disk makes things faster than simply adding swap onto the same disk. As an example, if you are compiling source located on one disk, and the swap is on another disk, this is much faster than both swap and compile on the same disk. This is true for SCSI disks specifically. When you have several disks, configuring a swap partition on each one is usually beneficial, even if you wind up putting swap on a work disk. Typically, each fast disk in your system should have some swap configured. FreeBSD supports up to 4 interleaved swap devices by default. When configuring multiple swap partitions you generally want to make them all about the same size, but people sometimes make their primary swap partition larger in order to accomodate a kernel core dump. Your primary swap partition must be at least as large as main memory in order to be able to accomodate a kernel core. IDE drives are not able to allow access to both drives on the same channel at the same time (FreeBSD does not support mode 4, so all IDE disk I/O is programmed). It is still suggested that you put your swap partition on a separate driver, however: the drives are so cheap, it is not worth worrying about. Swapping over NFS is only recommended if you do not have a local disk to swap to. Swapping over NFS is slow and inefficient in FreeBSD releases prior to 4.x, but reasonably fast in releases greater or equal to 4.0. Even so, it will be limited to the network bandwidth available and puts an additional burden on the NFS server. Here is an example for 64Mb vn-swap (/usr/swap0, though of course you can use any name that you want). Make sure your kernel was built with the line pseudo-device vn 1 #Vnode driver (turns a file into a device) in your config-file. The GENERIC kernel already contains this. create a vn-device &prompt.root; cd /dev &prompt.root; sh MAKEDEV vn0 create a swapfile (/usr/swap0) &prompt.root; dd if=/dev/zero of=/usr/swap0 bs=1024k count=64 set proper permissions on (/usr/swap0) &prompt.root; chmod 0600 /usr/swap0 enable the swap file in /etc/rc.conf swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired. reboot the machine To enable the swap file immediately, type &prompt.root; vnconfig -e /dev/vn0b /usr/swap0 swap Why am I having trouble setting up my printer? Please have a look at the Handbook entry on printing. It should cover most of your problem. See the Handbook entry on printing. Some printers require a host-based driver to do any kind of printing. These so-called WinPrinters are not natively supported by FreeBSD. If your printer does not work in DOS or Windows NT 4.0, it is probably a WinPrinter. Your only hope of getting one of these to work is to check if the ports/print/pnm2ppa port supports it. From its package description:
This software creates output using the PPA (printer performance architecture) protocol. This protocol is used by some HP "Windows-only" printers, including the HP Deskjet 820C series, the HP DeskJet 720 series, and the HP DeskJet 1000 series. [...] WWW: http://pnm2ppa.sourceforge.net/
How can I correct the keyboard mappings for my system? The kbdcontrol program has an option to load a keyboard map file. Under /usr/share/syscons/keymaps are a number of map files. Choose the one relevant to your system and load it. &prompt.root; kbdcontrol -l uk.iso Both the /usr/share/syscons/keymaps and the .kbd extension are assumed by &man.kbdcontrol.1;. This can be configured in /etc/sysconfig (or &man.rc.conf.5;). See the appropriate comments in this file. In 2.0.5R and later, everything related to text fonts, keyboard mapping is in /usr/share/examples/syscons. The following mappings are currently supported: Belgian ISO-8859-1 Brazilian 275 keyboard Codepage 850 Brazilian 275 keyboard ISO-8859-1 Danish Codepage 865 Danish ISO-8859-1 French ISO-8859-1 German Codepage 850 German ISO-8859-1 Italian ISO-8859-1 Japanese 106 Japanese 106x Latin American Norwegian ISO-8859-1 Polish ISO-8859-2 (programmer's) Russian Codepage 866 (alternative) Russian koi8-r (shift) Russian koi8-r Spanish ISO-8859-1 Swedish Codepage 850 Swedish ISO-8859-1 Swiss-German ISO-8859-1 United Kingdom Codepage 850 United Kingdom ISO-8859-1 United States of America ISO-8859-1 United States of America dvorak United States of America dvorakx Why do I get messages like: unknown: <PNP0303> can't assign resources on boot? The following is an excerpt from a post to the freebsd-current mailing list.
&a.wollman;, 24 April 2001 The can't assign resources messages indicate that the devices are legacy ISA devices for which a non-PnP-aware driver is compiled into the kernel. These include devices such as keyboard controllers, the programmable interrupt controller chip, and several other bits of standard infrastructure. The resources cannot be assigned because there is already a driver using those addresses.
How come I cannot get user quotas to work properly? Do not turn on quotas on /, Put the quota file on the file system that the quotas are to be enforced on. ie: Filesystem Quota file /usr /usr/admin/quotas /home /home/admin/quotas … … What is inappropriate about my ccd? The symptom of this is: &prompt.root; ccdconfig -C ccdconfig: ioctl (CCDIOCSET): /dev/ccd0c: Inappropriate file type or format This usually happens when you are trying to concatenate the c partitions, which default to type unused. The ccd driver requires the underlying partition type to be FS_BSDFFS. Edit the disklabel of the disks you are trying to concatenate and change the types of partitions to 4.2BSD. Why can't I edit the disklabel on my ccd? The symptom of this is: &prompt.root; disklabel ccd0 (it prints something sensible here, so let's try to edit it) &prompt.root; disklabel -e ccd0 (edit, save, quit) disklabel: ioctl DIOCWDINFO: No disk label on disk; use "disklabel -r" to install initial label This is because the disklabel returned by ccd is actually a fake one that is not really on the disk. You can solve this problem by writing it back explicitly, as in: &prompt.root; disklabel ccd0 > /tmp/disklabel.tmp &prompt.root; disklabel -Rr ccd0 /tmp/disklabel.tmp &prompt.root; disklabel -e ccd0 (this will work now) Does FreeBSD support System V IPC primitives? Yes, FreeBSD supports System V-style IPC. This includes shared memory, messages and semaphores. You need to add the following lines to your kernel config to enable them. options SYSVSHM options SYSVSHM # enable shared memory options SYSVSEM # enable for semaphores options SYSVMSG # enable for messaging In FreeBSD 3.2 and later, these options are already part of the GENERIC kernel, which means they should already be compiled into your system. Recompile and install your kernel. How do I use sendmail for mail delivery with UUCP? The sendmail configuration that ships with FreeBSD is suited for sites that connect directly to the Internet. Sites that wish to exchange their mail via UUCP must install another sendmail configuration file. Tweaking /etc/sendmail.cf manually is considered something for purists. Sendmail version 8 comes with a new approach of generating config files via some &man.m4.1; preprocessing, where the actual hand-crafted configuration is on a higher abstraction level. You should use the configuration files under /usr/src/usr.sbin/sendmail/cf If you did not install your system with full sources, the sendmail config stuff has been broken out into a separate source distribution tarball just for you. Assuming you have got your CDROM mounted, do: &prompt.root; cd /cdrom/src &prompt.root; cat scontrib.?? | tar xzf - -C /usr/src contrib/sendmail Do not panic, this is only a few hundred kilobytes in size. The file README in the cf directory can serve as a basic introduction to m4 configuration. For UUCP delivery, you are best advised to use the mailertable feature. This constitutes a database that sendmail can use to base its routing decision upon. First, you have to create your .mc file. The directory /usr/src/usr.sbin/sendmail/cf/cf is the home of these files. Look around, there are already a few examples. Assuming you have named your file foo.mc, all you need to do in order to convert it into a valid sendmail.cf is: &prompt.root; cd /usr/src/usr.sbin/sendmail/cf/cf &prompt.root; make foo.cf &prompt.root; cp foo.cf /etc/sendmail.cf A typical .mc file might look like: include(`../m4/cf.m4') VERSIONID(`Your version number') OSTYPE(bsd4.4) FEATURE(nodns) FEATURE(nocanonify) FEATURE(mailertable) define(`UUCP_RELAY', your.uucp.relay) define(`UUCP_MAX_SIZE', 200000) MAILER(local) MAILER(smtp) MAILER(uucp) Cw your.alias.host.name Cw youruucpnodename.UUCP The nodns and nocanonify features will prevent any usage of the DNS during mail delivery. The UUCP_RELAY clause is needed for bizarre reasons, do not ask. Simply put an Internet hostname there that is able to handle .UUCP pseudo-domain addresses; most likely, you will enter the mail relay of your ISP there. Once you have got this, you need this file called /etc/mailertable. A typical example of this gender again: # # makemap hash /etc/mailertable.db < /etc/mailertable # horus.interface-business.de uucp-dom:horus .interface-business.de uucp-dom:if-bus interface-business.de uucp-dom:if-bus .heep.sax.de smtp8:%1 horus.UUCP uucp-dom:horus if-bus.UUCP uucp-dom:if-bus . uucp-dom: As you can see, this is part of a real-life file. The first three lines handle special cases where domain-addressed mail should not be sent out to the default route, but instead to some UUCP neighbor in order to shortcut the delivery path. The next line handles mail to the local Ethernet domain that can be delivered using SMTP. Finally, the UUCP neighbors are mentioned in the .UUCP pseudo-domain notation, to allow for a uucp-neighbor !recipient override of the default rules. The last line is always a single dot, matching everything else, with UUCP delivery to a UUCP neighbor that serves as your universal mail gateway to the world. All of the node names behind the uucp-dom: keyword must be valid UUCP neighbors, as you can verify using the command uuname. As a reminder that this file needs to be converted into a DBM database file before being usable, the command line to accomplish this is best placed as a comment at the top of the mailertable. You always have to execute this command each time you change your mailertable. Final hint: if you are uncertain whether some particular mail routing would work, remember the option to sendmail. It starts sendmail in address test mode; simply enter 0, followed by the address you wish to test for the mail routing. The last line tells you the used internal mail agent, the destination host this agent will be called with, and the (possibly translated) address. Leave this mode by typing Control-D. &prompt.user; sendmail -bt ADDRESS TEST MODE (ruleset 3 NOT automatically invoked) Enter <ruleset> <address> > 0 foo@interface-business.de rewrite: ruleset 0 input: foo @ interface-business . de ... rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo \ < @ interface-business . de > > ^D How do I set up mail with a dialup connection to the 'net? If you have got a statically assigned IP number, you should not need to adjust anything from the default. Set your host name up as your assigned Internet name and sendmail will do the rest. If you have got a dynamically assigned IP number and use a dialup ppp connection to the Internet, you will probably be given a mailbox on your ISPs mail server. Lets assume your ISPs domain is myISP.com, and that your user name is user. Lets also assume you have called your machine bsd.home and that your ISP has told you that you may use relay.myISP.com as a mail relay. In order to retrieve mail from your mailbox, you will need to install a retrieval agent. Fetchmail is a good choice as it supports many different protocols. Usually, POP3 will be provided by your ISP. If you have chosen to use user-ppp, you can automatically fetch your mail when a connection to the 'net is established with the following entry in /etc/ppp/ppp.linkup: MYADDR: !bg su user -c fetchmail If you are using sendmail (as shown below) to deliver mail to non-local accounts, put the command !bg su user -c "sendmail -q" after the above shown entry. This forces sendmail to process your mailqueue as soon as the connection to the 'net is established. I am assuming that you have an account for user on bsd.home. In the home directory of user on bsd.home, create a .fetchmailrc file: poll myISP.com protocol pop3 fetchall pass MySecret Needless to say, this file should not be readable by anyone except user as it contains the password MySecret. In order to send mail with the correct from: header, you must tell sendmail to use user@myISP.com rather than user@bsd.home. You may also wish to tell sendmail to send all mail via relay.myISP.com, allowing quicker mail transmission. The following .mc file should suffice: VERSIONID(`bsd.home.mc version 1.0') OSTYPE(bsd4.4)dnl FEATURE(nouucp)dnl MAILER(local)dnl MAILER(smtp)dnl Cwlocalhost Cwbsd.home MASQUERADE_AS(`myISP.com')dnl FEATURE(allmasquerade)dnl FEATURE(masquerade_envelope)dnl FEATURE(nocanonify)dnl FEATURE(nodns)dnl define(`SMART_HOST', `relay.myISP.com') Dmbsd.home define(`confDOMAIN_NAME',`bsd.home')dnl define(`confDELIVERY_MODE',`deferred')dnl Refer to the previous section for details of how to turn this .mc file into a sendmail.cf file. Also, don't forget to restart sendmail after updating sendmail.cf. What is this UID 0 toor account? Have I been compromised? Do not worry. toor is an alternative superuser account (toor is root spelt backwards). Previously it was created when the &man.bash.1; shell was installed but now it is created by default. It is intended to be used with a non-standard shell so you do not have to change root's default shell. This is important as shells which are not part of the base distribution (for example a shell installed from ports or packages) are likely be to be installed in /usr/local/bin which, by default, resides on a different filesystem. If root's shell is located in /usr/local/bin and /usr (or whatever filesystem contains /usr/local/bin) is not mounted for some reason, root will not be able to log in to fix a problem (although if you reboot into single user mode you will be prompted for the path to a shell). Some people use toor for day-to-day root tasks with a non-standard shell, leaving root, with a standard shell, for single user mode or emergencies. By default you cannot log in using toor as it does not have a password, so log in as root and set a password for toor if you want to use it. I have forgotten the root password! What do I do? Do not Panic! Simply restart the system, type boot -s at the Boot: prompt (just -s for FreeBSD releases before 3.2) to enter Single User mode. At the question about the shell to use, hit ENTER. You will be dropped to a &prompt.root; prompt. Enter mount -u / to remount your root filesystem read/write, then run mount -a to remount all the filesystems. Run passwd root to change the root password then run &man.exit.1; to continue booting. How do I keep Control-Alt-Delete from rebooting the system? If you are using syscons (the default console driver) in FreeBSD 2.2.7-RELEASE or later, build and install a new kernel with the line options SC_DISABLE_REBOOT in the configuration file. If you use the PCVT console driver in FreeBSD 2.2.5-RELEASE or later, use the following kernel configuration line instead: options PCVT_CTRL_ALT_DEL For older versions of FreeBSD, edit the keymap you are using for the console and replace the boot keywords with nop. The default keymap is /usr/share/syscons/keymaps/us.iso.kbd. You may have to instruct /etc/rc.conf to load this keymap explicitly for the change to take effect. Of course if you are using an alternate keymap for your country, you should edit that one instead. How do I reformat DOS text files to Unix ones? Simply use this perl command: &prompt.user; perl -i.bak -npe 's/\r\n/\n/g' file ... file is the file(s) to process. The modification is done in-place, with the original file stored with a .bak extension. Alternatively you can use the &man.tr.1; command: &prompt.user; tr -d '\r' < dos-text-file > unix-file dos-text-file is the file containing DOS text while unix-file will contain the converted output. This can be quite a bit faster than using perl. How do I kill processes by name? Use &man.killall.1;. Why is su bugging me about not being in root's ACL? The error comes from the Kerberos distributed authentication system. The problem is not fatal but annoying. You can either run su with the -K option, or uninstall Kerberos as described in the next question. How do I uninstall Kerberos? To remove Kerberos from the system, reinstall the bin distribution for the release you are running. If you have the CDROM, you can mount the cd (we will assume on /cdrom) and run &prompt.root; cd /cdrom/bin &prompt.root; ./install.sh Alternately, you can remove all "MAKE_KERBEROS" options from /etc/make.conf and rebuild world. How do I add pseudoterminals to the system? If you have lots of telnet, ssh, X, or screen users, you will probably run out of pseudoterminals. Here is how to add more: Build and install a new kernel with the line pseudo-device pty 256 in the configuration file. Run the commands &prompt.root; cd /dev &prompt.root; sh MAKEDEV pty{1,2,3,4,5,6,7} to make 256 device nodes for the new terminals. Edit /etc/ttys and add lines for each of the 256 terminals. They should match the form of the existing entries, i.e. they look like ttyqc none network The order of the letter designations is tty[pqrsPQRS][0-9a-v], using a regular expression. Reboot the system with the new kernel and you are ready to go. How come I cannot create the snd0 device? There is no snd device. The name is used as a shorthand for the various devices that make up the FreeBSD sound driver, such as mixer, sequencer, and dsp. To create these devices you should &prompt.root; cd /dev &prompt.root; sh MAKEDEV snd0 How do I re-read /etc/rc.conf and re-start /etc/rc without a reboot? Go into single user mode and than back to multi user mode. On the console do: &prompt.root; shutdown now (Note: without -r or -h) &prompt.root; return &prompt.root; exit What is a sandbox? Sandbox is a security term. It can mean two things: A process which is placed inside a set of virtual walls that are designed to prevent someone who breaks into the process from being able to break into the wider system. The process is said to be able to play inside the walls. That is, nothing the process does in regards to executing code is supposed to be able to breech the walls so you do not have to do a detailed audit of its code to be able to say certain things about its security. The walls might be a userid, for example. This is the definition used in the security and named man pages. Take the ntalk service, for example (see /etc/inetd.conf). This service used to run as userid root. Now it runs as userid tty. The tty user is a sandbox designed to make it more difficult for someone who has successfully hacked into the system via ntalk from being able to hack beyond that user id. A process which is placed inside a simulation of the machine. This is more hard-core. Basically it means that someone who is able to break into the process may believe that he can break into the wider machine but is, in fact, only breaking into a simulation of that machine and not modifying any real data. The most common way to accomplish this is to build a simulated environment in a subdirectory and then run the processes in that directory chroot'd (i.e. / for that process is this directory, not the real / of the system). Another common use is to mount an underlying filesystem read-only and then create a filesystem layer on top of it that gives a process a seemingly writeable view into that filesystem. The process may believe it is able to write to those files, but only the process sees the effects - other processes in the system do not, necessarily. An attempt is made to make this sort of sandbox so transparent that the user (or hacker) does not realize that he is sitting in it. Unix implements two core sandboxes. One is at the process level, and one is at the userid level. Every Unix process is completely firewalled off from every other Unix process. One process cannot modify the address space of another. This is unlike Windows where a process can easily overwrite the address space of any other, leading to a crash. A Unix process is owned by a particular userid. If the userid is not the root user, it serves to firewall the process off from processes owned by other users. The userid is also used to firewall off on-disk data. What is securelevel? The securelevel is a security mechanism implemented in the kernel. Basically, when the securelevel is positive, the kernel restricts certain tasks; not even the superuser (i.e., root) is allowed to do them. At the time of this writing, the securelevel mechanism is capable of, among other things, limiting the ability to, unset certain file flags, such as schg (the system immutable flag), write to kernel memory via /dev/mem and /dev/kmem, load kernel modules, and alter &man.ipfirewall.4; rules. To check the status of the securelevel on a running system, simply execute the following command: &prompt.root; sysctl kern.securelevel The output will contain the name of the &man.sysctl.8; variable (in this case, kern.securelevel) and a number. The latter is the current value of the securelevel. If it is positive (i.e., greater than 0), at least some of the securelevel's protections are enabled. You cannot lower the securelevel of a running system; being able to do that would defeat its purpose. If you need to do a task that requires that the securelevel be non-positive (e.g., an installworld or changing the date), you will have to change the securelevel setting in /etc/rc.conf (you want to look for the kern_securelevel and kern_securelevel_enable variables) and reboot. For more information on securelevel and the specific things all the levels do, please consult the &man.init.8; manual page. Securelevel is not a silver bullet; it has many known deficiencies. More often than not, it provides a false sense of security. One of its biggest problems is that in order for it to be at all effective, all files used in the boot process up until the securelevel is set must be protected. If an attacker can get the system to execute their code prior to the securelevel being set (which happens quite late in the boot process since some things the system must do at start-up cannot be done at an elevated securelevel), its protections are invalidated. While this task of protecting all files used in the boot process is not technically impossible, if it is achieved, system maintenance will become a nightmare since one would have to take the system down, at least to single-user mode, to modify a configuration file. This point and others are often discussed on the mailing lists, particularly freebsd-security. Please search the archives here for an extensive discussion. Some people are hopeful that securelevel will soon go away in favor of a more fine-grained mechanism, but things are still hazy in this respect. Consider yourself warned. How do I let ordinary users mount floppies, CDROMs and other removable media? Ordinary users can be permitted to mount devices. Here is how: As root set the sysctl variable vfs.usermount to 1. &prompt.root; sysctl -w vfs.usermount=1 As root assign the appropriate permissions to the block device associated with the removable media. For example, to allow users to mount the first floppy drive, use: &prompt.root; chmod 666 /dev/fd0 To allow users in the group operator to mount the CDROM drive, use: &prompt.root; chgrp operator /dev/cd0c &prompt.root; chmod 640 /dev/cd0c Finally, add the line vfs.usermount=1 to the file /etc/sysctl.conf so that it is reset at system boot time. All users can now mount the floppy /dev/fd0 onto a directory that they own: &prompt.user; mkdir ~/my-mount-point &prompt.user; mount -t msdos /dev/fd0 ~/my-mount-point Users in group operator can now mount the CDROM /dev/cd0c onto a directory that they own: &prompt.user; mkdir ~/my-mount-point &prompt.user; mount -t msdos /dev/cd0c ~/my-mount-point Unmounting the device is simple: &prompt.user; umount ~/my-mount-point Enabling vfs.usermount, however, has negative security implications. A better way to access MSDOS formatted media is to use the mtools package in the ports collection. How do I move my system over to my huge new disk? The best way is to reinstall the OS on the new disk, then move the user data over. This is highly recommended if you have been tracking -stable for more than one release, or have updated a release instead of installing a new one. You can install booteasy on both disks with &man.boot0cfg.8;, and dual boot them until you are happy with the new configuration. Skip the next paragraph to find out how to move the data after doing this. Should you decide not to do a fresh install, you need to partition and label the new disk with either /stand/sysinstall, or &man.fdisk.8; and &man.disklabel.8;. You should also install booteasy on both disks with &man.boot0cfg.8;, so that you can dual boot to the old or new system after the copying is done. See the formatting-media tutorial for details on this process. Now you have got the new disk set up, and are ready to move the data. Unfortunately, you cannot just blindly copy the data. Things like device files (in /dev) and symbolic links tend to screw that up. You need to use tools that understand these things, which means &man.dump.8; and &man.tar.1;. Although it is suggested that you move the data in single user mode, it is not required. You should never use anything but &man.dump.8; and &man.restore.8; to move the root file system. The &man.tar.1; command may work - then again, it may not. You should also use &man.dump.8; and &man.restore.8; if you are moving a single partition to another empty partition. The sequence of steps to use dump to move a partitions data to a new partition is: newfs the new partition. mount it on a temporary mount point. cd to that directory. dump the old partition, piping output to the new one. For example, if you are going to move root to /dev/ad1s1a, with /mnt as the temporary mount point, it is: &prompt.root; newfs /dev/ad1s1a &prompt.root; mount /dev/ad1s1a &prompt.root; cd /mnt &prompt.root; dump 0uaf - / | restore xf - If you are going to rearrange your partitions - say, splitting one into two, or combing two into one, you may find yourself needing to move everything under a subdirectory to a new location. Since &man.dump.8; works with file systems, it cannot do this. So you use &man.tar.1;. The general command to move /old to /new for &man.tar.1; is: &prompt.root; (cd /old; tar cf - .) | (cd /new; tar xpf -) If /old has file systems mounted on that, and you do not want to move that data or unmount them, you just add the 'l' flag to the first &man.tar.1;: &prompt.root; (cd /old; tar clf - .) | (cd /new; tar xpf -). You might prefer &man.cpio.1;, &man.pax.1;, or cpdup (in ports/sysutils/cpdup) to &man.tar.1;. I tried to update my system to the latest -STABLE, but got -RC or -BETA! What is going on? Short answer: it is just a name. RC stands for Release Candidate. It signifies that a release is imminent. In FreeBSD, -BETA is typically synonymous with the code freeze before a release. Long answer: FreeBSD derives its releases from one of two places. Major, dot-zero, releases, such as 3.0-RELEASE and 4.0-RELEASE, are branched from the head of the development stream, commonly referred to as -CURRENT. Minor releases, such as 3.1-RELEASE or 4.2-RELEASE, have been snapshots of the active -STABLE branch. Starting with 4.3-RELEASE, each release also now has its own branch which can be tracked by people requiring an extremely conservative rate of development (typically only security advisories). When a release is about to be made, the branch from which it will be derived from has to undergo a certain process. Part of this process is a code freeze. When a code freeze is initiated, the name of the branch is changed to reflect that it is about to become a release. For example, if the branch used to be called 4.0-STABLE, its name will be changed to 4.1-BETA to signify the code freeze and signify that extra pre-release testing should be happening. Bug fixes can still be committed to be part of the release. When the source code is in shape for the release the name will be changed to 4.1-RC to signify that a release is about to be made from it. Once in the RC stage, only the most critical bugs found can be fixed. Once the release, 4.1-RELEASE in this example, has been made, the branch will be renamed to 4.1-STABLE. I tried to install a new kernel, and the chflags failed. How do I get around this? Short answer: You are probably at security level greater than 0. Reboot directly to single user mode to install the kernel. Long answer: FreeBSD disallows changing system flags at security levels greater than 0. You can check your security level with the command: &prompt.root; sysctl kern.securelevel You cannot lower the security level; you have to boot to single mode to install the kernel, or change the security in /etc/rc.conf then reboot. See the &man.init.8; man page for details on securelevel, and see /etc/defaults/rc.conf and the &man.rc.conf.5; man page for more information on rc.conf. I cannot change the time on my system by more than one second! How do I get around this? Short answer: You are probably at security level greater than 1. Reboot directly to single user mode to change the date. Long answer: FreeBSD disallows changing the time by more that one second at security levels greater than 1. You can check your security level with the command: &prompt.root; sysctl kern.securelevel You cannot lower the security level; you have to boot to single mode to change the date, or change the security level in /etc/rc.conf then reboot. See the &man.init.8; man page for details on securelevel, and see /etc/defaults/rc.conf and the &man.rc.conf.5; man page for more information on rc.conf. Why is rpc.statd using 256 megabytes of memory? No, there is no memory leak, and it is not using 256 Mbytes of memory. It simply likes to (i.e., always does) map an obscene amount of memory into its address space for convenience. There is nothing terribly wrong with this from a technical standpoint; it just throws off things like &man.top.1; and &man.ps.1;. &man.rpc.statd.8; maps its status file (resident on /var) into its address space; to save worrying about remapping it later when it needs to grow, it maps it with a generous size. This is very evident from the source code, where one can see that the length argument to &man.mmap.2; is 0x10000000, or one sixteenth of the address space on an IA32, or exactly 256MB. Why can't I unset the schg file flag? You are running at an elevated (i.e., greater than 0) securelevel. Lower the securelevel and try again. For more information, see the FAQ entry on securelevel and the &man.init.8; manual page. Why doesn't SSH authentication through .shosts work by default in recent versions of FreeBSD? The reason why .shosts authentication does not work by default in more recent versions of FreeBSD is because &man.ssh.1; is not installed suid root by default. To fix this, you can do one of the following: As a permanent fix, set ENABLE_SUID_SSH to true in /etc/make.conf and rebuild ssh (or run make world). As a temporary fix, change the mode on /usr/bin/ssh to 4555 by running chmod 4755 /usr/bin/ssh as root. Then add ENABLE_SUID_SSH= true to /etc/make.conf so the change takes effect the next time make world is run. The X Window System and Virtual Consoles I want to run X, how do I go about it? The easiest way is to simply specify that you want to run X during the installation process. Then read and follow the documentation on the xf86config tool, which assists you in configuring XFree86(tm) for your particular graphics card/mouse/etc. You may also wish to investigate the Xaccel server. See the section on Xi Graphics or Metro Link for more details. I tried to run X, but I get an KDENABIO failed (Operation not permitted) error when I type startx. What do I do now? Your system is running at a raised securelevel, is not it? It is, indeed, impossible to start X at a raised securelevel. To see why, look at the &man.init.8; man page. So the question is what else you should do instead, and you basically have two choices: set your securelevel back down to zero (usually from /etc/rc.conf), or run &man.xdm.1; at boot time (before the securelevel is raised). See for more information about running &man.xdm.1; at boot time. Why doesn't my mouse work with X? If you are using syscons (the default console driver), you can configure FreeBSD to support a mouse pointer on each virtual screen. In order to avoid conflicting with X, syscons supports a virtual device called /dev/sysmouse. All mouse events received from the real mouse device are written to the sysmouse device via moused. If you wish to use your mouse on one or more virtual consoles, and use X, see and set up moused. Then edit /etc/XF86Config and make sure you have the following lines. Section Pointer Protocol "SysMouse" Device "/dev/sysmouse" ..... The above example is for XFree86 3.3.2 or later. For earlier versions, the Protocol should be MouseSystems. Some people prefer to use /dev/mouse under X. To make this work, /dev/mouse should be linked to /dev/sysmouse (see &man.sysmouse.4;): &prompt.root; cd /dev &prompt.root; rm -f mouse &prompt.root; ln -s sysmouse mouse My mouse has a fancy wheel. Can I use it in X? Yes. But you need to customize X client programs. See Colas Nahaboo's web page (http://www.inria.fr/koala/colas/mouse-wheel-scroll/) . If you want to use the imwheel program, just follow these simple steps. Translate the Wheel Events The imwheel program works by translating mouse button 4 and mouse button 5 events into key events. Thus, you have to get the mouse driver to translate mouse wheel events to button 4 and 5 events. There are two ways of doing this, the first way is to have &man.moused.8; do the translation. The second way is for the X server itself to do the event translation. Using &man.moused.8; to Translate Wheel Events To have &man.moused.8; perform the event translations, simply add to the command line used to start &man.moused.8;. For example, if you normally start &man.moused.8; via moused -p /dev/psm0 you would start it by entering moused -p /dev/psm0 -z 4 instead. If you start &man.moused.8; automatically during bootup via /etc/rc.conf, you can simply add to the moused_flags variable in /etc/rc.conf. You now need to tell X that you have a 5 button mouse. To do this, simply add the line Buttons 5 to the Pointer section of /etc/XF86Config. For example, you might have the following Pointer section in /etc/XF86Config. <quote>Pointer</quote> Section for Wheeled Mouse in XFree86 3.3.x series XF86Config with moused Translation Section "Pointer" Protocol "SysMouse" Device "/dev/sysmouse" Buttons 5 EndSection <quote>InputDevice</quote> Section for Wheeled Mouse in XFree86 4.x series XF86Config with automatic protocol recognition and button mapping Translation Section "InputDevice" Identifier "Mouse1" Driver "mouse" Option "Protocol" "auto" Option "Device" "/dev/psm0" Option "Buttons" "5" Option "ZAxisMapping" "4 5" EndSection <quote>.emacs</quote> example for naive page scrolling with Wheeled Mouse ;; wheel mouse (global-set-key [mouse-4] 'scroll-down) (global-set-key [mouse-5] 'scroll-up) Using Your X Server to Translate the Wheel Events If you are not running &man.moused.8;, or if you do not want &man.moused.8; to translate your wheel events, you can have the X server do the event translation instead. This requires a couple of modifications to your /etc/XF86Config file. First, you need to choose the proper protocol for your mouse. Most wheeled mice use the IntelliMouse protocol. However, XFree86 does support other protocols, such as MouseManPlusPS/2 for the Logitech MouseMan+ mice. Once you have chosen the protocol you will use, you need to add a Protocol line to the Pointer section. Secondly, you need to tell the X server to remap wheel scroll events to mouse buttons 4 and 5. This is done with the ZAxisMapping option. For example, if you are not using &man.moused.8;, and you have an IntelliMouse attached to the PS/2 mouse port you would use the following in /etc/XF86Config. <quote>Pointer</quote> Section for Wheeled Mouse in <filename>XF86Config</filename> with X Server Translation Section "Pointer" Protocol "IntelliMouse" Device "/dev/psm0" ZAxisMapping 4 5 EndSection Install imwheel Next, install imwheel from the Ports collection. It can be found in the x11 category. This program will map the wheel events from your mouse into keyboard events. For example, it might send Page Up to a program when you scroll the wheel forwards. Imwheel uses a configuration file to map the wheel events to keypresses so that it can send different keys to different applications. The default imwheel configuration file is installed in /usr/X11R6/etc/imwheelrc. You can copy it to ~/.imwheelrc and then edit it if you wish to customize imwheel's configuration. The format of the configuration file is documented in &man.imwheel.1;. Configure Emacs to Work with Imwheel (optional) If you use emacs or Xemacs, then you need to add a small section to your ~/.emacs file. For emacs, add the following: <application>Emacs</application> Configuration for <application>Imwheel</application> ;;; For imwheel (setq imwheel-scroll-interval 3) (defun imwheel-scroll-down-some-lines () (interactive) (scroll-down imwheel-scroll-interval)) (defun imwheel-scroll-up-some-lines () (interactive) (scroll-up imwheel-scroll-interval)) (global-set-key [?\M-\C-\)] 'imwheel-scroll-up-some-lines) (global-set-key [?\M-\C-\(] 'imwheel-scroll-down-some-lines) ;;; end imwheel section For Xemacs, add the following to your ~/.emacs file instead: <application>Xemacs</application> Configuration for <application>Imwheel</application> ;;; For imwheel (setq imwheel-scroll-interval 3) (defun imwheel-scroll-down-some-lines () (interactive) (scroll-down imwheel-scroll-interval)) (defun imwheel-scroll-up-some-lines () (interactive) (scroll-up imwheel-scroll-interval)) (define-key global-map [(control meta \))] 'imwheel-scroll-up-some-lines) (define-key global-map [(control meta \()] 'imwheel-scroll-down-some-lines) ;;; end imwheel section Run Imwheel You can just type imwheel in an xterm to start it up once it is installed. It will background itself and take effect immediately. If you want to always use imwheel, simply add it to your .xinitrc or .xsession file. You can safely ignore any warnings imwheel displays about PID files. Those warnings only apply to the Linux version of imwheel. Why do X Window menus and dialog boxes not work right? Try turning off the Num Lock key. If your Num Lock key is on by default at boot-time, you may add the following line in the Keyboard section of the XF86Config file. # Let the server do the NumLock processing. This should only be # required when using pre-R6 clients ServerNumLock What is a virtual console and how do I make more? Virtual consoles, put simply, enable you to have several simultaneous sessions on the same machine without doing anything complicated like setting up a network or running X. When the system starts, it will display a login prompt on the monitor after displaying all the boot messages. You can then type in your login name and password and start working (or playing!) on the first virtual console. At some point, you will probably wish to start another session, perhaps to look at documentation for a program you are running or to read your mail while waiting for an FTP transfer to finish. Just do Alt-F2 (hold down the Alt key and press the F2 key), and you will find a login prompt waiting for you on the second virtual console! When you want to go back to the original session, do Alt-F1. The default FreeBSD installation has three virtual consoles enabled (8 starting with 3.3-RELEASE), and Alt-F1, Alt-F2, and Alt-F3 will switch between these virtual consoles. To enable more of them, edit /etc/ttys (see &man.ttys.5;) and add entries for ttyv4 to ttyvc after the comment on Virtual terminals: # Edit the existing entry for ttyv3 in /etc/ttys and change # "off" to "on". ttyv3 "/usr/libexec/getty Pc" cons25 on secure ttyv4 "/usr/libexec/getty Pc" cons25 on secure ttyv5 "/usr/libexec/getty Pc" cons25 on secure ttyv6 "/usr/libexec/getty Pc" cons25 on secure ttyv7 "/usr/libexec/getty Pc" cons25 on secure ttyv8 "/usr/libexec/getty Pc" cons25 on secure ttyv9 "/usr/libexec/getty Pc" cons25 on secure ttyva "/usr/libexec/getty Pc" cons25 on secure ttyvb "/usr/libexec/getty Pc" cons25 on secure Use as many or as few as you want. The more virtual terminals you have, the more resources that are used; this can be important if you have 8MB RAM or less. You may also want to change the secure to insecure. If you want to run an X server you must leave at least one virtual terminal unused (or turned off) for it to use. That is to say that if you want to have a login prompt pop up for all twelve of your Alt-function keys, you are out of luck - you can only do this for eleven of them if you also want to run an X server on the same machine. The easiest way to disable a console is by turning it off. For example, if you had the full 12 terminal allocation mentioned above and you wanted to run X, you would change settings for virtual terminal 12 from: ttyvb "/usr/libexec/getty Pc" cons25 on secure to: ttyvb "/usr/libexec/getty Pc" cons25 off secure If your keyboard has only ten function keys, you would end up with: ttyv9 "/usr/libexec/getty Pc" cons25 off secure ttyva "/usr/libexec/getty Pc" cons25 off secure ttyvb "/usr/libexec/getty Pc" cons25 off secure (You could also just delete these lines.) Once you have edited /etc/ttys, the next step is to make sure that you have enough virtualterminal devices. The easiest way to do this is: &prompt.root; cd /dev &prompt.root; sh MAKEDEV vty12 Next, the easiest (and cleanest) way to activate the virtual consoles is to reboot. However, if you really do not want to reboot, you can just shut down the X Window system and execute (as root): &prompt.root; kill -HUP 1 It is imperative that you completely shut down X Window if it is running, before running this command. If you don't, your system will probably appear to hang/lock up after executing the kill command. How do I access the virtual consoles from X? Use Ctrl Alt Fn to switch back to a virtual console. Ctrl Alt F1 would return you to the first virtual console. Once you are back to a text console, you can then use Alt Fn as normal to move between them. To return to the X session, you must switch to the virtual console running X. If you invoked X from the command line, (e.g., using startx) then the X session will attach to the next unused virtual console, not the text console from which it was invoked. If you have eight active virtual terminals then X will be running on the ninth, and you would use Alt F9 to return. How do I start XDM on boot? There are two schools of thought on how to start xdm. One school starts xdm from /etc/ttys (see &man.ttys.5;) using the supplied example, while the other simply runs xdm from rc.local (see &man.rc.8;) or from a X.sh script in /usr/local/etc/rc.d. Both are equally valid, and one may work in situations where the other does not. In both cases the result is the same: X will popup a graphical login: prompt. The ttys method has the advantage of documenting which vty X will start on and passing the responsibility of restarting the X server on logout to init. The rc.local method makes it easy to kill xdm if there is a problem starting the X server. If loaded from rc.local, xdm should be started without any arguments (i.e., as a daemon). xdm must start AFTER getty runs, or else getty and xdm will conflict, locking out the console. The best way around this is to have the script sleep 10 seconds or so then launch xdm. If you are to start xdm from /etc/ttys, there still is a chance of conflict between xdm and &man.getty.8;. One way to avoid this is to add the vt number in the /usr/X11R6/lib/X11/xdm/Xservers file. :0 local /usr/X11R6/bin/X vt4 The above example will direct the X server to run in /dev/ttyv3. Note the number is offset by one. The X server counts the vty from one, whereas the FreeBSD kernel numbers the vty from zero. Why do I get Couldn't open console when I run xconsole? If you start X with startx, the permissions on /dev/console will not get changed, resulting in things like xterm -C and xconsole not working. This is because of the way console permissions are set by default. On a multi-user system, one does not necessarily want just any user to be able to write on the system console. For users who are logging directly onto a machine with a VTY, the &man.fbtab.5; file exists to solve such problems. In a nutshell, make sure an uncommented line of the form /dev/ttyv0 0600 /dev/console is in /etc/fbtab (see &man.fbtab.5;) and it will ensure that whomever logs in on /dev/ttyv0 will own the console. Before, I was able to run XFree86 as a regular user. Why does it now say that I must be root? All X servers need to be run as root in order to get direct access to your video hardware. Older versions of XFree86 (<= 3.3.6) installed all bundled servers to be automatically run as root (setuid to root). This is obviously a security hazard because X servers are large, complicated programs. Newer versions of XFree86 do not install the servers setuid to root for just this reason. Obviously, running an X server as the root user is not acceptable, nor a good idea security-wise. There are two ways to be able to use X as a regular user. The first is to use xdm or another display manager (e.g., kdm); the second is to use the Xwrapper. xdm is a daemon that handles graphical logins. It is usually started at boot time, and is responsible for authenticating users and starting their sessions; it is essentially the graphical counterpart of &man.getty.8; and &man.login.1;. For more information on xdm see the XFree86 documentation, and the the FAQ entry on it. Xwrapper is the X server wrapper; it is a small utility to enable one to manually run an X server while maintaining reasonable safety. It performs some sanity checks on the command line arguments given, and if they pass, runs the appropriate X server. If you do not want to run a display manger for whatever reason, this is for you. If you have installed the complete ports collection, you can find the port in /usr/ports/x11/wrapper. Why does my PS/2 mouse misbehave under X? Your mouse and the mouse driver may have somewhat become out of synchronization. In versions 2.2.5 and earlier, switching away from X to a virtual terminal and getting back to X again may make them re-synchronized. If the problem occurs often, you may add the following option in your kernel configuration file and recompile it. options PSM_CHECKSYNC See the section on building a kernel if you have no experience with building kernels. With this option, there should be less chance of synchronization problem between the mouse and the driver. If, however, you still see the problem, click any mouse button while holding the mouse still to re-synchronize the mouse and the driver. Note that unfortunately this option may not work with all the systems and voids the tap feature of the ALPS GlidePoint device attached to the PS/2 mouse port. In versions 2.2.6 and later, synchronization check is done in a slightly better way and is standard in the PS/2 mouse driver. It should even work with GlidePoint. (As the check code has become a standard feature, PSM_CHECKSYNC option is not available in these versions.) However, in rare case the driver may erroneously report synchronization problem and you may see the kernel message: psmintr: out of sync (xxxx != yyyy) and find your mouse does not seem to work properly. If this happens, disable the synchronization check code by setting the driver flags for the PS/2 mouse driver to 0x100. Enter UserConfig by giving the option at the boot prompt: boot: -c Then, in the UserConfig command line, type: UserConfig> flags psm0 0x100 UserConfig> quit How come my PS/2 mouse from MouseSystems does not seem to work? There have been some reports that certain model of PS/2 mouse from MouseSystems works only if it is put into the high resolution mode. Otherwise, the mouse cursor may jump to the upper-left corner of the screen every so often. Unfortunately there is no workaround for versions 2.0.X and 2.1.X. In versions 2.2 through 2.2.5, apply the following patch to /sys/i386/isa/psm.c and rebuild the kernel. See the section on building a kernel if you have no experience with building kernels. @@ -766,6 +766,8 @@ if (verbose >= 2) log(LOG_DEBUG, "psm%d: SET_DEFAULTS return code:%04x\n", unit, i); + set_mouse_resolution(sc->kbdc, PSMD_RES_HIGH); + #if 0 set_mouse_scaling(sc->kbdc); /* 1:1 scaling */ set_mouse_mode(sc->kbdc); /* stream mode */ In versions 2.2.6 or later, specify the flags 0x04 to the PS/2 mouse driver to put the mouse into the high resolution mode. Enter UserConfig by giving the option at the boot prompt: boot: -c Then, in the UserConfig command line, type: UserConfig> flags psm0 0x04 UserConfig> quit See the previous section for another possible cause of mouse problems. When building an X app, imake cannot find Imake.tmpl. Where is it? Imake.tmpl is part of the Imake package, a standard X application building tool. Imake.tmpl, as well as several header files that are required to build X apps, is contained in the X prog distribution. You can install this from sysinstall or manually from the X distribution files. How do I reverse the mouse buttons? Run the command xmodmap -e "pointer = 3 2 1" from your .xinitrc or .xsession. How do I install a splash screen and where do I find them? Just prior to the release of FreeBSD 3.1, a new feature was added to allow the display of splash screens during the boot messages. The splash screens currently must be a 256 color bitmap (*.BMP) or ZSoft PCX (*.PCX) file. In addition, they must have a resolution of 320x200 or less to work on standard VGA adapters. If you compile VESA support into your kernel, then you can use larger bitmaps up to 1024x768. Note that VESA support requires the VM86 kernel option to be compiled into the kernel. The actual VESA support can either be compiled directly into the kernel with the VESA kernel config option or by loading the VESA kld module during bootup. To use a splash screen, you need to modify the startup files that control the boot process for FreeBSD. The files for this changed prior to the release of FreeBSD 3.2, so there are now two ways of loading a splash screen: FreeBSD 3.1 The first step is to find a bitmap version of your splash screen. Release 3.1 only supports Windows bitmap splash screens. Once you have found your splash screen of choice copy it to /boot/splash.bmp. Next, you need to have a /boot/loader.rc file that contains the following lines: load kernel load -t splash_image_data /boot/splash.bmp load splash_bmp autoboot FreeBSD 3.2+ In addition to adding support for PCX splash screens, FreeBSD 3.2 includes a nicer way of configuring the boot process. If you wish, you can use the method listed above for FreeBSD 3.1. If you do and you want to use PCX, replace splash_bmp with splash_pcx. If, on the other hand, you want to use the newer boot configuration, you need to create a /boot/loader.rc file that contains the following lines: include /boot/loader.4th start and a /boot/loader.conf that contains the following: splash_bmp_load="YES" bitmap_load="YES" This assumes you are using /boot/splash.bmp for your splash screen. If you would rather use a PCX file, copy it to /boot/splash.pcx, create a /boot/loader.rc as instructed above, and create a /boot/loader.conf that contains: splash_pcx_load="YES" bitmap_load="YES" bitmap_name="/boot/splash.pcx" Now all you need is a splash screen. For that you can surf on over to the gallery at http://www.baldwin.cx/splash/. Can I use the Windows(tm) keys on my keyboard in X? Yes. All you need to do is use &man.xmodmap.1; to define what function you wish them to perform. Assuming all Windows(tm) keyboards are standard then the keycodes for the 3 keys are 115 - Windows(tm) key, between the left-hand Ctrl and Alt keys 116 - Windows(tm) key, to the right of the Alt-Gr key 117 - Menu key, to the left of the right-hand Ctrl key To have the left Windows(tm) key print a comma, try this. &prompt.root; xmodmap -e "keycode 115 = comma" You will probably have to re-start your window manager to see the result. To have the Windows(tm) key-mappings enabled automatically every time you start X either put the xmodmap commands in your ~/.xinitrc file or, preferably, create a file ~/.xmodmaprc and include the xmodmap options, one per line, then add the line xmodmap $HOME/.xmodmaprc to your ~/.xinitrc. For example, you could map the 3 keys top be F13, F14, and F15, respectively. This would make it easy to map them to useful functions within applications or your window manager, as demonstrated further down. To do this put the following in ~/.xmodmaprc. keycode 115 = F13 keycode 116 = F14 keycode 117 = F15 If you use fvwm2, for example, you could map the keys so that F13 iconifies (or de-iconifies) the window the cursor is in, F14 brings the window the cursor is in to the front or, if it is already at the front, pushes it to the back, and F15 pops up the main Workplace (application) menu even if the cursor is not on the desktop, which is useful if you do not have any part of the desktop visible (and the logo on the key matches its functionality). The following entries in ~/.fvwmrc implement the aforementioned setup: Key F13 FTIWS A Iconify Key F14 FTIWS A RaiseLower Key F15 A A Menu Workplace Nop Networking Where can I get information on diskless booting? Diskless booting means that the FreeBSD box is booted over a network, and reads the necessary files from a server instead of its hard disk. For full details, please read the Handbook entry on diskless booting Can a FreeBSD box be used as a dedicated network router? Internet standards and good engineering practice prohibit us from providing packet forwarding by default in FreeBSD. You can however enable this feature by changing the following variable to YES in &man.rc.conf.5;: gateway_enable=YES # Set to YES if this host will be a gateway This option will put the &man.sysctl.8; variable net.inet.ip.forwarding to 1. In most cases, you will also need to run a routing process to tell other systems on your network about your router; FreeBSD comes with the standard BSD routing daemon &man.routed.8; or for more complex situations you may want to try GaTeD (available from http://www.gated.org/) which supports FreeBSD as of 3_5Alpha7. It is our duty to warn you that, even when FreeBSD is configured in this way, it does not completely comply with the Internet standard requirements for routers; however, it comes close enough for ordinary usage. Can I connect my Win95 box to the Internet via FreeBSD? Typically, people who ask this question have two PC's at home, one with FreeBSD and one with Win95; the idea is to use the FreeBSD box to connect to the Internet and then be able to access the Internet from the Windows95 box through the FreeBSD box. This is really just a special case of the previous question. ... and the answer is yes! In FreeBSD 3.x, user-mode ppp contains a option. If you run ppp with the , set gateway_enable to YES in /etc/rc.conf, and configure your Windows machine correctly, this should work fine. More detailed information about setting this up can be found in the Pedantic PPP Primer by Steve Sims. If you are using kernel-mode ppp, or have an Ethernet connection to the Internet, you will have to use &man.natd.8;. Please look at the natd section of this FAQ. Why does recompiling the latest BIND from ISC fail? There is a conflict between the cdefs.h file in the distribution and the one shipped with FreeBSD. Just remove compat/include/sys/cdefs.h. Does FreeBSD support SLIP and PPP? Yes. See the manual pages for &man.slattach.8;, &man.sliplogin.8;, &man.ppp.8;, and &man.pppd.8;. &man.ppp.8; and &man.pppd.8; provide support for both incoming and outgoing connections, while &man.sliplogin.8; deals exclusively with incoming connections, and &man.slattach.8; deals exclusively with outgoing connections. For more information on how to use these, please see the Handbook chapter on PPP and SLIP. If you only have access to the Internet through a shell account, you may want to have a look at the slirp package. It can provide you with (limited) access to services such as ftp and http direct from your local machine. Does FreeBSD support NAT or Masquerading? If you have a local subnet (one or more local machines), but have been allocated only a single IP number from your Internet provider (or even if you receive a dynamic IP number), you may want to look at the &man.natd.8; program. &man.natd.8; allows you to connect an entire subnet to the Internet using only a single IP number. The &man.ppp.8; program has similar functionality built in via the switch. The alias library (&man.libalias.3;) is used in both cases. How do I connect two FreeBSD systems over a parallel line using PLIP? Get a laplink cable. Make sure both computer have a kernel with lpt driver support. &prompt.root; dmesg | grep lp lpt0 at 0x378-0x37f irq 7 on isa lpt0: Interrupt-driven lp0: TCP/IP capable interface Plug in the laplink cable into the parallel interface. Configure the network interface parameters for lp0 on both sites as root. For example, if you want connect the host max with moritz max <-----> moritz IP Address 10.0.0.1 10.0.0.2 on max start &prompt.root; ifconfig lp0 10.0.0.1 10.0.0.2 on moritz start &prompt.root; ifconfig lp0 10.0.0.2 10.0.0.1 Thats all! Please read also the manpages &man.lp.4; and &man.lpt.4; . You should also add the hosts to /etc/hosts. 127.0.0.1 localhost.my.domain localhost 10.0.0.1 max.my.domain max 10.0.0.2 moritz.my.domain To check if it works do: on max: &prompt.root; ifconfig lp0 lp0: flags=8851<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet 10.0.0.1 --> 10.0.0.2 netmask 0xff000000 &prompt.root; netstat -r Routing tables Internet: Destination Gateway Flags Refs Use Netif Expire moritz max UH 4 127592 lp0 &prompt.root; ping -c 4 moritz PING moritz (10.0.0.2): 56 data bytes 64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms --- moritz ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms How come I cannot create a /dev/ed0 device? In the Berkeley networking framework, network interfaces are only directly accessible by kernel code. Please see the /etc/rc.network file and the manual pages for the various network programs mentioned there for more information. If this leaves you totally confused, then you should pick up a book describing network administration on another BSD-related operating system; with few significant exceptions, administering networking on FreeBSD is basically the same as on SunOS 4.0 or Ultrix. How can I setup Ethernet aliases? Add netmask 0xffffffff to your &man.ifconfig.8; command-line like the following: &prompt.root; ifconfig ed0 alias 204.141.95.2 netmask 0xffffffff How do I get my 3C503 to use the other network port? If you want to use the other ports, you will have to specify an additional parameter on the &man.ifconfig.8; command line. The default port is link0. To use the AUI port instead of the BNC one, use link2. These flags should be specified using the ifconfig_* variables in /etc/rc.conf (see &man.rc.conf.5;). Why am I having trouble with NFS and FreeBSD? Certain PC network cards are better than others (to put it mildly) and can sometimes cause problems with network intensive applications like NFS. See the Handbook entry on NFS for more information on this topic. Why can't I NFS-mount from a Linux box? Some versions of the Linux NFS code only accept mount requests from a privileged port; try &prompt.root; mount -o -P linuxbox:/blah /mnt Why can't I NFS-mount from a Sun box? Sun workstations running SunOS 4.X only accept mount requests from a privileged port; try &prompt.root; mount -o -P sunbox:/blah /mnt Why does mountd keep telling me it can't change attributes and that I have a bad exports list on my FreeBSD NFS server? The most frequent problem is not understanding this passage from the &man.exports.5; manual page correctly:
Each line in the file (other than comment lines that begin with a #) specifies the mount point(s) and export flags within one local server filesystem for one or more hosts. A host may be specified only once for each local filesystem on the server and there may be only one default entry for each server filesystem that applies to all other hosts.
This is made more clear by an example of a common mistake. If everything above /usr is part of one filesystem (there are no mounts above /usr) the following exports list is not valid: /usr/src client /usr/ports client There are two lines specifying properties for one filesystem, /usr, exported to the same host, client. The correct format is: /usr/src /usr/ports client To rephrase the passage from the manual page, the properties of one filesystem exported to a given host (world-wide exports are treated like another unique host) must all occur on one line. And yes, this does cause limitation in how you can export filesystems without ugly workarounds, but for most people, this is not an issue. The following is an example of a valid export list, where /usr and /exports are local filesystems: # Export src and ports to client01 and client02, but only # client01 has root privileges on it /usr/src /usr/ports -maproot=0 client01 /usr/src /usr/ports client02 # The "client" machines have root and can mount anywhere # up /exports. The world can mount /exports/obj read-only /exports -alldirs -maproot=0 client01 client02 /exports/obj -ro Why am I having problems talking PPP to NeXTStep machines? Try disabling the TCP extensions in /etc/rc.conf (see &man.rc.conf.5;) by changing the following variable to NO: tcp_extensions=NO Xylogic's Annex boxes are also broken in this regard and you must use the above change to connect thru them. How do I enable IP multicast support? Multicast host operations are fully supported in FreeBSD 2.0 and later by default. If you want your box to run as a multicast router, you will need to recompile your kernel with the MROUTING option and run &man.mrouted.8;. FreeBSD 2.2 and later will start &man.mrouted.8; at boot time if the flag mrouted_enable is set to "YES" in /etc/rc.conf. MBONE tools are available in their own ports category, mbone. If you are looking for the conference tools vic and vat, look there! For more information, see the Mbone Information Web. Which network cards are based on the DEC PCI chipset? Here is a list compiled by Glen Foster gfoster@driver.nsta.org, with some more modern additions: Network cards based on the DEC PCI chipset Vendor Model ASUS PCI-L101-TB Accton ENI1203 Cogent EM960PCI Compex ENET32-PCI D-Link DE-530 Dayna DP1203, DP2100 DEC DE435, DE450 Danpex EN-9400P3 JCIS Condor JC1260 Linksys EtherPCI Mylex LNP101 SMC EtherPower 10/100 (Model 9332) SMC EtherPower (Model 8432) TopWare TE-3500P Znyx (2.2.x) ZX312, ZX314, ZX342, ZX345, ZX346, ZX348 Znyx (3.x) ZX345Q, ZX346Q, ZX348Q, ZX412Q, ZX414, ZX442, ZX444, ZX474, ZX478, ZX212, ZX214 (10mbps/hd)
Why do I have to use the FQDN for hosts on my site? You will probably find that the host is actually in a different domain; for example, if you are in foo.bar.edu and you wish to reach a host called mumble in the bar.edu domain, you will have to refer to it by the fully-qualified domain name, mumble.bar.edu, instead of just mumble. Traditionally, this was allowed by BSD BIND resolvers. However the current version of bind (see &man.named.8;) that ships with FreeBSD no longer provides default abbreviations for non-fully qualified domain names other than the domain you are in. So an unqualified host mumble must either be found as mumble.foo.bar.edu, or it will be searched for in the root domain. This is different from the previous behavior, where the search continued across mumble.bar.edu, and mumble.edu. Have a look at RFC 1535 for why this was considered bad practice, or even a security hole. As a good workaround, you can place the line search foo.bar.edu bar.edu instead of the previous domain foo.bar.edu into your /etc/resolv.conf file (see &man.resolv.conf.5;). However, make sure that the search order does not go beyond the boundary between local and public administration, as RFC 1535 calls it. Why do I get an error, Permission denied, for all networking operations? If you have compiled your kernel with the IPFIREWALL option, you need to be aware that the default policy as of 2.1.7R (this actually changed during 2.1-STABLE development) is to deny all packets that are not explicitly allowed. If you had unintentionally misconfigured your system for firewalling, you can restore network operability by typing the following while logged in as root: &prompt.root; ipfw add 65534 allow all from any to any You can also set firewall_type="open" in /etc/rc.conf. For further information on configuring a FreeBSD firewall, see the Handbook section. How much overhead does IPFW incur? The answer to this depends mostly on your rule set and - processor speed. For most applications dealing with ethernet + processor speed. For most applications dealing with Ethernet and small rule sets, the answer is, negligible. For those of you that need actual measurements to satisfy your curiosity, read on. The following measurements were made using 2.2.5-STABLE on a 486-66. IPFW was modified to measure the time spent within the ip_fw_chk routine, displaying the results to the console every 1000 packets. Two rule sets, each with 1000 rules were tested. The first set was designed to demonstrate a worst case scenario by repeating the rule: &prompt.root; ipfw add deny tcp from any to any 55555 This demonstrates worst case by causing most of IPFW's packet check routine to be executed before finally deciding that the packet does not match the rule (by virtue of the port number). Following the 999th iteration of this rule was an allow ip from any to any. The second set of rules were designed to abort the rule check quickly: &prompt.root; ipfw add deny ip from 1.2.3.4 to 1.2.3.4 The nonmatching source IP address for the above rule causes these rules to be skipped very quickly. As before, the 1000th rule was an allow ip from any to any. The per-packet processing overhead in the former case was approximately 2.703ms/packet, or roughly 2.7 microseconds per rule. Thus the theoretical packet processing limit with these rules is around 370 packets per second. Assuming 10Mbps - ethernet and a ~1500 byte packet size, we would only be able to + Ethernet and a ~1500 byte packet size, we would only be able to achieve a 55.5% bandwidth utilization. For the latter case each packet was processed in approximately 1.172ms, or roughly 1.2 microseconds per rule. The theoretical packet processing limit here would be about - 853 packets per second, which could consume 10Mbps ethernet + 853 packets per second, which could consume 10Mbps Ethernet bandwidth. The excessive number of rules tested and the nature of those rules do not provide a real-world scenario -- they were used only to generate the timing information presented here. Here are a few things to keep in mind when building an efficient rule set: Place an established rule early on to handle the majority of TCP traffic. Do not put any allow tcp statements before this rule. Place heavily triggered rules earlier in the rule set than those rarely used (without changing the permissiveness of the firewall, of course). You can see which rules are used most often by examining the packet counting statistics with ipfw -a l. Why is my ipfw fwd rule to redirect a service to another machine not working? Possibly because you want to do network address translation (NAT) and not just forward packets. A fwd rule does exactly what it says; it forwards packets. It does not actually change the data inside the packet. Say we have a rule like: 01000 fwd 10.0.0.1 from any to foo 21 When a packet with a destination address of foo arrives at the machine with this rule, the packet is forwarded to 10.0.0.1, but it still has the destination address of foo! The destination address of the packet is not changed to 10.0.0.1. Most machines would probably drop a packet that they receive with a destination address that is not their own. Therefore, using a fwd rule does not often work the way the user expects. This behavior is a feature and not a bug. See the FAQ about redirecting services, the &man.natd.8; manual, or one of the several port redirecting utilities in the ports collection for a correct way to do this. How can I redirect service requests from one machine to another? You can redirect FTP (and other service) request with the socket package, available in the ports tree in category sysutils. Simply replace the service's commandline to call socket instead, like so: ftp stream tcp nowait nobody /usr/local/bin/socket socket ftp.foo.com ftp where ftp.foo.com and ftp are the host and port to redirect to, respectively. Where can I get a bandwidth management tool? There are two bandwidth management tools available for FreeBSD. ALTQ is available for free; Bandwidth Manager from Emerging Technologies is a commercial product. BIND (named) is listening on port 53 and some other high-numbered port. Has my host been compromised? Probably not. FreeBSD 3.0 and later use a version of BIND that uses a random high-numbered port for outgoing queries. If you want to use port 53 for outgoing queries, either to get past a firewall or to make yourself feel better, you can try the following in /etc/namedb/named.conf: options { query-source address * port 53; }; You can replace the * with a single IP address if you want to tighten things further. Congratulations, by the way. It is good practice to read your &man.sockstat.1; output and notice odd things! Why do I get /dev/bpf0: device not configured? The Berkeley Packet Filter (&man.bpf.4;) driver needs to be enabled before running programs that utilize it. Add this to your kernel config file and build a new kernel: pseudo-device bpfilter # Berkeley Packet Filter Secondly, after rebooting you will have to create the device node. This can be accomplished by a change to the /dev directory, followed by the execution of: &prompt.root; sh MAKEDEV bpf0 Please see the handbook's entry on device nodes for more information on creating devices. How do I mount a disk from a Windows machine that is on my network, like smbmount in Linux? Use the sharity light package in the ports collection. What are these messages about icmp-response bandwidth limit 300/200 pps in my log files? This is the kernel telling you that some activity is provoking it to send more ICMP or TCP reset (RST) responses than it thinks it should. ICMP responses are often generated as a result of attempted connections to unused UDP ports. TCP resets are generated as a result of attempted connections to unopened TCP ports. Among others, these are the kinds of activities which may cause these messages: Brute-force denial of service (DoS) attacks (as opposed to single-packet attacks which exploit a specific vulnerability). Port scans which attempt to connect to a large number of ports (as opposed to only trying a few well-known ports). The first number in the message tells you how many packets the kernel would have sent if the limit was not in place, and the second number tells you the limit. You can control the limit using the net.inet.icmp.icmplim sysctl variable like this, where 300 is the limit in packets per second: &prompt.root; sysctl -w net.inet.icmp.icmplim=300 If you do not want to see messages about this in your log files, but you still want the kernel to do response limiting, you can use the net.inet.icmp.icmplim_output sysctl variable to disable the output like this: &prompt.root; sysctl -w net.inet.icmp.icmplim_output=0 Finally, if you want to disable response limiting, you can set the net.inet.icmp.icmplim sysctl variable (see above for an example) to 0. Disabling response limiting is discouraged for the reasons listed above. PPP I cannot make &man.ppp.8; work. What am I doing wrong? You should first read the &man.ppp.8; man page and the ppp section of the handbook. Enable logging with the command set log Phase Chat Connect Carrier lcp ipcp ccp command This command may be typed at the ppp command prompt or it may be entered in the /etc/ppp/ppp.conf configuration file (the start of the default section is the best place to put it). Make sure that /etc/syslog.conf (see &man.syslog.conf.5;) contains the lines !ppp *.* /var/log/ppp.log and that the file /var/log/ppp.log exists. You can now find out a lot about what is going on from the log file. Do not worry if it does not all make sense. If you need to get help from someone, it may make sense to them. If your version of ppp does not understand the set log command, you should download the latest version. It will build on FreeBSD version 2.1.5 and higher. Why does &man.ppp.8; hang when I run it? This is usually because your hostname will not resolve. The best way to fix this is to make sure that /etc/hosts is consulted by your resolver first by editing /etc/host.conf and putting the hosts line first. Then, simply put an entry in /etc/hosts for your local machine. If you have no local network, change your localhost line: 127.0.0.1 foo.bar.com foo localhost Otherwise, simply add another entry for your host. Consult the relevant man pages for more details. You should be able to successfully ping -c1 `hostname` when you are done. Why won't &man.ppp.8; dial in -auto mode? First, check that you have got a default route. By running netstat -rn (see &man.netstat.1;), you should see two entries like this: Destination Gateway Flags Refs Use Netif Expire default 10.0.0.2 UGSc 0 0 tun0 10.0.0.2 10.0.0.1 UH 0 0 tun0 This is assuming that you have used the addresses from the handbook, the man page or from the ppp.conf.sample file. If you haven't got a default route, it may be because you are running an old version of &man.ppp.8; that does not understand the word HISADDR in the ppp.conf file. If your version of ppp is from before FreeBSD 2.2.5, change the add 0 0 HISADDR line to one saying add 0 0 10.0.0.2 Another reason for the default route line being missing is that you have mistakenly set up a default router in your /etc/rc.conf (see &man.rc.conf.5;) file (this file was called /etc/sysconfig prior to release 2.2.2), and you have omitted the line saying delete ALL from ppp.conf. If this is the case, go back to the Final system configuration section of the handbook. What does No route to host mean? This error is usually due to a missing MYADDR: delete ALL add 0 0 HISADDR section in your /etc/ppp/ppp.linkup file. This is only necessary if you have a dynamic IP address or do not know the address of your gateway. If you are using interactive mode, you can type the following after entering packet mode (packet mode is indicated by the capitalized PPP in the prompt): delete ALL add 0 0 HISADDR Refer to the PPP and Dynamic IP addresses section of the handbook for further details. Why does my connection drop after about 3 minutes? The default ppp timeout is 3 minutes. This can be adjusted with the line set timeout NNN where NNN is the number of seconds of inactivity before the connection is closed. If NNN is zero, the connection is never closed due to a timeout. It is possible to put this command in the ppp.conf file, or to type it at the prompt in interactive mode. It is also possible to adjust it on the fly while the line is active by connecting to ppps server socket using &man.telnet.1; or &man.pppctl.8;. Refer to the &man.ppp.8; man page for further details. Why does my connection drop under heavy load? If you have Link Quality Reporting (LQR) configured, it is possible that too many LQR packets are lost between your machine and the peer. Ppp deduces that the line must therefore be bad, and disconnects. Prior to FreeBSD version 2.2.5, LQR was enabled by default. It is now disabled by default. LQR can be disabled with the line disable lqr Why does my connection drop after a random amount of time? Sometimes, on a noisy phone line or even on a line with call waiting enabled, your modem may hang up because it thinks (incorrectly) that it lost carrier. There is a setting on most modems for determining how tolerant it should be to temporary losses of carrier. On a USR Sportster for example, this is measured by the S10 register in tenths of a second. To make your modem more forgiving, you could add the following send-expect sequence to your dial string: set dial "...... ATS10=10 OK ......" Refer to your modem manual for details. Why does my connection hang after a random amount of time? Many people experience hung connections with no apparent explanation. The first thing to establish is which side of the link is hung. If you are using an external modem, you can simply try using &man.ping.8; to see if the TD light is flashing when you transmit data. If it flashes (and the RD light does not), the problem is with the remote end. If TD does not flash, the problem is local. With an internal modem, you will need to use the set server command in your ppp.conf file. When the hang occurs, connect to ppp using pppctl. If your network connection suddenly revives (ppp was revived due to the activity on the diagnostic socket) or if you cannot connect (assuming the set socket command succeeded at startup time), the problem is local. If you can connect and things are still hung, enable local async logging with set log local async and use &man.ping.8; from another window or terminal to make use of the link. The async logging will show you the data being transmitted and received on the link. If data is going out and not coming back, the problem is remote. Having established whether the problem is local or remote, you now have two possibilities: The remote end is not responding. What can I do? There is very little you can do about this. Most ISPs will refuse to help if you are not running a Microsoft OS. You can enable lqr in your ppp.conf file, allowing ppp to detect the remote failure and hang up, but this detection is relatively slow and therefore not that useful. You may want to avoid telling your ISP that you are running user-ppp.... First, try disabling all local compression by adding the following to your configuration: disable pred1 deflate deflate24 protocomp acfcomp shortseq vj deny pred1 deflate deflate24 protocomp acfcomp shortseq vj Then reconnect to ensure that this makes no difference. If things improve or if the problem is solved completely, determine which setting makes the difference through trial and error. This will provide good ammunition when you contact your ISP (although it may make it apparent that you are not running a Microsoft product). Before contacting your ISP, enable async logging locally and wait until the connection hangs again. This may use up quite a bit of disk space. The last data read from the port may be of interest. It is usually ascii data, and may even describe the problem (Memory fault, core dumped?). If your ISP is helpful, they should be able to enable logging on their end, then when the next link drop occurs, they may be able to tell you why their side is having a problem. Feel free to send the details to &a.brian;, or even to ask your ISP to contact me directly. &man.ppp.8; has hung. What can I do? Your best bet here is to rebuild ppp by adding CFLAGS+=-g and STRIP= to the end of the Makefile, then doing a make clean && make && make install. When ppp hangs, find the ppp process id with ps ajxww | fgrep ppp and run gdb ppp PID. From the gdb prompt, you can then use bt to get a stack trace. Send the results to brian@Awfulhak.org. Why does nothing happen after the Login OK! message? Prior to FreeBSD version 2.2.5, once the link was established, &man.ppp.8; would wait for the peer to initiate the Line Control Protocol (LCP). Many ISPs will not initiate negotiations and expect the client to do so. To force ppp to initiate the LCP, use the following line: set openmode active It usually does no harm if both sides initiate negotiation, so openmode is now active by default. However, the next section explains when it does do some harm. I keep seeing errors about magic being the same. What does it mean? Occasionally, just after connecting, you may see messages in the log that say magic is the same. Sometimes, these messages are harmless, and sometimes one side or the other exits. Most ppp implementations cannot survive this problem, and even if the link seems to come up, you will see repeated configure requests and configure acknowledgments in the log file until ppp eventually gives up and closes the connection. This normally happens on server machines with slow disks that are spawning a getty on the port, and executing ppp from a login script or program after login. I have also heard reports of it happening consistently when using slirp. The reason is that in the time taken between getty exiting and ppp starting, the client-side ppp starts sending Line Control Protocol (LCP) packets. Because ECHO is still switched on for the port on the server, the client ppp sees these packets reflect back. One part of the LCP negotiation is to establish a magic number for each side of the link so that reflections can be detected. The protocol says that when the peer tries to negotiate the same magic number, a NAK should be sent and a new magic number should be chosen. During the period that the server port has ECHO turned on, the client ppp sends LCP packets, sees the same magic in the reflected packet and NAKs it. It also sees the NAK reflect (which also means ppp must change its magic). This produces a potentially enormous number of magic number changes, all of which are happily piling into the server's tty buffer. As soon as ppp starts on the server, it is flooded with magic number changes and almost immediately decides it has tried enough to negotiate LCP and gives up. Meanwhile, the client, who no longer sees the reflections, becomes happy just in time to see a hangup from the server. This can be avoided by allowing the peer to start negotiating with the following line in your ppp.conf file: set openmode passive This tells ppp to wait for the server to initiate LCP negotiations. Some servers however may never initiate negotiations. If this is the case, you can do something like: set openmode active 3 This tells ppp to be passive for 3 seconds, and then to start sending LCP requests. If the peer starts sending requests during this period, ppp will immediately respond rather than waiting for the full 3 second period. LCP negotiations continue 'till the connection is closed. What is wrong? There is currently an implementation mis-feature in ppp where it does not associate LCP, CCP & IPCP responses with their original requests. As a result, if one ppp implementation is more than 6 seconds slower than the other side, the other side will send two additional LCP configuration requests. This is fatal. Consider two implementations, A and B. A starts sending LCP requests immediately after connecting and B takes 7 seconds to start. When B starts, A has sent 3 LCP REQs. We are assuming the line has ECHO switched off, otherwise we would see magic number problems as described in the previous section. B sends a REQ, then an ACK to the first of A's REQs. This results in A entering the OPENED state and sending and ACK (the first) back to B. In the meantime, B sends back two more ACKs in response to the two additional REQs sent by A before B started up. B then receives the first ACK from A and enters the OPENED state. A receives the second ACK from B and goes back to the REQ-SENT state, sending another (forth) REQ as per the RFC. It then receives the third ACK and enters the OPENED state. In the meantime, B receives the forth REQ from A, resulting in it reverting to the ACK-SENT state and sending another (second) REQ and (forth) ACK as per the RFC. A gets the REQ, goes into REQ-SENT and sends another REQ. It immediately receives the following ACK and enters OPENED. This goes on 'till one side figures out that they are getting nowhere and gives up. The best way to avoid this is to configure one side to be passive - that is, make one side wait for the other to start negotiating. This can be done with the set openmode passive command. Care should be taken with this option. You should also use the set stopped N command to limit the amount of time that ppp waits for the peer to begin negotiations. Alternatively, the set openmode active N command (where N is the number of seconds to wait before starting negotiations) can be used. Check the manual page for details. Why does &man.ppp.8; lock up shortly after connection? Prior to version 2.2.5 of FreeBSD, it was possible that your link was disabled shortly after connection due to ppp mis-handling Predictor1 compression negotiation. This would only happen if both sides tried to negotiate different Compression Control Protocols (CCP). This problem is now corrected, but if you are still running an old version of ppp, the problem can be circumvented with the line disable pred1 Why does &man.ppp.8; lock up when I shell out to test it? When you execute the shell or ! command, ppp executes a shell (or if you have passed any arguments, ppp will execute those arguments). Ppp will wait for the command to complete before continuing. If you attempt to use the ppp link while running the command, the link will appear to have frozen. This is because ppp is waiting for the command to complete. If you wish to execute commands like this, use the !bg command instead. This will execute the given command in the background, and ppp can continue to service the link. How come &man.ppp.8; over a null-modem cable never exits? There is no way for ppp to automatically determine that a direct connection has been dropped. This is due to the lines that are used in a null-modem serial cable. When using this sort of connection, LQR should always be enabled with the line enable lqr LQR is accepted by default if negotiated by the peer. Why does &man.ppp.8; dial for no reason in -auto mode? If ppp is dialing unexpectedly, you must determine the cause, and set up Dial filters (dfilters) to prevent such dialing. To determine the cause, use the following line: set log +tcp/ip This will log all traffic through the connection. The next time the line comes up unexpectedly, you will see the reason logged with a convenient timestamp next to it. You can now disable dialing under these circumstances. Usually, this sort of problem arises due to DNS lookups. To prevent DNS lookups from establishing a connection (this will not prevent ppp from passing the packets through an established connection), use the following: set dfilter 1 deny udp src eq 53 set dfilter 2 deny udp dst eq 53 set dfilter 3 permit 0/0 0/0 This is not always suitable, as it will effectively break your demand-dial capabilities - most programs will need a DNS lookup before doing any other network related things. In the DNS case, you should try to determine what is actually trying to resolve a host name. A lot of the time, &man.sendmail.8; is the culprit. You should make sure that you tell sendmail not to do any DNS lookups in its configuration file. See the section on Mail Configuration for details on how to create your own configuration file and what should go into it. You may also want to add the following line to your .mc file: define(`confDELIVERY_MODE', `d')dnl This will make sendmail queue everything until the queue is run (usually, sendmail is invoked with , telling it to run the queue every 30 minutes) or until a sendmail -q is done (perhaps from your ppp.linkup file). What do these CCP errors mean? I keep seeing the following errors in my log file: CCP: CcpSendConfigReq CCP: Received Terminate Ack (1) state = Req-Sent (6) This is because ppp is trying to negotiate Predictor1 compression, and the peer does not want to negotiate any compression at all. The messages are harmless, but if you wish to remove them, you can disable Predictor1 compression locally too: disable pred1 Why does &man.ppp.8; lock up during file transfers with IO errors? Under FreeBSD 2.2.2 and before, there was a bug in the tun driver that prevents incoming packets of a size larger than the tun interface's MTU size. Receipt of a packet greater than the MTU size results in an IO error being logged via syslogd. The ppp specification says that an MRU of 1500 should always be accepted as a minimum, despite any LCP negotiations, therefore it is possible that should you decrease the MTU to less than 1500, your ISP will transmit packets of 1500 regardless, and you will tickle this non-feature - locking up your link. The problem can be circumvented by never setting an MTU of less than 1500 under FreeBSD 2.2.2 or before. Why doesn't &man.ppp.8; log my connection speed? In order to log all lines of your modem conversation, you must enable the following: set log +connect This will make &man.ppp.8; log everything up until the last requested expect string. If you wish to see your connect speed and are using PAP or CHAP (and therefore do not have anything to chat after the CONNECT in the dial script - no set login script), you must make sure that you instruct ppp to expect the whole CONNECT line, something like this: set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 4 \ \"\" ATZ OK-ATZ-OK ATDT\\T TIMEOUT 60 CONNECT \\c \\n" Here, we get our CONNECT, send nothing, then expect a line-feed, forcing ppp to read the whole CONNECT response. Why does &man.ppp.8; ignore the \ character in my chat script? Ppp parses each line in your config files so that it can interpret strings such as set phone "123 456 789" correctly (and realize that the number is actually only one argument. In order to specify a " character, you must escape it using a backslash (\). When the chat interpreter parses each argument, it re-interprets the argument in order to find any special escape sequences such as \P or \T (see the man page). As a result of this double-parsing, you must remember to use the correct number of escapes. If you wish to actually send a \ character to (say) your modem, you would need something like: set dial "\"\" ATZ OK-ATZ-OK AT\\\\X OK" resulting in the following sequence: ATZ OK AT\X OK or set phone 1234567 set dial "\"\" ATZ OK ATDT\\T" resulting in the following sequence: ATZ OK ATDT1234567 Why does &man.ppp.8; get a seg-fault, but I see no ppp.core file? Ppp (or any other program for that matter) should never dump core. Because ppp runs with an effective user id of 0, the operating system will not write ppps core image to disk before terminating it. If, however ppp is actually terminating due to a segmentation violation or some other signal that normally causes core to be dumped, and you are sure you are using the latest version (see the start of this section), then you should do the following: &prompt.user; tar xfz ppp-*.src.tar.gz &prompt.user; cd ppp*/ppp &prompt.user; echo STRIP= >>Makefile &prompt.user; echo CFLAGS+=-g >>Makefile &prompt.user; make clean all &prompt.user; su &prompt.root; make install &prompt.root; chmod 555 /usr/sbin/ppp You will now have a debuggable version of ppp installed. You will have to be root to run ppp as all of its privileges have been revoked. When you start ppp, take a careful note of what your current directory was at the time. Now, if and when ppp receives the segmentation violation, it will dump a core file called ppp.core. You should then do the following: &prompt.user; su &prompt.root; gdb /usr/sbin/ppp ppp.core (gdb) bt ..... (gdb) f 0 .... (gdb) i args .... (gdb) l ..... All of this information should be given alongside your question, making it possible to diagnose the problem. If you are familiar with gdb, you may wish to find out some other bits and pieces such as what actually caused the dump and the addresses & values of the relevant variables. Why does the process that forces a dial in auto mode never connect? This was a known problem with ppp set up to negotiate a dynamic local IP number with the peer in auto mode. It is fixed in the latest version - search the man page for iface. The problem was that when that initial program calls &man.connect.2;, the IP number of the tun interface is assigned to the socket endpoint. The kernel creates the first outgoing packet and writes it to the tun device. ppp then reads the packet and establishes a connection. If, as a result of ppps dynamic IP assignment, the interface address is changed, the original socket endpoint will be invalid. Any subsequent packets sent to the peer will usually be dropped. Even if they are not, any responses will not route back to the originating machine as the IP number is no longer owned by that machine. There are several theoretical ways to approach this problem. It would be nicest if the peer would re-assign the same IP number if possible :-) The current version of ppp does this, but most other implementations do not. The easiest method from our side would be to never change the tun interface IP number, but instead to change all outgoing packets so that the source IP number is changed from the interface IP to the negotiated IP on the fly. This is essentially what the iface-alias option in the latest version of ppp is doing (with the help of &man.libalias.3; and ppp's switch) - it is maintaining all previous interface addresses and NATing them to the last negotiated address. Another alternative (and probably the most reliable) would be to implement a system call that changes all bound sockets from one IP to another. ppp would use this call to modify the sockets of all existing programs when a new IP number is negotiated. The same system call could be used by dhcp clients when they are forced to re-bind() their sockets. Yet another possibility is to allow an interface to be brought up without an IP number. Outgoing packets would be given an IP number of 255.255.255.255 up until the first SIOCAIFADDR ioctl is done. This would result in fully binding the socket. It would be up to ppp to change the source IP number, but only if it is set to 255.255.255.255, and only the IP number and IP checksum would need to change. This, however is a bit of a hack as the kernel would be sending bad packets to an improperly configured interface, on the assumption that some other mechanism is capable of fixing things retrospectively. Why don't most games work with the -nat switch? The reason games and the like do not work when libalias is in use is that the machine on the outside will try to open a connection or send (unsolicited) UDP packets to the machine on the inside. The NAT software does not know that it should send these packets to the interior machine. To make things work, make sure that the only thing running is the software that you are having problems with, then either run tcpdump on the tun interface of the gateway or enable ppp tcp/ip logging (set log +tcp/ip) on the gateway. When you start the offending software, you should see packets passing through the gateway machine. When something comes back from the outside, it will be dropped (that is the problem). Note the port number of these packets then shut down the offending software. Do this a few times to see if the port numbers are consistent. If they are, then the following line in the relevant section of /etc/ppp/ppp.conf will make the software functional: nat port proto internalmachine:port port where proto is either tcp or udp, internalmachine is the machine that you want the packets to be sent to and port is the destination port number of the packets. You will not be able to use the software on other machines without changing the above command, and running the software on two internal machines at the same time is out of the question - after all, the outside world is seeing your entire internal network as being just a single machine. If the port numbers are not consistent, there are three more options: Submit support in libalias. Examples of special cases can be found in /usr/src/lib/libalias/alias_*.c (alias_ftp.c is a good prototype). This usually involves reading certain recognised outgoing packets, identifying the instruction that tells the outside machine to initiate a connection back to the internal machine on a specific (random) port and setting up a route in the alias table so that the subsequent packets know where to go. This is the most difficult solution, but it is the best and will make the software work with multiple machines. Use a proxy. The application may support socks5 for example, or (as in the cvsup case) may have a passive option that avoids ever requesting that the peer open connections back to the local machine. Redirect everything to the internal machine using nat addr. This is the sledge-hammer approach. Has anybody made a list of useful port numbers? Not yet, but this is intended to grow into such a list (if any interest is shown). In each example, internal should be replaced with the IP number of the machine playing the game. Asheron's Call nat port udp internal :65000 65000 Manually change the port number within the game to 65000. If you have got a number of machines that you wish to play on assign a unique port number for each (i.e. 65001, 65002, etc) and add a nat port line for each one. Half Life nat port udp internal:27005 27015 PCAnywhere 8.0 nat port udp internal:5632 5632 nat port tcp internal:5631 5631 Quake nat port udp internal:6112 6112 Alternatively, you may want to take a look at www.battle.net for Quake proxy support. Quake 2 nat port udp internal:27901 27910 Red Alert nat port udp internal:8675 8675 nat port udp internal:5009 5009 What are FCS errors? FCS stands for Frame Check Sequence. Each ppp packet has a checksum attached to ensure that the data being received is the data being sent. If the FCS of an incoming packet is incorrect, the packet is dropped and the HDLC FCS count is increased. The HDLC error values can be displayed using the show hdlc command. If your link is bad (or if your serial driver is dropping packets), you will see the occasional FCS error. This is not usually worth worrying about although it does slow down the compression protocols substantially. If you have an external modem, make sure your cable is properly shielded from interference - this may eradicate the problem. If your link freezes as soon as you have connected and you see a large number of FCS errors, this may be because your link is not 8 bit clean. Make sure your modem is not using software flow control (XON/XOFF). If your datalink must use software flow control, use the command set accmap 0x000a0000 to tell ppp to escape the ^Q and ^S characters. Another reason for seeing too many FCS errors may be that the remote end has stopped talking PPP. You may want to enable async logging at this point to determine if the incoming data is actually a login or shell prompt. If you have a shell prompt at the remote end, it is possible to terminate ppp without dropping the line by using the close lcp command (a following term command will reconnect you to the shell on the remote machine. If nothing in your log file indicates why the link might have been terminated, you should ask the remote administrator (your ISP?) why the session was terminated. Why do MacOS and Windows 98 connections freeze when running PPPoE on the gateway? Thanks to Michael Wozniak mwozniak@netcom.ca for figuring this out and Dan Flemming danflemming@mac.com for the Mac solution: This is due to what is called a Black Hole router. MacOS and Windows 98 (and maybe other Microsoft OSs) send TCP packets with a requested segment size too big to fit - into a PPPoE frame (MTU is 1500 by default for ethernet) + into a PPPoE frame (MTU is 1500 by default for Ethernet) and have the do not fragment bit set (default of TCP) and the Telco router is not sending ICMP must fragment back to the www site you are trying to load. (Alternatively, the router is sending the ICMP packet correctly, but the firewall at the www site is dropping it.) When the www server is sending you frames that do not fit into the PPPoE pipe the Telco router drops them on the floor and your page does not load (some pages/graphics do as they are smaller than a MSS.) This seems to be the default of most Telco PPPoE configurations (if only they knew how to program a router... sigh...) One fix is to use regedit on your 95/98 boxes to add the following registry entry... HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\NetTrans\0000\MaxMTU It should be a string with a value 1450 (more accurately it should be 1464 to fit TCP packets into a PPPoE frame perfectly but the 1450 gives you a margin of error for other IP protocols you may encounter). This registry key is reported to have moved to Tcpip\Parameters\Interfaces\ID for adapter\MTU in Windows 2000. Refer to Microsoft Knowledge Base documents Q158474 - Windows TCPIP Registry Entries and Q120642 - TCPIP & NBT Configuration Parameters for Windows NT for more information on changing Windoze MTU to work with a FreeBSD/NAT/PPPoE router. Unfortunately, MacOS does not provide an interface for changing TCP/IP settings. However, there is commercial software available, such as OTAdvancedTuner (OT for OpenTransport, the MacOS TCP/IP stack) by Sustainable Softworks, that will allow users to customize TCP/IP settings. MacOS NAT users should select ip_interface_MTU from the drop-down menu, enter 1450 instead of 1500 in the box, click the box next to Save as Auto Configure, and click Make Active. The latest version of ppp (2.3 or greater) has an enable tcpmssfixup command that will automatically adjust the MSS to an appropriate value. This facility is enabled by default. If you are stuck with an older version of ppp, you may want to look at the tcpmssd port. None of this helps - I am desperate! What can I do? If all else fails, send as much information as you can, including your config files, how you are starting ppp, the relevant parts of your log file and the output of the netstat -rn command (before and after connecting) to the &a.questions; or the comp.unix.bsd.freebsd.misc news group, and someone should point you in the right direction. Serial Communications This section answers common questions about serial communications with FreeBSD. PPP and SLIP are covered in the section. How do I tell if FreeBSD found my serial ports? As the FreeBSD kernel boots, it will probe for the serial ports in your system for which the kernel was configured. You can either watch your system closely for the messages it prints or run the command &prompt.user; dmesg | grep sio after your system is up and running. Here is some example output from the above command: sio0 at 0x3f8-0x3ff irq 4 on isa sio0: type 16550A sio1 at 0x2f8-0x2ff irq 3 on isa sio1: type 16550A This shows two serial ports. The first is on irq 4, is using port address 0x3f8, and has a 16550A-type UART chip. The second uses the same kind of chip but is on irq 3 and is at port address 0x2f8. Internal modem cards are treated just like serial ports---except that they always have a modem attached to the port. The GENERIC kernel includes support for two serial ports using the same irq and port address settings in the above example. If these settings are not right for your system, or if you've added modem cards or have more serial ports than your kernel is configured for, just reconfigure your kernel. See section about building a kernel for more details. How do I tell if FreeBSD found my modem cards? Refer to the answer to the previous question. I just upgraded to 2.0.5 and my tty0X are missing! How do I solve this problem? Do not worry, they have been merged with the ttydX devices. You will have to change any old configuration files you have, though. How do I access the serial ports on FreeBSD? The third serial port, sio2 (see &man.sio.4;, known as COM3 in DOS), is on /dev/cuaa2 for dial-out devices, and on /dev/ttyd2 for dial-in devices. What is the difference between these two classes of devices? You use ttydX for dial-ins. When opening /dev/ttydX in blocking mode, a process will wait for the corresponding cuaaX device to become inactive, and then wait for the carrier detect line to go active. When you open the cuaaX device, it makes sure the serial port is not already in use by the ttydX device. If the port is available, it steals it from the ttydX device. Also, the cuaaX device does not care about carrier detect. With this scheme and an auto-answer modem, you can have remote users log in and you can still dialout with the same modem and the system will take care of all the conflicts. How do I enable support for a multiport serial card? Again, the section on kernel configuration provides information about configuring your kernel. For a multiport serial card, place an &man.sio.4; line for each serial port on the card in the kernel configuration file. But place the irq and vector specifiers on only one of the entries. All of the ports on the card should share one irq. For consistency, use the last serial port to specify the irq. Also, specify the COM_MULTIPORT option. The following example is for an AST 4-port serial card on irq 7: options "COM_MULTIPORT" device sio4 at isa? port 0x2a0 tty flags 0x781 device sio5 at isa? port 0x2a8 tty flags 0x781 device sio6 at isa? port 0x2b0 tty flags 0x781 device sio7 at isa? port 0x2b8 tty flags 0x781 irq 7 vector siointr The flags indicate that the master port has minor number 7 (0x700), diagnostics enabled during probe (0x080), and all the ports share an irq (0x001). Can FreeBSD handle multiport serial cards sharing irqs? Not yet. You will have to use a different irq for each card. Can I set the default serial parameters for a port? The ttydX (or cuaaX) 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 CLOCAL mode, 8 bits, and XON/XOFF flow control by default for ttyd5, do: &prompt.root; stty -f /dev/ttyid5 clocal cs8 ixon ixoff A good place to do this is in /etc/rc.serial. Now, an application will have these settings by default when it opens ttyd5. It can still change these settings to its liking, though. You can also prevent certain settings from being changed by an application by making adjustments to the lock state device. For example, to lock the speed of ttyd5 to 57600 bps, do &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. Naturally, you should make the initial state and lock state devices writable only by root. The &man.MAKEDEV.8; script does NOT do this when it creates the device entries. How can I enable dialup logins on my modem? So you want to become an Internet service provider, eh? First, you will need one or more modems that can auto-answer. Your modem will need to assert carrier-detect when it detects a carrier and not assert it all the time. It will need to hang up the phone and reset itself when the data terminal ready (DTR) line goes from on to off. It should probably use RTS/CTS flow control or no local flow control at all. Finally, it must use a constant speed between the computer and itself, but (to be nice to your callers) it should negotiate a speed between itself and the remote modem. For many Hayes command-set--compatible modems, this command will make these settings and store them in nonvolatile memory: AT &C1 &D3 &K3 &Q6 S0=1 &W See the section on sending AT commands below for information on how to make these settings without resorting to an MS-DOS terminal program. Next, make an entry in /etc/ttys (see &man.ttys.5;) for the modem. This file lists all the ports on which the operating system will await logins. Add a line that looks something like this: ttyd1 "/usr/libexec/getty std.57600" dialup on insecure This line indicates that the second serial port (/dev/ttyd1) has a modem connected running at 57600 bps and no parity (std.57600, which comes from the file /etc/gettytab, see &man.gettytab.5;). The terminal type for this port is dialup. The port is on and is insecure---meaning root logins on the port are not allowed. For dialin ports like this one, use the ttydX entry. It is common practice to use dialup as the terminal type. Many users set up in their .profile or .login files a prompt for the actual terminal type if the starting type is dialup. The example shows the port as insecure. To become root on this port, you have to login as a regular user, then &man.su.1; to become root. If you use secure then root can login in directly. After making modifications to /etc/ttys, you need to send a hangup or HUP signal to the &man.init.8; process: &prompt.root; kill -HUP 1 This forces the &man.init.8; process to reread /etc/ttys. The init process will then start getty processes on all on ports. You can find out if logins are available for your port by typing &prompt.user; ps -ax | grep '[t]tyd1' You should see something like: 747 ?? I 0:00.04 /usr/libexec/getty std.57600 ttyd1 How can I connect a dumb terminal to my FreeBSD box? If you are using another computer as a terminal into your FreeBSD system, get a null modem cable to go between the two serial ports. If you are using an actual terminal, see its accompanying instructions. Then, modify /etc/ttys (see &man.ttys.5;), like above. For example, if you are hooking up a WYSE-50 terminal to the fifth serial port, use an entry like this: ttyd4 "/usr/libexec/getty std.38400" wyse50 on secure This example shows that the port on /dev/ttyd4 has a wyse50 terminal connected at 38400 bps with no parity (std.38400 from /etc/gettytab, see &man.gettytab.5;) and root logins are allowed (secure). Why can't I run tip or cu? On your system, the programs &man.tip.1; and &man.cu.1; are probably executable only by uucp and group dialer. You can use the group dialer to control who has access to your modem or remote systems. Just add yourself to group dialer. Alternatively, you can let everyone on your system run &man.tip.1; and &man.cu.1; by typing: &prompt.root; chmod 4511 /usr/bin/cu &prompt.root; chmod 4511 /usr/bin/tip My stock Hayes modem is not supported---what can I do? Actually, the man page for &man.tip.1; is out of date. There is a generic Hayes dialer already built in. Just use at=hayes in your /etc/remote (see &man.remote.5;) 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 &man.tip.1; (using ATX0&W). Also, the dial timeout for &man.tip.1; 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 &man.tip.1; 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? Make what is called a direct entry in your /etc/remote file (see &man.remote.5;). 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 (see &man.tip.1;) 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; sh MAKEDEV cuaa0 Or use cu as root with the following command: &prompt.root; cu -lline -sspeed with line being the serial port (e.g. /dev/cuaa0) and speed being the speed (e.g.57600). When you are done entering the AT commands hit ~. to exit. How come the <@> 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 (see &man.remote.5;). 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 do something like tip -115200 5551234. If you prefer &man.cu.1; over &man.tip.1;, 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 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. &man.tip.1; 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. How can I more easily 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 (see &man.remote.5;): 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 (see &man.remote.5;) 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 (see &man.phones.5;): big-university 5551111 big-university 5551112 big-university 5551113 big-university 5551114 &man.tip.1; will try each one in the listed order, then give up. If you want to keep retrying, run &man.tip.1; in a while loop. Why do I have to hit CTRL+P twice to send CTRL+P once? CTRL+P is the default force character, used to tell &man.tip.1; 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 CTRL+2 or CTRL+SPACE. A pretty good value for single-char is SHIFT+CTRL+6, which I have seen 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 Why is everything I type suddenly in UPPER CASE? You must have pressed CTRL+A, &man.tip.1; 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 CTRL+2 and CTRL+A a lot: force=^^ raisechar=^^ The ^^ is SHIFT+CTRL+6. How can I do file transfers with tip? If you are talking to another Unix system, you can send and receive files with ~p (put) and ~t (take). These commands run &man.cat.1; and &man.echo.1; 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 tip? First, install one of the zmodem programs from the ports collection (such as one of the two from the comms category, lrzsz or rzsz. To receive files, start the sending program on the remote end. Then, press enter and type ~C rz (or ~C lrz if you installed lrzsz) to begin receiving them locally. To send files, start the receiving program on the remote end. Then, press enter and type ~C sz files (or ~C lsz files) to send them to the remote system. How come FreeBSD cannot seem to find my serial ports, even when the settings are correct? Motherboards and cards with Acer UARTs do not probe properly under the FreeBSD sio probe. Obtain a patch from www.lemis.com to fix your problem. Miscellaneous Questions FreeBSD uses far more swap space than Linux. Why? FreeBSD only appears to use more swap than Linux. In actual fact, it does not. The main difference between FreeBSD and Linux in this regard is that FreeBSD will proactively move entirely idle, unused pages of main memory into swap in order to make more main memory available for active use. Linux tends to only move pages to swap as a last resort. The perceived heavier use of swap is balanced by the more efficient use of main memory. Note that while FreeBSD is proactive in this regard, it does not arbitrarily decide to swap pages when the system is truely idle. Thus you will not find your system all paged out when you get up in the morning after leaving it idle overnight. Why does top show very little free memory even when I have very few programs running? The simple answer is that free memory is wasted memory. Any memory that your programs do not actively allocate is used within the FreeBSD kernel as disk cache. The values shown by &man.top.1; labelled as Inact, Cache, and Buf are all cached data at different aging levels. This cached data means the system does not have to access a slow disk again for data it has accessed recently, thus increasing overall performance. In general, a low value shown for Free memory in &man.top.1; is good, provided it is not very low. Why use (what are) a.out and ELF executable formats? To understand why FreeBSD uses the ELF format, you must first know a little about the 3 currently dominant executable formats for Unix: Prior to FreeBSD 3.x, FreeBSD used the a.out format. &man.a.out.5; The oldest and classic unix object format. It uses a short and compact header with a magic number at the beginning that is often used to characterize the format (see &man.a.out.5; for more details). It contains three loaded segments: .text, .data, and .bss plus a symbol table and a string table. COFF The SVR3 object format. The header now comprises a section table, so you can have more than just .text, .data, and .bss sections. ELF The successor to COFF, featuring Multiple sections and 32-bit or 64-bit possible values. One major drawback: ELF was also designed with the assumption that there would be only one ABI per system architecture. That assumption is actually quite incorrect, and not even in the commercial SYSV world (which has at least three ABIs: SVR4, Solaris, SCO) does it hold true. FreeBSD tries to work around this problem somewhat by providing a utility for branding a known ELF executable with information about the ABI it is compliant with. See the man page for &man.brandelf.1; for more information. FreeBSD comes from the classic camp and has traditionally used the &man.a.out.5; format, a technology tried and proven through many generations of BSD releases. Though it has also been possible for some time to build and run native ELF binaries (and kernels) on a FreeBSD system, FreeBSD initially resisted the push to switch to ELF as the default format. Why? Well, when the Linux camp made their painful transition to ELF, it was not so much to flee the a.out executable format as it was their inflexible jump-table based shared library mechanism, which made the construction of shared libraries very difficult for vendors and developers alike. Since the ELF tools available offered a solution to the shared library problem and were generally seen as the way forward anyway, the migration cost was accepted as necessary and the transition made. In FreeBSD's case, our shared library mechanism is based more closely on Sun's SunOS-style shared library mechanism and, as such, is very easy to use. However, starting with 3.0, FreeBSD officially supports ELF binaries as the default format. Even though the a.out executable format has served us well, the GNU people, who author the compiler tools we use, have dropped support for the a.out format. This has forced us to maintain a divergent version of the compiler and linker, and has kept us from reaping the benefits of the latest GNU development efforts. Also the demands of ISO-C++, notably constructors and destructors, has also led to native ELF support in future FreeBSD releases. Yes, but why are there so many different formats? Back in the dim, dark past, there was simple hardware. This simple hardware supported a simple, small system. a.out was completely adequate for the job of representing binaries on this simple system (a PDP-11). As people ported unix from this simple system, they retained the a.out format because it was sufficient for the early ports of unix to architectures like the Motorola 68k, VAXen, etc. Then some bright hardware engineer decided that if he could force software to do some sleazy tricks, then he would be able to shave a few gates off the design and allow his CPU core to run faster. While it was made to work with this new kind of hardware (known these days as RISC), a.out was ill-suited for this hardware, so many formats were developed to get to a better performance from this hardware than the limited, simple a.out format could offer. Things like COFF, ECOFF, and a few obscure others were invented and their limitations explored before things seemed to settle on ELF. In addition, program sizes were getting huge and disks (and physical memory) were still relatively small so the concept of a shared library was born. The VM system also became more sophisticated. While each one of these advancements was done using the a.out format, its usefulness was stretched more and more with each new feature. In addition, people wanted to dynamically load things at run time, or to junk parts of their program after the init code had run to save in core memory and/or swap space. Languages became more sophisticated and people wanted code called before main automatically. Lots of hacks were done to the a.out format to allow all of these things to happen, and they basically worked for a time. In time, a.out was not up to handling all these problems without an ever increasing overhead in code and complexity. While ELF solved many of these problems, it would be painful to switch from the system that basically worked. So ELF had to wait until it was more painful to remain with a.out than it was to migrate to ELF. However, as time passed, the build tools that FreeBSD derived their build tools from (the assembler and loader especially) evolved in two parallel trees. The FreeBSD tree added shared libraries and fixed some bugs. The GNU folks that originally write these programs rewrote them and added simpler support for building cross compilers, plugging in different formats at will, etc. Since many people wanted to build cross compilers targeting FreeBSD, they were out of luck since the older sources that FreeBSD had for as and ld were not up to the task. The new gnu tools chain (binutils) does support cross compiling, ELF, shared libraries, C++ extensions, etc. In addition, many vendors are releasing ELF binaries, and it is a good thing for FreeBSD to run them. And if it is running ELF binaries, why bother having a.out any more? It is a tired old horse that has proven useful for a long time, but it is time to turn him out to pasture for his long, faithful years of service. ELF is more expressive than a.out and will allow more extensibility in the base system. The ELF tools are better maintained, and offer cross compilation support, which is important to many people. ELF may be a little slower than a.out, but trying to measure it can be difficult. There are also numerous details that are different between the two in how they map pages, handle init code, etc. None of these are very important, but they are differences. In time support for a.out will be moved out of the GENERIC kernel, and eventually removed from the kernel once the need to run legacy a.out programs is past. Why won't chmod change the permissions on symlinks? Symlinks do not have permissions, and by default, &man.chmod.1; will not follow symlinks to change the permissions on the target file. So if you have a file, foo, and a symlink to that file, bar, then this command will always succeed. &prompt.user; chmod g-w bar However, the permissions on foo will not have changed. You have to use either or together with the option to make this work. See the &man.chmod.1; and &man.symlink.7; man pages for more info. The option does a RECURSIVE &man.chmod.1;. Be careful about specifying directories or symlinks to directories to &man.chmod.1;. If you want to change the permissions of a directory referenced by a symlink, use &man.chmod.1; without any options and follow the symlink with a trailing slash (/). For example, if foo is a symlink to directory bar, and you want to change the permissions of foo (actually bar), you would do something like: &prompt.user; chmod 555 foo/ With the trailing slash, &man.chmod.1; will follow the symlink, foo, to change the permissions of the directory, bar. Why are login names still restricted to 8 characters? You would think it would be easy enough to change UT_NAMESIZE and rebuild the whole world, and everything would just work. Unfortunately there are often scads of applications and utilities (including system tools) that have hard-coded small numbers (not always 8 or 9, but oddball ones like 15 and 20) in structures and buffers. Not only will this get you log files which are trashed (due to variable-length records getting written when fixed records were expected), but it can break Suns NIS clients and potentially cause other problems in interacting with other Unix systems. In FreeBSD 3.0 and later, the maximum name length has been increased to 16 characters and those various utilities with hard-coded name sizes have been found and fixed. The fact that this touched so many areas of the system is why, in fact, the change was not made until 3.0. If you are absolutely confident in your ability to find and fix these sorts of problems for yourself when and if they pop up, you can increase the login name length in earlier releases by editing /usr/include/utmp.h and changing UT_NAMESIZE accordingly. You must also update MAXLOGNAME in /usr/include/sys/param.h to match the UT_NAMESIZE change. Finally, if you build from sources, do not forget that /usr/include is updated each time! Change the appropriate files in /usr/src/.. instead. Can I run DOS binaries under FreeBSD? Yes, starting with version 3.0 you can using BSDI's doscmd DOS emulation which has been integrated and enhanced. Send mail to the &a.emulation; if you are interested in joining this ongoing effort! For pre-3.0 systems, there is a neat utility called pcemu in the ports collection which emulates an 8088 and enough BIOS services to run DOS text mode applications. It requires the X Window System (provided as XFree86). What do I need to do to translate a FreeBSD document into my native language? See the Translation FAQ in the FreeBSD Documentation Project Primer. Where can I find a free FreeBSD account? While FreeBSD does not provide open access to any of their servers, others do provide open access Unix systems. The charge varies and limited services may be available. Arbornet, Inc, also known as M-Net, has been providing open access to Unix systems since 1983. Starting on an Altos running System III, the site switched to BSD/OS in 1991. In June of 2000, the site switched again to FreeBSD. M-Net can be accessed via telnet and SSH and provides basic access to the entire FreeBSD software suite. However, network access is limited to members and patrons who donate to the system, which is run as a non-profit organization. M-Net also provides an bulletin board system and interactive chat. Grex provides a site very similar to M-Net including the same bulletin board and interactive chat software. However, the machine is a Sun 4M and is running SunOS What is sup, and how do I use it? SUP stands for Software Update Protocol, and was developed by CMU for keeping their development trees in sync. We used it to keep remote sites in sync with our central development sources. SUP is not bandwidth friendly, and has been retired. The current recommended method to keep your sources up to date is Handbook entry on CVSup How cool is FreeBSD? Q. Has anyone done any temperature testing while running FreeBSD? I know Linux runs cooler than dos, but have never seen a mention of FreeBSD. It seems to run really hot. A. No, but we have done numerous taste tests on blindfolded volunteers who have also had 250 micrograms of LSD-25 administered beforehand. 35% of the volunteers said that FreeBSD tasted sort of orange, whereas Linux tasted like purple haze. Neither group mentioned any significant variances in temperature. We eventually had to throw the results of this survey out entirely anyway when we found that too many volunteers were wandering out of the room during the tests, thus skewing the results. We think most of the volunteers are at Apple now, working on their new scratch and sniff GUI. It's a funny old business we're in! Seriously, both FreeBSD and Linux use the HLT (halt) instruction when the system is idle thus lowering its energy consumption and therefore the heat it generates. Also if you have APM (advanced power management) configured, then FreeBSD can also put the CPU into a low power mode. Who is scratching in my memory banks?? Q. Is there anything odd that FreeBSD does when compiling the kernel which would cause the memory to make a scratchy sound? When compiling (and for a brief moment after recognizing the floppy drive upon startup, as well), a strange scratchy sound emanates from what appears to be the memory banks. A. Yes! You will see frequent references to daemons in the BSD documentation, and what most people do not know is that this refers to genuine, non-corporeal entities that now possess your computer. The scratchy sound coming from your memory is actually high-pitched whispering exchanged among the daemons as they best decide how to deal with various system administration tasks. If the noise gets to you, a good fdisk /mbr from DOS will get rid of them, but do not be surprised if they react adversely and try to stop you. In fact, if at any point during the exercise you hear the satanic voice of Bill Gates coming from the built-in speaker, take off running and don't ever look back! Freed from the counterbalancing influence of the BSD daemons, the twin demons of DOS and Windows are often able to re-assert total control over your machine to the eternal damnation of your soul. Now that you know, given a choice you would probably prefer to get used to the scratchy noises, no? What does MFC mean? MFC is an acronym for Merged From -CURRENT. It is used in the CVS logs to denote when a change was migrated from the CURRENT to the STABLE branches. What does BSD mean? It stands for something in a secret language that only members can know. It does not translate literally but its ok to tell you that BSD's translation is something between, Formula-1 Racing Team, Penguins are tasty snacks, and We have a better sense of humor than Linux. :-) Seriously, BSD is an acronym for Berkeley Software Distribution, which is the name the Berkeley CSRG (Computer Systems Research Group) chose for their Unix distribution way back when. What is a repo-copy? A repo-copy (which is a short form of repository copy) refers to the direct copying of files within the CVS repository. Without a repo-copy, if a file needed to be copied or moved to another place in the repository, the committer would run cvs add to put the file in its new location, and then cvs rm on the old file if the old copy was being removed. The disadvantage of this method is that the history (i.e. the entries in the CVS logs) of the file would not be copied to the new location. As the FreeBSD Project considers this history very useful, a repository copy is often used instead. This is a process where one of the repository meisters will copy the files directly within the repository, rather than using the &man.cvs.1; program. Why should I care what color the bikeshed is? The really, really short answer is that you should not. The somewhat longer answer is that just because you are capable of building a bikeshed doesn't mean you should stop others from building one just because you don't like the color they plan to paint it. This is a metaphor indicating that you need not argue about every little feature just because you know enough to do so. Some people have commented that the amount of noise generated by a change is inversely proportional to the complexity of the change. The longer and more complete answer is that after a very long argument about whether &man.sleep.1; should take fractional second arguments, &a.phk; posted a long message entitled A bike shed (any colour will do) on greener grass.... The appropriate portions of that message are quoted below.
&a.phk; on freebsd-hackers, October 2, 1999 What is it about this bike shed? Some of you have asked me. It is a long story, or rather it is an old story, but it is quite short actually. C. Northcote Parkinson wrote a book in the early 1960'ies, called Parkinson's Law, which contains a lot of insight into the dynamics of management. [snip a bit of commentary on the book] In the specific example involving the bike shed, the other vital component is an atomic power-plant, I guess that illustrates the age of the book. Parkinson shows how you can go in to the board of directors and get approval for building a multi-million or even billion dollar atomic power plant, but if you want to build a bike shed you will be tangled up in endless discussions. Parkinson explains that this is because an atomic plant is so vast, so expensive and so complicated that people cannot grasp it, and rather than try, they fall back on the assumption that somebody else checked all the details before it got this far. Richard P. Feynmann gives a couple of interesting, and very much to the point, examples relating to Los Alamos in his books. A bike shed on the other hand. Anyone can build one of those over a weekend, and still have time to watch the game on TV. So no matter how well prepared, no matter how reasonable you are with your proposal, somebody will seize the chance to show that he is doing his job, that he is paying attention, that he is here. In Denmark we call it setting your fingerprint. It is about personal pride and prestige, it is about being able to point somewhere and say There! I did that. It is a strong trait in politicians, but present in most people given the chance. Just think about footsteps in wet cement.
How many FreeBSD hackers does it take to change a lightbulb? One thousand, one hundred and seventy-two: Twenty-three to complain to -CURRENT about the lights being out; Four to claim that it is a configuration problem, and that such matters really belong on -questions; Three to submit PRs about it, one of which is misfiled under doc and consists only of "it's dark"; One to commit an untested lightbulb which breaks buildworld, then back it out five minutes later; Eight to flame the PR originators for not including patches in their PRs; Five to complain about buildworld being broken; Thirty-one to answer that it works for them, and they must have cvsupped at a bad time; One to post a patch for a new lightbulb to -hackers; One to complain that he had patches for this three years ago, but when he sent them to -CURRENT they were just ignored, and he has had bad experiences with the PR system; besides, the proposed new lightbulb is non-reflexive; Thirty-seven to scream that lightbulbs do not belong in the base system, that committers have no right to do things like this without consulting the Community, and WHAT IS -CORE DOING ABOUT IT!? Two hundred to complain about the color of the bicycle shed; Three to point out that the patch breaks &man.style.9;; Seventeen to complain that the proposed new lightbulb is under GPL; Five hundred and eighty-six to engage in a flame war about the comparative advantages of the GPL, the BSD license, the MIT license, the NPL, and the personal hygiene of unnamed FSF founders; Seven to move various portions of the thread to -chat and -advocacy; One to commit the suggested lightbulb, even though it shines dimmer than the old one; Two to back it out with a furious flame of a commit message, arguing that FreeBSD is better off in the dark than with a dim lightbulb; Forty-six to argue vociferously about the backing out of the dim lightbulb and demanding a statement from -core; Eleven to request a smaller lightbulb so it will fit their Tamagotchi if we ever decide to port FreeBSD to that platform; Seventy-three to complain about the SNR on -hackers and -chat and unsubscribe in protest; Thirteen to post "unsubscribe", "How do I unsubscribe?", or "Please remove me from the list", followed by the usual footer; One to commit a working lightbulb while everybody is too busy flaming everybody else to notice; Thirty-one to point out that the new lightbulb would shine 0.364% brighter if compiled with TenDRA (although it will have to be reshaped into a cube), and that FreeBSD should therefore switch to TenDRA instead of EGCS; One to complain that the new lightbulb lacks fairings; Nine (including the PR originators) to ask "what is MFC?"; Fifty-seven to complain about the lights being out two weeks after the bulb has been changed. &a.nik; adds: I was laughing quite hard at this. And then I thought, "Hang on, shouldn't there be '1 to document it.' in that list somewhere?" And then I was enlightened :-) This entry is Copyright (c) 1999 &a.des;. Please do not reproduce without attribution. Advanced Topics What are SNAPs and RELEASEs? There are currently three active/semi-active branches in the FreeBSD CVS Repository (the RELENG_2 branch is probably only changed twice a year, which is why there are only three active branches of development): RELENG_2_2 AKA 2.2-STABLE RELENG_3 AKA 3.X-STABLE RELENG_4 AKA 4-STABLE HEAD AKA -CURRENT AKA 5.0-CURRENT HEAD is not an actual branch tag, like the other two; it is simply a symbolic constant for the current, non-branched development stream which we simply refer to as -CURRENT. Right now, -CURRENT is the 5.0 development stream and the 4-STABLE branch, RELENG_4, forked off from -CURRENT in Mar 2000. The 2.2-STABLE branch, RELENG_2_2, departed -CURRENT in November 1996, and has pretty much been retired. How do I make my own custom release? To make a release you need to do three things: First, you need to be running a kernel with the &man.vn.4; driver configured in. Add this to your kernel config file and build a new kernel: pseudo-device vn #Vnode driver (turns a file into a device) Second, you have to have the whole CVS repository at hand. To get this you can use CVSUP but in your supfile set the release name to cvs and remove any tag or date fields: *default prefix=/home/ncvs *default base=/a *default host=cvsup.FreeBSD.org *default release=cvs *default delete compress use-rel-suffix ## Main Source Tree src-all src-eBones src-secure # Other stuff ports-all www doc-all Then run cvsup -g supfile to suck all the good bits onto your box... Finally, you need a chunk of empty space to build into. Let's say it is in /some/big/filesystem, and from the example above you have got the CVS repository in /home/ncvs: &prompt.root; setenv CVSROOT /home/ncvs # or export CVSROOT=/home/ncvs &prompt.root; cd /usr/src &prompt.root; make buildworld &prompt.root; cd /usr/src/release &prompt.root; make release BUILDNAME=3.0-MY-SNAP CHROOTDIR=/some/big/filesystem/release Please note that you do not need to build world if you already have a populated /usr/obj. An entire release will be built in /some/big/filesystem/release and you will have a full FTP-type installation in /some/big/filesystem/release/R/ftp when you are done. If you want to build your SNAP along some other branch than -CURRENT, you can also add RELEASETAG=SOMETAG to the make release command line above, e.g. RELEASETAG=RELENG_2_2 would build an up-to-the- minute 2.2-STABLE snapshot. How do I create customized installation disks? The entire process of creating installation disks and source and binary archives is automated by various targets in /usr/src/release/Makefile. The information there should be enough to get you started. However, it should be said that this involves doing a make world and will therefore take up a lot of time and disk space. Why does make world clobber my existing installed binaries? Yes, this is the general idea; as its name might suggest, make world rebuilds every system binary from scratch, so you can be certain of having a clean and consistent environment at the end (which is why it takes so long). If the environment variable DESTDIR is defined while running make world or make install, the newly-created binaries will be deposited in a directory tree identical to the installed one, rooted at ${DESTDIR}. Some random combination of shared libraries modifications and program rebuilds can cause this to fail in make world however. How come when my system boots, it says (bus speed defaulted)? The Adaptec 1542 SCSI host adapters allow the user to configure their bus access speed in software. Previous versions of the 1542 driver tried to determine the fastest usable speed and set the adapter to that. We found that this breaks some users' systems, so you now have to define the TUNE_1542 kernel configuration option in order to have this take place. Using it on those systems where it works may make your disks run faster, but on those systems where it does not, your data could be corrupted. Can I follow current with limited Internet access? Yes, you can do this without downloading the whole source tree by using the CTM facility. How did you split the distribution into 240k files? Newer BSD based systems have a option to split that allows them to split files on arbitrary byte boundaries. Here is an example from /usr/src/Makefile. bin-tarball: (cd ${DISTDIR}; \ tar cf - . \ gzip --no-name -9 -c | \ split -b 240640 - \ ${RELEASEDIR}/tarballs/bindist/bin_tgz.) I have written a kernel extension, who do I send it to? Please take a look at The Handbook entry on how to submit code. And thanks for the thought! How are Plug N Play ISA cards detected and initialized? By: Frank Durda IV uhclem@nemesis.lonestar.org In a nutshell, there a few I/O ports that all of the PnP boards respond to when the host asks if anyone is out there. So when the PnP probe routine starts, he asks if there are any PnP boards present, and all the PnP boards respond with their model # to a I/O read of the same port, so the probe routine gets a wired-OR yes to that question. At least one bit will be on in that reply. Then the probe code is able to cause boards with board model IDs (assigned by Microsoft/Intel) lower than X to go off-line. It then looks to see if any boards are still responding to the query. If the answer was 0, then there are no boards with IDs above X. Now probe asks if there are any boards below X. If so, probe knows there are boards with a model numbers below X. Probe then asks for boards greater than X-(limit/4) to go off-line. If repeats the query. By repeating this semi-binary search of IDs-in-range enough times, the probing code will eventually identify all PnP boards present in a given machine with a number of iterations that is much lower than what 2^64 would take. The IDs are two 32-bit fields (hence 2ˆ64) + 8 bit checksum. The first 32 bits are a vendor identifier. They never come out and say it, but it appears to be assumed that different types of boards from the same vendor could have different 32-bit vendor ids. The idea of needing 32 bits just for unique manufacturers is a bit excessive. - The lower 32 bits are a serial #, ethernet address, + The lower 32 bits are a serial #, Ethernet address, something that makes this one board unique. The vendor must never produce a second board that has the same lower 32 bits unless the upper 32 bits are also different. So you can have multiple boards of the same type in the machine and the full 64 bits will still be unique. The 32 bit groups can never be all zero. This allows the wired-OR to show non-zero bits during the initial binary search. Once the system has identified all the board IDs present, it will reactivate each board, one at a time (via the same I/O ports), and find out what resources the given board needs, what interrupt choices are available, etc. A scan is made over all the boards to collect this information. This info is then combined with info from any ECU files on the hard disk or wired into the MLB BIOS. The ECU and BIOS PnP support for hardware on the MLB is usually synthetic, and the peripherals do not really do genuine PnP. However by examining the BIOS info plus the ECU info, the probe routines can cause the devices that are PnP to avoid those devices the probe code cannot relocate. Then the PnP devices are visited once more and given their I/O, DMA, IRQ and Memory-map address assignments. The devices will then appear at those locations and remain there until the next reboot, although there is nothing that says you cannot move them around whenever you want. There is a lot of oversimplification above, but you should get the general idea. Microsoft took over some of the primary printer status ports to do PnP, on the logic that no boards decoded those addresses for the opposing I/O cycles. I found a genuine IBM printer board that did decode writes of the status port during the early PnP proposal review period, but MS said tough. So they do a write to the printer status port for setting addresses, plus that use that address + 0x800, and a third I/O port for reading that can be located anywhere between 0x200 and 0x3ff. Can you assign a major number for a device driver I have written? This depends on whether or not you plan on making the driver publicly available. If you do, then please send us a copy of the driver source code, plus the appropriate modifications to files.i386, a sample configuration file entry, and the appropriate &man.MAKEDEV.8; code to create any special files your device uses. If you do not, or are unable to because of licensing restrictions, then character major number 32 and block major number 8 have been reserved specifically for this purpose; please use them. In any case, we would appreciate hearing about your driver on &a.hackers;. What about alternative layout policies for directories? In answer to the question of alternative layout policies for directories, the scheme that is currently in use is unchanged from what I wrote in 1983. I wrote that policy for the original fast filesystem, and never revisited it. It works well at keeping cylinder groups from filling up. As several of you have noted, it works poorly for find. Most filesystems are created from archives that were created by a depth first search (aka ftw). These directories end up being striped across the cylinder groups thus creating a worst possible scenario for future depth first searches. If one knew the total number of directories to be created, the solution would be to create (total / fs_ncg) per cylinder group before moving on. Obviously, one would have to create some heuristic to guess at this number. Even using a small fixed number like say 10 would make an order of magnitude improvement. To differentiate restores from normal operation (when the current algorithm is probably more sensible), you could use the clustering of up to 10 if they were all done within a ten second window. Anyway, my conclusion is that this is an area ripe for experimentation. Kirk McKusick, September 1998 How can I make the most of the data I see when my kernel panics? [This section was extracted from a mail written by &a.wpaul; on the freebsd-current mailing list by &a.des;, who fixed a few typos and added the bracketed comments] From: Bill Paul <wpaul@skynet.ctr.columbia.edu> Subject: Re: the fs fun never stops To: ben@rosengart.com Date: Sun, 20 Sep 1998 15:22:50 -0400 (EDT) Cc: current@FreeBSD.org [<ben@rosengart.com> posted the following panic message] > Fatal trap 12: page fault while in kernel mode > fault virtual address = 0x40 > fault code = supervisor read, page not present > instruction pointer = 0x8:0xf014a7e5 ^^^^^^^^^^ > stack pointer = 0x10:0xf4ed6f24 > frame pointer = 0x10:0xf4ed6f28 > code segment = base 0x0, limit 0xfffff, type 0x1b > = DPL 0, pres 1, def32 1, gran 1 > processor eflags = interrupt enabled, resume, IOPL = 0 > current process = 80 (mount) > interrupt mask = > trap number = 12 > panic: page fault [When] you see a message like this, it is not enough to just reproduce it and send it in. The instruction pointer value that I highlighted up there is important; unfortunately, it is also configuration dependent. In other words, the value varies depending on the exact kernel image that you are using. If you are using a GENERIC kernel image from one of the snapshots, then it is possible for somebody else to track down the offending function, but if you are running a custom kernel then only you can tell us where the fault occurred. What you should do is this: Write down the instruction pointer value. Note that the 0x8: part at the beginning is not significant in this case: it is the 0xf0xxxxxx part that we want. When the system reboots, do the following: &prompt.user; nm -n /kernel.that.caused.the.panic | grep f0xxxxxx where f0xxxxxx is the instruction pointer value. The odds are you will not get an exact match since the symbols in the kernel symbol table are for the entry points of functions and the instruction pointer address will be somewhere inside a function, not at the start. If you do not get an exact match, omit the last digit from the instruction pointer value and try again, i.e.: &prompt.user; nm -n /kernel.that.caused.the.panic | grep f0xxxxx If that does not yield any results, chop off another digit. Repeat until you get some sort of output. The result will be a possible list of functions which caused the panic. This is a less than exact mechanism for tracking down the point of failure, but it is better than nothing. I see people constantly show panic messages like this but rarely do I see someone take the time to match up the instruction pointer with a function in the kernel symbol table. The best way to track down the cause of a panic is by capturing a crash dump, then using &man.gdb.1; to generate a stack trace on the crash dump. In any case, the method I normally use is this: Set up a kernel config file, optionally adding options DDB if you think you need the kernel debugger for something. (I use this mainly for setting breakpoints if I suspect an infinite loop condition of some kind.) Use config -g KERNELCONFIG to set up the build directory. cd /sys/compile/ KERNELCONFIG; make Wait for kernel to finish compiling. make install reboot The &man.make.1; process will have built two kernels. kernel and kernel.debug. kernel was installed as /kernel, while kernel.debug can be used as the source of debugging symbols for &man.gdb.1;. To make sure you capture a crash dump, you need edit /etc/rc.conf and set dumpdev to point to your swap partition. This will cause the &man.rc.8; scripts to use the &man.dumpon.8; command to enable crash dumps. You can also run &man.dumpon.8; manually. After a panic, the crash dump can be recovered using &man.savecore.8;; if dumpdev is set in /etc/rc.conf, the &man.rc.8; scripts will run &man.savecore.8; automatically and put the crash dump in /var/crash. FreeBSD crash dumps are usually the same size as the physical RAM size of your machine. That is, if you have 64MB of RAM, you will get a 64MB crash dump. Therefore you must make sure there is enough space in /var/crash to hold the dump. Alternatively, you run &man.savecore.8; manually and have it recover the crash dump to another directory where you have more room. It is possible to limit the size of the crash dump by using options MAXMEM=(foo) to set the amount of memory the kernel will use to something a little more sensible. For example, if you have 128MB of RAM, you can limit the kernel's memory usage to 16MB so that your crash dump size will be 16MB instead of 128MB. Once you have recovered the crash dump, you can get a stack trace with &man.gdb.1; as follows: &prompt.user; gdb -k /sys/compile/KERNELCONFIG/kernel.debug /var/crash/vmcore.0 (gdb) where Note that there may be several screens worth of information; ideally you should use &man.script.1; to capture all of them. Using the unstripped kernel image with all the debug symbols should show the exact line of kernel source code where the panic occurred. Usually you have to read the stack trace from the bottom up in order to trace the exact sequence of events that lead to the crash. You can also use &man.gdb.1; to print out the contents of various variables or structures in order to examine the system state at the time of the crash. Now, if you are really insane and have a second computer, you can also configure &man.gdb.1; to do remote debugging such that you can use &man.gdb.1; on one system to debug the kernel on another system, including setting breakpoints, single-stepping through the kernel code, just like you can do with a normal user-mode program. I have not played with this yet as I do not often have the chance to set up two machines side by side for debugging purposes. [Bill adds: "I forgot to mention one thing: if you have DDB enabled and the kernel drops into the debugger, you can force a panic (and a crash dump) just by typing 'panic' at the ddb prompt. It may stop in the debugger again during the panic phase. If it does, type 'continue' and it will finish the crash dump." -ed] Why has dlsym() stopped working for ELF executables? The ELF toolchain does not, by default, make the symbols defined in an executable visible to the dynamic linker. Consequently dlsym() searches on handles obtained from calls to dlopen(NULL, flags) will fail to find such symbols. If you want to search, using dlsym(), for symbols present in the main executable of a process, you need to link the executable using the option to the ELF linker (&man.ld.1;). How can I increase or reduce the kernel address space? By default, the kernel address space is 256 MB on FreeBSD 3.x and 1 GB on FreeBSD 4.x. If you run a network-intensive server (e.g. a large FTP or HTTP server), you might find that 256 MB is not enough. So how do you increase the address space? There are two aspects to this. First, you need to tell the kernel to reserve a larger portion of the address space for itself. Second, since the kernel is loaded at the top of the address space, you need to lower the load address so it does not bump its head against the ceiling. The first goal is achieved by increasing the value of NKPDE in src/sys/i386/include/pmap.h. Here is what it looks like for a 1 GB address space: #ifndef NKPDE #ifdef SMP #define NKPDE 254 /* addressable number of page tables/pde's */ #else #define NKPDE 255 /* addressable number of page tables/pde's */ #endif /* SMP */ #endif To find the correct value of NKPDE, divide the desired address space size (in megabytes) by four, then subtract one for UP and two for SMP. To achieve the second goal, you need to compute the correct load address: simply subtract the address space size (in bytes) from 0x100100000; the result is 0xc0100000 for a 1 GB address space. Set LOAD_ADDRESS in src/sys/i386/conf/Makefile.i386 to that value; then set the location counter in the beginning of the section listing in src/sys/i386/conf/kernel.script to the same value, as follows: OUTPUT_FORMAT("elf32-i386", "elf32-i386", "elf32-i386") OUTPUT_ARCH(i386) ENTRY(btext) SEARCH_DIR(/usr/lib); SEARCH_DIR(/usr/obj/elf/home/src/tmp/usr/i386-unknown-freebsdelf/lib); SECTIONS { /* Read-only sections, merged into text segment: */ . = 0xc0100000 + SIZEOF_HEADERS; .interp : { *(.interp) } Then reconfig and rebuild your kernel. You will probably have problems with &man.ps.1; &man.top.1; and the like; make world should take care of it (or a manual rebuild of libkvm, &man.ps.1; and &man.top.1; after copying the patched pmap.h to /usr/include/vm/. NOTE: the size of the kernel address space must be a multiple of four megabytes. [&a.dg; adds: I think the kernel address space needs to be a power of two, but I am not certain about that. The old(er) boot code used to monkey with the high order address bits and I think expected at least 256MB granularity.] Acknowledgments
FreeBSD Core Team If you see a problem with this FAQ, or wish to submit an entry, please mail the &a.faq;. We appreciate your feedback, and cannot make this a better FAQ without your help!
&a.jkh; Occasional fits of FAQ-reshuffling and updating. &a.dwhite; Services above and beyond the call of duty on freebsd-questions &a.joerg; Services above and beyond the call of duty on Usenet &a.wollman; Networking and formatting Jim Lowe Multicast information &a.pds; FreeBSD FAQ typing machine slavey The FreeBSD Team Kvetching, moaning, submitting data And to any others we have forgotten, apologies and heartfelt thanks! Bibliography 4.4BSD System Manager's Manual Computer Systems Research Group, University of California, Berkeley O'Reilly and Associates 1st Edition June 1994 804 pages ISBN 1-56592-080-5 4.4BSD User's Reference Manual Computer Systems Research Group, University of California, Berkeley O'Reilly and Associates 1st Edition June 1994 905 pages ISBN 1-56592-075-9 4.4BSD User's Supplementary Documents Computer Systems Research Group, University of California, Berkeley O'Reilly and Associates 1st Edition June 1994 712 pages ISBN 1-56592-076-7 4.4BSD Programmer's Reference Manual Computer Systems Research Group, University of California, Berkeley O'Reilly and Associates 1st Edition June 1994 866 pages ISBN 1-56592-078-3 4.4BSD Programmer's Supplementary Documents Computer Systems Research Group, University of California, Berkeley O'Reilly and Associates 1st Edition June 1994 596 pages ISBN 1-56592-079-1 The Design and Implementation of the 4.4BSD Operating System M. K. McKusick Kirk Marshall Keith Bostic Michael J Karels John Quarterman Addison-Wesley
Reading MA
1996 ISBN 0-201-54979-4 Unix System Administration Handbook Evi Nemeth Garth Snyder Scott Seebass Trent R. Hein John Quarterman Prentice-Hall 3rd edition 2000 ISBN 0-13-020601-6 The Complete FreeBSD Greg Lehey Walnut Creek 3rd edition June 1999 773 pages ISBN 1-57176-246-9 The FreeBSD Handbook FreeBSD Documentation Project BSDi 1st Edition November 1999 489 pages ISBN 1-57176-241-8 McKusick et al, 1994 Berkeley Software Architecture Manual, 4.4BSD Edition M. K. McKusick M. J. Karels S. J. Leffler W. N. Joy R. S. Faber 5:1-42 diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml index 0147832960..0ffd5d6ef4 100644 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -1,2600 +1,2600 @@ SGML Markup This chapter describes the two markup languages you will encounter when you contribute to the FreeBSD documentation project. Each section describes the markup language, and details the markup that you are likely to want to use, or that is already in use. These markup languages contain a large number of elements, and it can be confusing sometimes to know which element to use for a particular situation. This section goes through the elements you are most likely to need, and gives examples of how you would use them. This is not an exhaustive list of elements, since that would just reiterate the documentation for each language. The aim of this section is to list those elements more likely to be useful to you. If you have a question about how best to markup a particular piece of content, please post it to the FreeBSD Documentation Project mailing list freebsd-doc@FreeBSD.org. Inline vs. block In the remainder of this document, when describing elements, inline means that the element can occur within a block element, and does not cause a line break. A block element, by comparison, will cause a line break (and other processing) when it is encountered. HTML HTML, the HyperText Markup Language, is the markup language of choice on the World Wide Web. More information can be found at <URL:http://www.w3.org/>. HTML is used to markup pages on the FreeBSD web site. It should not (generally) be used to mark up other documention, since DocBook offers a far richer set of elements to choose from. Consequently, you will normally only encounter HTML pages if you are writing for the web site. HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the latest, 4.0 (available in both strict and loose variants). The HTML DTDs are available from the ports collection in the textproc/html port. They are automatically installed as part of the textproc/docproj port. Formal Public Identifier (FPI) There are a number of HTML FPIs, depending upon the version (also known as the level) of HTML that you want to declare your document to be compliant with. The majority of HTML documents on the FreeBSD web site comply with the loose version of HTML 4.0. PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Sectional elements An HTML document is normally split in to two sections. The first section, called the head, contains meta-information about the document, such as its title, the name of the author, the parent document, and so on. The second section, the body, contains the content that will be displayed to the user. These sections are indicated with head and body elements respectively. These elements are contained within the top-level html element. Normal HTML document structure <html> <head> <title>The document's title</title> </head> <body> … </body> </html> Block elements Headings HTML allows you to denote headings in your document, at up to six different levels. The largest and most prominent heading is h1, then h2, continuing down to h6. The element's content is the text of the heading. <sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc. Use: First section

This is the heading for the first section

This is the heading for the first sub-section

This is the heading for the second section

]]> Generally, an HTML page should have one first level heading (h1). This can contain many second level headings (h2), which can in turn contain many third level headings. Each hn element should have the same element, but one further up the hierarchy, preceeding it. Leaving gaps in the numbering is to be avoided. Bad ordering of <sgmltag>h<replaceable>n</replaceable></sgmltag> elements Use: First section

Sub-section

]]> Paragraphs HTML supports a single paragraph element, p. <sgmltag>p</sgmltag> Use: This is a paragraph. It can contain just about any other element.

]]> Block quotations A block quotation is an extended quotation from another document that should not appear within the current paragraph. <sgmltag>blockquote</sgmltag> Use: A small excerpt from the US Constitution:

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
]]> Lists You can present the user with three types of lists, ordered, unordered, and definition. Typically, each entry in an ordered list will be numbered, while each entry in an unordered list will be preceded by a bullet point. Definition lists are composed of two sections for each entry. The first section is the term being defined, and the second section is the definition of the term. Ordered lists are indicated by the ol element, unordered lists by the ul element, and definition lists by the dl element. Ordered and unordered lists contain listitems, indicated by the li element. A listitem can contain textual content, or it may be further wrapped in one or more p elements. Definition lists contain definition terms (dt) and definition descriptions (dd). A definition term can only contain inline elements. A definition description can contain other block elements. <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag> Use: An unordered list. Listitems will probably be preceeded by bullets.

  • First item
  • Second item
  • Third item

An ordered list, with list items consisting of multiple paragraphs. Each item (note: not each paragraph) will be numbered.

  1. This is the first item. It only has one paragraph.

  2. This is the first paragraph of the second item.

    This is the second paragraph of the second item.

  3. This is the first and only paragraph of the third item.

]]> Definition lists with <sgmltag>dl</sgmltag> Use:
Term 1

Paragraph 1 of definition 1.

Paragraph 2 of definition 1.

Term 2

Paragraph 1 of definition 2.

Term 3
Paragraph 1 of definition 3. Note that the <p> element is not required in the single paragraph case.
]]> Pre-formatted text You can indicate that text should be shown to the user exactly as it is in the file. Typically, this means that the text is shown in a fixed font, multiple spaces are not merged in to one, and line breaks in the text are significant. In order to do this, wrap the content in the pre element. <sgmltag>pre</sgmltag> You could use pre to mark up an e-mail message; From: nik@FreeBSD.org To: freebsd-doc@FreeBSD.org Subject: New documentation available There's a new copy of my primer for contributers to the FreeBSD Documentation Project available at Comments appreciated. N]]> Tables Most text-mode browsers (such as Lynx) do not render tables particularly effectively. If you are relying on the tabular display of your content, you should consider using alternative markup to prevent confusion. Mark up tabular information using the table element. A table consists of one or more table rows (tr), each containing one or more cells of table data (td). Each cell can contain other block elements, such as paragraphs or lists. It can also contain another table (this nesting can repeat indefinitely). If the cell only contains one paragraph then you do not need to include the p element. Simple use of <sgmltag>table</sgmltag> Use: This is a simple 2x2 table.

Top left cell Top right cell
Bottom left cell Bottom right cell
]]> A cell can span multiple rows and columns. To indicate this, add the rowspan and/or colspan attributes, with values indicating the number of rows of columns that should be spanned. Using <literal>rowspan</literal> Use: One tall thin cell on the left, two short cells next to it on the right.

Long and thin
Top cell Bottom cell
]]> Using <literal>colspan</literal> Use: One long cell on top, two short cells below it.

Top cell
Bottom left cell Bottom right cell
]]> Using <literal>rowspan</literal> and <literal>colspan</literal> together Use: On a 3x3 grid, the top left block is a 2x2 set of cells merged in to one. The other cells are normal.

Top left large cell Top right cell
Middle right cell
Bottom left cell Bottom middle cell Bottom right cell
]]> In-line elements Emphasising information You have two levels of emphasis available in HTML, em and strong. em is for a normal level of emphasis and strong indicates stronger emphasis. Typically, em is rendered in italic and strong is rendered in bold. This is not always the case, however, and you should not rely on it. <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag> Use: This has been emphasised, while this has been strongly emphasised.

]]> Bold and italics Because HTML includes presentational markup, you can also indicate that particular content should be rendered in bold or italic. The elements are b and i respectively. <sgmltag>b</sgmltag> and <sgmltag>i</sgmltag> This is in bold, while this is in italics.

]]> Indicating fixed pitch text If you have content that should be rendered in a fixed pitch (typewriter) typeface, use tt (for “teletype”). <sgmltag>tt</sgmltag> Use: This document was originally written by Nik Clayton, who can be reached by e-mail as nik@FreeBSD.org.

]]> Content size You can indicate that content should be shown in a larger or smaller font. There are three ways of doing this. Use big and small around the content you wish to change size. These tags can be nested, so <big><big>This is much bigger</big></big> is possible. Use font with the size attribute set to +1 or -1 respectively. This has the same effect as using big or small. However, the use of this approach is deprecated. Use font with the size attribute set to a number between 1 and 7. The default font size is 3. This approach is deprecated. <sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and <sgmltag>font</sgmltag> The following fragments all do the same thing. This text is slightly smaller. But this text is slightly bigger.

This text is slightly smaller. But this text is slightly bigger

This text is slightly smaller. But this text is slightly bigger.

]]> Links Links are also in-line elements. Linking to other documents on the WWW In order to include a link to another document on the WWW you must know the URL of the document you want to link to. The link is indicated with a, and the href attribute contains the URL of the target document. The content of the element becomes the link, and is normally indicated to the user in some way (underlining, change of colour, different mouse cursor when over the link, and so on). Using <literal><a href="..."></literal> Use: More information is available at the FreeBSD web site.

]]> These links will take the user to the top of the chosen document. Linking to other parts of documents Linking to a point within another document (or within the same document) requires that the document author include anchors that you can link to. Anchors are indicated with a and the name attribute instead of href. Using <literal><a name="..."></literal> Use: This paragraph can be referenced in other links with the name para1.

]]> To link to a named part of a document, write a normal link to that document, but include the name of the anchor after a # symbol. Linking to a named part of another document Assume that the para1 example resides in a document called foo.html. More information can be found in the first paragraph of foo.html.

]]> If you are linking to a named anchor within the same document then you can omit the document's URL, and just include the name of the anchor (with the preceeding #). Linking to a named part of the same document Assume that the para1 example resides in this document More information can be found in the first paragraph of this document.

]]> DocBook DocBook was designed by the Davenport Group to be a DTD for writing technical documentation. As such, and unlike LinuxDoc and HTML, DocBook is very heavily oriented towards markup that describes what something is, rather than describing how it should be presented. <literal>formal</literal> vs. <literal>informal</literal> Some elements may exist in two forms, formal and informal. Typically, the formal version of the element will consist of a title followed by the information version of the element. The informal version will not have a title. The DocBook DTD is available from the ports collection in the textproc/docbook port. It is automatically installed as part of the textproc/docproj port. FreeBSD extensions The FreeBSD Documentation Project has extended the DocBook DTD by adding some new elements. These elements serve to make some of the markup more precise. Where a FreeBSD specific element is listed below it is clearly marked. Throughout the rest of this document, the term “DocBook” is used to mean the FreeBSD extended DocBook DTD. There is nothing about these extensions that is FreeBSD specific, it was just felt that they were useful enhancements for this particular project. Should anyone from any of the other *nix camps (NetBSD, OpenBSD, Linux, …) be interested in collaborating on a standard DocBook extension set, please get in touch with Nik Clayton nik@FreeBSD.org. The FreeBSD extensions are not (currently) in the ports collection. They are stored in the FreeBSD CVS tree, as doc/share/sgml/freebsd.dtd. Formal Public Identifier (FPI) In compliance with the DocBook guidelines for writing FPIs for DocBook customisations, the FPI for the FreeBSD extended DocBook DTD is; PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" Document structure DocBook allows you to structure your documentation in several ways. In the FreeBSD Documentation Project we are using two primary types of DocBook document: the book and the article. A book is organised into chapters. This is a mandatory requirement. There may be parts between the book and the chapter to provide another layer of organisation. The Handbook is arranged in this way. A chapter may (or may not) contain one or more sections. These are indicated with the sect1 element. If a section contains another section then use the sect2 element, and so on, up to sect5. Chapters and sections contain the remainder of the content. An article is simpler than a book, and does not use chapters. Instead, the content of an article is organised into one or more sections, using the same sect1 (and sect2 and so on) elements that are used in books. Obviously, you should consider the nature of the documentation you are writing in order to decide whether it is best marked up as a book or an article. Articles are well suited to information that does not need to be broken down into several chapters, and that is, relatively speaking, quite short, at up to 20-25 pages of content. Books are best suited to information that can be broken up into several chapters, possibly with appendices and similar content as well. The FreeBSD tutorials are all marked up as articles, while this document, the FreeBSD FAQ, and the FreeBSD Handbook are all marked up as books. Starting a book The content of the book is contained within the book element. As well as containing structural markup, this element can contain elements that include additional information about the book. This is either meta-information, used for reference purposes, or additional content used to produce a title page. This additional information should be contained within bookinfo. Boilerplate <sgmltag>book</sgmltag> with <sgmltag>bookinfo</sgmltag> <book> <bookinfo> <title>Your title here</title> <author> <firstname>Your first name</firstname> <surname>Your surname</surname> <affiliation> <address><email>Your e-mail address</email></address> </affiliation> </author> <copyright> <year>1998</year> <holder role="mailto:your e-mail address">Your name</holder> </copyright> <pubdate role="rcs">$Date$</pubdate> <releaseinfo>$Id$</releaseinfo> <abstract> <para>Include an abstract of the book's contents here.</para> </abstract> </bookinfo> … </book> Starting an article The content of the article is contained within the article element. As well as containing structural markup, this element can contain elements that include additional information about the article. This is either meta-information, used for reference purposes, or additional content used to produce a title page. This additional information should be contained within articleinfo. Boilerplate <sgmltag>article</sgmltag> with <sgmltag>articleinfo</sgmltag> <article> <articleinfo> <title>Your title here</title> <author> <firstname>Your first name</firstname> <surname>Your surname</surname> <affiliation> <address><email>Your e-mail address</email></address> </affiliation> </author> <copyright> <year>1998</year> <holder role="mailto:your e-mail address">Your name</holder> </copyright> <pubdate role="rcs">$Date$</pubdate> <releaseinfo>$Id$</releaseinfo> <abstract> <para>Include an abstract of the article's contents here.</para> </abstract> </articleinfo> … </article> Indicating chapters Use chapter to mark up your chapters. Each chapter has a mandatory title. Articles do not contain chapters, they are reserved for books. A simple chapter The chapter's title ... ]]> A chapter cannot be empty; it must contain elements in addition to title. If you need to include an empty chapter then just use an empty paragraph. Empty chapters This is an empty chapter ]]> Sections below chapters In books, chapters may (but do not need to) be broken up into sections, subsections, and so on. In articles, sections are the main structural element, and each article must contain at least one section. Use the sectn element. The n indicates the section number, which identifies the section level. The first sectn is sect1. You can have one or more of these in a chapter. They can contain one or more sect2 elements, and so on, down to sect5. Sections in chapters A sample chapter Some text in the chapter. First section (1.1) … Second section (1.2) First sub-section (1.2.1) First sub-sub-section (1.2.1.1) … Second sub-section (1.2.2) … ]]> This example includes section numbers in the section titles. You should not do this in your documents. Adding the section numbers is carried out the by the stylesheets (of which more later), and you do not need to manage them yourself. Subdividing using <sgmltag>part</sgmltag>s You can introduce another layer of organisation between book and chapter with one or more parts. This cannot be done in an article. Introduction Overview ... What is FreeBSD? ... History ... ]]> Block elements Paragraphs DocBook supports three types of paragraphs: formalpara, para, and simpara. Most of the time you will only need to use para. formalpara includes a title element, and simpara disallows some elements from within para. Stick with para. <sgmltag>para</sgmltag> Use: This is a paragraph. It can contain just about any other element. ]]> Appearance: This is a paragraph. It can contain just about any other element. Block quotations A block quotation is an extended quotation from another document that should not appear within the current paragraph. You will probably only need it infrequently. Blockquotes can optionally contain a title and an attribution (or they can be left untitled and unattributed). <sgmltag>blockquote</sgmltag> Use: A small excerpt from the US Constitution;
Preamble to the Constitution of the United States Copied from a web site somewhere We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
]]> Appearance:
Preamble to the Constitution of the United States Copied from a web site somewhere We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
Tips, notes, warnings, cautions, important information and sidebars. You may need to include extra information separate from the main body of the text. Typically this is “meta” information that the user should be aware of. Depending on the nature of the information, one of tip, note, warning, caution, and important should be used. Alternatively, if the information is related to the main text but is not one of the above, use sidebar. The circumstances in which to choose one of these elements over another is unclear. The DocBook documentation suggests; A Note is for information that should be heeded by all readers. An Important element is a variation on Note. A Caution is for information regarding possible data loss or software damage. A Warning is for information regarding possible hardware damage or injury to life or limb. <sgmltag>warning</sgmltag> Use: Installing FreeBSD may make you want to delete Windows from your harddisk. ]]> Installing FreeBSD may make you want to delete Windows from your harddisk. Lists and procedures You will often need to list pieces of information to the user, or present them with a number of steps that must be carried out in order to accomplish a particular goal. In order to do this, use itemizedlist, orderedlist, or procedureThere are other types of list element in DocBook, but we're not concerned with those at the moment. itemizedlist and orderedlist are similar to their counterparts in HTML, ul and ol. Each one consists of one or more listitem elements, and each listitem contains one or more block elements. The listitem elements are analagous to HTML's li tags. However, unlike HTML, they are required. procedure is slightly different. It consists of steps, which may in turn consists of more steps or substeps. Each step contains block elements. <sgmltag>itemizedlist</sgmltag>, <sgmltag>orderedlist</sgmltag>, and <sgmltag>procedure</sgmltag> Use: This is the first itemized item. This is the second itemized item. This is the first ordered item. This is the second ordered item. Do this. Then do this. And now do this. ]]> Appearance: This is the first itemized item. This is the second itemized item. This is the first ordered item. This is the second ordered item. Do this. Then do this. And now do this. Showing file samples If you want to show a fragment of a file (or perhaps a complete file) to the user, wrap it in the programlisting element. White space and line breaks within programlisting are significant. In particular, this means that the opening tag should appear on the same line as the first line of the output, and the closing tag should appear on the same line as the last line of the output, otherwise spurious blank lines may be included. <sgmltag>programlisting</sgmltag> Use: When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); }]]> Notice how the angle brackets in the #include line need to be referenced by their entities instead of being included literally. Appearance: When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); } Callouts A callout is a mechanism for referring back to an earlier piece of text or specific position within an earlier example without linking to it within the text. To do this, mark areas of interest in your example (programlisting, literallayout, or whatever) with the co element. Each element must have a unique id assigned to it. After the example include a calloutlist that refers back to the example and provides additional commentary. <sgmltag>co</sgmltag> and <sgmltag>calloutlist</sgmltag> When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); } Includes the standard IO header file. Specifies that main() returns an int. The printf() call that writes hello, world to standard output. ]]> Appearance: When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); } Includes the standard IO header file. Specifies that main() returns an int. The printf() call that writes hello, world to standard output. Tables Unlike HTML, you do not need to use tables for layout purposes, as the stylesheet handles those issues for you. Instead, just use tables for marking up tabular data. In general terms (and see the DocBook documentation for more detail) a table (which can be either formal or informal) consists of a table element. This contains at least one tgroup element, which specifies (as an attribute) the number of columns in this table group. Within the tablegroup you can then have one thead element, which contains elements for the table headings (column headings), and one tbody which contains the body of the table. Both tgroup and thead contain row elements, which in turn contain entry elements. Each entry element specifies one cell in the table. <sgmltag>informaltable</sgmltag> Use: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 ]]> Appearance: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 If you don't want a border around the table the frame attribute can be added to the informaltable element with a value of none (i.e., <informaltable frame="none">). Tables where <literal>frame="none"</literal> Appearance: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 Examples for the user to follow A lot of the time you need to show examples for the user to follow. Typically, these will consist of dialogs with the computer; the user types in a command, the user gets a response back, they type in another command, and so on. A number of distinct elements and entities come in to play here. screen Everything the user sees in this example will be on the computer screen, so the next element is screen. Within screen, white space is significant. prompt, &prompt.root; and &prompt.user; Some of the things the user will be seeing on the screen are prompts from the computer (either from the OS, command shell, or application. These should be marked up using prompt. As a special case, the two shell prompts for the normal user and the root user have been provided as entities. Every time you want to indicate the user is at a shell prompt, use one of &prompt.root; and &prompt.user; as necessary. They do not need to be inside prompt. &prompt.root; and &prompt.user; are FreeBSD extensions to DocBook, and are not part of the original DTD. userinput When displaying text that the user should type in, wrap it in userinput tags. It will probably be displayed differently to the user. <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and <sgmltag>userinput</sgmltag> Use: &prompt.user; ls -1 foo1 foo2 foo3 &prompt.user; ls -1 | grep foo2 foo2 &prompt.user; su Password: &prompt.root; cat foo2 This is the file called 'foo2']]> Appearance: &prompt.user; ls -1 foo1 foo2 foo3 &prompt.user; ls -1 | grep foo2 foo2 &prompt.user; su Password: &prompt.root; cat foo2 This is the file called 'foo2' Even though we are displaying the contents of the file foo2, it is not marked up as programlisting. Reserve programlisting for showing fragments of files outside the context of user actions. In-line elements Emphasising information When you want to emphasise a particular word or phrase, use emphasis. This may be presented as italic, or bold, or might be spoken differently with a text-to-speech system. There is no way to change the presentation of the emphasis within your document, no equivalent of HTML's b and i. If the information you are presenting is important then consider presenting it in important rather than emphasis. <sgmltag>emphasis</sgmltag> Use: FreeBSD is without doubt the premiere Unix like operating system for the Intel architecture.]]> Appearance: FreeBSD is without doubt the premiere Unix like operating system for the Intel architecture. Keys, mouse buttons, and combinations To refer to a specific key on the keyboard, use keycap. To refer to a mouse button, use mousebutton. And to refer to combinations of key presses or mouse clicks, wrap them all in keycombo. keycombo has an attribute called action, which may be one of click, double-click, other, press, seq, or simul. The last two values denote whether the keys or buttons should be pressed in sequence, or simultaneously. The stylesheets automatically add any connecting symbols, such as +, between the key names, when wrapped in keycombo. Keys, mouse buttons, and combinations Use: To switch to the second virtual terminal, press Alt F1. To exit vi without saving your work, type Esc: q!. My window manager is configured so that Alt right mouse button is used to move windows.]]> Appearance: To switch to the second virtual terminal, press Alt F1. To exit vi without saving your work, type Esc: q!. My window manager is configured so that Alt right mouse button is used to move windows. Applications, commands, options, and cites You will frequently want to refer to both applications and commands when writing for the Handbook. The distinction between them is simple: an application is the name for a suite (or possibly just 1) of programs that fulfil a particular task. A command is the name of a program that the user can run. In addition, you will occasionally need to list one or more of the options that a command might take. Finally, you will often want to list a command with its manual section number, in the “command(number)” format so common in Unix manuals. Mark up application names with application. When you want to list a command with its manual section number (which should be most of the time) the DocBook element is citerefentry. This will contain a further two elements, refentrytitle and manvolnum. The content of refentrytitle is the name of the command, and the content of manvolnum is the manual page section. This can be cumbersome to write, and so a series of general entities have been created to make this easier. Each entity takes the form &man.manual-page.manual-section;. The file that contains these entities is in doc/share/sgml/man-refs.ent, and can be referred to using this FPI: PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" Therefore, the introduction to your documentation will probably look like this: <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> %man; … ]> Use command when you want to include a command name “in-line” but present it as something the user should type in. Use option to mark up a command's options. This can be confusing, and sometimes the choice is not always clear. Hopefully this example makes it clearer. Applications, commands, and options. Use: Sendmail is the most widely used Unix mail application. Sendmail includes the sendmail 8 , &man.mailq.8;, and &man.newaliases.8; programs. One of the command line parameters to sendmail 8 , , will display the current status of messages in the mail queue. Check this on the command line by running sendmail -bp.]]> Appearance: Sendmail is the most widely used Unix mail application. Sendmail includes the sendmail 8 , mailq 8 , and newaliases 8 programs. One of the command line parameters to sendmail 8 , , will display the current status of messages in the mail queue. Check this on the command line by running sendmail -bp. Notice how the &man.command.section; notation is easier to follow. Files, directories, extensions Whenever you wish to refer to the name of a file, a directory, or a file extension, use filename. <sgmltag>filename</sgmltag> Use: The SGML source for the Handbook in English can be found in /usr/doc/en/handbook/. The first file is called handbook.sgml in that directory. You should also see a Makefile and a number of files with a .ent extension.]]> Appearance: The SGML source for the Handbook in English can be found in /usr/doc/en/handbook/. The first file is called handbook.sgml in that directory. You should also see a Makefile and a number of files with a .ent extension. Devices FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. When referring to devices you have two choices. You can either refer to the device as it appears in /dev, or you can use the name of the device as it appears in the kernel. For this latter course, use devicename. Sometimes you will not have a choice. Some devices, such as networking cards, do not have entries in /dev, or the entries are markedly different from those entries. <sgmltag>devicename</sgmltag> Use: sio is used for serial communication in FreeBSD. sio manifests through a number of entries in /dev, including /dev/ttyd0 and /dev/cuaa0. By contrast, the networking devices, such as ed0 do not appear in /dev. In MS-DOS, the first floppy drive is referred to as a:. In FreeBSD it is /dev/fd0.]]> Appearance: sio is used for serial communication in FreeBSD. sio manifests through a number of entries in /dev, including /dev/ttyd0 and /dev/cuaa0. By contrast, the networking devices, such as ed0 do not appear in /dev. In MS-DOS, the first floppy drive is referred to as a:. In FreeBSD it is /dev/fd0. Hosts, domains, IP addresses, and so forth FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. You can markup identification information for networked computers (hosts) in several ways, depending on the nature of the information. All of them use hostid as the element, with the role attribute selecting the type of the marked up information. No role attribute, or role="hostname" With no role attribute (i.e., hostid...hostid the marked up information is the simple hostname, such as freefall or wcarchive. You can explicitly specify this with role="hostname". role="domainname" The text is a domain name, such as FreeBSD.org or ngo.org.uk. There is no hostname component. role="fqdn" The text is a Fully Qualified Domain Name, with both hostname and domain name parts. role="ipaddr" The text is an IP address, probably expressed as a dotted quad. role="ip6addr" The text is an IPv6 address. role="netmask" The text is a network mask, which might be expressed as a dotted quad, a hexadecimal string, or as a / followed by a number. role="mac" - The text is an ethernet MAC address, expressed as a series + The text is an Ethernet MAC address, expressed as a series of 2 digit hexadecimal numbers separated by colons. <sgmltag>hostid</sgmltag> and roles Use: The local machine can always be referred to by the name localhost, which will have the IP address 127.0.0.1. The FreeBSD.org domain contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org. When adding an IP alias to an interface (using ifconfig) always use a netmask of 255.255.255.255 (which can also be expressed as 0xffffffff. The MAC address uniquely identifies every network card in existence. A typical MAC address looks like 08:00:20:87:ef:d0.]]> Appearance: The local machine can always be referred to by the name localhost, which will have the IP address 127.0.0.1. The FreeBSD.org domain contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org. When adding an IP alias to an interface (using ifconfig) always use a netmask of 255.255.255.255 (which can also be expressed as 0xffffffff. The MAC address uniquely identifies every network card in existence. A typical MAC address looks like 08:00:20:87:ef:d0. Usernames FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. When you need to refer to a specific username, such as root or bin, use username. <sgmltag>username</sgmltag> Use: To carry out most system administration functions you will need to be root.]]> Appearance: To carry out most system administration functions you will need to be root. Describing <filename>Makefile</filename>s FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. Two elements exist to describe parts of Makefiles, maketarget and makevar. maketarget identifies a build target exported by a Makefile that can be given as a parameter to make. makevar identifies a variable that can be set (in the environment, on the make command line, or within the Makefile) to influence the process. <sgmltag>maketarget</sgmltag> and <sgmltag>makevar</sgmltag> Use: Two common targets in a Makefile are all and clean. Typically, invoking all will rebuild the application, and invoking clean will remove the temporary files (.o for example) created by the build process. clean may be controlled by a number of variables, including CLOBBER and RECURSE.]]> Appearance: Two common targets in a Makefile are all and clean. Typically, invoking all will rebuild the application, and invoking clean will remove the temporary files (.o for example) created by the build process. clean may be controlled by a number of variables, including CLOBBER and RECURSE. Literal text You will often need to include “literal” text in the Handbook. This is text that is excerpted from another file, or which should be copied from the Handbook into another file verbatim. Some of the time, programlisting will be sufficient to denote this text. programlisting is not always appropriate, particularly when you want to include a portion of a file “in-line” with the rest of the paragraph. On these occasions, use literal. <sgmltag>literal</sgmltag> Use: The maxusers 10 line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.]]> Appearance: The maxusers 10 line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. Showing items that the user <emphasis>must</emphasis> fill in There will often be times when you want to show the user what to do, or refer to a file, or command line, or similar, where the user cannot simply copy the examples that you provide, but must instead include some information themselves. replaceable is designed for this eventuality. Use it inside other elements to indicate parts of that element's content that the user must replace. <sgmltag>replaceable</sgmltag> Use: &prompt.user; man command ]]> Appearance: &prompt.user; man command replaceable can be used in many different elements, including literal. This example also shows that replaceable should only be wrapped around the content that the user is meant to provide. The other content should be left alone. Use: The maxusers n line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. For a desktop workstation, 32 is a good value for n.]]> Appearance: The maxusers n line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. For a desktop workstation, 32 is a good value for n. Images Image support in the documentation is currently extremely experimental. I think the mechanisms described here are unlikely to change, but that's not guaranteed. You will also need to install the graphics/ImageMagick port, which is used to convert between the different image formats. This is a big port, and most of it is not required. However, while we're working on the Makefiles and other infrastructure it makes things easier. This port is not in the textproc/docproj meta port, you must install it by hand. The best example of what follows in practice is the en_US.ISO8859-1/articles/vm-design/ document. If you're unsure of the description that follows, take a look at the files in that directory to see how everything hangs togther. Experiment with creating different formatted versions of the document to see how the image markup appears in the formatted output. Image formats We currently support two formats for images. The format you should use will depend on the nature of your image. For images that are primarily vector based, such as network diagrams, timelines, and similar, use Encapsulated Postscript, and make sure that your images have the .eps extension. For bitmaps, such as screen captures, use the Portable Network Graphic format, and make sure that your images have the .png extension. These are the only formats in which images should be committed to the CVS repository. Use the right format for the right image. It is to be expected that your documentation will have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format that you use for your documentation. Do not commit the same image to the repository in two different formats. It is anticipated that the Documentation Project will switch to using the Scalable Vector Graphic (SVG) format for vector images. However, the current state of SVG capable editing tools makes this impractical. Markup The markup for an image is relatively simple. First, markup a mediaobject. The mediaobject can contain other, more specific objects. We are concerned with two, the imageobject and the textobject. You should include one imageobject, and two textobject elements. The imageobject will point to the name of the image file that will be used (without the extension). The textobject elements contain information that will be presented to the user as well as, or instead of, the image. There are two circumstances where this can happen. When the reader is viewing the documentation in HTML. In this case, each image will need to have associated alternate text to show the user, typically whilst the image is loading, or if they hover the mouse pointer over the image. When the reader is viewing the documentation in plain text. In this case, each image should have an ASCII art equivalent to show the user. An example will probably make things easier to understand. Suppose you have an image, called fig1, that you want to include in the document. This image is of a rectangle with an A inside it. The markup for this would be as follows. <mediaobject> <imageobject> <imagedata fileref="fig1"> </imageobject> <textobject> <literallayout class="monospaced">+---------------+ | A | +---------------+</literallayout> </textobject> <textobject> <phrase>A picture</phrase> </textobject> </mediaobject> Include an imagedata element inside the imageobject element. The fileref attribute should contain the filename of the image to include, without the extension. The stylesheets will work out which extension should be added to the filename automatically. The first textobject should contain a literallayout element, where the class attribute is set to monospaced. This is your opportunity to demonstrate your ASCII art skills. This content will be used if the document is converted to plain text. Notice how the first and last lines of the content of the literallayout element butt up next to the element's tags. This ensures no extraneous white space is included. The second textobject should contain a single phrase element. The contents of this will become the alt attribute for the image when this document is converted to HTML. <filename>Makefile</filename> entries Your images must be listed in the Makefile in the IMAGES variable. This variable should contain the name of all your source images. For example, if you have created three figures, fig1.eps, fig2.png, fig3.png, then your Makefile should have lines like this in it. … IMAGES= fig1.eps fig2.png fig3.png … or … IMAGES= fig1.eps IMAGES+= fig2.png IMAGES+= fig3.png … Again, the Makefile will work out the complete list of images it needs to build your source document, you only need to list the image files you provided. Images and chapters in subdirectories You must be careful when you separate your documentation in to smaller files (see ) in different directories. Suppose you have a book with three chapters, and the chapters are stored in their own directories, called chapter1/chapter.sgml, chapter2/chapter.sgml, and chapter3/chapter.sgml. If each chapter has images associated with it, I suggest you place those images in each chapter's subdirectory (chapter1/, chapter2/, and chapter3/). However, if you do this you must include the directory names in the IMAGES variable in the Makefile, and you must include the directory name in the imagedata element in your document. For example, if you have chapter1/fig1.png, then chapter1/chapter.sgml should contain <mediaobject> <imageobject> <imagedata fileref="chapter1/fig1"> </imageobject> … </mediaobject> The directory name must be included in the fileref attribute The Makefile must contain … IMAGES= chapter1/fig1.png … Then everything should just work. Links Links are also in-line elements. Linking to other parts of the same document Linking within the same document requires you to specify where you are linking from (i.e., the text the user will click, or otherwise indicate, as the source of the link) and where you are linking to (the link's destination). Each element within DocBook has an attribute called id. You can place text in this attribute to uniquely name the element it is attached to. This value will be used when you specify the link source. Normally, you will only be linking to chapters or sections, so you would add the id attribute to these elements. <literal>id on chapters and sections</literal> Introduction This is the introduction. It contains a subsection, which is identified as well. Sub-sect 1 This is the subsection. ]]> Obviously, you should use more descriptive values. The values must be unique within the document (i.e., not just the file, but the document the file might be included in as well). Notice how the id for the subsection is constructed by appending text to the id of the chapter. This helps to ensure that they are unique. If you want to allow the user to jump into a specific portion of the document (possibly in the middle of a paragraph or an example), use anchor. This element has no content, but takes an id attribute. <sgmltag>anchor</sgmltag> This paragraph has an embedded link target in it. It won't show up in the document.]]> When you want to provide the user with a link they can activate (probably by clicking) to go to a section of the document that has an id attribute, you can use either xref or link. Both of these elements have a linkend attribute. The value of this attribute should be the value that you have used in a id attribute (it does not matter if that value has not yet occurred in your document; this will work for forward links as well as backward links). If you use xref then you have no control over the text of the link. It will be generated for you. Using <sgmltag>xref</sgmltag> Assume that this fragment appears somewhere in a document that includes the id example; More information can be found in . More specific information can be found in .]]> The text of the link will be generated automatically, and will look like (emphasised text indicates the text that will be the link);
More information can be found in Chapter One. More specific information can be found in the section called Sub-sect 1.
Notice how the text from the link is derived from the section title or the chapter number. This means that you cannot use xref to link to an id attribute on an anchor element. The anchor has no content, so the xref cannot generate the text for the link. If you want to control the text of the link then use link. This element wraps content, and the content will be used for the link. Using <sgmltag>link</sgmltag> Assume that this fragment appears somewhere in a document that includes the id example. More information can be found in the first chapter. More specific information can be found in FreeBSD home page instead.]]> Appearance: Of course, you could stop reading this document and go to the FreeBSD home page instead. 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 c52f577af6..caa54f43fa 100644 --- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml @@ -1,3859 +1,3859 @@ 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. Gateways and Routes Contributed by &a.gryphon;. 6 October 1995. route 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. + 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 + role="mac">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, + (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 + 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 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. + rather than sending it out over the Ethernet interface. The two host2 lines are an example of what - happens when we use an ifconfig alias (see the section of ethernet for + happens when we use an ifconfig 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 + 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 + 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 + 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 ifconfig aliasing. The former is - used if two physically separate ethernet networks are in use, the + have one Ethernet card, and be using ifconfig 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;. Bridging Written by Steve Peterson steve@zpfe.com. 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 ipfw, 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. NFS Written by &a.unfurl;, 4 March 2000. 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 nfsd 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! Problems integrating with other systems Contributed by &a.jlind;. 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. Diskless Operation Contributed by &a.martin;. 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, 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 cfg file might contain: rootfs 192.1.2.3:/rootfs/myclient swapfs 192.1.2.3:/swapfs swapsize 20000 hostname myclient.mydomain A cfg 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 addr, 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. ISDN Cards Contributed by &a.hm;. 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 + 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 + 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. NIS/YP Written by &a.unfurl;, 21 January 2000, enhanced with parts and comments from Eric Ogren eogren@earthlink.net and Udo Erdelhoff ue@nathan.ruhr.de in June 2000. 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 Unices (Solaris, HP-UX, AIX, Linux, NetBSD, OpenBSD, FreeBSD, etc) support NIS. yellow pages (see NIS) NIS was formerly known as Yellow Pages (or yp), but due to copyright violations, Sun was forced to change the name. 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 ypserv 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 OSs, 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 ypserv and retrieve the contents of your NIS maps, provided the remote user knows your domainname. To prevent such unauthorized transactions, ypserv supports a feature called securenets which can be used to restrict access to a given set of hosts. At startup, ypserv 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 ypserv 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; Using netgroups netgroups The netgroups part was contributed by Udo Erdelhoff ue@nathan.ruhr.de in July 2000. 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 ypinit 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 /usr/lib/libcrypt.a@ -> libdescrypt.a lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libdescrypt.so lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libdescrypt.so.2 lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libdescrypt_p.a -r--r--r-- 1 root wheel 13018 Nov 8 14:27 /usr/lib/libdescrypt.a lrwxr-xr-x 1 root wheel 16 Nov 8 14:27 /usr/lib/libdescrypt.so@ -> libdescrypt.so.2 -r--r--r-- 1 root wheel 12965 Nov 8 14:27 /usr/lib/libdescrypt.so.2 -r--r--r-- 1 root wheel 14750 Nov 8 14:27 /usr/lib/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 /usr/lib/libcrypt.a@ -> libscrypt.a lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libscrypt.so lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libscrypt.so.2 lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libscrypt_p.a -r--r--r-- 1 root wheel 6194 Nov 8 14:27 /usr/lib/libscrypt.a lrwxr-xr-x 1 root wheel 14 Nov 8 14:27 /usr/lib/libscrypt.so@ -> libscrypt.so.2 -r--r--r-- 1 root wheel 7579 Nov 8 14:27 /usr/lib/libscrypt.so.2 -r--r--r-- 1 root wheel 6684 Nov 8 14:27 /usr/lib/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. DHCP Written by &a.gsutter;, March 2000. 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. DNS Contributed by &a.chern;, April 12, 2001. 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 IPs, and vice versa. For example, a query for www.freebsd.org will send back a reply for the IP address of The FreeBSD Project's webpage, whereas, a query for ftp.freebsd.org will return the IP - of the corresponding ftp machine. Likewise, the opposite can + of the corresponding FTP machine. Likewise, the opposite can happen. A query for an IP address can resolve its hostname. 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 relay individual domain information. This document refers to BIND 8.x, as it is the most current, stable version used in FreeBSD. RFC1034 and RFC1035 dictates the DNS protocol. Currently, BIND is maintained by the Internet Software Consortium (www.isc.org) Terminology zones zone - Each individual domain, subdomain, or 'area' dictated by DNS is considered a zone. 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 ips which fall under the 3.2.1.* ip space. named, bind, name server - these are all common names for the BIND name server package within FreeBSD. resolver resolver - a network process by which a system queries a nameserver for answers 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 origin - refers to the point of start for the particular zone forward dns - mapping of hostnames to ip addresses reverse DNS reverse dns - the opposite, mapping of ip addresses to hostnames Reasons to run a name server You need your machine to host DNS information to the world An authoritative nameserver replies exclusively to requests. For example, you register foobardomain.org and wish to assign hostnames to the proper IP addresses. A slave nameserver, which replies to queries for a domain when the primary is down or inaccessible. The above two can also be done with in-addr.arpa, IP to hostname entries You wish your machine to act as a local relay of DNS information DNS traffic has been measured to be about 5% or more of the total Internet traffic. A local DNS server may have some added benefit by providing a local cache of DNS information. For example, when one queries for www.freebsd.org, their resolver goes out to (usually) your ISP's name server, and retrieves the query. With a local, caching DNS server, the query only has to be made once to the outside world. Every additional query will not have to go outside of the local network, since the information is cached. How it works A DNS server in FreeBSD relies on the BIND daemon. This daemon is called 'named' for obvious reasons. named - the bind daemon ndc - name daemon control program /etc/namedb - directory where all the bind information resides /etc/namedb/named.conf - daemon configuration file zone files are usually contained within the /etc/namedb directory, and contain the information (query answers from your site) served by your 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 your /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 your local reverse dns zone file in /etc/namedb/localhost.rev. <filename>/etc/namedb/named.conf</filename> - // $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.57 2001/07/17 00:11:17 chern Exp $ + // $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.58 2001/07/17 20:51:51 chern Exp $ // // 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, if you want to benefit from your uplink's cache, you can enable this section of the config file. Normally, your nameserver will recursively query different nameservers until it finds the answer it is looking for. Having this enabled will have it automatically see if your uplink's (or whatever provided) ns has the requested query. If your uplink has a heavily trafficked, fast nameserver, enabling this properly could work to your advantage. 127.0.0.1 will *NOT* work here; change this to the IP of 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 /* 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; }; }; */ These are example slave entries, read below to see more. For each new domain added to your nameserver, you must add one of these entries to your named.conf The simplest zone entry, can look like zone "foobardomain.org" { type master; file "foorbardomain.org"; }; For a master entry with the zone information within foobardomain.org, or zone "foobardomain.org" { type slave; file "foobardomain.org"; }; for a slave. Note that slave zones automatically query the listed master (authoritative) name servers for the zone file. Zone files An example master '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 be www.foobardomain.org. The format of this 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, e-mail address with @ replaced. (admin@foobardomain.org becomes admin.foobardomain.org) 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 to hostname mappings of our above fictitious domain. Caching Name Server BIND caching name server A caching nameserver is simply 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. Running named in a Sandbox BIND running in a sandbox Contributed by Mike Makonnen mike_makonnen@yahoo.com, May 1, 2001 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 ndc 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" 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 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 your sources up to date and having a fresh build of named can't hurt. Further Reading &man.ndc.8; &man.named.8; &man.named.conf.5; Official ISC BIND Page http://www.isc.org/products/BIND/ BIND FAQ http://www.nominum.com/resources/faqs/bind-faqs.html O'Reilly DNS and BIND 4th Edition RFC1034 - Domain Names - Concepts and Facilities RFC1035 - Domain Names - Implementation and Specification Network Address Translation daemon (natd) Contributed by &a.chern;, June 2001. 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 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 requestor. 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 makes &man.natd.8; a reasonable choice. Most commonly, a user has a machine connected to a cable or DSL line with one ip 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 numbers in the private network space as defined by RFC 1918 and have a default gateway of the natd machine's internal ip. For example, client a and b behind the LAN have ips of 192.168.0.2 and 192.168.0.3, while the natd machine's LAN interface has an ip 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 ips are available, yet they must be on one machine. With this, &man.natd.8; can assign each LAN client its own external ip. &man.natd.8; then rewrites outgoing packets from the LAN clients with the proper external ip and redirects all traffic incoming on that particular ip back to the specific LAN client. This is also known as static NAT. For example, the ips 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: -redirect_address localIP publicIP localIP The internal ip of the LAN client. publicIP The external ip corresponding to the LAN client. In the example, this argument would read: -redirect_address 192.168.0.2 128.1.1.2 -redirect_address 192.168.0.3 128.1.1.3 Like -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 ips on the natd machine must be active and aliased to the external interface. Look at &man.rc.conf.5; to do so. diff --git a/en_US.ISO8859-1/books/handbook/hw/chapter.sgml b/en_US.ISO8859-1/books/handbook/hw/chapter.sgml index 33fbdb642f..5bc073eb28 100644 --- a/en_US.ISO8859-1/books/handbook/hw/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/hw/chapter.sgml @@ -1,5854 +1,5854 @@ PC Hardware compatibility Issues of hardware compatibility are among the most troublesome in the computer industry today and FreeBSD is by no means immune to trouble. In this respect, FreeBSD's advantage of being able to run on inexpensive commodity PC hardware is also its liability when it comes to support for the amazing variety of components on the market. While it would be impossible to provide an exhaustive listing of hardware that FreeBSD supports, this section serves as a catalog of the device drivers included with FreeBSD and the hardware each drivers supports. Where possible and appropriate, notes about specific products are included. You may also want to refer to the kernel configuration file section in this handbook for a list of supported devices. As FreeBSD is a volunteer project without a funded testing department, we depend on you, the user, for much of the information contained in this catalog. If you have direct experience of hardware that does or does not work with FreeBSD, please let us know by sending e-mail to the &a.doc;. Questions about supported hardware should be directed to the &a.questions; (see Mailing Lists for more information). When submitting information or asking a question, please remember to specify exactly what version of FreeBSD you are using and include as many details of your hardware as possible. Resources on the Internet The following links have proven useful in selecting hardware. Though some of what you see won't necessarily be specific (or even applicable) to FreeBSD, most of the hardware information out there is OS independent. Please check with the FreeBSD hardware guide to make sure that your chosen configuration is supported before making any purchases. The Pentium Systems Hardware Performance Guide Sample Configurations The following list of sample hardware configurations by no means constitutes an endorsement of a given hardware vendor or product by The FreeBSD Project. This information is provided only as a public service and merely catalogs some of the experiences that various individuals have had with different hardware combinations. Your mileage may vary. Slippery when wet. Beware of dog. Jordan's Picks I have had fairly good luck building workstation and server configurations with the following components. I can't guarantee that you will too, nor that any of the companies here will remain best buys forever. I will try, when I can, to keep this list up-to-date but cannot obviously guarantee that it will be at any given time. Motherboards For Pentium Pro (P6) systems, I'm quite fond of the Tyan S1668 dual-processor motherboard as well as the Intel PR440FX motherboard with on-board SCSI WIDE and 100/10MB Intel EtherExpress NIC. You can build a dandy little single or dual processor system (which is supported in FreeBSD 3.0) for very little cost now that the Pentium Pro 180/256K chips have fallen so greatly in price, but no telling how much longer this will last. For the Pentium II, I'm rather partial to the ASUS P2l97-S motherboard with the on-board Adaptec SCSI WIDE controller. For Pentium machines, the ASUS P55T2P4 motherboard appears to be a good choice for mid-to-high range Pentium server and workstation systems. Those wishing to build more fault-tolerant systems should also be sure to use Parity memory or, for truly 24/7 applications, ECC memory. ECC memory does involve a slight performance trade-off (which may or may not be noticeable depending on your application) but buys you significantly increased fault-tolerance to memory errors. Disk Controllers This one is a bit trickier, and while I used to recommend the Buslogic controllers unilaterally for everything from ISA to PCI, now I tend to lean towards the Adaptec 1542CF for ISA, Buslogic Bt747c for EISA and Adaptec 2940UW for PCI. The NCR/Symbios cards for PCI have also worked well for me, though you need to make sure that your motherboard supports the BIOS-less model if you're using one of those (if your card has nothing which looks even vaguely like a ROM chip on it, you've probably got one which expects its BIOS to be on your motherboard). If you should find that you need more than one SCSI controller in a PCI machine, you may wish to consider conserving your scarce PCI bus resources by buying the Adaptec 3940 card, which puts two SCSI controllers (and internal busses) in a single slot. There are two types of 3940 on the market—the older model with AIC 7880 chips on it, and the newer one with AIC 7895 chips. The newer model requires CAM support which is not yet part of FreeBSD—you have to add it, or install from one of the CAM binary snapshot release. Disk drives In this particular game of Russian roulette, I'll make few specific recommendations except to say SCSI over IDE whenever you can afford it. Even in small desktop configurations, SCSI often makes more sense since it allows you to easily migrate drives from server to desktop as falling drive prices make it economical to do so. If you have more than one machine to administer then think of it not simply as storage, think of it as a food chain! For a serious server configuration, there's not even any argument—use SCSI equipment and good cables. CDROM drives My SCSI preferences extend to SCSI CDROM drives as well, and while the Toshiba drives have always been favorites of mine (in whatever speed is hot that week), I'm still fond of my good old Plextor PX-12CS drive. It's only a 12 speed, but it's offered excellent performance and reliability. Generally speaking, most SCSI CDROM drives I've seen have been of pretty solid construction and you probably won't go wrong with an HP or NEC SCSI CDROM drive either. SCSI CDROM prices also appear to have dropped considerably in the last few months and are now quite competitive with IDE CDROMs while remaining a technically superior solution. I now see no reason whatsoever to settle for an IDE CDROM drive if given a choice between the two. CD Recordable (WORM) drives At the time of this writing, FreeBSD supports 3 types of CDR drives (though I believe they all ultimately come from Phillips anyway): The Phillips CDD 522 (Acts like a Plasmon), the PLASMON RF4100 and the HP 6020i. I myself use the HP 6020i for burning CDROMs (in 2.2 and later releases—it does not work with earlier releases of the SCSI code) and it works very well. See /usr/share/examples/worm on your 2.2 system for example scripts used to created ISO9660 filesystem images (with RockRidge extensions) and burn them onto an HP6020i CDR. Tape drives I've had pretty good luck with both 8mm drives from Exabyte and 4mm (DAT) drives from HP. For backup purposes, I'd have to give the higher recommendation to the Exabyte due to the more robust nature (and higher storage capacity) of 8mm tape. Video Cards If you can also afford to buy a commercial X server for US$99 from Xi Graphics, Inc. (formerly X Inside, Inc) then I can heartily recommend the Matrox Millenium II card. Note that support for this card is also excellent with the XFree86 server, which is now at version 3.3.2. You also certainly can't go wrong with one of Number 9's cards — their S3 Vision 868 and 968 based cards (the 9FX series) also being quite fast and very well supported by XFree86's S3 server. You can also pick up their Revolution 3D cards very cheaply these days, especially if you require a lot of video memory. Monitors I have had very good luck with the Sony Multiscan 17seII monitors, as have I with the Viewsonic offering in the same (Trinitron) tube. For larger than 17", all I can recommend at the time of this writing is to not spend any less than U.S. $2,000 for a 21" monitor or $1,700 for a 20" monitor if that's what you really need. There are good monitors available in the >=20" range and there are also cheap monitors in the >=20" range. Unfortunately, very few are both cheap and good! Networking I can recommend the Intel EtherExpress Pro/100B card first and foremost, followed by the SMC Ultra 16 controller for any ISA application and the SMC EtherPower or Compex ENET32 cards for slightly cheaper PCI based networking. In general, any PCI NIC based around DEC's DC21041 Ethernet controller chip, such as the Znyx ZX342 or DEC DE435/450, will generally work quite well and can frequently be found in 2-port and 4-port version (useful for firewalls and routers), though the Pro/100MB card has the edge when it comes to providing the best performance with lower overhead. If what you're looking for is the cheapest possible solution then almost any NE2000 clone will do a fine job for very little cost. Serial If you're looking for high-speed serial networking solutions, then Digi International makes the SYNC/570 series, with drivers now in FreeBSD-CURRENT. Emerging Technologies also manufactures a board with T1/E1 capabilities, using software they provide. I have no direct experience using either product, however. multiport card options are somewhat more numerous, though it has to be said that FreeBSD's support for Cyclades's products is probably the tightest, primarily as a result of that company's commitment to making sure that we are adequately supplied with evaluation boards and technical specs. I've heard that the Cyclom-16Ye offers the best price/performance, though I've not checked the prices lately. Other multiport cards I've heard good things about are the BOCA and AST cards, and Stallion Technologies apparently offers an unofficial driver for their cards at this location. Audio I currently use a Creative Labs AWE32 though just about anything from Creative Labs will generally work these days. This is not to say that other types of sound cards don't also work, simply that I have little experience with them (I was a former GUS fan, but Gravis's sound card situation has been dire for some time). Video For video capture, there are two good choices — any card based on the Brooktree BT848 chip, such as the Hauppauge or WinTV boards, will work very nicely with FreeBSD. Another board which works for me is the Matrox Meteor card. FreeBSD also supports the older video spigot card from Creative Labs, but those are getting somewhat difficult to find. Note that the Meteor frame grabber card will not work with motherboards based on the 440FX chipset! See the motherboard reference section for details. In such cases, it's better to go with a BT848 based board. Core/Processing Motherboards, busses, and chipsets * ISA * EISA * VLB PCI Contributed by &a.obrien; from postings by &a.rgrimes;. 25 April 1995. Continuing updates by &a.jkh;. Last update on 26 August 1996. Of the Intel PCI chip sets, the following list describes various types of known-brokenness and the degree of breakage, listed from worst to best. Mercury: Cache coherency problems, especially if there are ISA bus masters behind the ISA to PCI bridge chip. Hardware flaw, only known work around is to turn the cache off. Saturn-I (ie, 82424ZX at rev 0, 1 or 2): Write back cache coherency problems. Hardware flaw, only known work around is to set the external cache to write-through mode. Upgrade to Saturn-II. Saturn-II (ie, 82424ZX at rev 3 or 4): Works fine, but many MB manufactures leave out the external dirty bit SRAM needed for write back operation. You can work around this either by running it in write through mode, or get the dirty bit SRAM installed (I have these for the ASUS PCI/I-486SP3G rev 1.6 and later boards). Neptune: Cannot run more than 2 bus master devices. Admitted Intel design flaw. Workarounds include do not run more than 2 bus masters, special hardware design to replace the PCI bus arbiter (appears on Intel Altair board and several other Intel server group MB's). And of course Intel's official answer, move to the Triton chip set, we fixed it there. Triton (ie, 430FX): No known cache coherency or bus master problems, chip set does not implement parity checking. Workaround for parity issue. Use Triton-II based motherboards if you have the choice. Triton-II (ie, 430HX): All reports on motherboards using this chipset have been favorable so far. No known problems. Orion: Early versions of this chipset suffered from a PCI write-posting bug which can cause noticeable performance degradation in applications where large amounts of PCI bus traffic is involved. B0 stepping or later revisions of the chipset fixed this problem. 440FX: This Pentium Pro support chipset seems to work well, and does not suffer from any of the early Orion chipset problems. It also supports a wider variety of memory, including ECC and parity. The only known problem with it is that the Matrox Meteor frame grabber card doesn't like it. CPUs/FPUs Contributed by &a.asami;. 26 December 1997. P6 class (Pentium Pro/Pentium II) Both the Pentium Pro and Pentium II work fine with FreeBSD. In fact, our main FTP site ftp.FreeBSD.org (also known - as "ftp.cdrom.com", world's largest ftp site) + as "ftp.cdrom.com", world's largest FTP site) runs FreeBSD on a Pentium Pro. Configurations details are available for interested parties. Pentium class The Intel Pentium (P54C), Pentium MMX (P55C), AMD K6 and Cyrix/IBM 6x86MX processors are all reported to work with FreeBSD. I will not go into details of which processor is faster than what, there are millions of web sites on the Internet that tells you one way or another. :) Various CPUs have different voltage/cooling requirements. Make sure your motherboard can supply the exact voltage needed by the CPU. For instance, many recent MMX chips require split voltage (e.g., 2.9V core, 3.3V I/O). Also, some AMD and Cyrix/IBM chips run hotter than Intel chips. In that case, make sure you have good heatsink/fans (you can get the list of certified parts from their web pages). Clock speeds Contributed by &a.rgrimes;. 1 October 1996. Updated by &a.asami;. 27 December 1997. Pentium class machines use different clock speeds for the various parts of the system. These being the speed of the CPU, external memory bus, and the PCI bus. It is not always true that a faster processor will make a system faster than a slower one, due to the various clock speeds used. Below is a table showing the differences: Rated CPU MHz External Clock and Memory Bus MHz External to Internal Clock Multiplier PCI Bus Clock MHz 60 60 1.0 30 66 66 1.0 33 75 50 1.5 25 90 60 1.5 30 100 50 2 25 100 66 1.5 33 120 60 2 30 133 66 2 33 150 60 2.5 30 (Intel, AMD) 150 75 2 37.5 (Cyrix/IBM 6x86MX) 166 66 2.5 33 180 60 3 30 200 66 3 33 233 66 3.5 33 66MHz may actually be 66.667MHz, but don't assume so. The Pentium 100 can be run at either 50MHz external clock with a multiplier of 2 or at 66MHz and a multiplier of 1.5. As can be seen the best parts to be using are the 100, 133, 166, 200 and 233, with the exception that at a multiplier of 3 or more the CPU starves for memory. The AMD K6 Bug In 1997, there have been reports of the AMD K6 seg faulting during heavy compilation. That problem has been fixed in 3Q '97. According to reports, K6 chips with date mark 9733 or larger (i.e., manufactured in the 33rd week of '97 or later) do not have this bug. * 486 class * 386 class 286 class Sorry, FreeBSD does not run on 80286 machines. It is nearly impossible to run today's large full-featured unices on such hardware. * Memory The minimum amount of memory you must have to install FreeBSD is 5 MB. Once your system is up and running you can build a custom kernel that will use less memory. If you use the boot4.flp you can get away with having only 4 MB. * BIOS Input/Output Devices * Video cards * Sound cards Serial ports and multiport cards The UART: What it is and how it works Copyright © 1996 &a.uhclem;, All Rights Reserved. 13 January 1996. The Universal Asynchronous Receiver/Transmitter (UART) controller is the key component of the serial communications subsystem of a computer. The UART takes bytes of data and transmits the individual bits in a sequential fashion. At the destination, a second UART re-assembles the bits into complete bytes. Serial transmission is commonly used with modems and for non-networked communication between computers, terminals and other devices. There are two primary forms of serial transmission: Synchronous and Asynchronous. Depending on the modes that are supported by the hardware, the name of the communication sub-system will usually include a A if it supports Asynchronous communications, and a S if it supports Synchronous communications. Both forms are described below. Some common acronyms are:
UART Universal Asynchronous Receiver/Transmitter
USART Universal Synchronous-Asynchronous Receiver/Transmitter
Synchronous Serial Transmission Synchronous serial transmission requires that the sender and receiver share a clock with one another, or that the sender provide a strobe or other timing signal so that the receiver knows when to read the next bit of the data. In most forms of serial Synchronous communication, if there is no data available at a given instant to transmit, a fill character must be sent instead so that data is always being transmitted. Synchronous communication is usually more efficient because only data bits are transmitted between sender and receiver, and synchronous communication can be more costly if extra wiring and circuits are required to share a clock signal between the sender and receiver. A form of Synchronous transmission is used with printers and fixed disk devices in that the data is sent on one set of wires while a clock or strobe is sent on a different wire. Printers and fixed disk devices are not normally serial devices because most fixed disk interface standards send an entire word of data for each clock or strobe signal by using a separate wire for each bit of the word. In the PC industry, these are known as Parallel devices. The standard serial communications hardware in the PC does not support Synchronous operations. This mode is described here for comparison purposes only. Asynchronous Serial Transmission Asynchronous transmission allows data to be transmitted without the sender having to send a clock signal to the receiver. Instead, the sender and receiver must agree on timing parameters in advance and special bits are added to each word which are used to synchronize the sending and receiving units. When a word is given to the UART for Asynchronous transmissions, a bit called the "Start Bit" is added to the beginning of each word that is to be transmitted. The Start Bit is used to alert the receiver that a word of data is about to be sent, and to force the clock in the receiver into synchronization with the clock in the transmitter. These two clocks must be accurate enough to not have the frequency drift by more than 10% during the transmission of the remaining bits in the word. (This requirement was set in the days of mechanical teleprinters and is easily met by modern electronic equipment.) After the Start Bit, the individual bits of the word of data are sent, with the Least Significant Bit (LSB) being sent first. Each bit in the transmission is transmitted for exactly the same amount of time as all of the other bits, and the receiver looks at the wire at approximately halfway through the period assigned to each bit to determine if the bit is a 1 or a 0. For example, if it takes two seconds to send each bit, the receiver will examine the signal to determine if it is a 1 or a 0 after one second has passed, then it will wait two seconds and then examine the value of the next bit, and so on. The sender does not know when the receiver has looked at the value of the bit. The sender only knows when the clock says to begin transmitting the next bit of the word. When the entire data word has been sent, the transmitter may add a Parity Bit that the transmitter generates. The Parity Bit may be used by the receiver to perform simple error checking. Then at least one Stop Bit is sent by the transmitter. When the receiver has received all of the bits in the data word, it may check for the Parity Bits (both sender and receiver must agree on whether a Parity Bit is to be used), and then the receiver looks for a Stop Bit. If the Stop Bit does not appear when it is supposed to, the UART considers the entire word to be garbled and will report a Framing Error to the host processor when the data word is read. The usual cause of a Framing Error is that the sender and receiver clocks were not running at the same speed, or that the signal was interrupted. Regardless of whether the data was received correctly or not, the UART automatically discards the Start, Parity and Stop bits. If the sender and receiver are configured identically, these bits are not passed to the host. If another word is ready for transmission, the Start Bit for the new word can be sent as soon as the Stop Bit for the previous word has been sent. Because asynchronous data is self synchronizing, if there is no data to transmit, the transmission line can be idle. Other UART Functions In addition to the basic job of converting data from parallel to serial for transmission and from serial to parallel on reception, a UART will usually provide additional circuits for signals that can be used to indicate the state of the transmission media, and to regulate the flow of data in the event that the remote device is not prepared to accept more data. For example, when the device connected to the UART is a modem, the modem may report the presence of a carrier on the phone line while the computer may be able to instruct the modem to reset itself or to not take calls by asserting or disasserting one more of these extra signals. The function of each of these additional signals is defined in the EIA RS232-C standard. The RS232-C and V.24 Standards In most computer systems, the UART is connected to circuitry that generates signals that comply with the EIA RS232-C specification. There is also a CCITT standard named V.24 that mirrors the specifications included in RS232-C. RS232-C Bit Assignments (Marks and Spaces) In RS232-C, a value of 1 is called a Mark and a value of 0 is called a Space. When a communication line is idle, the line is said to be Marking, or transmitting continuous 1 values. The Start bit always has a value of 0 (a Space). The Stop Bit always has a value of 1 (a Mark). This means that there will always be a Mark (1) to Space (0) transition on the line at the start of every word, even when multiple word are transmitted back to back. This guarantees that sender and receiver can resynchronize their clocks regardless of the content of the data bits that are being transmitted. The idle time between Stop and Start bits does not have to be an exact multiple (including zero) of the bit rate of the communication link, but most UARTs are designed this way for simplicity. In RS232-C, the "Marking" signal (a 1) is represented by a voltage between -2 VDC and -12 VDC, and a "Spacing" signal (a 0) is represented by a voltage between 0 and +12 VDC. The transmitter is supposed to send +12 VDC or -12 VDC, and the receiver is supposed to allow for some voltage loss in long cables. Some transmitters in low power devices (like portable computers) sometimes use only +5 VDC and -5 VDC, but these values are still acceptable to a RS232-C receiver, provided that the cable lengths are short. RS232-C Break Signal RS232-C also specifies a signal called a Break, which is caused by sending continuous Spacing values (no Start or Stop bits). When there is no electricity present on the data circuit, the line is considered to be sending Break. The Break signal must be of a duration longer than the time it takes to send a complete byte plus Start, Stop and Parity bits. Most UARTs can distinguish between a Framing Error and a Break, but if the UART cannot do this, the Framing Error detection can be used to identify Breaks. In the days of teleprinters, when numerous printers around the country were wired in series (such as news services), any unit could cause a Break by temporarily opening the entire circuit so that no current flowed. This was used to allow a location with urgent news to interrupt some other location that was currently sending information. In modern systems there are two types of Break signals. If the Break is longer than 1.6 seconds, it is considered a "Modem Break", and some modems can be programmed to terminate the conversation and go on-hook or enter the modems' command mode when the modem detects this signal. If the Break is smaller than 1.6 seconds, it signifies a Data Break and it is up to the remote computer to respond to this signal. Sometimes this form of Break is used as an Attention or Interrupt signal and sometimes is accepted as a substitute for the ASCII CONTROL-C character. Marks and Spaces are also equivalent to Holes and No Holes in paper tape systems. Breaks cannot be generated from paper tape or from any other byte value, since bytes are always sent with Start and Stop bit. The UART is usually capable of generating the continuous Spacing signal in response to a special command from the host processor. RS232-C DTE and DCE Devices The RS232-C specification defines two types of equipment: the Data Terminal Equipment (DTE) and the Data Carrier Equipment (DCE). Usually, the DTE device is the terminal (or computer), and the DCE is a modem. Across the phone line at the other end of a conversation, the receiving modem is also a DCE device and the computer that is connected to that modem is a DTE device. The DCE device receives signals on the pins that the DTE device transmits on, and vice versa. When two devices that are both DTE or both DCE must be connected together without a modem or a similar media translater between them, a NULL modem must be used. The NULL modem electrically re-arranges the cabling so that the transmitter output is connected to the receiver input on the other device, and vice versa. Similar translations are performed on all of the control signals so that each device will see what it thinks are DCE (or DTE) signals from the other device. The number of signals generated by the DTE and DCE devices are not symmetrical. The DTE device generates fewer signals for the DCE device than the DTE device receives from the DCE. RS232-C Pin Assignments The EIA RS232-C specification (and the ITU equivalent, V.24) calls for a twenty-five pin connector (usually a DB25) and defines the purpose of most of the pins in that connector. In the IBM Personal Computer and similar systems, a subset of RS232-C signals are provided via nine pin connectors (DB9). The signals that are not included on the PC connector deal mainly with synchronous operation, and this transmission mode is not supported by the UART that IBM selected for use in the IBM PC. Depending on the computer manufacturer, a DB25, a DB9, or both types of connector may be used for RS232-C communications. (The IBM PC also uses a DB25 connector for the parallel printer interface which causes some confusion.) Below is a table of the RS232-C signal assignments in the DB25 and DB9 connectors. DB25 RS232-C Pin DB9 IBM PC Pin EIA Circuit Symbol CCITT Circuit Symbol Common Name Signal Source Description 1 - AA 101 PG/FG - Frame/Protective Ground 2 3 BA 103 TD DTE Transmit Data 3 2 BB 104 RD DCE Receive Data 4 7 CA 105 RTS DTE Request to Send 5 8 CB 106 CTS DCE Clear to Send 6 6 CC 107 DSR DCE Data Set Ready 7 5 AV 102 SG/GND - Signal Ground 8 1 CF 109 DCD/CD DCE Data Carrier Detect 9 - - - - - Reserved for Test 10 - - - - - Reserved for Test 11 - - - - - Reserved for Test 12 - CI 122 SRLSD DCE Sec. Recv. Line Signal Detector 13 - SCB 121 SCTS DCE Secondary Clear to Send 14 - SBA 118 STD DTE Secondary Transmit Data 15 - DB 114 TSET DCE Trans. Sig. Element Timing 16 - SBB 119 SRD DCE Secondary Received Data 17 - DD 115 RSET DCE Receiver Signal Element Timing 18 - - 141 LOOP DTE Local Loopback 19 - SCA 120 SRS DTE Secondary Request to Send 20 4 CD 108.2 DTR DTE Data Terminal Ready 21 - - - RDL DTE Remote Digital Loopback 22 9 CE 125 RI DCE Ring Indicator 23 - CH 111 DSRS DTE Data Signal Rate Selector 24 - DA 113 TSET DTE Trans. Sig. Element Timing 25 - - 142 - DCE Test Mode Bits, Baud and Symbols Baud is a measurement of transmission speed in asynchronous communication. Because of advances in modem communication technology, this term is frequently misused when describing the data rates in newer devices. Traditionally, a Baud Rate represents the number of bits that are actually being sent over the media, not the amount of data that is actually moved from one DTE device to the other. The Baud count includes the overhead bits Start, Stop and Parity that are generated by the sending UART and removed by the receiving UART. This means that seven-bit words of data actually take 10 bits to be completely transmitted. Therefore, a modem capable of moving 300 bits per second from one place to another can normally only move 30 7-bit words if Parity is used and one Start and Stop bit are present. If 8-bit data words are used and Parity bits are also used, the data rate falls to 27.27 words per second, because it now takes 11 bits to send the eight-bit words, and the modem still only sends 300 bits per second. The formula for converting bytes per second into a baud rate and vice versa was simple until error-correcting modems came along. These modems receive the serial stream of bits from the UART in the host computer (even when internal modems are used the data is still frequently serialized) and converts the bits back into bytes. These bytes are then combined into packets and sent over the phone line using a Synchronous transmission method. This means that the Stop, Start, and Parity bits added by the UART in the DTE (the computer) were removed by the modem before transmission by the sending modem. When these bytes are received by the remote modem, the remote modem adds Start, Stop and Parity bits to the words, converts them to a serial format and then sends them to the receiving UART in the remote computer, who then strips the Start, Stop and Parity bits. The reason all these extra conversions are done is so that the two modems can perform error correction, which means that the receiving modem is able to ask the sending modem to resend a block of data that was not received with the correct checksum. This checking is handled by the modems, and the DTE devices are usually unaware that the process is occurring. By striping the Start, Stop and Parity bits, the additional bits of data that the two modems must share between themselves to perform error-correction are mostly concealed from the effective transmission rate seen by the sending and receiving DTE equipment. For example, if a modem sends ten 7-bit words to another modem without including the Start, Stop and Parity bits, the sending modem will be able to add 30 bits of its own information that the receiving modem can use to do error-correction without impacting the transmission speed of the real data. The use of the term Baud is further confused by modems that perform compression. A single 8-bit word passed over the telephone line might represent a dozen words that were transmitted to the sending modem. The receiving modem will expand the data back to its original content and pass that data to the receiving DTE. Modern modems also include buffers that allow the rate that bits move across the phone line (DCE to DCE) to be a different speed than the speed that the bits move between the DTE and DCE on both ends of the conversation. Normally the speed between the DTE and DCE is higher than the DCE to DCE speed because of the use of compression by the modems. Because the number of bits needed to describe a byte varied during the trip between the two machines plus the differing bits-per-seconds speeds that are used present on the DTE-DCE and DCE-DCE links, the usage of the term Baud to describe the overall communication speed causes problems and can misrepresent the true transmission speed. So Bits Per Second (bps) is the correct term to use to describe the transmission rate seen at the DCE to DCE interface and Baud or Bits Per Second are acceptable terms to use when a connection is made between two systems with a wired connection, or if a modem is in use that is not performing error-correction or compression. Modern high speed modems (2400, 9600, 14,400, and 19,200bps) in reality still operate at or below 2400 baud, or more accurately, 2400 Symbols per second. High speed modem are able to encode more bits of data into each Symbol using a technique called Constellation Stuffing, which is why the effective bits per second rate of the modem is higher, but the modem continues to operate within the limited audio bandwidth that the telephone system provides. Modems operating at 28,800 and higher speeds have variable Symbol rates, but the technique is the same. The IBM Personal Computer UART Starting with the original IBM Personal Computer, IBM selected the National Semiconductor INS8250 UART for use in the IBM PC Parallel/Serial Adapter. Subsequent generations of compatible computers from IBM and other vendors continued to use the INS8250 or improved versions of the National Semiconductor UART family. National Semiconductor UART Family Tree There have been several versions and subsequent generations of the INS8250 UART. Each major version is described below. INS8250 -> INS8250B \ \ \-> INS8250A -> INS82C50A \ \ \-> NS16450 -> NS16C450 \ \ \-> NS16550 -> NS16550A -> PC16550D INS8250 This part was used in the original IBM PC and IBM PC/XT. The original name for this part was the INS8250 ACE (Asynchronous Communications Element) and it is made from NMOS technology. The 8250 uses eight I/O ports and has a one-byte send and a one-byte receive buffer. This original UART has several race conditions and other flaws. The original IBM BIOS includes code to work around these flaws, but this made the BIOS dependent on the flaws being present, so subsequent parts like the 8250A, 16450 or 16550 could not be used in the original IBM PC or IBM PC/XT. INS8250-B This is the slower speed of the INS8250 made from NMOS technology. It contains the same problems as the original INS8250. INS8250A An improved version of the INS8250 using XMOS technology with various functional flaws corrected. The INS8250A was used initially in PC clone computers by vendors who used clean BIOS designs. Because of the corrections in the chip, this part could not be used with a BIOS compatible with the INS8250 or INS8250B. INS82C50A This is a CMOS version (low power consumption) of the INS8250A and has similar functional characteristics. NS16450 Same as NS8250A with improvements so it can be used with faster CPU bus designs. IBM used this part in the IBM AT and updated the IBM BIOS to no longer rely on the bugs in the INS8250. NS16C450 This is a CMOS version (low power consumption) of the NS16450. NS16550 Same as NS16450 with a 16-byte send and receive buffer but the buffer design was flawed and could not be reliably be used. NS16550A Same as NS16550 with the buffer flaws corrected. The 16550A and its successors have become the most popular UART design in the PC industry, mainly due it its ability to reliably handle higher data rates on operating systems with sluggish interrupt response times. NS16C552 This component consists of two NS16C550A CMOS UARTs in a single package. PC16550D Same as NS16550A with subtle flaws corrected. This is revision D of the 16550 family and is the latest design available from National Semiconductor. The NS16550AF and the PC16550D are the same thing National reorganized their part numbering system a few years ago, and the NS16550AFN no longer exists by that name. (If you have a NS16550AFN, look at the date code on the part, which is a four digit number that usually starts with a nine. The first two digits of the number are the year, and the last two digits are the week in that year when the part was packaged. If you have a NS16550AFN, it is probably a few years old.) The new numbers are like PC16550DV, with minor differences in the suffix letters depending on the package material and its shape. (A description of the numbering system can be found below.) It is important to understand that in some stores, you may pay $15(US) for a NS16550AFN made in 1990 and in the next bin are the new PC16550DN parts with minor fixes that National has made since the AFN part was in production, the PC16550DN was probably made in the past six months and it costs half (as low as $5(US) in volume) as much as the NS16550AFN because they are readily available. As the supply of NS16550AFN chips continues to shrink, the price will probably continue to increase until more people discover and accept that the PC16550DN really has the same function as the old part number. National Semiconductor Part Numbering System The older NSnnnnnrqp part numbers are now of the format PCnnnnnrgp. The r is the revision field. The current revision of the 16550 from National Semiconductor is D. The p is the package-type field. The types are: "F" QFP (quad flat pack) L lead type "N" DIP (dual inline package) through hole straight lead type "V" LPCC (lead plastic chip carrier) J lead type The g is the product grade field. If an I precedes the package-type letter, it indicates an industrial grade part, which has higher specs than a standard part but not as high as Military Specification (Milspec) component. This is an optional field. So what we used to call a NS16550AFN (DIP Package) is now called a PC16550DN or PC16550DIN. Other Vendors and Similar UARTs Over the years, the 8250, 8250A, 16450 and 16550 have been licensed or copied by other chip vendors. In the case of the 8250, 8250A and 16450, the exact circuit (the megacell) was licensed to many vendors, including Western Digital and Intel. Other vendors reverse-engineered the part or produced emulations that had similar behavior. In internal modems, the modem designer will frequently emulate the 8250A/16450 with the modem microprocessor, and the emulated UART will frequently have a hidden buffer consisting of several hundred bytes. Because of the size of the buffer, these emulations can be as reliable as a 16550A in their ability to handle high speed data. However, most operating systems will still report that the UART is only a 8250A or 16450, and may not make effective use of the extra buffering present in the emulated UART unless special drivers are used. Some modem makers are driven by market forces to abandon a design that has hundreds of bytes of buffer and instead use a 16550A UART so that the product will compare favorably in market comparisons even though the effective performance may be lowered by this action. A common misconception is that all parts with 16550A written on them are identical in performance. There are differences, and in some cases, outright flaws in most of these 16550A clones. When the NS16550 was developed, the National Semiconductor obtained several patents on the design and they also limited licensing, making it harder for other vendors to provide a chip with similar features. Because of the patents, reverse-engineered designs and emulations had to avoid infringing the claims covered by the patents. Subsequently, these copies almost never perform exactly the same as the NS16550A or PC16550D, which are the parts most computer and modem makers want to buy but are sometimes unwilling to pay the price required to get the genuine part. Some of the differences in the clone 16550A parts are unimportant, while others can prevent the device from being used at all with a given operating system or driver. These differences may show up when using other drivers, or when particular combinations of events occur that were not well tested or considered in the Windows driver. This is because most modem vendors and 16550-clone makers use the Microsoft drivers from Windows for Workgroups 3.11 and the Microsoft MS-DOS utility as the primary tests for compatibility with the NS16550A. This over-simplistic criteria means that if a different operating system is used, problems could appear due to subtle differences between the clones and genuine components. National Semiconductor has made available a program named COMTEST that performs compatibility tests independent of any OS drivers. It should be remembered that the purpose of this type of program is to demonstrate the flaws in the products of the competition, so the program will report major as well as extremely subtle differences in behavior in the part being tested. In a series of tests performed by the author of this document in 1994, components made by National Semiconductor, TI, StarTech, and CMD as well as megacells and emulations embedded in internal modems were tested with COMTEST. A difference count for some of these components is listed below. Because these tests were performed in 1994, they may not reflect the current performance of the given product from a vendor. It should be noted that COMTEST normally aborts when an excessive number or certain types of problems have been detected. As part of this testing, COMTEST was modified so that it would not abort no matter how many differences were encountered. Vendor Part Number Errors (aka "differences" reported) National (PC16550DV) 0 National (NS16550AFN) 0 National (NS16C552V) 0 TI (TL16550AFN) 3 CMD (16C550PE) 19 StarTech (ST16C550J) 23 Rockwell Reference modem with internal 16550 or an emulation (RC144DPi/C3000-25) 117 Sierra Modem with an internal 16550 (SC11951/SC11351) 91 To date, the author of this document has not found any non-National parts that report zero differences using the COMTEST program. It should also be noted that National has had five versions of the 16550 over the years and the newest parts behave a bit differently than the classic NS16550AFN that is considered the benchmark for functionality. COMTEST appears to turn a blind eye to the differences within the National product line and reports no errors on the National parts (except for the original 16550) even when there are official erratas that describe bugs in the A, B and C revisions of the parts, so this bias in COMTEST must be taken into account. It is important to understand that a simple count of differences from COMTEST does not reveal a lot about what differences are important and which are not. For example, about half of the differences reported in the two modems listed above that have internal UARTs were caused by the clone UARTs not supporting five- and six-bit character modes. The real 16550, 16450, and 8250 UARTs all support these modes and COMTEST checks the functionality of these modes so over fifty differences are reported. However, almost no modern modem supports five- or six-bit characters, particularly those with error-correction and compression capabilities. This means that the differences related to five- and six-bit character modes can be discounted. Many of the differences COMTEST reports have to do with timing. In many of the clone designs, when the host reads from one port, the status bits in some other port may not update in the same amount of time (some faster, some slower) as a real NS16550AFN and COMTEST looks for these differences. This means that the number of differences can be misleading in that one device may only have one or two differences but they are extremely serious, and some other device that updates the status registers faster or slower than the reference part (that would probably never affect the operation of a properly written driver) could have dozens of differences reported. COMTEST can be used as a screening tool to alert the administrator to the presence of potentially incompatible components that might cause problems or have to be handled as a special case. If you run COMTEST on a 16550 that is in a modem or a modem is attached to the serial port, you need to first issue a ATE0&W command to the modem so that the modem will not echo any of the test characters. If you forget to do this, COMTEST will report at least this one difference: Error (6)...Timeout interrupt failed: IIR = c1 LSR = 61 8250/16450/16550 Registers The 8250/16450/16550 UART occupies eight contiguous I/O port addresses. In the IBM PC, there are two defined locations for these eight ports and they are known collectively as COM1 and COM2. The makers of PC-clones and add-on cards have created two additional areas known as COM3 and COM4, but these extra COM ports conflict with other hardware on some systems. The most common conflict is with video adapters that provide IBM 8514 emulation. COM1 is located from 0x3f8 to 0x3ff and normally uses IRQ 4 COM2 is located from 0x2f8 to 0x2ff and normally uses IRQ 3 COM3 is located from 0x3e8 to 0x3ef and has no standardized IRQ COM4 is located from 0x2e8 to 0x2ef and has no standardized IRQ. A description of the I/O ports of the 8250/16450/16550 UART is provided below. I/O Port Access Allowed Description +0x00 write (DLAB==0) Transmit Holding Register (THR).Information written to this port are treated as data words and will be transmitted by the UART. +0x00 read (DLAB==0) Receive Buffer Register (RBR).Any data words received by the UART form the serial link are accessed by the host by reading this port. +0x00 write/read (DLAB==1) Divisor Latch LSB (DLL)This value will be divided from the master input clock (in the IBM PC, the master clock is 1.8432MHz) and the resulting clock will determine the baud rate of the UART. This register holds bits 0 thru 7 of the divisor. +0x01 write/read (DLAB==1) Divisor Latch MSB (DLH)This value will be divided from the master input clock (in the IBM PC, the master clock is 1.8432MHz) and the resulting clock will determine the baud rate of the UART. This register holds bits 8 thru 15 of the divisor. +0x01 write/read (DLAB==0) Interrupt Enable Register (IER)The 8250/16450/16550 UART classifies events into one of four categories. Each category can be configured to generate an interrupt when any of the events occurs. The 8250/16450/16550 UART generates a single external interrupt signal regardless of how many events in the enabled categories have occurred. It is up to the host processor to respond to the interrupt and then poll the enabled interrupt categories (usually all categories have interrupts enabled) to determine the true cause(s) of the interrupt. Bit 7 Reserved, always 0. Bit 6 Reserved, always 0. Bit 5 Reserved, always 0. Bit 4 Reserved, always 0. Bit 3 Enable Modem Status Interrupt (EDSSI). Setting this bit to "1" allows the UART to generate an interrupt when a change occurs on one or more of the status lines. Bit 2 Enable Receiver Line Status Interrupt (ELSI) Setting this bit to "1" causes the UART to generate an interrupt when the an error (or a BREAK signal) has been detected in the incoming data. Bit 1 Enable Transmitter Holding Register Empty Interrupt (ETBEI) Setting this bit to "1" causes the UART to generate an interrupt when the UART has room for one or more additional characters that are to be transmitted. Bit 0 Enable Received Data Available Interrupt (ERBFI) Setting this bit to "1" causes the UART to generate an interrupt when the UART has received enough characters to exceed the trigger level of the FIFO, or the FIFO timer has expired (stale data), or a single character has been received when the FIFO is disabled. +0x02 write FIFO Control Register (FCR) (This port does not exist on the 8250 and 16450 UART.) Bit 7 Receiver Trigger Bit #1 Bit 6 Receiver Trigger Bit #0These two bits control at what point the receiver is to generate an interrupt when the FIFO is active. 7 6 How many words are received before an interrupt is generated 0 0 1 0 1 4 1 0 8 1 1 14 Bit 5 Reserved, always 0. Bit 4 Reserved, always 0. Bit 3 DMA Mode Select. If Bit 0 is set to "1" (FIFOs enabled), setting this bit changes the operation of the -RXRDY and -TXRDY signals from Mode 0 to Mode 1. Bit 2 Transmit FIFO Reset. When a "1" is written to this bit, the contents of the FIFO are discarded. Any word currently being transmitted will be sent intact. This function is useful in aborting transfers. Bit 1 Receiver FIFO Reset. When a "1" is written to this bit, the contents of the FIFO are discarded. Any word currently being assembled in the shift register will be received intact. Bit 0 16550 FIFO Enable. When set, both the transmit and receive FIFOs are enabled. Any contents in the holding register, shift registers or FIFOs are lost when FIFOs are enabled or disabled. +0x02 read Interrupt Identification Register Bit 7 FIFOs enabled. On the 8250/16450 UART, this bit is zero. Bit 6 FIFOs enabled. On the 8250/16450 UART, this bit is zero. Bit 5 Reserved, always 0. Bit 4 Reserved, always 0. Bit 3 Interrupt ID Bit #2. On the 8250/16450 UART, this bit is zero. Bit 2 Interrupt ID Bit #1 Bit 1 Interrupt ID Bit #0.These three bits combine to report the category of event that caused the interrupt that is in progress. These categories have priorities, so if multiple categories of events occur at the same time, the UART will report the more important events first and the host must resolve the events in the order they are reported. All events that caused the current interrupt must be resolved before any new interrupts will be generated. (This is a limitation of the PC architecture.) 2 1 0 Priority Description 0 1 1 First Received Error (OE, PE, BI, or FE) 0 1 0 Second Received Data Available 1 1 0 Second Trigger level identification (Stale data in receive buffer) 0 0 1 Third Transmitter has room for more words (THRE) 0 0 0 Fourth Modem Status Change (-CTS, -DSR, -RI, or -DCD) Bit 0 Interrupt Pending Bit. If this bit is set to "0", then at least one interrupt is pending. +0x03 write/read Line Control Register (LCR) Bit 7 Divisor Latch Access Bit (DLAB). When set, access to the data transmit/receive register (THR/RBR) and the Interrupt Enable Register (IER) is disabled. Any access to these ports is now redirected to the Divisor Latch Registers. Setting this bit, loading the Divisor Registers, and clearing DLAB should be done with interrupts disabled. Bit 6 Set Break. When set to "1", the transmitter begins to transmit continuous Spacing until this bit is set to "0". This overrides any bits of characters that are being transmitted. Bit 5 Stick Parity. When parity is enabled, setting this bit causes parity to always be "1" or "0", based on the value of Bit 4. Bit 4 Even Parity Select (EPS). When parity is enabled and Bit 5 is "0", setting this bit causes even parity to be transmitted and expected. Otherwise, odd parity is used. Bit 3 Parity Enable (PEN). When set to "1", a parity bit is inserted between the last bit of the data and the Stop Bit. The UART will also expect parity to be present in the received data. Bit 2 Number of Stop Bits (STB). If set to "1" and using 5-bit data words, 1.5 Stop Bits are transmitted and expected in each data word. For 6, 7 and 8-bit data words, 2 Stop Bits are transmitted and expected. When this bit is set to "0", one Stop Bit is used on each data word. Bit 1 Word Length Select Bit #1 (WLSB1) Bit 0 Word Length Select Bit #0 (WLSB0) Together these bits specify the number of bits in each data word. 1 0 Word Length 0 0 5 Data Bits 0 1 6 Data Bits 1 0 7 Data Bits 1 1 8 Data Bits +0x04 write/read Modem Control Register (MCR) Bit 7 Reserved, always 0. Bit 6 Reserved, always 0. Bit 5 Reserved, always 0. Bit 4 Loop-Back Enable. When set to "1", the UART transmitter and receiver are internally connected together to allow diagnostic operations. In addition, the UART modem control outputs are connected to the UART modem control inputs. CTS is connected to RTS, DTR is connected to DSR, OUT1 is connected to RI, and OUT 2 is connected to DCD. Bit 3 OUT 2. An auxiliary output that the host processor may set high or low. In the IBM PC serial adapter (and most clones), OUT 2 is used to tri-state (disable) the interrupt signal from the 8250/16450/16550 UART. Bit 2 OUT 1. An auxiliary output that the host processor may set high or low. This output is not used on the IBM PC serial adapter. Bit 1 Request to Send (RTS). When set to "1", the output of the UART -RTS line is Low (Active). Bit 0 Data Terminal Ready (DTR). When set to "1", the output of the UART -DTR line is Low (Active). +0x05 write/read Line Status Register (LSR) Bit 7 Error in Receiver FIFO. On the 8250/16450 UART, this bit is zero. This bit is set to "1" when any of the bytes in the FIFO have one or more of the following error conditions: PE, FE, or BI. Bit 6 Transmitter Empty (TEMT). When set to "1", there are no words remaining in the transmit FIFO or the transmit shift register. The transmitter is completely idle. Bit 5 Transmitter Holding Register Empty (THRE). When set to "1", the FIFO (or holding register) now has room for at least one additional word to transmit. The transmitter may still be transmitting when this bit is set to "1". Bit 4 Break Interrupt (BI). The receiver has detected a Break signal. Bit 3 Framing Error (FE). A Start Bit was detected but the Stop Bit did not appear at the expected time. The received word is probably garbled. Bit 2 Parity Error (PE). The parity bit was incorrect for the word received. Bit 1 Overrun Error (OE). A new word was received and there was no room in the receive buffer. The newly-arrived word in the shift register is discarded. On 8250/16450 UARTs, the word in the holding register is discarded and the newly- arrived word is put in the holding register. Bit 0 Data Ready (DR) One or more words are in the receive FIFO that the host may read. A word must be completely received and moved from the shift register into the FIFO (or holding register for 8250/16450 designs) before this bit is set. +0x06 write/read Modem Status Register (MSR) Bit 7 Data Carrier Detect (DCD). Reflects the state of the DCD line on the UART. Bit 6 Ring Indicator (RI). Reflects the state of the RI line on the UART. Bit 5 Data Set Ready (DSR). Reflects the state of the DSR line on the UART. Bit 4 Clear To Send (CTS). Reflects the state of the CTS line on the UART. Bit 3 Delta Data Carrier Detect (DDCD). Set to "1" if the -DCD line has changed state one more time since the last time the MSR was read by the host. Bit 2 Trailing Edge Ring Indicator (TERI). Set to "1" if the -RI line has had a low to high transition since the last time the MSR was read by the host. Bit 1 Delta Data Set Ready (DDSR). Set to "1" if the -DSR line has changed state one more time since the last time the MSR was read by the host. Bit 0 Delta Clear To Send (DCTS). Set to "1" if the -CTS line has changed state one more time since the last time the MSR was read by the host. +0x07 write/read Scratch Register (SCR). This register performs no function in the UART. Any value can be written by the host to this location and read by the host later on. Beyond the 16550A UART Although National Semiconductor has not offered any components compatible with the 16550 that provide additional features, various other vendors have. Some of these components are described below. It should be understood that to effectively utilize these improvements, drivers may have to be provided by the chip vendor since most of the popular operating systems do not support features beyond those provided by the 16550. ST16650 By default this part is similar to the NS16550A, but an extended 32-byte send and receive buffer can be optionally enabled. Made by StarTech. TIL16660 By default this part behaves similar to the NS16550A, but an extended 64-byte send and receive buffer can be optionally enabled. Made by Texas Instruments. Hayes ESP This proprietary plug-in card contains a 2048-byte send and receive buffer, and supports data rates to 230.4Kbit/sec. Made by Hayes. In addition to these dumb UARTs, many vendors produce intelligent serial communication boards. This type of design usually provides a microprocessor that interfaces with several UARTs, processes and buffers the data, and then alerts the main PC processor when necessary. Because the UARTs are not directly accessed by the PC processor in this type of communication system, it is not necessary for the vendor to use UARTs that are compatible with the 8250, 16450, or the 16550 UART. This leaves the designer free to components that may have better performance characteristics. Configuring the <devicename>sio</devicename> driver The sio driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. Several multiport cards are supported as well. See the &man.sio.4; manual page for detailed technical documentation. Digi International (DigiBoard) PC/8 Contributed by &a.awebster;. 26 August 1995. Here is a config snippet from a machine with a Digi International PC/8 with 16550. It has 8 modems connected to these 8 lines, and they work just great. Do not forget to add options COM_MULTIPORT or it will not work very well! device sio4 at isa? port 0x100 tty flags 0xb05 device sio5 at isa? port 0x108 tty flags 0xb05 device sio6 at isa? port 0x110 tty flags 0xb05 device sio7 at isa? port 0x118 tty flags 0xb05 device sio8 at isa? port 0x120 tty flags 0xb05 device sio9 at isa? port 0x128 tty flags 0xb05 device sio10 at isa? port 0x130 tty flags 0xb05 device sio11 at isa? port 0x138 tty flags 0xb05 irq 9 vector siointr The trick in setting this up is that the MSB of the flags represent the last SIO port, in this case 11 so flags are 0xb05. Boca 16 Contributed by &a.whiteside;. 26 August 1995. The procedures to make a Boca 16 port board with FreeBSD are pretty straightforward, but you will need a couple things to make it work: You either need the kernel sources installed so you can recompile the necessary options or you will need someone else to compile it for you. The 2.0.5 default kernel does not come with multiport support enabled and you will need to add a device entry for each port anyways. Two, you will need to know the interrupt and IO setting for your Boca Board so you can set these options properly in the kernel. One important note — the actual UART chips for the Boca 16 are in the connector box, not on the internal board itself. So if you have it unplugged, probes of those ports will fail. I have never tested booting with the box unplugged and plugging it back in, and I suggest you do not either. If you do not already have a custom kernel configuration file set up, refer to Kernel Configuration for general procedures. The following are the specifics for the Boca 16 board and assume you are using the kernel name MYKERNEL and editing with vi. Add the line options COM_MULTIPORT to the config file. Where the current device sion lines are, you will need to add 16 more devices. Only the last device includes the interrupt vector for the board. (See the &man.sio.4; manual page for detail as to why.) The following example is for a Boca Board with an interrupt of 3, and a base IO address 100h. The IO address for Each port is +8 hexadecimal from the previous port, thus the 100h, 108h, 110h... addresses. device sio1 at isa? port 0x100 tty flags 0x1005 device sio2 at isa? port 0x108 tty flags 0x1005 device sio3 at isa? port 0x110 tty flags 0x1005 device sio4 at isa? port 0x118 tty flags 0x1005 … device sio15 at isa? port 0x170 tty flags 0x1005 device sio16 at isa? port 0x178 tty flags 0x1005 irq 3 vector siointr The flags entry must be changed from this example unless you are using the exact same sio assignments. Flags are set according to 0xMYY where M indicates the minor number of the master port (the last port on a Boca 16) and YY indicates if FIFO is enabled or disabled(enabled), IRQ sharing is used(yes) and if there is an AST/4 compatible IRQ control register(no). In this example, flags 0x1005 indicates that the master port is sio16. If I added another board and assigned sio17 through sio28, the flags for all 16 ports on that board would be 0x1C05, where 1C indicates the minor number of the master port. Do not change the 05 setting. Save and complete the kernel configuration, recompile, install and reboot. Presuming you have successfully installed the recompiled kernel and have it set to the correct address and IRQ, your boot message should indicate the successful probe of the Boca ports as follows: (obviously the sio numbers, IO and IRQ could be different) sio1 at 0x100-0x107 flags 0x1005 on isa sio1: type 16550A (multiport) sio2 at 0x108-0x10f flags 0x1005 on isa sio2: type 16550A (multiport) sio3 at 0x110-0x117 flags 0x1005 on isa sio3: type 16550A (multiport) sio4 at 0x118-0x11f flags 0x1005 on isa sio4: type 16550A (multiport) sio5 at 0x120-0x127 flags 0x1005 on isa sio5: type 16550A (multiport) sio6 at 0x128-0x12f flags 0x1005 on isa sio6: type 16550A (multiport) sio7 at 0x130-0x137 flags 0x1005 on isa sio7: type 16550A (multiport) sio8 at 0x138-0x13f flags 0x1005 on isa sio8: type 16550A (multiport) sio9 at 0x140-0x147 flags 0x1005 on isa sio9: type 16550A (multiport) sio10 at 0x148-0x14f flags 0x1005 on isa sio10: type 16550A (multiport) sio11 at 0x150-0x157 flags 0x1005 on isa sio11: type 16550A (multiport) sio12 at 0x158-0x15f flags 0x1005 on isa sio12: type 16550A (multiport) sio13 at 0x160-0x167 flags 0x1005 on isa sio13: type 16550A (multiport) sio14 at 0x168-0x16f flags 0x1005 on isa sio14: type 16550A (multiport) sio15 at 0x170-0x177 flags 0x1005 on isa sio15: type 16550A (multiport) sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa sio16: type 16550A (multiport master) If the messages go by too fast to see, &prompt.root; dmesg | more will show you the boot messages. Next, appropriate entries in /dev for the devices must be made using the /dev/MAKEDEV script. After becoming root: &prompt.root; cd /dev &prompt.root; ./MAKEDEV tty1 &prompt.root; ./MAKEDEV cua1 (everything in between) &prompt.root; ./MAKEDEV ttyg &prompt.root; ./MAKEDEV cuag If you do not want or need call-out devices for some reason, you can dispense with making the cua* devices. If you want a quick and sloppy way to make sure the devices are working, you can simply plug a modem into each port and (as root) &prompt.root; echo at > ttyd* for each device you have made. You should see the RX lights flash for each working port. Support for Cheap Multi-UART Cards Contributed by Helge Oldach hmo@sep.hamburg.com, September 1999 Ever wondered about FreeBSD support for your 20$ multi-I/O card with two (or more) COM ports, sharing IRQs? Here's how: Usually the only option to support these kind of boards is to use a distinct IRQ for each port. For example, if your CPU board has an on-board COM1 port (aka sio0–I/O address 0x3F8 and IRQ 4) and you have an extension board with two UARTs, you will commonly need to configure them as COM2 (aka sio1–I/O address 0x2F8 and IRQ 3), and the third port (aka sio2) as I/O 0x3E8 and IRQ 5. Obviously this is a waste of IRQ resources, as it should be basically possible to run both extension board ports using a single IRQ with the COM_MULTIPORT configuration described in the previous sections. Such cheap I/O boards commonly have a 4 by 3 jumper matrix for the COM ports, similar to the following: o o o * Port A | o * o * Port B | o * o o IRQ 2 3 4 5 Shown here is port A wired for IRQ 5 and port B wired for IRQ 3. The IRQ columns on your specific board may vary—other boards may supply jumpers for IRQs 3, 4, 5, and 7 instead. One could conclude that wiring both ports for IRQ 3 using a handcrafted wire-made jumper covering all three connection points in the IRQ 3 column would solve the issue, but no. You cannot duplicate IRQ 3 because the output drivers of each UART are wired in a totem pole fashion, so if one of the UARTs drives IRQ 3, the output signal will not be what you would expect. Depending on the implementation of the extension board or your motherboard, the IRQ 3 line will continuously stay up, or always stay low. You need to decouple the IRQ drivers for the two UARTs, so that the IRQ line of the board only goes up if (and only if) one of the UARTs asserts a IRQ, and stays low otherwise. The solution was proposed by Joerg Wunsch j@ida.interface-business.de: To solder up a wired-or consisting of two diodes (Germanium or Schottky-types strongly preferred) and a 1 kOhm resistor. Here is the schematic, starting from the 4 by 3 jumper field above: Diode +---------->|-------+ / | o * o o | 1 kOhm Port A +----|######|-------+ o * o o | | Port B `-------------------+ ==+== o * o o | Ground \ | +--------->|-------+ IRQ 2 3 4 5 Diode The cathodes of the diodes are connected to a common point, together with a 1 kOhm pull-down resistor. It is essential to connect the resistor to ground to avoid floating of the IRQ line on the bus. Now we are ready to configure a kernel. Staying with this example, we would configure: # standard on-board COM1 port device sio0 at isa? port "IO_COM1" tty flags 0x10 # patched-up multi-I/O extension board options COM_MULTIPORT device sio1 at isa? port "IO_COM2" tty flags 0x205 device sio2 at isa? port "IO_COM3" tty flags 0x205 irq 3 Note that the flags setting for sio1 and sio2 is truly essential; refer to &man.sio.4; for details. (Generally, the 2 in the "flags" attribute refers to sio2 which holds the IRQ, and you surely want a 5 low nibble.) With kernel verbose mode turned on this should yield something similar to this: sio0: irq maps: 0x1 0x11 0x1 0x1 sio0 at 0x3f8-0x3ff irq 4 flags 0x10 on isa sio0: type 16550A sio1: irq maps: 0x1 0x9 0x1 0x1 sio1 at 0x2f8-0x2ff flags 0x205 on isa sio1: type 16550A (multiport) sio2: irq maps: 0x1 0x9 0x1 0x1 sio2 at 0x3e8-0x3ef irq 3 flags 0x205 on isa sio2: type 16550A (multiport master) Though /sys/i386/isa/sio.c is somewhat cryptic with its use of the irq maps array above, the basic idea is that you observe 0x1 in the first, third, and fourth place. This means that the corresponding IRQ was set upon output and cleared after, which is just what we would expect. If your kernel does not display this behavior, most likely there is something wrong with your wiring. Configuring the <devicename>cy</devicename> driver Contributed by Alex Nash. 6 June 1996. The Cyclades multiport cards are based on the cy driver instead of the usual sio driver used by other multiport cards. Configuration is a simple matter of: Add the cy device to your kernel configuration (note that your irq and iomem settings may differ). device cy0 at isa? tty irq 10 iomem 0xd4000 iosiz 0x2000 vector cyintr Rebuild and install the new kernel. Make the device nodes by typing (the following example assumes an 8-port board): &prompt.root; cd /dev &prompt.root; for i in 0 1 2 3 4 5 6 7;do ./MAKEDEV cuac$i ttyc$i;done If appropriate, add dialup entries to /etc/ttys by duplicating serial device (ttyd) entries and using ttyc in place of ttyd. For example: ttyc0 "/usr/libexec/getty std.38400" unknown on insecure ttyc1 "/usr/libexec/getty std.38400" unknown on insecure ttyc2 "/usr/libexec/getty std.38400" unknown on insecure … ttyc7 "/usr/libexec/getty std.38400" unknown on insecure Reboot with the new kernel. Configuring the <devicename>si</devicename> driver Contributed by &a.nsayer;. 25 March 1998. The Specialix SI/XIO and SX multiport cards use the si driver. A single machine can have up to 4 host cards. The following host cards are supported: ISA SI/XIO host card (2 versions) EISA SI/XIO host card PCI SI/XIO host card ISA SX host card PCI SX host card Although the SX and SI/XIO host cards look markedly different, their functionality are basically the same. The host cards do not use I/O locations, but instead require a 32K chunk of memory. The factory configuration for ISA cards places this at 0xd0000-0xd7fff. They also require an IRQ. PCI cards will, of course, auto-configure themselves. You can attach up to 4 external modules to each host card. The external modules contain either 4 or 8 serial ports. They come in the following varieties: SI 4 or 8 port modules. Up to 57600 bps on each port supported. XIO 8 port modules. Up to 115200 bps on each port supported. One type of XIO module has 7 serial and 1 parallel port. SXDC 8 port modules. Up to 921600 bps on each port supported. Like XIO, a module is available with one parallel port as well. To configure an ISA host card, add the following line to your kernel configuration file, changing the numbers as appropriate: device si0 at isa? tty iomem 0xd0000 irq 11 Valid IRQ numbers are 9, 10, 11, 12 and 15 for SX ISA host cards and 11, 12 and 15 for SI/XIO ISA host cards. To configure an EISA or PCI host card, use this line: device si0 After adding the configuration entry, rebuild and install your new kernel. After rebooting with the new kernel, you need to make the device nodes in /dev. The MAKEDEV script will take care of this for you. Count how many total ports you have and type: &prompt.root; cd /dev &prompt.root; ./MAKEDEV ttyAnn cuaAnn (where nn is the number of ports) If you want login prompts to appear on these ports, you will need to add lines like this to /etc/ttys: ttyA01 "/usr/libexec/getty std.9600" vt100 on insecure Change the terminal type as appropriate. For modems, dialup or unknown is fine. * Parallel ports * Modems * Network cards * Keyboards Mice Contributed by Joel Sutton jsutton@bbcon.com.au January 2000 FreeBSD supports a variety of different mice via the PS/2, serial and USB ports. Most users choose to use the mouse daemon to handle their mouse because it allows interaction in both X and on the system console. For more information on the mouse daemon refer to &man.moused.8;. The examples throughout this section assume that the mouse daemon is being used. This section contains the names of specific products that the author has confirmed will work with FreeBSD. Other similar devices not listed may also be supported. PS/2 System Configuration To ensure that your PS/2 mouse functions correctly with the mouse daemon you will need to include the following text in /etc/rc.conf moused_enable="YES" moused_type="ps/2" moused_port="/dev/psm0" Known Compatible Devices Logitech First Mouse - Three Button Microsoft Serial - PS/2 Compatible Mouse Serial System Configuration To ensure that your serial mouse functions correctly with the mouse daemon you will need to include the following text in /etc/rc.conf. This example assumes that the mouse is connected to COM1: and can be automatically recognized by the mouse daemon. moused_enable="YES" moused_type="auto" moused_port="/dev/cuaa0" See the &man.moused.8; manual page for a detailed description of how to configure the mouse daemon to work with specific types of serial mice. Known Compatible Devices Generic Microsoft Compatible Mice Logitech First Mouse - Three Button Microsoft Serial - PS/2 Compatible Mouse USB System Configuration The USB device drivers are a relatively new addition to FreeBSD and have not yet been included in the GENERIC kernel. The following procedure is an example of how to setup the relevant drivers on a typical system. Add the ums device to the usb section of your kernel configuration. For example: controller usb0 controller uhci0 device ums0 Rebuild and install the new kernel. Make the device node by typing: &prompt.root; cd /dev &prompt.root; sh MAKEDEV ums0 Include the following text in /etc/rc.conf to ensure correct operation of the mouse daemon: moused_enable="YES" moused_type="auto" moused_port="/dev/ums0" Reboot the system. &prompt.root; shutdown -r now Known Compatible Devices Logitech TrackMan - Marble Wheel * Other ]]> Storage Devices Using ESDI hard disks Copyright © 1995, &a.wilko;. 24 September 1995. ESDI is an acronym that means Enhanced Small Device Interface. It is loosely based on the good old ST506/412 interface originally devised by Seagate Technology, the makers of the first affordable 5.25" winchester disk. The acronym says Enhanced, and rightly so. In the first place the speed of the interface is higher, 10 or 15 Mbits/second instead of the 5 Mbits/second of ST412 interfaced drives. Secondly some higher level commands are added, making the ESDI interface somewhat 'smarter' to the operating system driver writers. It is by no means as smart as SCSI by the way. ESDI is standardized by ANSI. Capacities of the drives are boosted by putting more sectors on each track. Typical is 35 sectors per track, high capacity drives I have seen were up to 54 sectors/track. Although ESDI has been largely obsoleted by IDE and SCSI interfaces, the availability of free or cheap surplus drives makes them ideal for low (or now) budget systems. Concepts of ESDI Physical connections The ESDI interface uses two cables connected to each drive. One cable is a 34 pin flat cable edge connector that carries the command and status signals from the controller to the drive and vice-versa. The command cable is daisy chained between all the drives. So, it forms a bus onto which all drives are connected. The second cable is a 20 pin flat cable edge connector that carries the data to and from the drive. This cable is radially connected, so each drive has its own direct connection to the controller. To the best of my knowledge PC ESDI controllers are limited to using a maximum of 2 drives per controller. This is compatibility feature(?) left over from the WD1003 standard that reserves only a single bit for device addressing. Device addressing On each command cable a maximum of 7 devices and 1 controller can be present. To enable the controller to uniquely identify which drive it addresses, each ESDI device is equipped with jumpers or switches to select the devices address. On PC type controllers the first drive is set to address 0, the second disk to address 1. Always make sure you set each disk to an unique address! So, on a PC with its two drives/controller maximum the first drive is drive 0, the second is drive 1. Termination The daisy chained command cable (the 34 pin cable remember?) needs to be terminated at the last drive on the chain. For this purpose ESDI drives come with a termination resistor network that can be removed or disabled by a jumper when it is not used. So, one and only one drive, the one at the farthest end of the command cable has its terminator installed/enabled. The controller automatically terminates the other end of the cable. Please note that this implies that the controller must be at one end of the cable and not in the middle. Using ESDI disks with FreeBSD Why is ESDI such a pain to get working in the first place? People who tried ESDI disks with FreeBSD are known to have developed a profound sense of frustration. A combination of factors works against you to produce effects that are hard to understand when you have never seen them before. This has also led to the popular legend ESDI and FreeBSD is a plain NO-GO. The following sections try to list all the pitfalls and solutions. ESDI speed variants As briefly mentioned before, ESDI comes in two speed flavors. The older drives and controllers use a 10 Mbits/second data transfer rate. Newer stuff uses 15 Mbits/second. It is not hard to imagine that 15 Mbits/second drive cause problems on controllers laid out for 10 Mbits/second. As always, consult your controller and drive documentation to see if things match. Stay on track Mainstream ESDI drives use 34 to 36 sectors per track. Most (older) controllers cannot handle more than this number of sectors. Newer, higher capacity, drives use higher numbers of sectors per track. For instance, I own a 670 MB drive that has 54 sectors per track. In my case, the controller could not handle this number of sectors. It proved to work well except that it only used 35 sectors on each track. This meant losing a lot of disk space. Once again, check the documentation of your hardware for more info. Going out-of-spec like in the example might or might not work. Give it a try or get another more capable controller. Hard or soft sectoring Most ESDI drives allow hard or soft sectoring to be selected using a jumper. Hard sectoring means that the drive will produce a sector pulse on the start of each new sector. The controller uses this pulse to tell when it should start to write or read. Hard sectoring allows a selection of sector size (normally 256, 512 or 1024 bytes per formatted sector). FreeBSD uses 512 byte sectors. The number of sectors per track also varies while still using the same number of bytes per formatted sector. The number of unformatted bytes per sector varies, dependent on your controller it needs more or less overhead bytes to work correctly. Pushing more sectors on a track of course gives you more usable space, but might give problems if your controller needs more bytes than the drive offers. In case of soft sectoring, the controller itself determines where to start/stop reading or writing. For ESDI hard sectoring is the default (at least on everything I came across). I never felt the urge to try soft sectoring. In general, experiment with sector settings before you install FreeBSD because you need to re-run the low-level format after each change. Low level formatting ESDI drives need to be low level formatted before they are usable. A reformat is needed whenever you figgle with the number of sectors/track jumpers or the physical orientation of the drive (horizontal, vertical). So, first think, then format. The format time must not be underestimated, for big disks it can take hours. After a low level format, a surface scan is done to find and flag bad sectors. Most disks have a manufacturer bad block list listed on a piece of paper or adhesive sticker. In addition, on most disks the list is also written onto the disk. Please use the manufacturer's list. It is much easier to remap a defect now than after FreeBSD is installed. Stay away from low-level formatters that mark all sectors of a track as bad as soon as they find one bad sector. Not only does this waste space, it also and more importantly causes you grief with bad144 (see the section on bad144). Translations Translations, although not exclusively a ESDI-only problem, might give you real trouble. Translations come in multiple flavors. Most of them have in common that they attempt to work around the limitations posed upon disk geometries by the original IBM PC/AT design (thanks IBM!). First of all there is the (in)famous 1024 cylinder limit. For a system to be able to boot, the stuff (whatever operating system) must be in the first 1024 cylinders of a disk. Only 10 bits are available to encode the cylinder number. For the number of sectors the limit is 64 (0-63). When you combine the 1024 cylinder limit with the 16 head limit (also a design feature) you max out at fairly limited disk sizes. To work around this problem, the manufacturers of ESDI PC controllers added a BIOS prom extension on their boards. This BIOS extension handles disk I/O for booting (and for some operating systems all disk I/O) by using translation. For instance, a big drive might be presented to the system as having 32 heads and 64 sectors/track. The result is that the number of cylinders is reduced to something below 1024 and is therefore usable by the system without problems. It is noteworthy to know that FreeBSD does not use the BIOS after its kernel has started. More on this later. A second reason for translations is the fact that most older system BIOSes could only handle drives with 17 sectors per track (the old ST412 standard). Newer system BIOSes usually have a user-defined drive type (in most cases this is drive type 47). Whatever you do to translations after reading this document, keep in mind that if you have multiple operating systems on the same disk, all must use the same translation While on the subject of translations, I have seen one controller type (but there are probably more like this) offer the option to logically split a drive in multiple partitions as a BIOS option. I had select 1 drive == 1 partition because this controller wrote this info onto the disk. On power-up it read the info and presented itself to the system based on the info from the disk. Spare sectoring Most ESDI controllers offer the possibility to remap bad sectors. During/after the low-level format of the disk bad sectors are marked as such, and a replacement sector is put in place (logically of course) of the bad one. In most cases the remapping is done by using N-1 sectors on each track for actual data storage, and sector N itself is the spare sector. N is the total number of sectors physically available on the track. The idea behind this is that the operating system sees a 'perfect' disk without bad sectors. In the case of FreeBSD this concept is not usable. The problem is that the translation from bad to good is performed by the BIOS of the ESDI controller. FreeBSD, being a true 32 bit operating system, does not use the BIOS after it has been booted. Instead, it has device drivers that talk directly to the hardware. So: don't use spare sectoring, bad block remapping or whatever it may be called by the controller manufacturer when you want to use the disk for FreeBSD. Bad block handling The preceding section leaves us with a problem. The controller's bad block handling is not usable and still FreeBSD's filesystems assume perfect media without any flaws. To solve this problem, FreeBSD use the bad144 tool. Bad144 (named after a Digital Equipment standard for bad block handling) scans a FreeBSD slice for bad blocks. Having found these bad blocks, it writes a table with the offending block numbers to the end of the FreeBSD slice. When the disk is in operation, the disk accesses are checked against the table read from the disk. Whenever a block number is requested that is in the bad144 list, a replacement block (also from the end of the FreeBSD slice) is used. In this way, the bad144 replacement scheme presents 'perfect' media to the FreeBSD filesystems. There are a number of potential pitfalls associated with the use of bad144. First of all, the slice cannot have more than 126 bad sectors. If your drive has a high number of bad sectors, you might need to divide it into multiple FreeBSD slices each containing less than 126 bad sectors. Stay away from low-level format programs that mark every sector of a track as bad when they find a flaw on the track. As you can imagine, the 126 limit is quickly reached when the low-level format is done this way. Second, if the slice contains the root filesystem, the slice should be within the 1024 cylinder BIOS limit. During the boot process the bad144 list is read using the BIOS and this only succeeds when the list is within the 1024 cylinder limit. The restriction is not that only the root filesystem must be within the 1024 cylinder limit, but rather the entire slice that contains the root filesystem. Kernel configuration ESDI disks are handled by the same wddriver as IDE and ST412 MFM disks. The wd driver should work for all WD1003 compatible interfaces. Most hardware is jumperable for one of two different I/O address ranges and IRQ lines. This allows you to have two wd type controllers in one system. When your hardware allows non-standard strappings, you can use these with FreeBSD as long as you enter the correct info into the kernel config file. An example from the kernel config file (they live in /sys/i386/conf BTW). # First WD compatible controller controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr disk wd0 at wdc0 drive 0 disk wd1 at wdc0 drive 1 # Second WD compatible controller controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr disk wd2 at wdc1 drive 0 disk wd3 at wdc1 drive 1 Particulars on ESDI hardware Adaptec 2320 controllers I successfully installed FreeBSD onto a ESDI disk controlled by a ACB-2320. No other operating system was present on the disk. To do so I low level formatted the disk using NEFMT.EXE (ftpable from www.adaptec.com) and answered NO to the question whether the disk should be formatted with a spare sector on each track. The BIOS on the ACD-2320 was disabled. I used the free configurable option in the system BIOS to allow the BIOS to boot it. Before using NEFMT.EXE I tried to format the disk using the ACB-2320 BIOS built-in formatter. This proved to be a show stopper, because it did not give me an option to disable spare sectoring. With spare sectoring enabled the FreeBSD installation process broke down on the bad144 run. Please check carefully which ACB-232xy variant you have. The x is either 0 or 2, indicating a controller without or with a floppy controller on board. The y is more interesting. It can either be a blank, a A-8 or a D. A blank indicates a plain 10 Mbits/second controller. An A-8 indicates a 15 Mbits/second controller capable of handling 52 sectors/track. A D means a 15 Mbits/second controller that can also handle drives with > 36 sectors/track (also 52 ?). All variations should be capable of using 1:1 interleaving. Use 1:1, FreeBSD is fast enough to handle it. Western Digital WD1007 controllers I successfully installed FreeBSD onto a ESDI disk controlled by a WD1007 controller. To be precise, it was a WD1007-WA2. Other variations of the WD1007 do exist. To get it to work, I had to disable the sector translation and the WD1007's onboard BIOS. This implied I could not use the low-level formatter built into this BIOS. Instead, I grabbed WDFMT.EXE from www.wdc.com Running this formatted my drive just fine. Ultrastor U14F controllers According to multiple reports from the net, Ultrastor ESDI boards work OK with FreeBSD. I lack any further info on particular settings. Further reading If you intend to do some serious ESDI hacking, you might want to have the official standard at hand: The latest ANSI X3T10 committee document is: Enhanced Small Device Interface (ESDI) [X3.170-1990/X3.170a-1991] [X3T10/792D Rev 11] On Usenet the newsgroup comp.periphs is a noteworthy place to look for more info. The World Wide Web (WWW) also proves to be a very handy info source: For info on Adaptec ESDI controllers see http://www.adaptec.com/. For info on Western Digital controllers see http://www.wdc.com/. Thanks to... Andrew Gordon for sending me an Adaptec 2320 controller and ESDI disk for testing. What is SCSI? Copyright © 1995, &a.wilko;. July 6, 1996. SCSI is an acronym for Small Computer Systems Interface. It is an ANSI standard that has become one of the leading I/O buses in the computer industry. The foundation of the SCSI standard was laid by Shugart Associates (the same guys that gave the world the first mini floppy disks) when they introduced the SASI bus (Shugart Associates Standard Interface). After some time an industry effort was started to come to a more strict standard allowing devices from different vendors to work together. This effort was recognized in the ANSI SCSI-1 standard. The SCSI-1 standard (approximately 1985) is rapidly becoming obsolete. The current standard is SCSI-2 (see Further reading), with SCSI-3 on the drawing boards. In addition to a physical interconnection standard, SCSI defines a logical (command set) standard to which disk devices must adhere. This standard is called the Common Command Set (CCS) and was developed more or less in parallel with ANSI SCSI-1. SCSI-2 includes the (revised) CCS as part of the standard itself. The commands are dependent on the type of device at hand. It does not make much sense of course to define a Write command for a scanner. The SCSI bus is a parallel bus, which comes in a number of variants. The oldest and most used is an 8 bit wide bus, with single-ended signals, carried on 50 wires. (If you do not know what single-ended means, do not worry, that is what this document is all about.) Modern designs also use 16 bit wide buses, with differential signals. This allows transfer speeds of 20Mbytes/second, on cables lengths of up to 25 meters. SCSI-2 allows a maximum bus width of 32 bits, using an additional cable. Quickly emerging are Ultra SCSI (also called Fast-20) and Ultra2 (also called Fast-40). Fast-20 is 20 million transfers per second (20 Mbytes/sec on a 8 bit bus), Fast-40 is 40 million transfers per second (40 Mbytes/sec on a 8 bit bus). Most hard drives sold today are single-ended Ultra SCSI (8 or 16 bits). Of course the SCSI bus not only has data lines, but also a number of control signals. A very elaborate protocol is part of the standard to allow multiple devices to share the bus in an efficient manner. In SCSI-2, the data is always checked using a separate parity line. In pre-SCSI-2 designs parity was optional. In SCSI-3 even faster bus types are introduced, along with a serial SCSI busses that reduces the cabling overhead and allows a higher maximum bus length. You might see names like SSA and fibre channel in this context. None of the serial buses are currently in widespread use (especially not in the typical FreeBSD environment). For this reason the serial bus types are not discussed any further. As you could have guessed from the description above, SCSI devices are intelligent. They have to be to adhere to the SCSI standard (which is over 2 inches thick BTW). So, for a hard disk drive for instance you do not specify a head/cylinder/sector to address a particular block, but simply the number of the block you want. Elaborate caching schemes, automatic bad block replacement etc are all made possible by this 'intelligent device' approach. On a SCSI bus, each possible pair of devices can communicate. Whether their function allows this is another matter, but the standard does not restrict it. To avoid signal contention, the 2 devices have to arbitrate for the bus before using it. The philosophy of SCSI is to have a standard that allows older-standard devices to work with newer-standard ones. So, an old SCSI-1 device should normally work on a SCSI-2 bus. I say Normally, because it is not absolutely sure that the implementation of an old device follows the (old) standard closely enough to be acceptable on a new bus. Modern devices are usually more well-behaved, because the standardization has become more strict and is better adhered to by the device manufacturers. Generally speaking, the chances of getting a working set of devices on a single bus is better when all the devices are SCSI-2 or newer. This implies that you do not have to dump all your old stuff when you get that shiny 2GB disk: I own a system on which a pre-SCSI-1 disk, a SCSI-2 QIC tape unit, a SCSI-1 helical scan tape unit and 2 SCSI-1 disks work together quite happily. From a performance standpoint you might want to separate your older and newer (=faster) devices however. Components of SCSI As said before, SCSI devices are smart. The idea is to put the knowledge about intimate hardware details onto the SCSI device itself. In this way, the host system does not have to worry about things like how many heads a hard disks has, or how many tracks there are on a specific tape device. If you are curious, the standard specifies commands with which you can query your devices on their hardware particulars. FreeBSD uses this capability during boot to check out what devices are connected and whether they need any special treatment. The advantage of intelligent devices is obvious: the device drivers on the host can be made in a much more generic fashion, there is no longer a need to change (and qualify!) drivers for every odd new device that is introduced. For cabling and connectors there is a golden rule: get good stuff. With bus speeds going up all the time you will save yourself a lot of grief by using good material. So, gold plated connectors, shielded cabling, sturdy connector hoods with strain reliefs etc are the way to go. Second golden rule: do no use cables longer than necessary. I once spent 3 days hunting down a problem with a flaky machine only to discover that shortening the SCSI bus by 1 meter solved the problem. And the original bus length was well within the SCSI specification. SCSI bus types From an electrical point of view, there are two incompatible bus types: single-ended and differential. This means that there are two different main groups of SCSI devices and controllers, which cannot be mixed on the same bus. It is possible however to use special converter hardware to transform a single-ended bus into a differential one (and vice versa). The differences between the bus types are explained in the next sections. In lots of SCSI related documentation there is a sort of jargon in use to abbreviate the different bus types. A small list: FWD: Fast Wide Differential FND: Fast Narrow Differential SE: Single Ended FN: Fast Narrow etc. With a minor amount of imagination one can usually imagine what is meant. Wide is a bit ambiguous, it can indicate 16 or 32 bit buses. As far as I know, the 32 bit variant is not (yet) in use, so wide normally means 16 bit. Fast means that the timing on the bus is somewhat different, so that on a narrow (8 bit) bus 10 Mbytes/sec are possible instead of 5 Mbytes/sec for 'slow' SCSI. As discussed before, bus speeds of 20 and 40 million transfers/second are also emerging (Fast-20 == Ultra SCSI and Fast-40 == Ultra2 SCSI). The data lines > 8 are only used for data transfers and device addressing. The transfers of commands and status messages etc are only performed on the lowest 8 data lines. The standard allows narrow devices to operate on a wide bus. The usable bus width is negotiated between the devices. You have to watch your device addressing closely when mixing wide and narrow. Single ended buses A single-ended SCSI bus uses signals that are either 5 Volts or 0 Volts (indeed, TTL levels) and are relative to a COMMON ground reference. A singled ended 8 bit SCSI bus has approximately 25 ground lines, who are all tied to a single `rail' on all devices. A standard single ended bus has a maximum length of 6 meters. If the same bus is used with fast-SCSI devices, the maximum length allowed drops to 3 meters. Fast-SCSI means that instead of 5Mbytes/sec the bus allows 10Mbytes/sec transfers. Fast-20 (Ultra SCSI) and Fast-40 allow for 20 and 40 million transfers/second respectively. So, F20 is 20 Mbytes/second on a 8 bit bus, 40 Mbytes/second on a 16 bit bus etc. For F20 the max bus length is 1.5 meters, for F40 it becomes 0.75 meters. Be aware that F20 is pushing the limits quite a bit, so you will quickly find out if your SCSI bus is electrically sound. If some devices on your bus use 'fast' to communicate your bus must adhere to the length restrictions for fast buses! It is obvious that with the newer fast-SCSI devices the bus length can become a real bottleneck. This is why the differential SCSI bus was introduced in the SCSI-2 standard. For connector pinning and connector types please refer to the SCSI-2 standard (see Further reading) itself, connectors etc are listed there in painstaking detail. Beware of devices using non-standard cabling. For instance Apple uses a 25pin D-type connecter (like the one on serial ports and parallel printers). Considering that the official SCSI bus needs 50 pins you can imagine the use of this connector needs some 'creative cabling'. The reduction of the number of ground wires they used is a bad idea, you better stick to 50 pins cabling in accordance with the SCSI standard. For Fast-20 and 40 do not even think about buses like this. Differential buses A differential SCSI bus has a maximum length of 25 meters. Quite a difference from the 3 meters for a single-ended fast-SCSI bus. The idea behind differential signals is that each bus signal has its own return wire. So, each signal is carried on a (preferably twisted) pair of wires. The voltage difference between these two wires determines whether the signal is asserted or de-asserted. To a certain extent the voltage difference between ground and the signal wire pair is not relevant (do not try 10 kVolts though). It is beyond the scope of this document to explain why this differential idea is so much better. Just accept that electrically seen the use of differential signals gives a much better noise margin. You will normally find differential buses in use for inter-cabinet connections. Because of the lower cost single ended is mostly used for shorter buses like inside cabinets. There is nothing that stops you from using differential stuff with FreeBSD, as long as you use a controller that has device driver support in FreeBSD. As an example, Adaptec marketed the AHA1740 as a single ended board, whereas the AHA1744 was differential. The software interface to the host is identical for both. Terminators Terminators in SCSI terminology are resistor networks that are used to get a correct impedance matching. Impedance matching is important to get clean signals on the bus, without reflections or ringing. If you once made a long distance telephone call on a bad line you probably know what reflections are. With 20Mbytes/sec traveling over your SCSI bus, you do not want signals echoing back. Terminators come in various incarnations, with more or less sophisticated designs. Of course, there are internal and external variants. Many SCSI devices come with a number of sockets in which a number of resistor networks can (must be!) installed. If you remove terminators from a device, carefully store them. You will need them when you ever decide to reconfigure your SCSI bus. There is enough variation in even these simple tiny things to make finding the exact replacement a frustrating business. There are also SCSI devices that have a single jumper to enable or disable a built-in terminator. There are special terminators you can stick onto a flat cable bus. Others look like external connectors, or a connector hood without a cable. So, lots of choice as you can see. There is much debate going on if and when you should switch from simple resistor (passive) terminators to active terminators. Active terminators contain slightly more elaborate circuit to give cleaner bus signals. The general consensus seems to be that the usefulness of active termination increases when you have long buses and/or fast devices. If you ever have problems with your SCSI buses you might consider trying an active terminator. Try to borrow one first, they reputedly are quite expensive. Please keep in mind that terminators for differential and single-ended buses are not identical. You should not mix the two variants. OK, and now where should you install your terminators? This is by far the most misunderstood part of SCSI. And it is by far the simplest. The rule is: every single line on the SCSI bus has 2 (two) terminators, one at each end of the bus. So, two and not one or three or whatever. Do yourself a favor and stick to this rule. It will save you endless grief, because wrong termination has the potential to introduce highly mysterious bugs. (Note the potential here; the nastiest part is that it may or may not work.) A common pitfall is to have an internal (flat) cable in a machine and also an external cable attached to the controller. It seems almost everybody forgets to remove the terminators from the controller. The terminator must now be on the last external device, and not on the controller! In general, every reconfiguration of a SCSI bus must pay attention to this. Termination is to be done on a per-line basis. This means if you have both narrow and wide buses connected to the same host adapter, you need to enable termination on the higher 8 bits of the bus on the adapter (as well as the last devices on each bus, of course). What I did myself is remove all terminators from my SCSI devices and controllers. I own a couple of external terminators, for both the Centronics-type external cabling and for the internal flat cable connectors. This makes reconfiguration much easier. On modern devices, sometimes integrated terminators are used. These things are special purpose integrated circuits that can be enabled or disabled with a control pin. It is not necessary to physically remove them from a device. You may find them on newer host adapters, sometimes they are software configurable, using some sort of setup tool. Some will even auto-detect the cables attached to the connectors and automatically set up the termination as necessary. At any rate, consult your documentation! Terminator power The terminators discussed in the previous chapter need power to operate properly. On the SCSI bus, a line is dedicated to this purpose. So, simple huh? Not so. Each device can provide its own terminator power to the terminator sockets it has on-device. But if you have external terminators, or when the device supplying the terminator power to the SCSI bus line is switched off you are in trouble. The idea is that initiators (these are devices that initiate actions on the bus, a discussion follows) must supply terminator power. All SCSI devices are allowed (but not required) to supply terminator power. To allow for un-powered devices on a bus, the terminator power must be supplied to the bus via a diode. This prevents the backflow of current to un-powered devices. To prevent all kinds of nastiness, the terminator power is usually fused. As you can imagine, fuses might blow. This can, but does not have to, lead to a non functional bus. If multiple devices supply terminator power, a single blown fuse will not put you out of business. A single supplier with a blown fuse certainly will. Clever external terminators sometimes have a LED indication that shows whether terminator power is present. In newer designs auto-restoring fuses that 'reset' themselves after some time are sometimes used. Device addressing Because the SCSI bus is, ehh, a bus there must be a way to distinguish or address the different devices connected to it. This is done by means of the SCSI or target ID. Each device has a unique target ID. You can select the ID to which a device must respond using a set of jumpers, or a dip switch, or something similar. Some SCSI host adapters let you change the target ID from the boot menu. (Yet some others will not let you change the ID from 7.) Consult the documentation of your device for more information. Beware of multiple devices configured to use the same ID. Chaos normally reigns in this case. A pitfall is that one of the devices sharing the same ID sometimes even manages to answer to I/O requests! For an 8 bit bus, a maximum of 8 targets is possible. The maximum is 8 because the selection is done bitwise using the 8 data lines on the bus. For wide buses this increases to the number of data lines (usually 16). A narrow SCSI device cannot communicate with a SCSI device with a target ID larger than 7. This means it is generally not a good idea to move your SCSI host adapter's target ID to something higher than 7 (or your CDROM will stop working). The higher the SCSI target ID, the higher the priority the devices has. When it comes to arbitration between devices that want to use the bus at the same time, the device that has the highest SCSI ID will win. This also means that the SCSI host adapter usually uses target ID 7. Note however that the lower 8 IDs have higher priorities than the higher 8 IDs on a wide-SCSI bus. Thus, the order of target IDs is: [7 6 .. 1 0 15 14 .. 9 8] on a wide-SCSI system. (If you are wondering why the lower 8 have higher priority, read the previous paragraph for a hint.) For a further subdivision, the standard allows for Logical Units or LUNs for short. A single target ID may have multiple LUNs. For example, a tape device including a tape changer may have LUN 0 for the tape device itself, and LUN 1 for the tape changer. In this way, the host system can address each of the functional units of the tape changer as desired. Bus layout SCSI buses are linear. So, not shaped like Y-junctions, star topologies, rings, cobwebs or whatever else people might want to invent. One of the most common mistakes is for people with wide-SCSI host adapters to connect devices on all three connecters (external connector, internal wide connector, internal narrow connector). Don't do that. It may appear to work if you are really lucky, but I can almost guarantee that your system will stop functioning at the most unfortunate moment (this is also known as Murphy's law). You might notice that the terminator issue discussed earlier becomes rather hairy if your bus is not linear. Also, if you have more connectors than devices on your internal SCSI cable, make sure you attach devices on connectors on both ends instead of using the connectors in the middle and let one or both ends dangle. This will screw up the termination of the bus. The electrical characteristics, its noise margins and ultimately the reliability of it all are tightly related to linear bus rule. Stick to the linear bus rule! Using SCSI with FreeBSD About translations, BIOSes and magic... As stated before, you should first make sure that you have a electrically sound bus. When you want to use a SCSI disk on your PC as boot disk, you must aware of some quirks related to PC BIOSes. The PC BIOS in its first incarnation used a low level physical interface to the hard disk. So, you had to tell the BIOS (using a setup tool or a BIOS built-in setup) how your disk physically looked like. This involved stating number of heads, number of cylinders, number of sectors per track, obscure things like precompensation and reduced write current cylinder etc. One might be inclined to think that since SCSI disks are smart you can forget about this. Alas, the arcane setup issue is still present today. The system BIOS needs to know how to access your SCSI disk with the head/cyl/sector method in order to load the FreeBSD kernel during boot. The SCSI host adapter or SCSI controller you have put in your AT/EISA/PCI/whatever bus to connect your disk therefore has its own on-board BIOS. During system startup, the SCSI BIOS takes over the hard disk interface routines from the system BIOS. To fool the system BIOS, the system setup is normally set to No hard disk present. Obvious, isn't it? The SCSI BIOS itself presents to the system a so called translated drive. This means that a fake drive table is constructed that allows the PC to boot the drive. This translation is often (but not always) done using a pseudo drive with 64 heads and 32 sectors per track. By varying the number of cylinders, the SCSI BIOS adapts to the actual drive size. It is useful to note that 32 * 64 / 2 = the size of your drive in megabytes. The division by 2 is to get from disk blocks that are normally 512 bytes in size to Kbytes. Right. All is well now?! No, it is not. The system BIOS has another quirk you might run into. The number of cylinders of a bootable hard disk cannot be greater than 1024. Using the translation above, this is a show-stopper for disks greater than 1 GB. With disk capacities going up all the time this is causing problems. Fortunately, the solution is simple: just use another translation, e.g. with 128 heads instead of 32. In most cases new SCSI BIOS versions are available to upgrade older SCSI host adapters. Some newer adapters have an option, in the form of a jumper or software setup selection, to switch the translation the SCSI BIOS uses. It is very important that all operating systems on the disk use the same translation to get the right idea about where to find the relevant partitions. So, when installing FreeBSD you must answer any questions about heads/cylinders etc using the translated values your host adapter uses. Failing to observe the translation issue might lead to un-bootable systems or operating systems overwriting each others partitions. Using fdisk you should be able to see all partitions. You might have heard some talk of lying devices? Older FreeBSD kernels used to report the geometry of SCSI disks when booting. An example from one of my systems: aha0 targ 0 lun 0: <MICROP 1588-15MB1057404HSP4> sd0: 636MB (1303250 total sec), 1632 cyl, 15 head, 53 sec, bytes/sec 512 Newer kernels usually do not report this information. e.g. (bt0:0:0): "SEAGATE ST41651 7574" type 0 fixed SCSI 2 sd0(bt0:0:0): Direct-Access 1350MB (2766300 512 byte sectors) Why has this changed? This info is retrieved from the SCSI disk itself. Newer disks often use a technique called zone bit recording. The idea is that on the outer cylinders of the drive there is more space so more sectors per track can be put on them. This results in disks that have more tracks on outer cylinders than on the inner cylinders and, last but not least, have more capacity. You can imagine that the value reported by the drive when inquiring about the geometry now becomes suspect at best, and nearly always misleading. When asked for a geometry , it is nearly always better to supply the geometry used by the BIOS, or if the BIOS is never going to know about this disk, (e.g. it is not a booting disk) to supply a fictitious geometry that is convenient. SCSI subsystem design FreeBSD uses a layered SCSI subsystem. For each different controller card a device driver is written. This driver knows all the intimate details about the hardware it controls. The driver has a interface to the upper layers of the SCSI subsystem through which it receives its commands and reports back any status. On top of the card drivers there are a number of more generic drivers for a class of devices. More specific: a driver for tape devices (abbreviation: st), magnetic disks (sd), CDROMs (cd) etc. In case you are wondering where you can find this stuff, it all lives in /sys/scsi. See the man pages in section 4 for more details. The multi level design allows a decoupling of low-level bit banging and more high level stuff. Adding support for another piece of hardware is a much more manageable problem. Kernel configuration Dependent on your hardware, the kernel configuration file must contain one or more lines describing your host adapter(s). This includes I/O addresses, interrupts etc. Consult the man page for your adapter driver to get more info. Apart from that, check out /sys/i386/conf/LINT for an overview of a kernel config file. LINT contains every possible option you can dream of. It does not imply LINT will actually get you to a working kernel at all. Although it is probably stating the obvious: the kernel config file should reflect your actual hardware setup. So, interrupts, I/O addresses etc must match the kernel config file. During system boot messages will be displayed to indicate whether the configured hardware was actually found. Note that most of the EISA/PCI drivers (namely ahb, ahc, ncr and amd will automatically obtain the correct parameters from the host adapters themselves at boot time; thus, you just need to write, for instance, controller ahc0. An example loosely based on the FreeBSD 2.2.5-Release kernel config file LINT with some added comments (between []): # SCSI host adapters: `aha', `ahb', `aic', `bt', `nca' # # aha: Adaptec 154x # ahb: Adaptec 174x # ahc: Adaptec 274x/284x/294x # aic: Adaptec 152x and sound cards using the Adaptec AIC-6360 (slow!) # amd: AMD 53c974 based SCSI cards (e.g., Tekram DC-390 and 390T) # bt: Most Buslogic controllers # nca: ProAudioSpectrum cards using the NCR 5380 or Trantor T130 # ncr: NCR/Symbios 53c810/815/825/875 etc based SCSI cards # uha: UltraStore 14F and 34F # sea: Seagate ST01/02 8 bit controller (slow!) # wds: Western Digital WD7000 controller (no scatter/gather!). # [For an Adaptec AHA274x/284x/294x/394x etc controller] controller ahc0 [For an NCR/Symbios 53c875 based controller] controller ncr0 [For an Ultrastor adapter] controller uha0 at isa? port "IO_UHA0" bio irq ? drq 5 vector uhaintr # Map SCSI buses to specific SCSI adapters controller scbus0 at ahc0 controller scbus2 at ncr0 controller scbus1 at uha0 # The actual SCSI devices disk sd0 at scbus0 target 0 unit 0 [SCSI disk 0 is at scbus 0, LUN 0] disk sd1 at scbus0 target 1 [implicit LUN 0 if omitted] disk sd2 at scbus1 target 3 [SCSI disk on the uha0] disk sd3 at scbus2 target 4 [SCSI disk on the ncr0] tape st1 at scbus0 target 6 [SCSI tape at target 6] device cd0 at scbus? [the first ever CDROM found, no wiring] The example above tells the kernel to look for a ahc (Adaptec 274x) controller, then for an NCR/Symbios board, and so on. The lines following the controller specifications tell the kernel to configure specific devices but only attach them when they match the target ID and LUN specified on the corresponding bus. Wired down devices get first shot at the unit numbers so the first non wired down device, is allocated the unit number one greater than the highest wired down unit number for that kind of device. So, if you had a SCSI tape at target ID 2 it would be configured as st2, as the tape at target ID 6 is wired down to unit number 1. Wired down devices need not be found to get their unit number. The unit number for a wired down device is reserved for that device, even if it is turned off at boot time. This allows the device to be turned on and brought on-line at a later time, without rebooting. Notice that a device's unit number has no relationship with its target ID on the SCSI bus. Below is another example of a kernel config file as used by FreeBSD version < 2.0.5. The difference with the first example is that devices are not wired down. Wired down means that you specify which SCSI target belongs to which device. A kernel built to the config file below will attach the first SCSI disk it finds to sd0, the second disk to sd1 etc. If you ever removed or added a disk, all other devices of the same type (disk in this case) would 'move around'. This implies you have to change /etc/fstab each time. Although the old style still works, you are strongly recommended to use this new feature. It will save you a lot of grief whenever you shift your hardware around on the SCSI buses. So, when you re-use your old trusty config file after upgrading from a pre-FreeBSD2.0.5.R system check this out. [driver for Adaptec 174x] controller ahb0 at isa? bio irq 11 vector ahbintr [for Adaptec 154x] controller aha0 at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr [for Seagate ST01/02] controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr controller scbus0 device sd0 [support for 4 SCSI harddisks, sd0 up sd3] device st0 [support for 2 SCSI tapes] [for the CDROM] device cd0 #Only need one of these, the code dynamically grows Both examples support SCSI disks. If during boot more devices of a specific type (e.g. sd disks) are found than are configured in the booting kernel, the system will simply allocate more devices, incrementing the unit number starting at the last number wired down. If there are no wired down devices then counting starts at unit 0. Use man 4 scsi to check for the latest info on the SCSI subsystem. For more detailed info on host adapter drivers use e.g., man 4 ahc for info on the Adaptec 294x driver. Tuning your SCSI kernel setup Experience has shown that some devices are slow to respond to INQUIRY commands after a SCSI bus reset (which happens at boot time). An INQUIRY command is sent by the kernel on boot to see what kind of device (disk, tape, CDROM etc.) is connected to a specific target ID. This process is called device probing by the way. To work around the 'slow response' problem, FreeBSD allows a tunable delay time before the SCSI devices are probed following a SCSI bus reset. You can set this delay time in your kernel configuration file using a line like: options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device This line sets the delay time to 15 seconds. On my own system I had to use 3 seconds minimum to get my trusty old CDROM drive to be recognized. Start with a high value (say 30 seconds or so) when you have problems with device recognition. If this helps, tune it back until it just stays working. Rogue SCSI devices Although the SCSI standard tries to be complete and concise, it is a complex standard and implementing things correctly is no easy task. Some vendors do a better job then others. This is exactly where the rogue devices come into view. Rogues are devices that are recognized by the FreeBSD kernel as behaving slightly (...) non-standard. Rogue devices are reported by the kernel when booting. An example for two of my cartridge tape units: Feb 25 21:03:34 yedi /kernel: ahb0 targ 5 lun 0: <TANDBERG TDC 3600 -06:> Feb 25 21:03:34 yedi /kernel: st0: Tandberg tdc3600 is a known rogue Mar 29 21:16:37 yedi /kernel: aha0 targ 5 lun 0: <ARCHIVE VIPER 150 21247-005> Mar 29 21:16:37 yedi /kernel: st1: Archive Viper 150 is a known rogue For instance, there are devices that respond to all LUNs on a certain target ID, even if they are actually only one device. It is easy to see that the kernel might be fooled into believing that there are 8 LUNs at that particular target ID. The confusion this causes is left as an exercise to the reader. The SCSI subsystem of FreeBSD recognizes devices with bad habits by looking at the INQUIRY response they send when probed. Because the INQUIRY response also includes the version number of the device firmware, it is even possible that for different firmware versions different workarounds are used. See e.g. /sys/scsi/st.c and /sys/scsi/scsiconf.c for more info on how this is done. This scheme works fine, but keep in mind that it of course only works for devices that are known to be weird. If you are the first to connect your bogus Mumbletech SCSI CDROM you might be the one that has to define which workaround is needed. After you got your Mumbletech working, please send the required workaround to the FreeBSD development team for inclusion in the next release of FreeBSD. Other Mumbletech owners will be grateful to you. Multiple LUN devices In some cases you come across devices that use multiple logical units (LUNs) on a single SCSI ID. In most cases FreeBSD only probes devices for LUN 0. An example are so called bridge boards that connect 2 non-SCSI harddisks to a SCSI bus (e.g. an Emulex MD21 found in old Sun systems). This means that any devices with LUNs != 0 are not normally found during device probe on system boot. To work around this problem you must add an appropriate entry in /sys/scsi/scsiconf.c and rebuild your kernel. Look for a struct that is initialized like below: { T_DIRECT, T_FIXED, "MAXTOR", "XT-4170S", "B5A", "mx1", SC_ONE_LU } For you Mumbletech BRIDGE2000 that has more than one LUN, acts as a SCSI disk and has firmware revision 123 you would add something like: { T_DIRECT, T_FIXED, "MUMBLETECH", "BRIDGE2000", "123", "sd", SC_MORE_LUS } The kernel on boot scans the inquiry data it receives against the table and acts accordingly. See the source for more info. Tagged command queuing Modern SCSI devices, particularly magnetic disks, support what is called tagged command queuing (TCQ). In a nutshell, TCQ allows the device to have multiple I/O requests outstanding at the same time. Because the device is intelligent, it can optimize its operations (like head positioning) based on its own request queue. On SCSI devices like RAID (Redundant Array of Independent Disks) arrays the TCQ function is indispensable to take advantage of the device's inherent parallelism. Each I/O request is uniquely identified by a tag (hence the name tagged command queuing) and this tag is used by FreeBSD to see which I/O in the device drivers queue is reported as complete by the device. It should be noted however that TCQ requires device driver support and that some devices implemented it not quite right in their firmware. This problem bit me once, and it leads to highly mysterious problems. In such cases, try to disable TCQ. Busmaster host adapters Most, but not all, SCSI host adapters are bus mastering controllers. This means that they can do I/O on their own without putting load onto the host CPU for data movement. This is of course an advantage for a multitasking operating system like FreeBSD. It must be noted however that there might be some rough edges. For instance an Adaptec 1542 controller can be set to use different transfer speeds on the host bus (ISA or AT in this case). The controller is settable to different rates because not all motherboards can handle the higher speeds. Problems like hang-ups, bad data etc might be the result of using a higher data transfer rate then your motherboard can stomach. The solution is of course obvious: switch to a lower data transfer rate and try if that works better. In the case of a Adaptec 1542, there is an option that can be put into the kernel config file to allow dynamic determination of the right, read: fastest feasible, transfer rate. This option is disabled by default: options "TUNE_1542" #dynamic tune of bus DMA speed Check the man pages for the host adapter that you use. Or better still, use the ultimate documentation (read: driver source). Tracking down problems The following list is an attempt to give a guideline for the most common SCSI problems and their solutions. It is by no means complete. Check for loose connectors and cables. Check and double check the location and number of your terminators. Check if your bus has at least one supplier of terminator power (especially with external terminators. Check if no double target IDs are used. Check if all devices to be used are powered up. Make a minimal bus config with as little devices as possible. If possible, configure your host adapter to use slow bus speeds. Disable tagged command queuing to make things as simple as possible (for a NCR host adapter based system see man ncrcontrol) If you can compile a kernel, make one with the SCSIDEBUG option, and try accessing the device with debugging turned on for that device. If your device does not even probe at startup, you may have to define the address of the device that is failing, and the desired debug level in /sys/scsi/scsidebug.h. If it probes but just does not work, you can use the &man.scsi.8; command to dynamically set a debug level to it in a running kernel (if SCSIDEBUG is defined). This will give you copious debugging output with which to confuse the gurus. See man 4 scsi for more exact information. Also look at man 8 scsi. Further reading If you intend to do some serious SCSI hacking, you might want to have the official standard at hand: Approved American National Standards can be purchased from ANSI at
13th Floor 11 West 42nd Street New York NY 10036 Sales Dept: (212) 642-4900
You can also buy many ANSI standards and most committee draft documents from Global Engineering Documents,
15 Inverness Way East Englewood CO, 80112-5704 Phone: (800) 854-7179 Outside USA and Canada: (303) 792-2181 Fax: (303) 792- 2192
Many X3T10 draft documents are available electronically on the SCSI BBS (719-574-0424) and on the ncrinfo.ncr.com anonymous ftp site. + role="fqdn">ncrinfo.ncr.com anonymous FTP site. Latest X3T10 committee documents are: AT Attachment (ATA or IDE) [X3.221-1994] (Approved) ATA Extensions (ATA-2) [X3T10/948D Rev 2i] Enhanced Small Device Interface (ESDI) [X3.170-1990/X3.170a-1991] (Approved) Small Computer System Interface — 2 (SCSI-2) [X3.131-1994] (Approved) SCSI-2 Common Access Method Transport and SCSI Interface Module (CAM) [X3T10/792D Rev 11] Other publications that might provide you with additional information are: SCSI: Understanding the Small Computer System Interface, written by NCR Corporation. Available from: Prentice Hall, Englewood Cliffs, NJ, 07632 Phone: (201) 767-5937 ISBN 0-13-796855-8 Basics of SCSI, a SCSI tutorial written by Ancot Corporation Contact Ancot for availability information at: Phone: (415) 322-5322 Fax: (415) 322-0455 SCSI Interconnection Guide Book, an AMP publication (dated 4/93, Catalog 65237) that lists the various SCSI connectors and suggests cabling schemes. Available from AMP at (800) 522-6752 or (717) 564-0100 Fast Track to SCSI, A Product Guide written by Fujitsu. Available from: Prentice Hall, Englewood Cliffs, NJ, 07632 Phone: (201) 767-5937 ISBN 0-13-307000-X The SCSI Bench Reference, The SCSI Encyclopedia, and the SCSI Tutor, ENDL Publications, 14426 Black Walnut Court, Saratoga CA, 95070 Phone: (408) 867-6642 Zadian SCSI Navigator (quick ref. book) and Discover the Power of SCSI (First book along with a one-hour video and tutorial book), Zadian Software, Suite 214, 1210 S. Bascom Ave., San Jose, CA 92128, (408) 293-0800 On Usenet the newsgroups comp.periphs.scsi and comp.periphs are noteworthy places to look for more info. You can also find the SCSI-Faq there, which is posted periodically. - Most major SCSI device and host adapter suppliers operate ftp + Most major SCSI device and host adapter suppliers operate FTP sites and/or BBS systems. They may be valuable sources of information about the devices you own. * Disk/tape controllers * SCSI * IDE * Floppy Hard drives SCSI hard drives Contributed by &a.asami;. 17 February 1998. As mentioned in the SCSI section, virtually all SCSI hard drives sold today are SCSI-2 compliant and thus will work fine as long as you connect them to a supported SCSI host adapter. Most problems people encounter are either due to badly designed cabling (cable too long, star topology, etc.), insufficient termination, or defective parts. Please refer to the SCSI section first if your SCSI hard drive is not working. However, there are a couple of things you may want to take into account before you purchase SCSI hard drives for your system. Rotational speed Rotational speeds of SCSI drives sold today range from around 4,500RPM to 10,000RPM. Most of them are either 5,400RPM or 7,200RPM. Even though the 7,200RPM drives can generally transfer data faster, they run considerably hotter than their 5,400RPM counterparts. A large fraction of today's disk drive malfunctions are heat-related. If you do not have very good cooling in your PC case, you may want to stick with 5,400RPM or slower drives. Note that newer drives, with higher areal recording densities, can deliver much more bits per rotation than older ones. Today's top-of-line 5,400RPM drives can sustain a throughput comparable to 7,200RPM drives of one or two model generations ago. The number to find on the spec sheet for bandwidth is internal data (or transfer) rate. It is usually in megabits/sec so divide it by 8 and you'll get the rough approximation of how much megabytes/sec you can get out of the drive. (If you are a speed maniac and want a 10,000RPM drive for your cute little PC, be my guest; however, those drives become extremely hot. Don't even think about it if you don't have a fan blowing air directly at the drive or a properly ventilated disk enclosure.) Obviously, the latest 10,000RPM drives and 7,200RPM drives can deliver more data than the latest 5,400RPM drives, so if absolute bandwidth is the necessity for your applications, you have little choice but to get the faster drives. Also, if you need low latency, faster drives are better; not only do they usually have lower average seek times, but also the rotational delay is one place where slow-spinning drives can never beat a faster one. (The average rotational latency is half the time it takes to rotate the drive once; thus, it's 3 milliseconds for 10,000RPM drives, 4.2ms for 7,200RPM drives and 5.6ms for 5,400RPM drives.) Latency is seek time plus rotational delay. Make sure you understand whether you need low latency or more accesses per second, though; in the latter case (e.g., news servers), it may not be optimal to purchase one big fast drive. You can achieve similar or even better results by using the ccd (concatenated disk) driver to create a striped disk array out of multiple slower drives for comparable overall cost. Make sure you have adequate air flow around the drive, especially if you are going to use a fast-spinning drive. You generally need at least 1/2" (1.25cm) of spacing above and below a drive. Understand how the air flows through your PC case. Most cases have the power supply suck the air out of the back. See where the air flows in, and put the drive where it will have the largest volume of cool air flowing around it. You may need to seal some unwanted holes or add a new fan for effective cooling. Another consideration is noise. Many 7,200 or faster drives generate a high-pitched whine which is quite unpleasant to most people. That, plus the extra fans often required for cooling, may make 7,200 or faster drives unsuitable for some office and home environments. Form factor Most SCSI drives sold today are of 3.5" form factor. They come in two different heights; 1.6" (half-height) or 1" (low-profile). The half-height drive is the same height as a CDROM drive. However, don't forget the spacing rule mentioned in the previous section. If you have three standard 3.5" drive bays, you will not be able to put three half-height drives in there (without frying them, that is). Interface The majority of SCSI hard drives sold today are Ultra or Ultra-wide SCSI. The maximum bandwidth of Ultra SCSI is 20MB/sec, and Ultra-wide SCSI is 40MB/sec. There is no difference in max cable length between Ultra and Ultra-wide; however, the more devices you have on the same bus, the sooner you will start having bus integrity problems. Unless you have a well-designed disk enclosure, it is not easy to make more than 5 or 6 Ultra SCSI drives work on a single bus. On the other hand, if you need to connect many drives, going for Fast-wide SCSI may not be a bad idea. That will have the same max bandwidth as Ultra (narrow) SCSI, while electronically it's much easier to get it right. My advice would be: if you want to connect many disks, get wide SCSI drives; they usually cost a little more but it may save you down the road. (Besides, if you can't afford the cost difference, you shouldn't be building a disk array.) There are two variant of wide SCSI drives; 68-pin and 80-pin SCA (Single Connector Attach). The SCA drives don't have a separate 4-pin power connector, and also read the SCSI ID settings through the 80-pin connector. If you are really serious about building a large storage system, get SCA drives and a good SCA enclosure (dual power supply with at least one extra fan). They are more electronically sound than 68-pin counterparts because there is no stub of the SCSI bus inside the disk canister as in arrays built from 68-pin drives. They are easier to install too (you just need to screw the drive in the canister, instead of trying to squeeze in your fingers in a tight place to hook up all the little cables (like the SCSI ID and disk activity LED lines). * IDE hard drives Tape drives Contributed by &a.jmb;. 2 July 1996. General tape access commands &man.mt.1; provides generic access to the tape drives. Some of the more common commands are rewind, erase, and status. See the &man.mt.1; manual page for a detailed description. Controller Interfaces There are several different interfaces that support tape drives. The interfaces are SCSI, IDE, Floppy and Parallel Port. A wide variety of tape drives are available for these interfaces. Controllers are discussed in Disk/tape controllers. SCSI drives The &man.st.4; driver provides support for 8mm (Exabyte), 4mm (DAT: Digital Audio Tape), QIC (Quarter-Inch Cartridge), DLT (Digital Linear Tape), QIC Mini cartridge and 9-track (remember the big reels that you see spinning in Hollywood computer rooms) tape drives. See the &man.st.4; manual page for a detailed description. The drives listed below are currently being used by members of the FreeBSD community. They are not the only drives that will work with FreeBSD. They just happen to be the ones that we use. 4mm (DAT: Digital Audio Tape) Archive Python 28454 Archive Python 04687 HP C1533A HP C1534A HP 35450A HP 35470A HP 35480A SDT-5000 Wangtek 6200 8mm (Exabyte) EXB-8200 EXB-8500 EXB-8505 QIC (Quarter-Inch Cartridge) Archive Anaconda 2750 Archive Viper 60 Archive Viper 150 Archive Viper 2525 Tandberg TDC 3600 Tandberg TDC 3620 Tandberg TDC 3800 Tandberg TDC 4222 Wangtek 5525ES DLT (Digital Linear Tape) Digital TZ87 Mini-Cartridge Conner CTMS 3200 Exabyte 2501 Autoloaders/Changers Hewlett-Packard HP C1553A Autoloading DDS2 * IDE drives Floppy drives Conner 420R * Parallel port drives Detailed Information Archive Anaconda 2750 The boot message identifier for this drive is ARCHIVE ANCDA 2750 28077 -003 type 1 removable SCSI 2 This is a QIC tape drive. Native capacity is 1.35GB when using QIC-1350 tapes. This drive will read and write QIC-150 (DC6150), QIC-250 (DC6250), and QIC-525 (DC6525) tapes as well. Data transfer rate is 350kB/s using &man.dump.8;. Rates of 530kB/s have been reported when using Amanda Production of this drive has been discontinued. The SCSI bus connector on this tape drive is reversed from that on most other SCSI devices. Make sure that you have enough SCSI cable to twist the cable one-half turn before and after the Archive Anaconda tape drive, or turn your other SCSI devices upside-down. Two kernel code changes are required to use this drive. This drive will not work as delivered. If you have a SCSI-2 controller, short jumper 6. Otherwise, the drive behaves are a SCSI-1 device. When operating as a SCSI-1 device, this drive, locks the SCSI bus during some tape operations, including: fsf, rewind, and rewoffl. If you are using the NCR SCSI controllers, patch the file /usr/src/sys/pci/ncr.c (as shown below). Build and install a new kernel. *** 4831,4835 **** }; ! if (np->latetime>4) { /* ** Although we tried to wake it up, --- 4831,4836 ---- }; ! if (np->latetime>1200) { /* ** Although we tried to wake it up, Reported by: &a.jmb; Archive Python 28454 The boot message identifier for this drive is ARCHIVE Python 28454-XXX4ASB type 1 removable SCSI 2 density code 0x8c, 512-byte blocks This is a DDS-1 tape drive. Native capacity is 2.5GB on 90m tapes. Data transfer rate is XXX. This drive was repackaged by Sun Microsystems as model 595-3067. Reported by: Bob Bishop rb@gid.co.uk Throughput is in the 1.5 MByte/sec range, however this will drop if the disks and tape drive are on the same SCSI controller. Reported by: Robert E. Seastrom rs@seastrom.com Archive Python 04687 The boot message identifier for this drive is ARCHIVE Python 04687-XXX 6580 Removable Sequential Access SCSI-2 device This is a DAT-DDS-2 drive. Native capacity is 4GB when using 120m tapes. This drive supports hardware data compression. Switch 4 controls MRS (Media Recognition System). MRS tapes have stripes on the transparent leader. Switch 4 off enables MRS, on disables MRS. Parity is controlled by switch 5. Switch 5 on to enable parity control. Compression is enabled with Switch 6 off. It is possible to override compression with the SCSI MODE SELECT command (see &man.mt.1;). Data transfer rate is 800kB/s. Archive Viper 60 The boot message identifier for this drive is ARCHIVE VIPER 60 21116 -007 type 1 removable SCSI 1 This is a QIC tape drive. Native capacity is 60MB. Data transfer rate is XXX. Production of this drive has been discontinued. Reported by: Philippe Regnauld regnauld@hsc.fr Archive Viper 150 The boot message identifier for this drive is ARCHIVE VIPER 150 21531 -004 Archive Viper 150 is a known rogue type 1 removable SCSI 1. A multitude of firmware revisions exist for this drive. Your drive may report different numbers (e.g 21247 -005. This is a QIC tape drive. Native capacity is 150/250MB. Both 150MB (DC6150) and 250MB (DC6250) tapes have the recording format. The 250MB tapes are approximately 67% longer than the 150MB tapes. This drive can read 120MB tapes as well. It cannot write 120MB tapes. Data transfer rate is 100kB/s This drive reads and writes DC6150 (150MB) and DC6250 (250MB) tapes. This drives quirks are known and pre-compiled into the scsi tape device driver (&man.st.4;). Under FreeBSD 2.2-CURRENT, use mt blocksize 512 to set the blocksize. (The particular drive had firmware revision 21247 -005. Other firmware revisions may behave differently) Previous versions of FreeBSD did not have this problem. Production of this drive has been discontinued. Reported by: Pedro A M Vazquez vazquez@IQM.Unicamp.BR &a.msmith; Archive Viper 2525 The boot message identifier for this drive is ARCHIVE VIPER 2525 25462 -011 type 1 removable SCSI 1 This is a QIC tape drive. Native capacity is 525MB. Data transfer rate is 180kB/s at 90 inches/sec. The drive reads QIC-525, QIC-150, QIC-120 and QIC-24 tapes. Writes QIC-525, QIC-150, and QIC-120. Firmware revisions prior to 25462 -011 are bug ridden and will not function properly. Production of this drive has been discontinued. Conner 420R The boot message identifier for this drive is Conner tape. This is a floppy controller, mini cartridge tape drive. Native capacity is XXXX Data transfer rate is XXX The drive uses QIC-80 tape cartridges. Reported by: Mark Hannon mark@seeware.DIALix.oz.au Conner CTMS 3200 The boot message identifier for this drive is CONNER CTMS 3200 7.00 type 1 removable SCSI 2. This is a mini cartridge tape drive. Native capacity is XXXX Data transfer rate is XXX The drive uses QIC-3080 tape cartridges. Reported by: Thomas S. Traylor tst@titan.cs.mci.com <ulink url="http://www.digital.com/info/Customer-Update/931206004.txt.html">DEC TZ87</ulink> The boot message identifier for this drive is DEC TZ87 (C) DEC 9206 type 1 removable SCSI 2 density code 0x19 This is a DLT tape drive. Native capacity is 10GB. This drive supports hardware data compression. Data transfer rate is 1.2MB/s. This drive is identical to the Quantum DLT2000. The drive firmware can be set to emulate several well-known drives, including an Exabyte 8mm drive. Reported by: &a.wilko; <ulink url="http://www.Exabyte.COM:80/Products/Minicartridge/2501/Rfeatures.html">Exabyte EXB-2501</ulink> The boot message identifier for this drive is EXABYTE EXB-2501 This is a mini-cartridge tape drive. Native capacity is 1GB when using MC3000XL mini cartridges. Data transfer rate is XXX This drive can read and write DC2300 (550MB), DC2750 (750MB), MC3000 (750MB), and MC3000XL (1GB) mini cartridges. WARNING: This drive does not meet the SCSI-2 specifications. The drive locks up completely in response to a SCSI MODE_SELECT command unless there is a formatted tape in the drive. Before using this drive, set the tape blocksize with &prompt.root; mt -f /dev/st0ctl.0 blocksize 1024 Before using a mini cartridge for the first time, the mini cartridge must be formated. FreeBSD 2.1.0-RELEASE and earlier: &prompt.root; /sbin/scsi -f /dev/rst0.ctl -s 600 -c "4 0 0 0 0 0" (Alternatively, fetch a copy of the scsiformat shell script from FreeBSD 2.1.5/2.2.) FreeBSD 2.1.5 and later: &prompt.root; /sbin/scsiformat -q -w /dev/rst0.ctl Right now, this drive cannot really be recommended for FreeBSD. Reported by: Bob Beaulieu ez@eztravel.com Exabyte EXB-8200 The boot message identifier for this drive is EXABYTE EXB-8200 252X type 1 removable SCSI 1 This is an 8mm tape drive. Native capacity is 2.3GB. Data transfer rate is 270kB/s. This drive is fairly slow in responding to the SCSI bus during boot. A custom kernel may be required (set SCSI_DELAY to 10 seconds). There are a large number of firmware configurations for this drive, some have been customized to a particular vendor's hardware. The firmware can be changed via EPROM replacement. Production of this drive has been discontinued. Reported by: &a.msmith; Exabyte EXB-8500 The boot message identifier for this drive is EXABYTE EXB-8500-85Qanx0 0415 type 1 removable SCSI 2 This is an 8mm tape drive. Native capacity is 5GB. Data transfer rate is 300kB/s. Reported by: Greg Lehey grog@lemis.de <ulink url="http://www.Exabyte.COM:80/Products/8mm/8505XL/Rfeatures.html">Exabyte EXB-8505</ulink> The boot message identifier for this drive is EXABYTE EXB-85058SQANXR1 05B0 type 1 removable SCSI 2 This is an 8mm tape drive which supports compression, and is upward compatible with the EXB-5200 and EXB-8500. Native capacity is 5GB. The drive supports hardware data compression. Data transfer rate is 300kB/s. Reported by: Glen Foster gfoster@gfoster.com Hewlett-Packard HP C1533A The boot message identifier for this drive is HP C1533A 9503 type 1 removable SCSI 2. This is a DDS-2 tape drive. DDS-2 means hardware data compression and narrower tracks for increased data capacity. Native capacity is 4GB when using 120m tapes. This drive supports hardware data compression. Data transfer rate is 510kB/s. This drive is used in Hewlett-Packard's SureStore 6000eU and 6000i tape drives and C1533A DDS-2 DAT drive. The drive has a block of 8 dip switches. The proper settings for FreeBSD are: 1 ON; 2 ON; 3 OFF; 4 ON; 5 ON; 6 ON; 7 ON; 8 ON. switch 1 switch 2 Result On On Compression enabled at power-on, with host control On Off Compression enabled at power-on, no host control Off On Compression disabled at power-on, with host control Off Off Compression disabled at power-on, no host control Switch 3 controls MRS (Media Recognition System). MRS tapes have stripes on the transparent leader. These identify the tape as DDS (Digital Data Storage) grade media. Tapes that do not have the stripes will be treated as write-protected. Switch 3 OFF enables MRS. Switch 3 ON disables MRS. See HP SureStore Tape Products and Hewlett-Packard Disk and Tape Technical Information for more information on configuring this drive. Warning: Quality control on these drives varies greatly. One FreeBSD core-team member has returned 2 of these drives. Neither lasted more than 5 months. Reported by: &a.se; Hewlett-Packard HP 1534A The boot message identifier for this drive is HP HP35470A T503 type 1 removable SCSI 2 Sequential-Access density code 0x13, variable blocks. This is a DDS-1 tape drive. DDS-1 is the original DAT tape format. Native capacity is 2GB when using 90m tapes. Data transfer rate is 183kB/s. The same mechanism is used in Hewlett-Packard's SureStore 2000i tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT drive and HP C1536A DDS format DAT drive. The HP C1534A DDS format DAT drive has two indicator lights, one green and one amber. The green one indicates tape action: slow flash during load, steady when loaded, fast flash during read/write operations. The amber one indicates warnings: slow flash when cleaning is required or tape is nearing the end of its useful life, steady indicates an hard fault. (factory service required?) Reported by Gary Crutcher gcrutchr@nightflight.com Hewlett-Packard HP C1553A Autoloading DDS2 The boot message identifier for this drive is "". This is a DDS-2 tape drive with a tape changer. DDS-2 means hardware data compression and narrower tracks for increased data capacity. Native capacity is 24GB when using 120m tapes. This drive supports hardware data compression. Data transfer rate is 510kB/s (native). This drive is used in Hewlett-Packard's SureStore 12000e tape drive. The drive has two selectors on the rear panel. The selector closer to the fan is SCSI id. The other selector should be set to 7. There are four internal switches. These should be set: 1 ON; 2 ON; 3 ON; 4 OFF. At present the kernel drivers do not automatically change tapes at the end of a volume. This shell script can be used to change tapes: #!/bin/sh PATH="/sbin:/usr/sbin:/bin:/usr/bin"; export PATH usage() { echo "Usage: dds_changer [123456ne] raw-device-name echo "1..6 = Select cartridge" echo "next cartridge" echo "eject magazine" exit 2 } if [ $# -ne 2 ] ; then usage fi cdb3=0 cdb4=0 cdb5=0 case $1 in [123456]) cdb3=$1 cdb4=1 ;; n) ;; e) cdb5=0x80 ;; ?) usage ;; esac scsi -f $2 -s 100 -c "1b 0 0 $cdb3 $cdb4 $cdb5" Hewlett-Packard HP 35450A The boot message identifier for this drive is HP HP35450A -A C620 type 1 removable SCSI 2 Sequential-Access density code 0x13 This is a DDS-1 tape drive. DDS-1 is the original DAT tape format. Native capacity is 1.2GB. Data transfer rate is 160kB/s. Reported by: Mark Thompson mark.a.thompson@pobox.com Hewlett-Packard HP 35470A The boot message identifier for this drive is HP HP35470A 9 09 type 1 removable SCSI 2 This is a DDS-1 tape drive. DDS-1 is the original DAT tape format. Native capacity is 2GB when using 90m tapes. Data transfer rate is 183kB/s. The same mechanism is used in Hewlett-Packard's SureStore 2000i tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT drive, and HP C1536A DDS format DAT drive. Warning: Quality control on these drives varies greatly. One FreeBSD core-team member has returned 5 of these drives. None lasted more than 9 months. Reported by: David Dawes dawes@rf900.physics.usyd.edu.au (9 09) Hewlett-Packard HP 35480A The boot message identifier for this drive is HP HP35480A 1009 type 1 removable SCSI 2 Sequential-Access density code 0x13. This is a DDS-DC tape drive. DDS-DC is DDS-1 with hardware data compression. DDS-1 is the original DAT tape format. Native capacity is 2GB when using 90m tapes. It cannot handle 120m tapes. This drive supports hardware data compression. Please refer to the section on HP C1533A for the proper switch settings. Data transfer rate is 183kB/s. This drive is used in Hewlett-Packard's SureStore 5000eU and 5000i tape drives and C35480A DDS format DAT drive.. This drive will occasionally hang during a tape eject operation (mt offline). Pressing the front panel button will eject the tape and bring the tape drive back to life. WARNING: HP 35480-03110 only. On at least two occasions this tape drive when used with FreeBSD 2.1.0, an IBM Server 320 and an 2940W SCSI controller resulted in all SCSI disk partitions being lost. The problem has not be analyzed or resolved at this time. <ulink url="http://www.sel.sony.com/SEL/ccpg/storage/tape/t5000.html">Sony SDT-5000</ulink> There are at least two significantly different models: one is a DDS-1 and the other DDS-2. The DDS-1 version is SDT-5000 3.02. The DDS-2 version is SONY SDT-5000 327M. The DDS-2 version has a 1MB cache. This cache is able to keep the tape streaming in almost any circumstances. The boot message identifier for this drive is SONY SDT-5000 3.02 type 1 removable SCSI 2 Sequential-Access density code 0x13 Native capacity is 4GB when using 120m tapes. This drive supports hardware data compression. Data transfer rate is depends upon the model or the drive. The rate is 630kB/s for the SONY SDT-5000 327M while compressing the data. For the SONY SDT-5000 3.02, the data transfer rate is 225kB/s. In order to get this drive to stream, set the blocksize to 512 bytes (mt blocksize 512) reported by Kenneth Merry ken@ulc199.residence.gatech.edu. SONY SDT-5000 327M information reported by Charles Henrich henrich@msu.edu. Reported by: &a.jmz; Tandberg TDC 3600 The boot message identifier for this drive is TANDBERG TDC 3600 =08: type 1 removable SCSI 2 This is a QIC tape drive. Native capacity is 150/250MB. This drive has quirks which are known and work around code is present in the scsi tape device driver (&man.st.4;). Upgrading the firmware to XXX version will fix the quirks and provide SCSI 2 capabilities. Data transfer rate is 80kB/s. IBM and Emerald units will not work. Replacing the firmware EPROM of these units will solve the problem. Reported by: &a.msmith; Tandberg TDC 3620 This is very similar to the Tandberg TDC 3600 drive. Reported by: &a.joerg; Tandberg TDC 3800 The boot message identifier for this drive is TANDBERG TDC 3800 =04Y Removable Sequential Access SCSI-2 device This is a QIC tape drive. Native capacity is 525MB. Reported by: &a.jhs; Tandberg TDC 4222 The boot message identifier for this drive is TANDBERG TDC 4222 =07 type 1 removable SCSI 2 This is a QIC tape drive. Native capacity is 2.5GB. The drive will read all cartridges from the 60 MB (DC600A) upwards, and write 150 MB (DC6150) upwards. Hardware compression is optionally supported for the 2.5 GB cartridges. This drives quirks are known and pre-compiled into the scsi tape device driver (&man.st.4;) beginning with FreeBSD 2.2-CURRENT. For previous versions of FreeBSD, use mt to read one block from the tape, rewind the tape, and then execute the backup program (mt fsr 1; mt rewind; dump ...) Data transfer rate is 600kB/s (vendor claim with compression), 350 KB/s can even be reached in start/stop mode. The rate decreases for smaller cartridges. Reported by: &a.joerg; Wangtek 5525ES The boot message identifier for this drive is WANGTEK 5525ES SCSI REV7 3R1 type 1 removable SCSI 1 density code 0x11, 1024-byte blocks This is a QIC tape drive. Native capacity is 525MB. Data transfer rate is 180kB/s. The drive reads 60, 120, 150, and 525MB tapes. The drive will not write 60MB (DC600 cartridge) tapes. In order to overwrite 120 and 150 tapes reliably, first erase (mt erase) the tape. 120 and 150 tapes used a wider track (fewer tracks per tape) than 525MB tapes. The extra width of the previous tracks is not overwritten, as a result the new data lies in a band surrounded on both sides by the previous data unless the tape have been erased. This drives quirks are known and pre-compiled into the scsi tape device driver (&man.st.4;). Other firmware revisions that are known to work are: M75D Reported by: Marc van Kempen marc@bowtie.nl REV73R1 Andrew Gordon Andrew.Gordon@net-tel.co.uk M75D Wangtek 6200 The boot message identifier for this drive is WANGTEK 6200-HS 4B18 type 1 removable SCSI 2 Sequential-Access density code 0x13 This is a DDS-1 tape drive. Native capacity is 2GB using 90m tapes. Data transfer rate is 150kB/s. Reported by: Tony Kimball alk@Think.COM * Problem drives CDROM drives Contributed by &a.obrien;. 23 November 1997. As mentioned in Jordan's Picks Generally speaking those in The FreeBSD Project prefer SCSI CDROM drives over IDE CDROM drives. However not all SCSI CDROM drives are equal. Some feel the quality of some SCSI CDROM drives have been deteriorating to that of IDE CDROM drives. Toshiba used to be the favored stand-by, but many on the SCSI mailing list have found displeasure with the 12x speed XM-5701TA as its volume (when playing audio CDROMs) is not controllable by the various audio player software. Another area where SCSI CDROM manufacturers are cutting corners is adherence to the SCSI specification. Many SCSI CDROMs will respond to multiple LUNs for its target address. Known violators include the 6x Teac CD-56S 1.0D. * Other * Other * PCMCIA diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.sgml b/en_US.ISO8859-1/books/handbook/install/chapter.sgml index ea1aa6d6e8..aa7be2301f 100644 --- a/en_US.ISO8859-1/books/handbook/install/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/install/chapter.sgml @@ -1,2057 +1,2057 @@ Jim Mock Restructured, reorganized, and parts rewritten Installing FreeBSD Synopsis installation The following chapter will attempt to guide you through the installation of FreeBSD on your system. It can be installed through a variety of methods, including anonymous FTP (assuming you have network connectivity via modem or local network), CDROM, floppy disk, tape, an MS-DOS partition, or even NFS. No matter which method you choose, you will need to get started by creating the installation disks as described in the next section. Booting into the FreeBSD installer, even if you are not planning on installing FreeBSD right away, will provide important information about compatibility with your hardware. This information may dictate which installation options are even possible for you. It can also provide clues early-on in the process to potential problems you may come across later. installation network anonymous FTP If you plan to install FreeBSD via anonymous FTP, the only things you will need are the installation floppies. The installation program itself will handle anything else that is required. For more information about obtaining FreeBSD, see the Obtaining FreeBSD section of the Appendix. By now, you are probably wondering what exactly it is you need to do. Continue on to the installation guide. Installation Guide The following sections will guide you through preparing for and actually installing FreeBSD. If you find something missing, please let us know about it by sending email to the &a.doc;. Preparing for the Installation There are various things you should do in preparation for the installation. The following describes what needs to be done prior to each type of installation. The first thing to do is to make sure your hardware is supported by FreeBSD. The list of supported hardware should come in handy here. ;-) It would also be a good idea to make a list of any special cards you have installed, - such as SCSI controllers, ethernet cards, sound cards, etc.. + such as SCSI controllers, Ethernet cards, sound cards, etc.. The list should include their IRQs and IO port addresses. Creating the Installation Floppies installation boot floppies installation CDROM You may need to prepare some floppy disks. These disks will be used to boot your computer in to the FreeBSD install process. This step is not necessary if you are installing from CDROM, and your computer supports booting from the CDROM. If you do not meet these requirements then you will need to create some floppies to boot from. If you are not sure whether your computer can boot from the CDROM it does not hurt to try. Just insert the CDROM as normal and restart your computer. You might need to adjust some options in your BIOS so that your computer will try and boot from the CDROM drive before the hard disk. Even if you have the CDROM it might make sense for you to download the files. There have been occasions where bugs in the FreeBSD installer have been discovered after the CDs have been released. When this happens the copies of the images on the FTP site will be fixed as soon as possible. Obviously, it is not possible to update the CDs after they have been pressed. Acquire the boot floppy images These are files with a .flp extension. If you have a CDROM release of FreeBSD then you will find the files in the floppies subdirectory. Alternatively, you can download the images from the floppies directory of the FreeBSD FTP site or your local mirror. The names of the files you will need varies between FreeBSD releases (sometimes) and the architecture you will be installing on. The installation boot image information on the FTP site provides up-to-the-minute information about the specific files you will need. Prepare the floppy disks You must prepare one floppy disk per image file you had to download. It is imperative that these disks are free from defects. The easiest way to test this is to format the disks for yourself. Do not trust pre-formatted floppies. If you try to install FreeBSD and the installation program crashes, freezes, or otherwise misbehaves one of the first things to suspect is the floppies. Try writing the floppy image files to some other disks, and try again. Write the image files to the floppy disks. The image files, such as kern.flp, are not regular files you copy to the disk. Instead, they are images of the complete contents of the disk. This means that you can not use commands like DOS' copy to write the files. Instead, you must use specific tools to write the images directly to the disk. DOS If you are creating the floppies on a computer running DOS then we provide a tool to do this called fdimage. If you are using the floppies from the CDROM, and your CDROM is the E: drive then you would run this: E:\> tools\fdimage floppies\kern.flp A: Repeat this command for each .flp file, replacing the floppy disk each time. Adjust the command line as necessary, depending on where you have placed the .flp files. If you do not have the CDROM then fdimage can be downloaded from the tools directory on the FreeBSD FTP site. If you are writing the floppies on a Unix system (such as another FreeBSD system) you can use the &man.dd.1; command to write the image files directly to disk. On FreeBSD you would run: &prompt.root; dd if=kern.flp of=/dev/fd0 On FreeBSD /dev/fd0 refers to the first floppy disk (the A: drive). /dev/rfd1 would be the B: drive, and so on. Other Unix variants might have different names for the floppy disk devices, and you will need to check the documentation for the system as necessary. Before Installing from CDROM If your CDROM is of an unsupported type, please skip ahead to the MS-DOS Preparation section. There is not a whole lot of preparation needed if you are installing from one of BSDi's FreeBSD CDROMs (other CDROM distributions may work as well, though we cannot say for certain as we have no hand or say in how they created). You can either boot into the CD installation directly from DOS using the install.bat or you can make floppies with the makeflp.bat command. If the CD has El Torito boot support and your system supports booting directly from the CDROM drive (many older systems do NOT), simply insert the first CD of the set into the drive and reboot your system. You will be put into the installation menu directly from the CD. DOS If you are installing from an MS-DOS partition and have the proper drivers to access your CD, run the install.bat script provided on the CDROM. This will attempt to boot the FreeBSD installation directly from DOS. You must do this from actual DOS (i.e., boot in DOS mode) and not from a DOS window under Windows. For the easiest interface of all (from DOS), type view. This will bring up a DOS menu utility that leads you through all of the available options. Unix If you are creating the boot floppies from a Unix machine, see the Creating the Boot Floppies section of this guide for examples. Once you have booted from DOS or floppy, you should then be able to select CDROM as the media type during the install process and load the entire distribution from CDROM. No other types of installation media should be required. After your system is fully installed and you have rebooted (from the hard disk), you can mount the CDROM at any time by typing: &prompt.root; mount /cdrom Before removing the CD from the drive again, you must first unmount it. This is done with the following command: &prompt.root; umount /cdrom Do not just remove it from the drive! Before invoking the installation, be sure that the CDROM is in the drive so that the install probe can find it. This is also true if you wish the CDROM to be added to the default system configuration automatically during the installation (whether or not you actually use it as the installation media). installationnetworkFTP Finally, if you would like people to be able to FTP install FreeBSD directly from the CDROM in your machine, you will find it quite easy. After the machine is fully installed, you simply need to add the following line to the password file (using the vipw command): ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent Anyone with network connectivity to your machine can now chose a media type of FTP and type in ftp://your machine after picking Other in the FTP sites menu during the install. If you choose to enable anonymous FTP during the installation of your system, the installation program will do the above for you. Before installing from Floppies installationfloppies If you must install from floppy disk (which we suggest you do NOT do), either due to unsupported hardware or simply because you insist on doing things the hard way, you must first prepare some floppies for the installation. At a minimum, you will need as many 1.44MB or 1.2MB floppies as it takes to hold all the files in the bin (binary distribution) directory. If you are preparing the floppies from DOS, then they MUST be formatted using the MS-DOS FORMAT command. If you are using Windows, use Explorer to format the disks (right-click on the A: drive, and select "Format". Do NOT trust factory pre-formatted floppies! Format them again yourself, just to be sure. Many problems reported by our users in the past have resulted from the use of improperly formatted media, which is why we are making a point of it now. If you are creating the floppies on another FreeBSD machine, a format is still not a bad idea, though you do not need to put a DOS filesystem on each floppy. You can use the disklabel and newfs commands to put a UFS filesystem on them instead, as the following sequence of commands (for a 3.5" 1.44MB floppy) illustrates: &prompt.root; fdformat -f 1440 fd0.1440 &prompt.root; disklabel -w -r fd0.1440 floppy3 &prompt.root; newfs -t 2 -u 18 -l 1 -i 65536 /dev/fd0 Use fd0.1200 and floppy5 for 5.25" 1.2MB disks. Then you can mount and write to them like any other filesystem. After you have formatted the floppies, you will need to copy the files to them. The distribution files are split into chunks conveniently sized so that 5 of them will fit on a conventional 1.44MB floppy. Go through all your floppies, packing as many files as will fit on each one, until you have all of the distributions you want packed up in this fashion. Each distribution should go into a subdirectory on the floppy, e.g.: a:\bin\bin.aa, a:\bin\bin.ab, and so on. Once you come to the Media screen during the install process, select Floppy and you will be prompted for the rest. Before Installing from MS-DOS installationfrom MS-DOS To prepare for an installation from an MS-DOS partition, copy the files from the distribution into a directory named, for example, c:\FreeBSD. The directory structure of the CDROM or FTP site must be partially reproduced within this directory, so we suggest using the DOS xcopy command if you are copying it from a CD. For example, to prepare for a minimal installation of FreeBSD: C:\> md c:\FreeBSD C:\> xcopy e:\bin c:\FreeBSD\bin\ /s C:\> xcopy e:\manpages c:\FreeBSD\manpages\ /s Assuming that C: is where you have free space and E: is where your CDROM is mounted. If you do not have a CDROM drive, you can download the distribution from ftp.FreeBSD.org. Each distribution is in its own directory; for example, the bin distribution can be found in the &rel.current;/bin directory. For as many distributions you wish to install from an MS-DOS partition (and you have the free space for), install each one under c:\FreeBSD — the BIN distribution is the only one required for a minimum installation. Before Installing from QIC/SCSI Tape installationfrom QIC/SCSI Tape Installing from tape is probably the easiest method, short of an online FTP install or CDROM install. The installation program expects the files to be simply tarred onto the tape, so after getting all of the distribution files you are interested in, simply tar them onto the tape like so: &prompt.root; cd /freebsd/distdir &prompt.root; tar cvf /dev/rwt0 dist1 ... dist2 When you go to do the installation, you should also make sure that you leave enough room in some temporary directory (which you will be allowed to choose) to accommodate the full contents of the tape you have created. Due to the non-random access nature of tapes, this method of installation requires quite a bit of temporary storage. You should expect to require as much temporary storage as you have stuff written on tape. When starting the installation, the tape must be in the drive before booting from the boot floppy. The installation probe may otherwise fail to find it. Before Installing over a Network installationnetworkserial (SLIP or PPP) installationnetworkparallel (PLIP) installationnetworkEthernet There are three types of network installations you can do. Serial port (SLIP or PPP), Parallel port (PLIP (laplink cable)), - or Ethernet (a standard ethernet controller (includes some + or Ethernet (a standard Ethernet controller (includes some PCMCIA)). The SLIP support is rather primitive, and limited primarily to hard-wired links, such as a serial cable running between a laptop computer and another computer. The link should be hard-wired as the SLIP installation does not currently offer a dialing capability; that facility is provided with the PPP utility, which should be used in preference to SLIP whenever possible. If you are using a modem, then PPP is almost certainly your only choice. Make sure that you have your service provider's information handy as you will need to know it fairly early in the installation process. If you use PAP or CHAP to connect your ISP (in other words, if you can connect to the ISP in Windows without using a script), then all you will need to do is type in dial at the ppp prompt. Otherwise, you will need to know how to dial your ISP using the AT commands specific to your modem, as the PPP dialer provides only a very simple terminal emulator. Please refer to the user-ppp handbook and FAQ entries for further information. If you have problems, logging can be directed to the screen using the command set log local .... If a hard-wired connection to another FreeBSD (2.0-R or later) machine is available, you might also consider installing over a laplink parallel port cable. The data rate over the parallel port is much higher than what is typically possible over a serial line (up to 50kbytes/sec), thus resulting in a quicker installation. Finally, for the fastest possible network installation, an - ethernet adapter is always a good choice! FreeBSD supports most - common PC ethernet cards; a table of supported cards (and their + Ethernet adapter is always a good choice! FreeBSD supports most + common PC Ethernet cards; a table of supported cards (and their required settings) is provided in the Supported Hardware list. If you are - using one of the supported PCMCIA ethernet cards, also be sure + using one of the supported PCMCIA Ethernet cards, also be sure that it is plugged in before the laptop is powered on! FreeBSD does not, unfortunately, currently support hot insertion of PCMCIA cards during installation. You will also need to know your IP address on the network, the netmask value for your address class, and the name of your machine. If you are installing over a PPP connection and do not have a static IP, fear not, the IP address can be dynamically assigned by your ISP. Your system administrator can tell you which values to use for your particular network setup. If you will be referring to other hosts by name rather than IP address, you will also need a name server and possibly the address of a gateway (if you are using PPP, it is your provider's IP address) to use in talking to it. If you want to install by FTP via a HTTP proxy (see below), you will also need the proxy's address. If you do not know the answers to all or most of these questions, then you should really probably talk to your system administrator or ISP before trying this type of installation. Before Installing via NFS installationnetworkNFS The NFS installation is fairly straight-forward. Simply copy the FreeBSD distribution files you want onto a server somewhere and then point the NFS media selection at it. If this server supports only privileged port (as is generally the default for Sun workstations), you will need to set this option in the Options menu before installation can proceed. - If you have a poor quality ethernet card which suffers + If you have a poor quality Ethernet card which suffers from very slow transfer rates, you may also wish to toggle the appropriate Options flag. In order for NFS installation to work, the server must support subdir mounts, e.g., if your FreeBSD 3.4 distribution directory lives on:ziggy:/usr/archive/stuff/FreeBSD, then ziggy will have to allow the direct mounting of /usr/archive/stuff/FreeBSD, not just /usr or /usr/archive/stuff. In FreeBSD's /etc/exports file, this is controlled by the . Other NFS servers may have different conventions. If you are getting permission denied messages from the server, then it is likely that you do not have this enabled properly. Before Installing via FTP installationnetworkFTP FTP installation may be done from any FreeBSD mirror site containing a reasonably up-to-date version of FreeBSD. A full list of FTP mirrors located all over the world is provided during the install process. If you are installing from an FTP site not listed in this menu, or are having trouble getting your name server configured properly, you can also specify a URL to use by selecting the choice labeled Other in that menu. You can also use the IP address of a machine you wish to install from, so the following would work in the absence of a name server: ftp://209.55.82.20/pub/FreeBSD/&rel.current;-RELEASE There are three FTP installation modes you can choose from: active or passive FTP or via a HTTP proxy. FTP Active This option will make all FTP transfers use Active mode. This will not work through firewalls, but will often work with older FTP servers that do not support passive mode. If your connection hangs with passive mode (the default), try active! FTP Passive FTPPassive mode This option instructs FreeBSD to use Passive mode for all FTP operations. This allows the user to pass through firewalls that do not allow incoming connections on random port addresses. FTP via a HTTP proxy FTPvia a HTTP proxy This option instructs FreeBSD to use the HTTP protocol (like a web browser) to connect to a proxy for all FTP operations. The proxy will translate the requests and send them to the FTP server. This allows the user to pass through firewalls that do not allow FTP at all, but offer a HTTP proxy. In this case, you have to specify the proxy in addition to the FTP server. There is another type of FTP proxy other tha HTTP proxies. This type is very uncommon, though. If you are not absolutely certain, you can assume that you have a HTTP proxy as described above. For a proxy FTP server, you should usually give the name of the server you really want as a part of the username, after an @ sign. The proxy server then fakes the real server. For example, assuming you want to install from ftp.FreeBSD.org, using the proxy FTP server foo.bar.com, listening on port 1024. In this case, you go to the options menu, set the FTP username to ftp@ftp.FreeBSD.org, and the password to your email address. As your installation media, you specify FTP (or passive FTP, if the proxy supports it), and the URL ftp://foo.bar.com:1234/pub/FreeBSD. Since /pub/FreeBSD from ftp.FreeBSD.org is proxied under foo.bar.com, you are able to install from that machine (which will fetch the files from ftp.FreeBSD.org as your installation requests them. Check your BIOS drive numbering If you have used features in your BIOS to renumber your disk drives without re-cabling them then you should read first to avoid confusion. Installing FreeBSD Once you have completed the pre-installation step relevant to your situation, you are ready to install FreeBSD! Although you should not experience any difficulty, there is always the chance that you may, no matter how slight it is. If this is the case in your situation, then you may wish to go back and re-read the relevant preparation section or sections. Perhaps you will come across something you missed the first time. If you are having hardware problems, or FreeBSD refuses to boot at all, read the Hardware Guide for a list of possible solutions. sysinstall The FreeBSD boot floppies contain all of the online documentation you should need to be able to navigate through an installation. If it does not, please let us know what you found to be the most confusing or most lacking. Send your comments to the &a.doc;. It is the objective of the installation program (sysinstall) to be self-documenting enough that painful step-by-step guides are no longer necessary. It may take us a little while to reach that objective, but nonetheless, it is still our objective :-) Meanwhile, you may also find the following typical installation sequence to be helpful: Boot the kern.flp floppy and when asked, remove it and insert the mfsroot.flp and hit return. After a boot sequence which can take anywhere from 30 seconds to 3 minutes, depending on your hardware, you should be presented with a menu of initial choices. If the kern.flp floppy does not boot at all or the boot hangs at some stage, read the Q&A section of the Hardware Guide for possible causes. Press F1. You should see some basic usage instructions on the menu screen and general navigation. If you have not used this menu system before then please read this thoroughly. Select the Options item and set any special preferences you may have. installationstandard installationexpress installationcustom Select a Standard, Express, or Custom install, depending on whether or not you would like the installation to help you through a typical installation, give you a high degree of control over each step, or simply whiz through it (using reasonable defaults when possible) as fast as possible. If you have never used FreeBSD before, the Standard installation method is most recommended. The final configuration menu choice allows you to further configure your FreeBSD installation by giving you menu-driven access to various system defaults. Some items, like networking, may be especially important if you did a CDROM, tape, or floppy install and have not yet configured your network interfaces (assuming you have any). Properly configuring such interfaces here will allow FreeBSD to come up on the network when you first reboot from the hard disk. Supported Hardware hardware FreeBSD currently runs on a wide variety of ISA, VLB, EISA, and PCI bus based PCs, ranging from the 386SX to Pentium class machines (though the 386SX is not recommended). Support for generic IDE or ESDI drive configurations, various SCSI controllers, and network and serial cards is also provided. FreeBSD also supports IBM's microchannel (MCA) bus. In order to run FreeBSD, a recommended minimum of eight megabytes of RAM is suggested. Sixteen megabytes is the preferred amount of RAM as you may have some trouble with anything less than sixteen depending on your hardware. What follows is a list of hardware currently known to work with FreeBSD. There may be other hardware that works as well, but we have simply not received any confirmation of it. Disk Controllers disk controllers WD1003 (any generic MFM/RLL) WD1007 (any generic IDE/ESDI) IDE ATA Adaptec 1535 ISA SCSI controllers Adaptec 154X series ISA SCSI controllers Adaptec 174X series EISA SCSI controllers in standard and enhanced mode Adaptec 274X/284X/2920C/294X/2950/3940/3950 (Narrow/Wide/Twin) series EISA/VLB/PCI SCSI controllers Adaptec AIC-7850, AIC-7860, AIC-7880, AIC-789X on-board SCSI controllers Adaptec 1510 series ISA SCSI controllers (not for bootable devices) Adaptec 152X series ISA SCSI controllers Adaptec AIC-6260 and AIC-6360 based boards, which include the AHA-152X and SoundBlaster SCSI cards AdvanSys SCSI controllers (all models) BusLogic MultiMaster W Series Host Adapters including BT-948, BT-958, BT-9580 BusLogic MultiMaster C Series Host Adapters including BT-946C, BT-956C, BT-956CD, BT-445C, BT-747C, BT-757C, BT-757CD, BT-545C, BT-540CF BusLogic MultiMaster S Series Host Adapters including BT-445S, BT-747S, BT-747D, BT-757S, BT-757D, BT-545S, BT-542D, BT-742A, BT-542B BusLogic MultiMaster A Series Host Adapters including BT-742A, BT-542B AMI FastDisk controllers that are true BusLogic MultiMaster clones are also supported. BusLogic/Mylex Flashpoint adapters are NOT yet supported. DPT SmartCACHE Plus, SmartCACHE III, SmartRAID III, SmartCACHE IV, and SmartRAID IV SCSI/RAID are supported. The DPT SmartRAID/CACHE V is not yet supported. The DPT PM3754U2-16M SCSI RAID Controller is also supported. Compaq Intelligent Disk Array Controllers: IDA, IDA-2, IAES, SMART, SMART-2/E, Smart-2/P, SMART-2SL, Integrated Array, and Smart Arrays 3200, 3100ES, 221, 4200, 4200, 4250ES. SymBios (formerly NCR) 53C810, 53C810a, 53C815, 53C820, 53C825a, 53C860, 53C875, 53C875j, 53C885, and 53C896 PCI SCSI controllers including ASUS SC-200, Data Technology DTC3130 (all variants), Diamond FirePort (all), NCR cards (all), SymBios cards (all), Tekram DC390W, 390U, and 390F, and Tyan S1365 QLogic 1020, 1040, 1040B, and 2100 SCSI and Fibre Channel Adapters DTC 3290 EISA SCSI controller in 1542 evaluation mode With all supported SCSI controllers, full support is provided for SCSI-I and SCSI-II peripherals, including hard disks, optical disks, tape drives (including DAT and 8mm Exabyte), medium changers, processor target devices, and CDROM drives. WORM devices that support CDROM commands are supported for read-only access by the CDROM driver. WORM/CD-R/CD-RW writing support is provided by cdrecord, which is in the ports tree. The following CDROM type systems are supported at this time: cd - SCSI interface (includes ProAudio Spectrum and SoundBlaster SCSI) matcd - Matsushita/Panasonic (Creative SoundBlaster) proprietary interface (562/563 models) scd - Sony proprietary interface (all models) acd - ATAPI IDE interface The following drivers were supported under the old SCSI subsystem, but are NOT YET supported under the new CAM SCSI subsystem: NCR5380/NCR53400 (ProAudio Spectrum) SCSI controller UltraStor 14F, 24F, and 34F SCSI controllers Seagate ST01/02 SCSI controllers Future Domain 8XX/950 series SCSI controllers WD7000 SCSI controller There is work-in-progress to port the UltraStor driver to the new CAM framework, but no estimates on when or if it will be completed. Unmaintained drivers, which might or might not work for your hardware: Floppy tape interface (Colorado/Mountain/Insight) mcd - Mitsumi proprietary CDROM interface (all models) Network Cards network cards Adaptec Duralink PCI fast ethernet adapters based on the Adaptec AIC-6195 fast ethernet controller chip, including the following: ANA-62011 64-bit single port 10/100baseTX adapter ANA-62022 64-bit dual port 10/100baseTX adapter ANA-62044 64-bit quad port 10/100baseTX adapter ANA-69011 32-bit single port 10/100baseTX adapter ANA-62020 64-bit single port 100baseFX adapter Allied-Telesyn AT1700 and RE2000 cards Alteon Networks PCI gigabit ethernet NICs based on the Tigon 1 and Tigon 2 chipsets including the Alteon AceNIC (Tigon 1 and 2), 3Com 3c985-SX (Tigon 1 and 2), Netgear GA620 (Tigon 2), Silicon Graphics Gigabit Ethernet, DEC/Compaq EtherWORKS 1000, NEC Gigabit Ethernet AMD PCnet/PCI (79c970 and 53c974 or 79c974) RealTek 8129/8139 fast ethernet NICs including the following: Allied-Telesyn AT2550 Allied-Telesyn AT2500TX Genius GF100TXR (RTL8139) NDC Communications NE100TX-E OvisLink LEF-8129TX OvisLink LEF-8139TX Netronix Inc. EA-1210 NetEther 10/100 KTX-9130TX 10/100 Fast Ethernet Accton Cheetah EN1207D (MPX 5030/5038; RealTek 8139 clone) SMC EZ Card 10/100 PCI 1211-TX Lite-On 98713, 98713A, 98715, and 98725 fast ethernet NICs, including the LinkSys EtherFast LNE100TX, NetGear FA310-TX Rev. D1, Matrox FastNIC 10/100, Kingston KNE110TX Macronix 98713, 98713A, 98715, 98715A, and 98725 fast ethernet NICs including the NDC Communications SFA100A (98713A), CNet Pro120A (98713 or 98713A), CNet Pro120B (98715), SVEC PN102TX (98713) Macronix/Lite-On PNIC II LC82C115 fast ethernet NICs including the LinkSys EtherFast LNE100TX version 2 Winbond W89C840F fast ethernet NICs including the Trendware TE100-PCIE VIA Technologies VT3043 Rhine I and VT86C100A Rhine II fast ethernet NICs including the Hawking Technologies PN102TX and D-Link DFE-530TX Silicon Integrated Systems SiS 900 and SiS 7016 PCI fast ethernet NICs Sundance Technologies ST201 PCI fast ethernet NICs including the D-Link DFE-550TX SysKonnect SK-984x PCI gigabit ethernet cards including the SK-9841 1000baseLX (single mode fiber, single port), the SK-9842 1000baseSX (multimode fiber, single port), the SK-9843 1000baseLX (single mode fiber, dual port), and the SK-9844 1000baseSX (multimode fiber, dual port). Texas Instruments ThunderLAN PCI NICs, including the Compaq Netelligent 10, 10/100, 10/100 Proliant, 10/100 Dual-Port, 10/100 TX Embedded UTP, 10 T PCI UTP/Coax, and 10/100 TX UTP, the Compaq NetFlex 3P, 3P Integrated, and 3P w/BNC, the Olicom OC-2135/2138, OC-2325, OC-2326 10/100 TX UTP, and the Racore 8165 10/100baseTX and 8148 10baseT/100baseTX/100baseFX multi-personality cards ADMtek AL981-based and AN985-based PCI fast ethernet NICs ASIX Electronics AX88140A PCI NICs including the Alfa Inc. GFC2204 and CNet Pro110B DEC EtherWORKS III NICs (DE203, DE204, and DE205) DEC EtherWORKS II NICs (DE200, DE201, DE202, and DE422) DEC DC21040, DC21041, or DC21140 based NICs (SMC Etherpower 8432T, DE245, etc.) DEC FDDI (DEFPA/DEFEA) NICs Efficient ENI-155p ATM PCI FORE PCA-200E ATM PCI Fujitsu MB86960A/MB86965A HP PC Lan+ cards (model numbers: 27247B and 27252A) Intel EtherExpress ISA (not recommended due to driver instability) Intel EtherExpress Pro/10 Intel EtherExpress Pro/100B PCI Fast Ethernet Isolan AT 4141-0 (16 bit) Isolink 4110 (8 bit) Novell NE1000, NE2000, and NE2100 Ethernet interfaces PCI network cards emulating the NE2000, including the RealTek 8029, NetVin 5000, Winbond W89C940, Surecom NE-34, VIA VT86C926 3Com 3C501, 3C503 Etherlink II, 3C505 Etherlink/+, 3C507 Etherlink 16/TP, 3C509, 3C579, 3C589 (PCMCIA), 3C590/592/595/900/905/905B/905C PCI and EISA (Fast) Etherlink III / (Fast) Etherlink XL, 3C980/3C980B Fast Etherlink XL server adapter, 3CSOHO100-TX OfficeConnect adapter Toshiba ethernet cards PCMCIA ethernet cards from IBM and National Semiconductor are also supported USB Peripherals USB Peripherals A wide range of USB peripherals are supported. Owing to the generic nature of most USB devices, with some exceptions any device of a given class will be supported even if not explicitly listed here. USB keyboards USB mice USB printers and USB to parallel printer conversion cables USB hubs Motherboard chipsets: ALi Aladdin-V Intel 82371SB (PIIX3) and 82371AB and EB (PIIX4) chipsets NEC uPD 9210 Host Controller VIA 83C572 USB Host Controller and any other UHCI or OHCI compliant motherboard chipset (no exceptions known). PCI plug-in USB host controllers ADS Electronics PCI plug-in card (2 ports) Entrega PCI plug-in card (4 ports) Specific USB devices reported to be working: Agiler Mouse 29UO Andromeda hub Apple iMac mouse and keyboard ATen parallel printer adapter Belkin F4U002 parallel printer adapter and Belkin mouse BTC BTC7935 keyboard with mouse port Cherry G81-3504 Chic mouse Cypress mouse Entrega USB-to-parallel printer adapter Genius Niche mouse Iomega USB Zip 100 MB Kensington Mouse-in-a-Box Logitech M2452 keyboard Logitech wheel mouse (3 buttons) Logitech PS/2 / USB mouse (3 buttons) MacAlly mouse (3 buttons) MacAlly self-powered hub (4 ports) Microsoft Intellimouse (3 buttons) Microsoft keyboard NEC hub Trust Ami Mouse (3 buttons) ISDN (European DSS1 [Q.921/Q.931] protocol) ISDN Asuscom I-IN100-ST-DV (experimental, may work) Asuscom ISDNlink 128K AVM A1 AVM Fritz!Card classic AVM Fritz!Card PCI AVM Fritz!Card PCMCIA (currently FreeBSD 3.X only) AVM Fritz!Card PnP (currently FreeBSD 3.X only) Creatix ISDN-S0/8 Creatix ISDN-S0/16 Creatix ISDN-S0 PnP Dr.Neuhaus Niccy 1008 Dr.Neuhaus Niccy 1016 Dr.Neuhaus Niccy GO@ (ISA PnP) Dynalink IS64PH (no longer maintained) ELSA 1000pro ISA ELSA 1000pro PCI ELSA PCC-16 ITK ix1 micro (currently FreeBSD 3.X only) ITK ix1 micro V.3 (currently FreeBSD 3.X only) Sagem Cybermod (ISA PnP, may work) Sedlbauer Win Speed Siemens I-Surf 2.0 Stollman Tina-pp (under development) Teles S0/8 Teles S0/16 Teles S0/16.3 (the c Versions - like 16.3c - are unsupported!) Teles S0 PnP (experimental, may work) 3Com/USRobotics Sportster ISDN TA intern (non-PnP version) Sound Devices The following soundcards or codecs are supported (devices marked 'experimental' are only supported in FreeBSD-CURRENT and might work only unstably): sound cards 16550 UART (Midi) (experimental, needs a trick in the hints file) Advance Asound 100, 110 and Logic ALS120 Aureal Vortex1/Vortex2 and Vortex Advantage based soundcards by a third party driver Creative Labs SB16, SB32, SB AWE64 (including Gold), Vibra16, SB PCI (experimental), SB Live! (experimental) and most SoundBlaster compatible cards Creative Labs SB Midi Port (experimental), SB OPL3 Synthesizer (experimental) Crystal Semiconductor CS461x/462x Audio Accelerator, the support for the CS461x Midi port is experimental Crystal Semiconductor CS428x Audio Controller CS4237, CS4236, CS4232, CS4231 (ISA) ENSONIQ AudioPCI ES1370/1371 ESS ES1868, ES1869, ES1879, ES1888 Gravis UltraSound PnP, MAX NeoMagic 256AV/ZX (PCI) OPTi931 (ISA) OSS-compatible sequencer (Midi) (experimental) Trident 4DWave DX/NX (PCI) Yahama OPL-SAx (ISA) Miscellaneous Devices AST 4 port serial card using shared IRQ ARNET 8 port serial card using shared IRQ ARNET (now Digiboard) Sync 570/i high-speed serial Boca BB1004 4-Port serial card (Modems NOT supported) Boca IOAT66 6-Port serial card (Modems supported) Boca BB1008 8-Port serial card (Modems NOT supported) Boca BB2016 16-Port serial card (Modems supported) Cyclades Cyclom-y Serial Board Moxa SmartIO CI-104J 4-Port serial card STB 4 port card using shared IRQ SDL Communications RISCom/8 Serial Board SDL Communications RISCom/N2 and N2pci high-speed sync serial boards Specialix SI/XIO/SX multiport serial cards, with both the older SIHOST2.x and the new enhanced (transputer based, aka JET) host cards; ISA, EISA and PCI are supported Stallion multiport serial boards: EasyIO, EasyConnection 8/32 & 8/64, ONboard 4/16 and Brumby Adlib, SoundBlaster, SoundBlaster Pro, ProAudioSpectrum, Gravis UltraSound, and Roland MPU-401 sound cards Connectix QuickCam Matrox Meteor Video frame grabber Creative Labs Video Spigot frame grabber Cortex1 frame grabber Various frame grabbers based on the Brooktree Bt848 and Bt878 chip HP4020, HP6020, Philips CDD2000/CDD2660 and Plasmon CD-R drives Bus mice PS/2 mice Standard PC Joystick X-10 power controllers GPIB and Transputer drives Genius and Mustek hand scanners Floppy tape drives (some rather old models only, driver is rather stale) Lucent Technologies WaveLAN/IEEE 802.11 PCMCIA and ISA standard speed (2Mbps) and turbo speed (6Mbps) wireless network adapters and workalikes (NCR WaveLAN/IEEE 802.11, Cabletron RoamAbout 802.11 DS) The ISA versions of these adapters are actually PCMCIA cards combined with an ISA to PCMCIA bridge card, so both kinds of devices work with the same driver. Troubleshooting installationtroubleshooting The following section covers basic installation troubleshooting, such as common problems people have reported. There are also a few questions and answers for people wishing to dual-boot FreeBSD with MS-DOS. What to do if something goes wrong... Due to various limitations of the PC architecture, it is impossible for probing to be 100% reliable, however, there are a few things you can do if it fails. Check the supported hardware list to make sure your hardware is supported. If your hardware is supported and you still experience lock-ups or other problems, reset your computer, and when the visual kernel configuration option is given, choose it. This will allow you to go through your hardware and supply information to the system about it. The kernel on the boot disks is configured assuming that most hardware devices are in their factory default configuration in terms of IRQs, IO addresses, and DMA channels. If your hardware has been reconfigured, you will most likely need to use the configuration editor to tell FreeBSD where to find things. It is also possible that a probe for a device not present will cause a later probe for another device that is present to fail. In that case, the probes for the conflicting driver(s) should be disabled. Do not disable any drivers you will need during the installation, such as your screen (sc0). If the installation wedges or fails mysteriously after leaving the configuration editor, you have probably removed or changed something you should not have. Reboot and try again. In configuration mode, you can: List the device drivers installed in the kernel. Change device drivers for hardware that is not present in your system. Change IRQs, DRQs, and IO port addresses used by a device driver. After adjusting the kernel to match your hardware configuration, type Q to boot with the new settings. Once the installation has completed, any changes you made in the configuration mode will be permanent so you do not have to reconfigure every time you boot. It is still highly likely that you will eventually want to build a custom kernel. MS-DOS User's Questions and Answers DOS Many users wish to install FreeBSD on PCs inhabited by MS-DOS. Here are some commonly asked questions about installing FreeBSD on such systems. Help, I have no space! Do I need to delete everything first? If your machine is already running MS-DOS and has little or no free space available for the FreeBSD installation, all hope is not lost! You may find the FIPS utility, provided in the tools directory on the FreeBSD CDROM or various FreeBSD FTP sites to be quite useful. FIPS FIPS allows you to split an existing MS-DOS partition into two pieces, preserving the original partition and allowing you to install onto the second free piece. You first defragment your MS-DOS partition using the Windows DEFRAG utility (go into Explorer, right-click on the hard drive, and choose to defrag your hard drive), or Norton Disk Tools. You then must run FIPS. It will prompt you for the rest of the information it needs. Afterwards, you can reboot and install FreeBSD on the new free slice. See the Distributions menu for an estimate of how much free space you will need for the kind of installation you want. Partition Magic There is also a very useful product from PowerQuest called Partition Magic. This application has far more functionality than FIPS, and is highly recommended if you plan to often add/remove operating systems (like me). However, it does cost money, and if you plan to install FreeBSD once and then leave it there, FIPS will probably be fine for you. Can I use compressed MS-DOS filesystems from FreeBSD? No. If you are using a utility such as Stacker(tm) or DoubleSpace(tm), FreeBSD will only be able to use whatever portion of the filesystem you leave uncompressed. The rest of the filesystem will show up as one large file (the stacked/double spaced file!). Do not remove that file or you will probably regret it greatly! It is probably better to create another uncompressed primary MS-DOS partition and use this for communications between MS-DOS and FreeBSD. Can I mount my extended MS-DOS partition? partitions slices Yes. DOS extended partitions are mapped in at the end of the other slices in FreeBSD, e.g., your D: drive might be /dev/da0s5, your E: drive, /dev/da0s6, and so on. This example assumes, of course, that your extended partition is on SCSI drive 0. For IDE drives, substitute ad for da appropriately if installing 4.0-RELEASE or later, and substitute wd for da if you are installing a version of FreeBSD prior to 4.0. You otherwise mount extended partitions exactly like you would any other DOS drive, for example: &prompt.root; mount -t msdos /dev/ad0s5 /dos_d Advanced Installation Guide Written by &a.logo;, May 2001. This section describes how to install FreeBSD in exceptional cases. Installing FreeBSD on a system without a monitor or keyboard installationheadless (serial console) serial console This type of installation is called a "headless install", because the machine that you are trying to install FreeBSD on either doesnt have a monitor attached to it, or doesnt even have a VGA output. How is this possible you ask? Using a serial console. A serial console is basically using another machine to act as the main display and keyboard for a system. To do this, just follow these steps: Fetch the right boot floppy images First you will need to get the right disk images so that you can boot into the install program. The secret with using a serial console is that you tell the boot loader to send I/O through a serial port instead of displaying console output to the VGA device and trying to read input from a local keyboard. Enough of that now, let's get back to getting these disk images. You will need to get kern.flp and mfsroot.flp from the floppies directory. Write the image files to the floppy disks. The image files, such as kern.flp, are not regular files that you copy to the disk. Instead, they are images of the complete contents of the disk. This means that you can not use commands like DOS' copy to write the files. Instead, you must use specific tools to write the images directly to the disk. fdimage If you are creating the floppies on a computer running DOS then we provide a tool to do this called fdimage. If you are using the floppies from the CDROM, and your CDROM is the E: drive then you would run this: E:\> tools\fdimage floppies\kern.flp A: Repeat this command for each .flp file, replacing the floppy disk each time. Adjust the command line as necessary, depending on where you have placed the .flp files. If you do not have the CDROM then fdimage can be downloaded from the tools directory on the FreeBSD FTP site. If you are writing the floppies on a Unix system (such as another FreeBSD system) you can use the &man.dd.1; command to write the image files directly to disk. On FreeBSD you would run: &prompt.root; dd if=kern.flp of=/dev/fd0 On FreeBSD /dev/fd0 refers to the first floppy disk (the A: drive). /dev/rfd1 would be the B: drive, and so on. Other Unix variants might have different names for the floppy disk devices, and you will need to check the documentation for the system as necessary. Enabling the boot floppies to boot into a serial console Do not try to mount the floppy if it is write-protected mount If you were to boot into the floppies that you just made, FreeBSD would boot into its normal install mode. We want FreeBSD to boot into a serial console for our install. To do this, you have to mount the kern.flp floppy onto your FreeBSD system using the &man.mount.8; command. &prompt.root; mount /dev/fd0 /mnt Now that you have the floppy mounted, you must change into the floppy directory &prompt.root; cd /mnt Here is where you must set the floppy to boot into a serial console. You have to make a file called boot.config containing "/boot/loader -h". All this does is pass a flag to the bootloader to boot into a serial console. &prompt.root; echo "/boot/loader -h" > boot.config Now that you have your floppy configured correctly, you must unmount the floppy using the &man.umount.8; command &prompt.root; cd / &prompt.root; umount /mnt Now you can remove the floppy from the floppy drive Connecting your null modem cable null modem cable You now need to connect a null modem cable between the two machines. Just connect the cable to the serial ports of the 2 machines. A normal serial cable will not work here, you need a null modem cable because it has some of the wires inside crossed over. Booting up for the install It's now time to go ahead and start the install. Put the kern.flp floppy in the floppy drive of the machine you're doing the headless install on, and power on the machine. Connecting to your headless machine cu Now you have to connect to that machine with &man.cu.1;: &prompt.root; cu -l /dev/cuaa0 That's it! You should be able to control the headless machine through your cu session now. It will ask you to put in the mfsroot.flp, and then it will come up with a selection of what kind of terminal to use. Just select the FreeBSD color console and proceed with your install! diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml index f87dc24646..44e4672d07 100644 --- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml @@ -1,1235 +1,1235 @@ Configuring the FreeBSD Kernel Synopsis Updated and restructured by &a.jim;, March 2000. Originally contributed by &a.jehamby;, 6 October 1995. kernel building a custom kernel The following chapter of the handbook covers everything you will need to know in order to build a custom kernel. If you are wondering what the benefits of a custom kernel are, or would like to know how to configure, compile, and install a custom kernel, this chapter is for you. Why Build a Custom Kernel? Building a custom kernel is one of the most important rites of passage nearly every Unix user must endure. This process, while time consuming, will provide many benefits to your FreeBSD system. Unlike the GENERIC kernel, which must support a wide range of hardware, a custom kernel only contains support for your PC's hardware. This has a number of benefits, such as: Faster boot time. Since the kernel will only probe the hardware you have on your system, the time it takes your system to boot will decrease dramatically. Less memory use. A custom kernel often uses less memory than the GENERIC kernel, which is important because the kernel is one process that must always be present in memory. For this reason, a custom kernel is especially useful on a system with a small amount of RAM. Additional hardware support. A custom kernel allows you to add in support for devices such as sound cards, which are not present in the GENERIC kernel. Building and Installing a Custom Kernel kernel building / installing First, let us take a quick tour of the kernel build directory. All directories mentioned will be relative to the main /usr/src/sys directory, which is also accessible through /sys. There are a number of subdirectories here representing different parts of the kernel, but the most important, for our purposes, are arch/conf, where you will edit your custom kernel configuration, and compile, which is the staging area where your kernel will be built. arch represents either i386, alpha, or pc98 (an alternative development branch of PC hardware, popular in Japan). Everything inside a particular architecture's directory deals with that architecture only; the rest of the code is common to all platforms to which FreeBSD could potentially be ported. Notice the logical organization of the directory structure, with each supported device, filesystem, and option in its own subdirectory. If there is not a /usr/src/sys directory on your system, then the kernel source has not been installed. The easiest way to do this is by running /stand/sysinstall as root, choosing Configure, then Distributions, then src, then sys. Next, move to the arch/conf directory and copy the GENERIC configuration file to the name you want to give your kernel. For example: &prompt.root; cd /usr/src/sys/i386/conf &prompt.root; cp GENERIC MYKERNEL Traditionally, this name is in all capital letters and, if you are maintaining multiple FreeBSD machines with different hardware, it is a good idea to name it after your machine's hostname. We will call it MYKERNEL for the purpose of this example. Storing your kernel config file directly under /usr/src can be a bad idea. If you are experiencing problems it can be tempting to just delete /usr/src and start again. Five seconds after you do that you realise that you have deleted your custom kernel config file. You might want to keep your kernel config file elsewhere, and then create a symbolic link to the file in the i386 directory. For example: &prompt.root; cd /usr/src/sys/i386/conf &prompt.root; mkdir /root/kernels &prompt.root; cp GENERIC /root/kernels/MYKERNEL &prompt.root; ln -s /root/kernels/MYKERNEL You must execute these and all of the following commands under the root account or you will get permission denied errors. Now, edit MYKERNEL with your favorite text editor. If you are just starting out, the only editor available will probably be vi, which is too complex to explain here, but is covered well in many books in the bibliography. However, FreeBSD does offer an easier editor called ee which, if you are a beginner, should be your editor of choice. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from GENERIC. SunOS If you have built a kernel under SunOS or some other BSD operating system, much of this file will be very familiar to you. If you are coming from some other operating system such as DOS, on the other hand, the GENERIC configuration file might seem overwhelming to you, so follow the descriptions in the Configuration File section slowly and carefully. Be sure to always check the file /usr/src/UPDATING, before you perform any update steps, in the case you sync your source-tree with the latest sources of the FreeBSD project. In this file all important issues with updating FreeBSD are written down. /usr/src/UPDATING always fits to your version of the FreeBSD source, and is therefore more accurate for those information than the handbook. You must now compile the source code for the kernel. There are two procedures you can use to do this, and the one you will use depends on why you are rebuilding the kernel, and the version of FreeBSD you are running. If you have installed only the kernel source code, use procedure 1. If you are running a FreeBSD version prior to 4.0, and you are not upgrading to FreeBSD 4.0 or higher using the make world procedure, use procedure 1. If you are building a new kernel without updating the source code (perhaps just to add a new option, such as IPFIREWALL) you can use either procedure. If you are rebuilding the kernel as part of a make world process, use procedure 2. Procedure 1. Building a kernel the <quote>traditional</quote> way Run &man.config.8; to generate the kernel source code. &prompt.root; /usr/sbin/config MYKERNEL Change in to the build directory. &prompt.root; cd ../../compile/MYKERNEL Compile the kernel. &prompt.root; make depend &prompt.root; make Install the new kernel. &prompt.root; make install Procedure 2. Building a kernel the <quote>new</quote> way Change to the /usr/src directory &prompt.root; cd /usr/src Compile the kernel. &prompt.root; make buildkernel KERNCONF=MYKERNEL Install the new kernel. &prompt.root; make installkernel KERNCONF=MYKERNEL In FreeBSD 4.2 and older you must replace KERNCONF= with KERNEL=. 4.2-STABLE that was fetched after Feb 2nd, 2001 does recognize KERNCONF= CVSup anoncvs CTM CVS anonymous If you have not upgraded your source tree in any way (you have not run CVSup, CTM, or used anoncvs), then you should use the config, make depend, make, make install sequence. kernel.old The new kernel will be copied to the root directory as /kernel and the old kernel will be moved to /kernel.old. Now, shutdown the system and reboot to use your kernel. In case something goes wrong, there are some troubleshooting instructions at the end of this document. Be sure to read the section which explains how to recover in case your new kernel does not boot. If you have added any new devices (such as sound cards) you may have to add some device nodes to your /dev directory before you can use them. The Configuration File kernelLINT LINT kernel config file The general format of a configuration file is quite simple. Each line contains a keyword and one or more arguments. For simplicity, most lines only contain one argument. Anything following a # is considered a comment and ignored. The following sections describe each keyword, generally in the order they are listed in GENERIC, although some related keywords have been grouped together in a single section (such as Networking) even though they are actually scattered throughout the GENERIC file. An exhaustive list of options and more detailed explanations of the device lines is present in the LINT configuration file, located in the same directory as GENERIC. If you are in doubt as to the purpose or necessity of a line, check first in LINT. Quoting numbers In all versions of FreeBSD up to and including 3.X, &man.config.8; required that any strings in the configuration file that contained numbers used as text had to be enclosed in double quotes. This requirement was removed in the 4.X branch, which this book covers, so if you are on a pre-4.X system, see the /usr/src/sys/i386/conf/LINT and /usr/src/sys/i386/conf/GENERIC files on your system for examples. kernel example config The following is an example GENERIC kernel configuration file with various additional comments where needed for clarity. This example should match your copy in /usr/src/sys/i386/conf/GENERIC fairly closely. For details of all the possible kernel options, see /usr/src/sys/i386/conf/LINT. # # GENERIC -- Generic kernel configuration file for FreeBSD/i386 # # For more information on this file, please read the handbook section on # Kernel Configuration Files: # # http://www.freebsd.org/handbook/kernelconfig-config.html # # The handbook is also available locally in /usr/share/doc/handbook # if you've installed the doc distribution, otherwise always see the # FreeBSD World Wide Web server (http://www.FreeBSD.ORG/) for the # latest information. # # An exhaustive list of options and more detailed explanations of the # device lines is also present in the ./LINT configuration file. If you are # in doubt as to the purpose or necessity of a line, check first in LINT. # # $FreeBSD: src/sys/i386/conf/GENERIC,v 1.246 2000/03/09 16:32:55 jlemon Exp $ The following are the mandatory keywords required in every kernel you build: kernel options machine machine i386 This is the machine architecture. It must be either i386, alpha, or pc98. kernel options cpu cpu I386_CPU cpu I486_CPU cpu I586_CPU cpu I686_CPU The above specifies the type of CPU you have in your system. You may have multiple instances of the CPU line (i.e., you are not sure whether you should use I586_CPU or I686_CPU), however, for a custom kernel, it is best to specify only the CPU you have. If you are unsure which type your CPU use, you can use the dmesg command to view your boot up messages. kernel options cpu type The Alpha architecture has different values for cpu_type. They include: cpu EV4 cpu EV5 If you are using an Alpha machine, you should be using one of the above CPU types. kernel options ident ident GENERIC This is the identification of the kernel. You should change this to whatever you named your kernel, in our previous example, MYKERNEL. The value you put in the ident string will print when you boot up the kernel, so it is useful to give a kernel a different name if you want to keep it separate from your usual kernel (i.e., you want to build an experimental kernel). kernel options maxusers maxusers 32 The maxusers option sets the size of a number of important system tables. This number is supposed to be roughly equal to the number of simultaneous users you expect to have on your machine. However, under normal circumstances, you will want to set maxusers to at least 4, especially if you are using the X Window System or compiling software. The reason is that the most important table set by maxusers is the maximum number of processes, which is set to 20 + 16 * maxusers, so if you set maxusers to 1, then you can only have 36 simultaneous processes, including the 18 or so that the system starts up at boot time, and the 15 or so you will probably create when you start the X Window System. Even a simple task like reading a man page will start up nine processes to filter, decompress, and view it. Setting maxusers to 64 will allow you to have up to 1044 simultaneous processes, which should be enough for nearly all uses. If, however, you see the dreaded proc table full error when trying to start another program, or are running a server with a large number of simultaneous users (like ftp.FreeBSD.org), you can always increase the number and rebuild. maxusers does not limit the number of users which can log into your machine. It simply sets various table sizes to reasonable values considering the maximum number of users you will likely have on your system and how many processes each of them will be running. One keyword which does limit the number of simultaneous remote logins is pseudo-device pty 16. Everything that follows is more or less optional. See the notes underneath or next to each option for more information. #makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols options MATH_EMULATE #Support for x87 emulation This line allows the kernel to simulate a math co-processor if your computer does not have one (386 or 486SX). If you have a 486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or higher (Pentium, Pentium II, etc.), you can comment this line out. The normal math co-processor emulation routines that come with FreeBSD are not very accurate. If you do not have a math co-processor, and you need the best accuracy, it is recommended that you change this option to GPL_MATH_EMULATION to use the GNU math support, which is not included by default for licensing reasons. options INET #InterNETworking Networking support. Leave this in, even if you do not plan to be connected to a network. Most programs require at least loopback networking (i.e., making network connections within your PC), so this is essentially mandatory. options INET6 #IPv6 communications protocols This enables the IPv6 communication protocols. options FFS #Berkeley Fast Filesystem options FFS_ROOT #FFS usable as root device [keep this!] This is the basic hard drive filesystem. Leave it in if you boot from the hard disk. options MFS #Memory Filesystem options MD_ROOT #MD is a potential root device This is the memory-mapped filesystem. This is basically a RAM disk for fast storage of temporary files, useful if you have a lot of swap space that you want to take advantage of. A perfect place to mount an MFS partition is on the /tmp directory, since many programs store temporary data here. To mount an MFS RAM disk on /tmp, add the following line to /etc/fstab: /dev/ad1s2b /tmp mfs rw 0 0 Now you simply need to either reboot, or run the command mount /tmp. kernel options NFS kernel options NFS_ROOT options NFS #Network Filesystem options NFS_ROOT #NFS usable as root device, NFS required The network filesystem. Unless you plan to mount partitions from a Unix file server over TCP/IP, you can comment these out. kernel options MSDOSFS options MSDOSFS #MSDOS Filesystem The MS-DOS filesystem. Unless you plan to mount a DOS formatted hard drive partition at boot time, you can safely comment this out. It will be automatically loaded the first time you mount a DOS partition, as described above. Also, the excellent mtools software (in the ports collection) allows you to access DOS floppies without having to mount and unmount them (and does not require MSDOSFS at all). options CD9660 #ISO 9660 Filesystem options CD9660_ROOT #CD-ROM usable as root, CD9660 required The ISO 9660 filesystem for CDROMs. Comment it out if you do not have a CDROM drive or only mount data CDs occasionally (since it will be dynamically loaded the first time you mount a data CD). Audio CDs do not need this filesystem. options PROCFS #Process filesystem The process filesystem. This is a pretend filesystem mounted on /proc which allows programs like &man.ps.1; to give you more information on what processes are running. options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!] Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out. options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI This causes the kernel to pause for 15 seconds before probing each SCSI device in your system. If you only have IDE hard drives, you can ignore this, otherwise you will probably want to lower this number, perhaps to 5 seconds, to speed up booting. Of course, if you do this, and FreeBSD has trouble recognizing your SCSI devices, you will have to raise it back up. options UCONSOLE #Allow users to grab the console Allow users to grab the console, which is useful for X users. For example, you can create a console xterm by typing xterm -C, which will display any write, talk, and any other messages you receive, as well as any console messages sent by the kernel. options USERCONFIG #boot -c editor This option allows you to boot the configuration editor from the boot menu. options VISUAL_USERCONFIG #visual boot -c editor This option allows you to boot the visual configuration editor from the boot menu. options KTRACE #ktrace(1) support This enables kernel process tracing, which is useful in debugging. options SYSVSHM #SYSV-style shared memory This option provides for System V shared memory. The most common use of this is the XSHM extension in X, which many graphics-intensive programs will automatically take advantage of for extra speed. If you use X, you'll definitely want to include this. options SYSVSEM #SYSV-style semaphores Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel. options SYSVMSG #SYSV-style message queues Support for System V messages. Again, only adds a few hundred bytes to the kernel. The &man.ipcs.1; command will list any processes using each of these System V facilities. options P1003_1B #Posix P1003_1B real-time extensions options _KPOSIX_PRIORITY_SCHEDULING Real-time extensions added in the 1993 POSIX. Certain applications in the ports collection use these (such as Star Office). kernel options ICMP_BANDLIM options ICMP_BANDLIM #Rate limit bad replies This option enables ICMP error response bandwidth limiting. You typically want this option as it will help protect the machine from denial of service packet attacks. kernel options SMP # To make an SMP kernel, the next two are needed #options SMP # Symmetric MultiProcessor Kernel #options APIC_IO # Symmetric (APIC) I/O The above are both required for SMP support. device isa All PCs supported by FreeBSD have one of these. If you have an IBM PS/2 (Micro Channel Architecture), you cannot run FreeBSD at this time (support is being worked on). device eisa Include this if you have an EISA motherboard. This enables auto-detection and configuration support for all devices on the EISA bus. device pci Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to ISA bus. # Floppy drives device fdc0 at isa? port IO_FD1 irq 6 drq 2 device fd0 at fdc0 drive 0 device fd1 at fdc0 drive 1 This is the floppy drive controller. fd0 is the A: floppy drive, and fd1 is the B: drive. device ata This driver supports all ATA and ATAPI devices. You only need one device ata line for the kernel to detect all PCI ATA/ATAPI devices on modern machines. device atadisk # ATA disk drives This is needed along with device ata for ATAPI disk drives. device atapicd # ATAPI CDROM drives This is needed along with device ata for ATAPI CDROM drives. device atapifd # ATAPI floppy drives This is needed along with device ata for ATAPI floppy drives. device atapist # ATAPI tape drives This is needed along with device ata for ATAPI tape drives. options ATA_STATIC_ID #Static device numbering This makes the controller number static (like the old driver) or else the device numbers are dynamically allocated. # ATA and ATAPI devices device ata0 at isa? port IO_WD1 irq 14 device ata1 at isa? port IO_WD2 irq 15 Use the above for older, non-PCI systems. # SCSI Controllers device ahb # EISA AHA1742 family device ahc # AHA2940 and onboard AIC7xxx devices device amd # AMD 53C974 (Teckram DC-390(T)) device dpt # DPT Smartcache - See LINT for options! device isp # Qlogic family device ncr # NCR/Symbios Logic device sym # NCR/Symbios Logic (newer chipsets) device adv0 at isa? device adw device bt0 at isa? device aha0 at isa? device aic0 at isa? SCSI controllers. Comment out any you do not have in your system. If you have an IDE only system, you can remove these altogether. # SCSI peripherals device scbus # SCSI bus (required) device da # Direct Access (disks) device sa # Sequential Access (tape etc) device cd # CD device pass # Passthrough device (direct SCSI access) SCSI peripherals. Again, comment out any you do not have, or if you have only IDE hardware, you can remove them completely. # RAID controllers device ida # Compaq Smart RAID device amr # AMI MegaRAID device mlx # Mylex DAC960 family Supported RAID controllers. If you do not have any of these, you can comment them out or remove them. # atkbdc0 controls both the keyboard and the PS/2 mouse device atkbdc0 at isa? port IO_KBD The keyboard controller (atkbdc) provides I/O services for the AT keyboard and PS/2 style pointing devices. This controller is required by the keyboard driver (atkbd) and the PS/2 pointing device driver (psm). device atkbd0 at atkbdc? irq 1 The atkbd driver, together with atkbdc controller, provides access to the AT 84 keyboard or the AT enhanced keyboard which is connected to the AT keyboard controller. device psm0 at atkbdc? irq 12 Use this device if your mouse plugs into the PS/2 mouse port. device vga0 at isa? The video card driver. # splash screen/screen saver pseudo-device splash Splash screen at start up! Screen savers require this too. # syscons is the default console driver, resembling an SCO console device sc0 at isa? sc0 is the default console driver, which resembles a SCO console. Since most full-screen programs access the console through a terminal database library like termcap, it should not matter whether you use this or vt0, the VT220 compatible console driver. When you log in, set your TERM variable to scoansi if full-screen programs have trouble running under this console. # Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver #device vt0 at isa? #options XSERVER # support for X server on a vt console #options FAT_CURSOR # start with block cursor # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines #options PCVT_SCANSET=2 # IBM keyboards are non-std This is a VT220-compatible console driver, backward compatible to VT100/102. It works well on some laptops which have hardware incompatibilities with sc0. Also set your TERM variable to vt100 or vt220 when you log in. This driver might also prove useful when connecting to a large number of different machines over the network, where termcap or terminfo entries for the sc0 device are often not available — vt100 should be available on virtually any platform. # Floating point support - do not disable. device npx0 at nexus? port IO_NPX irq 13 npx0 is the interface to the floating point math unit in FreeBSD, which is either the hardware co-processor or the software math emulator. This is not optional. # Power management support (see LINT for more options) device apm0 at nexus? disable flags 0x20 # Advanced Power Management Advanced Power Management support. Useful for laptops. # PCCARD (PCMCIA) support device card device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000 device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable PCMCIA support. You need this if you are installing on a laptop. # Serial (COM) ports device sio0 at isa? port IO_COM1 flags 0x10 irq 4 device sio1 at isa? port IO_COM2 irq 3 device sio2 at isa? disable port IO_COM3 irq 5 device sio3 at isa? disable port IO_COM4 irq 9 These are the four serial ports referred to as COM1 through COM4 in the MS-DOS/Windows world. If you have an internal modem on COM4 and a serial port at COM2, you will have to change the IRQ of the modem to 2 (for obscure technical reasons, IRQ2 = IRQ 9) in order to access it from FreeBSD. If you have a multiport serial card, check the manual page for &man.sio.4; for more information on the proper values for these lines. Some video cards (notably those based on S3 chips) use IO addresses in the form of 0x*2e8, and since many cheap serial cards do not fully decode the 16-bit IO address space, they clash with these cards making the COM4 port practically unavailable. Each serial port is required to have a unique IRQ (unless you are using one of the multiport cards where shared interrupts are supported), so the default IRQs for COM3 and COM4 cannot be used. # Parallel port device ppc0 at isa? irq 7 This is the ISA-bus parallel port interface. device ppbus # Parallel port bus (required) Provides support for the parallel port bus. device lpt # Printer Support for parallel port printers. All three of the above are required to enable parallel printer support. device plip # TCP/IP over parallel This is the driver for the parallel network interface. device ppi # Parallel port interface device The general-purpose I/O (geek port) + IEEE1284 I/O. #device vpo # Requires scbus and da zip drive This is for an Iomega Zip drive. It requires scbus and da support. Best performance is achieved with ports in EPP 1.9 mode. # PCI Ethernet NICs. device de # DEC/Intel DC21x4x (Tulip) device fxp # Intel EtherExpress PRO/100B (82557, 82558) device tx # SMC 9432TX (83c170 EPIC) device vx # 3Com 3c590, 3c595 (Vortex) device wx # Intel Gigabit Ethernet Card (Wiseman) Various PCI network card drivers. Comment out or remove any of these not present in your system. # PCI Ethernet NICs that use the common MII bus controller code. device miibus # MII bus support - MII bus support is required for some PCI 10/100 ethernet NICs, + MII bus support is required for some PCI 10/100 Ethernet NICs, namely those which use MII-compliant transceivers or implement transceiver control interfaces that operate like an MII. Adding device miibus to the kernel config pulls in support for the generic miibus API and all of the PHY drivers, including a generic one for PHYs that are not specifically handled by an individual driver device dc # DEC/Intel 21143 and various workalikes device rl # RealTek 8129/8139 device sf # Adaptec AIC-6915 (Starfire) device sis # Silicon Integrated Systems SiS 900/SiS 7016 device ste # Sundance ST201 (D-Link DFE-550TX) device tl # Texas Instruments ThunderLAN device vr # VIA Rhine, Rhine II device wb # Winbond W89C840F device xl # 3Com 3c90x (Boomerang, Cyclone) Drivers that use the MII bus controller code. # ISA Ethernet NICs. device ed0 at isa? port 0x280 irq 10 iomem 0xd8000 device ex device ep # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really # exists only as a PCMCIA device, so there is no ISA attachment needed # and resources will always be dynamically assigned by the pccard code. device wi # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP # mode (the factory default). If you set the switches on your ISA # card for a manually chosen I/O address and IRQ, you must specify # those parameters here. device an # The probe order of these is presently determined by i386/isa/isa_compat.c. device ie0 at isa? port 0x300 irq 10 iomem 0xd0000 device fe0 at isa? port 0x300 device le0 at isa? port 0x300 irq 5 iomem 0xd0000 device lnc0 at isa? port 0x280 irq 10 drq 0 device cs0 at isa? port 0x300 device sn0 at isa? port 0x300 irq 10 # requires PCCARD (PCMCIA) support to be activated #device xe0 at isa? - ISA ethernet drivers. See + ISA Ethernet drivers. See /usr/src/sys/i386/conf/LINT for which cards are supported by which driver. # Pseudo devices - the number indicates how many units to allocate. pseudo-device loop # Network loopback This is the generic loopback device for TCP/IP. If you telnet or FTP to localhost (a.k.a., 127.0.0.1) it will come back at you through this pseudo-device. This is mandatory. pseudo-device ether # Ethernet support ether is only needed if you have an Ethernet card. It includes generic Ethernet protocol code. pseudo-device sl 1 # Kernel SLIP sl is for SLIP support. This has been almost entirely supplanted by PPP, which is easier to set up, better suited for modem-to-modem connection, and more powerful. The number after sl specifies how many simultaneous SLIP sessions to support. pseudo-device ppp 1 # Kernel PPP This is for kernel PPP support for dial-up connections. There is also a version of PPP implemented as a userland application that uses tun and offers more flexibility and features such as demand dialing. The number after ppp specifies how many simultaneous PPP connections to support. pseudo-device tun # Packet tunnel. This is used by the userland PPP software. The number after tun specifies the number of simultaneous PPP sessions to support. See the PPP section of this book for more information. pseudo-device pty # Pseudo-ttys (telnet etc) This is a pseudo-terminal or simulated login port. It is used by incoming telnet and rlogin sessions, xterm, and some other applications such as emacs. The number indicates the number of ptys to create. If you need more than the default of 16 simultaneous xterm windows and/or remote logins, be sure to increase this number accordingly, up to a maximum of 256. pseudo-device md # Memory disks Memory disk pseudo-devices. pseudo-device gif 4 # IPv6 and IPv4 tunneling This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. pseudo-device faith 1 # IPv6-to-IPv4 relaying (translation) This pseudo-device captures packets that are sent to it and diverts them to the IPv4/IPv6 translation daemon. # The `bpf' pseudo-device enables the Berkeley Packet Filter. # Be aware of the administrative consequences of enabling this! pseudo-device bpf # Berkeley packet filter This is the Berkeley Packet Filter. This pseudo-device allows network interfaces to be placed in promiscuous mode, capturing every - packet on a broadcast network (e.g., an ethernet). These packets + packet on a broadcast network (e.g., an Ethernet). These packets can be captured to disk and or examined with the &man.tcpdump.1; program. # USB support #device uhci # UHCI PCI->USB interface #device ohci # OHCI PCI->USB interface #device usb # USB Bus (required) #device ugen # Generic #device uhid # Human Interface Devices #device ukbd # Keyboard #device ulpt # Printer #device umass # Disks/Mass storage - Requires scbus and da #device ums # Mouse # USB Ethernet, requires mii #device aue # ADMtek USB ethernet #device cue # CATC USB ethernet #device kue # Kawasaki LSI USB ethernet Support for various USB devices. For more information and additional devices supported by FreeBSD, see /usr/src/sys/i386/conf/LINT. Making Device Nodes device nodes MAKEDEV Almost every device in the kernel has a corresponding node entry in the /dev directory. These nodes look like regular files, but are actually special entries into the kernel which programs use to access the device. The shell script /dev/MAKEDEV, which is executed when you first install the operating system, creates nearly all of the device nodes supported. However, it does not create all of them, so when you add support for a new device, it pays to make sure that the appropriate entries are in this directory, and if not, add them. Here is a simple example: Suppose you add the IDE CD-ROM support to the kernel. The line to add is: device acd0 This means that you should look for some entries that start with acd0 in the /dev directory, possibly followed by a letter, such as c, or preceded by the letter r, which means a raw device. It turns out that those files are not there, so you must change to the /dev directory and type: MAKEDEV &prompt.root; sh MAKEDEV acd0 When this script finishes, you will find that there are now acd0c and racd0c entries in /dev so you know that it executed correctly. For sound cards, the following command creates the appropriate entries: &prompt.root; sh MAKEDEV snd0 When creating device nodes for devices such as sound cards, if other people have access to your machine, it may be desirable to protect the devices from outside access by adding them to the /etc/fbtab file. See &man.fbtab.5; for more information. Follow this simple procedure for any other non-GENERIC devices which do not have entries. All SCSI controllers use the same set of /dev entries, so you do not need to create these. Also, network cards and SLIP/PPP pseudo-devices do not have entries in /dev at all, so you do not have to worry about these either. If Something Goes Wrong There are four categories of trouble that can occur when building a custom kernel. They are: config fails If the config command fails when you give it your kernel description, you have probably made a simple error somewhere. Fortunately, config will print the line number that it had trouble with, so you can quickly skip to it with vi. For example, if you see: config: line 17: syntax error You can skip to the problem in vi by typing 17G in command mode. Make sure the keyword is typed correctly, by comparing it to the GENERIC kernel or another reference. make fails If the make command fails, it usually signals an error in your kernel description, but not severe enough for config to catch it. Again, look over your configuration, and if you still cannot resolve the problem, send mail to the &a.questions; with your kernel configuration, and it should be diagnosed very quickly. The kernel will not boot If your new kernel does not boot, or fails to recognize your devices, do not panic! Fortunately, BSD has an excellent mechanism for recovering from incompatible kernels. Simply choose the kernel you want to boot from at the FreeBSD boot loader (i.e., boot kernel.old). When reconfiguring a kernel, it is always a good idea to keep a kernel that is known to work on hand. After booting with a good kernel you can check over your configuration file and try to build it again. One helpful resource is the /var/log/messages file which records, among other things, all of the kernel messages from every successful boot. Also, the &man.dmesg.8; command will print the kernel messages from the current boot. If you are having trouble building a kernel, make sure to keep a GENERIC, or some other kernel that is known to work on hand as a different name that will not get erased on the next build. You cannot rely on kernel.old because when installing a new kernel, kernel.old is overwritten with the last installed kernel which may be non-functional. Also, as soon as possible, move the working kernel to the proper kernel location or commands such as &man.ps.1; will not work properly. The proper command to unlock the kernel file that make installs (in order to move another kernel back permanently) is: &prompt.root; chflags noschg /kernel And, if you want to lock your new kernel into place, or any file for that matter, so that it cannot be moved or tampered with: &prompt.root; chflags schg /kernel The kernel works, but ps does not work any more! If you have installed a different version of the kernel from the one that the system utilities have been built with, for example, a 4.X kernel on a 3.X system, many system-status commands like &man.ps.1; and &man.vmstat.8; will not work any more. You must recompile the libkvm library as well as these utilities. This is one reason it is not normally a good idea to use a different version of the kernel from the rest of the operating system. diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml index 9b1b3a32dd..aca2a11be0 100644 --- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml @@ -1,2247 +1,2247 @@ Linux Binary Compatibility Restructured and parts updated by &a.jim;, 22 March 2000. Originally contributed by &a.handy; and &a.rich; Synopsis Linux binary compatibility binary compatibility Linux The following chapter will cover FreeBSD's Linux binary compatibility features, how to install it, and how it works. At this point, you may be asking yourself why exactly, does FreeBSD need to be able to run Linux binaries? The answer to that question is quite simple. Many companies and developers develop only for Linux, since it is the latest hot thing in the computing world. That leaves the rest of us FreeBSD users bugging these same companies and developers to put out native FreeBSD versions of their applications. The problem is, that most of these companies do not really realize how many people would use their product if there were FreeBSD versions too, and most continue to only develop for Linux. So what is a FreeBSD user to do? This is where the Linux binary compatibility of FreeBSD comes into play. In a nutshell, the compatibility allows FreeBSD users to run about 90% of all Linux applications without modification. This includes applications such as Star Office, the Linux version of Netscape, Adobe Acrobat, RealPlayer 5 and 7, VMWare, Oracle, WordPerfect, Doom, Quake, and more. It is also reported that in some situations, Linux binaries perform better on FreeBSD than they do under Linux. Linux /proc filesystem There are, however, some Linux-specific operating system features that are not supported under FreeBSD. Linux binaries will not work on FreeBSD if they overly use the Linux /proc filesystem (which is different from FreeBSD's /proc filesystem), or i386-specific calls, such as enabling virtual 8086 mode. For information on installing the Linux binary compatibility mode, see the next section. Installation With the advent of 3.0-RELEASE, it is no longer necessary to specify options LINUX or options COMPAT_LINUX in your kernel configuration. KLD (kernel loadable object) The Linux binary compatibility is now done via a KLD object (Kernel LoaDable object), so it can be installed on-the-fly without having to reboot. You will, however, need to have the following in /etc/rc.conf: linux_enable=YES This, in turn, triggers the following action in /etc/rc.i386: # Start the Linux binary compatibility if requested. # case ${linux_enable} in [Yy][Ee][Ss]) echo -n ' linux'; linux > /dev/null 2>&1 ;; esac If you wish to verify that the KLD is loaded, kldstat will do that: &prompt.user; kldstat Id Refs Address Size Name 1 2 0xc0100000 16bdb8 kernel 7 1 0xc24db000 d000 linux.ko kernel options LINUX If for some reason you do not want to or cannot load the KLD, then you may statically link the binary compatibility in the kernel by adding options LINUX to your kernel configuration file. Then install your new kernel as described in the kernel configuration section of this handbook. Installing Linux Runtime Libraries Linux installing Linux libraries This can be done one of two ways, either by using the linux_base port, or by installing them manually. Installing using the linux_base port ports collection This is by far the easiest method to use when installing the runtime libraries. It is just like installing any other port from the ports collection. Simply do the following: &prompt.root; cd /usr/ports/emulators/linux_base &prompt.root; make install distclean You should now have working Linux binary compatibility. Some programs may complain about incorrect minor versions of the system libraries. In general, however, this does not seem to be a problem. Installing libraries manually If you do not have the ports collection installed, you can install the libraries by hand instead. You will need the Linux shared libraries that the program depends on and the runtime linker. Also, you will need to create a shadow root directory, /compat/linux, for Linux libraries on your FreeBSD system. Any shared libraries opened by Linux programs run under FreeBSD will look in this tree first. So, if a Linux program loads, for example, /lib/libc.so, FreeBSD will first try to open /compat/linux/lib/libc.so, and if that does not exist, it will then try /lib/libc.so. Shared libraries should be installed in the shadow tree /compat/linux/lib rather than the paths that the Linux ld.so reports. Generally, you will need to look for the shared libraries that Linux binaries depend on only the first few times that you install a Linux program on your FreeBSD system. After a while, you will have a sufficient set of Linux shared libraries on your system to be able to run newly imported Linux binaries without any extra work. How to install additional shared libraries shared libraries What if you install the linux_base port and your application still complains about missing shared libraries? How do you know which shared libraries Linux binaries need, and where to get them? Basically, there are 2 possibilities (when following these instructions you will need to be root on your FreeBSD system). If you have access to a Linux system, see what shared libraries the application needs, and copy them to your FreeBSD system. Look at the following example: Let us assume you used FTP to get the Linux binary of Doom, and put it on a Linux system you have access to. You then can check which shared libraries it needs by running ldd linuxdoom, like so: &prompt.user; ldd linuxdoom libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 symbolic links You would need to get all the files from the last column, and put them under /compat/linux, with the names in the first column as symbolic links pointing to them. This means you eventually have these files on your FreeBSD system: /compat/linux/usr/X11/lib/libXt.so.3.1.0 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
Note that if you already have a Linux shared library with a matching major revision number to the first column of the ldd output, you will not need to copy the file named in the last column to your system, the one you already have should work. It is advisable to copy the shared library anyway if it is a newer version, though. You can remove the old one, as long as you make the symbolic link point to the new one. So, if you have these libraries on your system: /compat/linux/lib/libc.so.4.6.27 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27 and you find a new binary that claims to require a later version according to the output of ldd: libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29 If it is only one or two versions out of date in the in the trailing digit then do not worry about copying /lib/libc.so.4.6.29 too, because the program should work fine with the slightly older version. However, if you like, you can decide to replace the libc.so anyway, and that should leave you with: /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
The symbolic link mechanism is only needed for Linux binaries. The FreeBSD runtime linker takes care of looking for matching major revision numbers itself and you do not need to worry about it.
Installing Linux ELF binaries Linux ELF binaries ELF binaries sometimes require an extra step of branding. If you attempt to run an unbranded ELF binary, you will get an error message like the following; &prompt.user; ./my-linux-elf-binary ELF binary type not known Abort To help the FreeBSD kernel distinguish between a FreeBSD ELF binary from a Linux binary, use the &man.brandelf.1; utility. &prompt.user; brandelf -t Linux my-linux-elf-binary GNU toolchain The GNU toolchain now places the appropriate branding information into ELF binaries automatically, so you this step should become increasingly more rare in the future. Configuring the host name resolver If DNS does not work or you get this message: resolv+: "bind" is an invalid keyword resolv+: "hosts" is an invalid keyword You will need to configure a /compat/linux/etc/host.conf file containing: order hosts, bind multi on The order here specifies that /etc/hosts is searched first and DNS is searched second. When /compat/linux/etc/host.conf is not installed, linux applications find FreeBSD's /etc/host.conf and complain about the incompatible FreeBSD syntax. You should remove bind if you have not configured a name server using the /etc/resolv.conf file. Installing Mathematica Updated for Mathematica version 4.X by &a.murray and merged with work by Bojan Bistrovic bojanb@physics.odu.edu. applications Mathematica This document describes the process of installing the Linux version of Mathematica 4.X onto a FreeBSD system. The Linux version of Mathematica runs perfectly under FreeBSD however the binaries shipped by Wolfram need to be branded so that FreeBSD knows to use the Linux ABI to execute them. The Linux version of Mathematica or Mathematica for Students can be ordered directly from Wolfram at http://www.wolfram.com/. Branding the Linux binaries The Linux binaries are located in the Unix directory of the Mathematica CDROM distributed by Wolfram. You need to copy this directory tree to your local hard drive so that you can brand the Linux binaries with &man.brandelf.1; before running the installer: &prompt.root; mount /cdrom &prompt.root; cp -rp /cdrom/Unix/ /localdir/ &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm &prompt.root; cd /localdir/Installers/Linux/ &prompt.root; ./MathInstaller Alternatively, you can simply set the default ELF brand to Linux for all unbranded binaries with the command: &prompt.root; sysctl -w kern.fallback_elf_brand=3 This will make FreeBSD assume that unbranded ELF binaries use the Linux ABI and so you should be able to run the installer straight from the CDROM. Obtaining your Mathematica Password Before you can run Mathematica you will have to obtain a password from Wolfram that corresponds to your machine ID. Ethernet MAC address Once you have installed the Linux compatibility runtime libraries and unpacked Mathematica you can obtain the machine ID by running the program mathinfo in the Install directory. This machine ID is based solely on the MAC address of your first - ethernet card. + Ethernet card. &prompt.root; cd /localdir/Files/SystemFiles/Installation/Binaries/Linux &prompt.root; mathinfo disco.example.com 7115-70839-20412 When you register with Wolfram, either by email, phone or fax, you will give them the machine ID and they will respond with a corresponding password consisting of groups of numbers. You can then enter this information when you attempt to run Mathematica for the first time exactly as you would for any other Mathematica platform. Running the Mathematica front end over a network Mathematica uses some special fonts to display characters not present in any of the standard font sets (integrals, sums, greek letters, etc.). The X protocol requires these fonts to be install locally. This means you will have to copy these fonts from the CDROM or from a host with Mathematica installed to your local machine. These fonts are normally stored in /cdrom/Unix/Files/SystemFiles/Fonts on the CDROM, or /usr/local/mathematica/SystemFiles/Fonts on your hard drive. The actual fonts are in the subdirectories Type1 and X. There are several ways to use them, as described below. The first way is to copy them into one of the existing font directories in /usr/X11R6/lib/X11/fonts. This will require editing the fonts.dir file, adding the font names to it, and changing the number of fonts on the first line. Alternatively, you should also just be able to run mkfontdir in the directory you have copied them to. The second way to do this is to copy the directories to /usr/X11R6/lib/X11/fonts: &prompt.root; cd /usr/X11R6/lib/X11/fonts &prompt.root; mkdir X &prompt.root; mkdir MathType1 &prompt.root; cd /cdrom/Unix/Files/SystemFiles/Fonts &prompt.root; cp X/* /usr/X11R6/lib/X11/fonts/X &prompt.root; cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1 &prompt.root; cd /usr/X11R6/lib/X11/fonts/X &prompt.root; mkfontdir &prompt.root; cd ../MathType1 &prompt.root; mkfontdir Now add the new font directories to your font path: &prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/X &prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/MathType1 &prompt.root; xset fp rehash If you are using the XFree86 server, you can have these font directories loaded automatically by adding them to your XF86Config file. fonts If you do not already have a directory called /usr/X11R6/lib/X11/fonts/Type1, you can change the name of the MathType1 directory in the example above to Type1. Installing Oracle Contributed by Marcel Moolenaar marcel@cup.hp.com applications Oracle Preface This document describes the process of installing Oracle 8.0.5 and Oracle 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD machine Installing the Linux environment Make sure you have both linux_base and linux_devtools from the ports collection installed. These ports are added to the collection after the release of FreeBSD 3.2. If you are using FreeBSD 3.2 or an older version for that matter, update your ports collection. You may want to consider updating your FreeBSD version too. If you run into difficulties with linux_base-6.1 or linux_devtools-6.1 you may have to use version 5.2 of these packages. If you want to run the intelligent agent, you'll - also need to install the Red Hat TCL package: + also need to install the Red Hat Tcl package: tcl-8.0.3-20.i386.rpm. The general command for installing packages with the official RPM port is : &prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm package Installation of the package should not generate any errors. Creating the Oracle environment Before you can install Oracle, you need to set up a proper environment. This document only describes what to do specially to run Oracle for Linux on FreeBSD, not what has been described in the Oracle installation guide. Kernel Tuning kernel tuning As described in the Oracle installation guide, you need to set the maximum size of shared memory. Don't use SHMMAX under FreeBSD. SHMMAX is merely calculated out of SHMMAXPGS and PGSIZE. Therefore define SHMMAXPGS. All other options can be used as described in the guide. For example: options SHMMAXPGS=10000 options SHMMNI=100 options SHMSEG=10 options SEMMNS=200 options SEMMNI=70 options SEMMSL=61 Set these options to suit your intended use of Oracle. Also, make sure you have the following options in your kernel config-file: options SYSVSHM #SysV shared memory options SYSVSEM #SysV semaphores options SYSVMSG #SysV interprocess communication Oracle account Create an Oracle account just as you would create any other account. The Oracle account is special only that you need to give it a Linux shell. Add /compat/linux/bin/bash to /etc/shells and set the shell for the Oracle account to /compat/linux/bin/bash. Environment Besides the normal Oracle variables, such as ORACLE_HOME and ORACLE_SID you must set the following environment variables: Variable Value LD_LIBRARY_PATH $ORACLE_HOME/lib CLASSPATH $ORACLE_HOME/jdbc/lib/classes111.zip PATH /compat/linux/bin /compat/linux/sbin /compat/linux/usr/bin /compat/linux/usr/sbin /bin /sbin /usr/bin /usr/sbin /usr/local/bin $ORACLE_HOME/bin It is advised to set all the environment variables in .profile. A complete example is: ORACLE_BASE=/oracle; export ORACLE_BASE ORACLE_HOME=/oracle; export ORACLE_HOME LD_LIBRARY_PATH=$ORACLE_HOME/lib export LD_LIBRARY_PATH ORACLE_SID=ORCL; export ORACLE_SID ORACLE_TERM=386x; export ORACLE_TERM CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip export CLASSPATH PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:$ORACLE_HOME/bin export PATH Installing Oracle Due to a slight inconsistency in the Linux emulator, you need to create a directory named .oracle in /var/tmp before you start the installer. Either make it world writable or let it be owner by the oracle user. You should be able to install Oracle without any problems. If you have problems, check your Oracle distribution and/or configuration first! After you have installed Oracle, apply the patches described in the next two subsections. A frequent problem is that the TCP protocol adapter is not installed right. As a consequence, you cannot start any TCP listeners. The following actions help solve this problem: &prompt.root; cd $ORACLE_HOME/network/lib &prompt.root; make -f ins_network.mk ntcontab.o &prompt.root; cd $ORACLE_HOME/lib &prompt.root; ar r libnetwork.a ntcontab.o &prompt.root; cd $ORACLE_HOME/network/lib &prompt.root; make -f ins_network.mk install Don't forget to run root.sh again! Patching root.sh When installing Oracle, some actions, which need to be performed as root, are recorded in a shell script called root.sh. root.sh is written in the orainst directory. Apply the following patch to root.sh, to have it use to proper location of chown or alternatively run the script under a Linux native shell. *** orainst/root.sh.orig Tue Oct 6 21:57:33 1998 --- orainst/root.sh Mon Dec 28 15:58:53 1998 *************** *** 31,37 **** # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h ! CHOWN=/bin/chown # # Define variables to be used in this script --- 31,37 ---- # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h ! CHOWN=/usr/sbin/chown # # Define variables to be used in this script When you don't install Oracle from CD, you can patch the source for root.sh. It is called rthd.sh and is located in the orainst directory in the source tree. Patching genclntsh The script genclntsh is used to create a single shared client library. It is used when building the demos. Apply the following patch to comment out the definition of PATH: *** bin/genclntsh.orig Wed Sep 30 07:37:19 1998 --- bin/genclntsh Tue Dec 22 15:36:49 1998 *************** *** 32,38 **** # # Explicit path to ensure that we're using the correct commands #PATH=/usr/bin:/usr/ccs/bin export PATH ! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH # # each product MUST provide a $PRODUCT/admin/shrept.lst --- 32,38 ---- # # Explicit path to ensure that we're using the correct commands #PATH=/usr/bin:/usr/ccs/bin export PATH ! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH # # each product MUST provide a $PRODUCT/admin/shrept.lst Running Oracle When you have followed the instructions, you should be able to run Oracle as if it was run on Linux itself. Installing SAP R/3 (4.6B - IDES) Contributed by Holger Kipp holger.kipp@alogis.com Converted to SGML by &a.logo; applications SAP R/3 Preface This document describes a possible way of installing a SAP R/3 4.6B IDES-System with Oracle 8.0.5 for Linux onto a FreeBSD 4.3 machine, including the installation of FreeBSD 4.3 stable and Oracle 8.0.5. Even though this document tries to describe all important steps in a greater detail, it is not intended as a replacement for the Oracle and SAP R/3 installation guides. Please see the documentation that comes with the SAP R/3 Linux edition for SAP- and Oracle-specific questions, as well as resources from Oracle and SAP OSS. Software The following CDROMs have been used for SAP-installation: Name Number Description KERNEL 51009113 SAP Kernel Oracle / Installation / AIX, Linux, Solaris RDBMS 51007558 Oracle / RDBMS 8.0.5.X / Linux EXPORT1 51010208 IDES / DB-Export / Disc 1 of 6 EXPORT2 51010209 IDES / DB-Export / Disc 2 of 6 EXPORT3 51010210 IDES / DB-Export / Disc3 of 6 EXPORT4 51010211 IDES / DB-Export / Disc4 of 6 EXPORT5 51010212 IDES / DB-Export / Disc5 of 6 EXPORT6 51010213 IDES / DB-Export / Disc6 of 6 Additionally, I used the Oracle 8 Server (Pre-production version 8.0.5 for Linux, Kernel Version 2.0.33) CD which is not really necessary, and of course FreeBSD 4.3 stable (it was only a few days past 4.3 RELEASE). SAP-Notes The following notes should be read before installing SAP R/3 or proved to be useful during installation: Number Title 0171356 SAP Software auf Linux: grundlegenden Anmerkungen 0201147 INST: 4.6C R/3 Inst. on UNIX - Oracle 0373203 Update / Migration Oracle 8.0.5 --> 8.0.6/8.1.6 LINUX 0072984 Release of Digital UNIX 4.0B for Oracle 0130581 R3SETUP step DIPGNTAB terminates 0144978 Your system has not been installed correctly 0162266 Questions and tips for R3SETUP on Windows NT / W2K Hardware-Requirements The following equipment is sufficient for a SAP R/3 System (4.6B): Component 4.6B 4.6C Processor 2 x 800MHz Pentium III 2 x 800MHz Pentium III Memory 1GB ECC 2GB ECC Hard Disc Space 50-60GB (IDES) 50-60GB (IDES) For use in production, Xeon-Processors with large cache, high-speed disc access (SCSI, RAID hardware controller), USV and ECC-RAM is recommended. The large amount of Hard disc space is due to the preconfigured IDES System, which creates 27 GB of database files during installation. Usually after installation it is then necessary to extend some tablespaces. I used a dual processor board with 2 800MHz Pentium III processors, Adaptec 29160 Ultra160 SCSI adapter (for accessing a 40/80 GB DLT tape drive and CDROM), Mylex AcelleRAID (2 channels, firmware 6.00-1-00 with 32MB RAM). To the Mylex Raid-controller are attached two 17GB hard discs (mirrored) and four 36GB hard discs (RAID level 5). Installation of FreeBSD 4.3 stable First I installed FreeBSD 4.3 stable. I did the - default-installation via ftp. + default-installation via FTP. Installation via FTP Get the diskimages kern.flp and mfsroot.flp and put them on floppy disks (I got mine from ftp7.de.freebsd.org. Please choose the appropriate mirror). &prompt.root; dd if=kern.flp of=/dev/fd0 &prompt.root; dd if=mfsroot.flp of=/dev/fd0 Don't forget to use different disks for the two images :-), then boot from the floppy with the kern.flp-image on it and follow instructions. I used the following disk layout: Filesystem Size (1k-blocks) Size (GB) Mounted on /dev/da0s1a 1.016.303 1 / /dev/da0s1b 6 <swap> /dev/da0s1e 2.032.623 2 /var /dev/da0s1f 8.205.339 8 /usr /dev/da1s1e 45.734.361 45 /compat/linux/oracle /dev/da1s1f 2.032.623 2 /compat/linux/sapmnt /dev/da1s1g 2.032.623 2 /compat/linux/usr/sap I had to configure and initialise the two logical drives with the Mylex software beforehand. It is located on the board itself and can be started during the boot phase of the pc. Please note that this disk layout differs slightly from the SAP recommendations, as SAP suggests mounting the oracle-subdirectories (and some others) separately - I decided to just create them as real subdirectories for simplicity. Get the latest stable-sources For FreeBSD 4.3 stable onwards, it is quite easy to get the latest stable sources. With the older versions of FreeBSD, I had my own script located in /etc/cvsup. Setting up cvsup for FreeBSD 4.3 is quite easy. As user root do the following: &prompt.root; cp /etc/defaults/make.conf /etc/make.conf &prompt.root; vi /etc/make.conf The file /etc/make.conf requires the following entries to be active: SUP_UPDATE= yes SUP= /usr/local/bin/cvsup SUPFLAGS= -g -L 2 SUPHOST= cvsup8.FreeBSD.org SUPFILE= /usr/share/examples/cvsup/stable-supfile PORTSSUPFILE= /usr/share/examples/cvsup/ports-supfile DOCSUPFILE= /usr/share/examples/cvsup/doc-supfile Change the SUPHOST-value appropriately. The supfiles in /usr/share/examples/cvsup should be fine. If you don't want to load all the docfiles, leave the corresponding DOCSUPFILE-entry inactive. Starting cvsup to get the latest stable-sources is then very easy: &prompt.root; cd /usr/src &prompt.root; make update Make world and a new kernel The first thing to do is to install the sources. As user root, do the following: &prompt.root; cd /usr/src &prompt.root; make world If this goes through, one can then continue creating and configuring the new kernel. Usually this is where to customize the kernel configuration file. As the computer is named troubadix, the natural name for the config file also is troubadix: &prompt.root; cd /usr/src/sys/i386/conf &prompt.root; cp GENERIC TROUBADIX &prompt.root; vi TROUBADIX At this stage one can define the drivers to use and not to use, etc. See the appropriate documentation or have a look at file LINT for some additional explanations. One can then also include the parameters as described below Creating the new kernel then requires: &prompt.root; cd /usr/src/sys/i386/conf &prompt.root; config TROUBADIX &prompt.root; cd /usr/src/sys/compile/TROUBADIX &prompt.root; make depend &prompt.root; make &prompt.root; make install After make install finished successfully, one should reboot the computer to have the new kernel available. Installing the Linux environment I had some trouble downloading the required RPM-files (for 4.3 stable, 2nd May 2001), so you might try one of the following locations (if all the others fail and the following aren't out of date): ftp7.de.freebsd.org/pub/FreeBSD/distfiles/rpm ftp.redhat.com/pub/redhat/linux/6.1/en/os/i386/RedHat/RPMS Installing Linux base-system First the linux base-system needs to be installed (as root): &prompt.root; cd /usr/ports/emulators/linux_base &prompt.root; make package Installing Linux development Next, the linux development is needed: &prompt.root; cd /usr/ports/devel/linux_devtools &prompt.root; make package Installing necessary RPMs RPMs To start the R3SETUP-Program, pam support is needed. As this also requires some other packages, I ended up installing several packages. After that, pam still complained about a missing package, so I forced the installation and it worked. I wonder if the other packages are really needed or if it would have been sufficient to install the pam-package. Anyway, here is the list of packages I installed: cracklib-2.7-5.i386.rpm cracklib-dicts-2.7-5.i386.rpm pwdb-0.60-1.i386.rpm pam-0.68-7.i386.rpm I installed these packages with the following command: &prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <package_name> except for the pam package, which I forced with &prompt.root; rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm pam-0.68-7.i386.rpm For Oracle to run the intelligent agent, I also had to install the following - RedHat TCL package (as is stated in the FreeBSD Handbook): + RedHat Tcl package (as is stated in the FreeBSD Handbook): tcl-8.0.5-30.i386.rpm (otherwise the relinking during Oracle install won't work). There are some other issues regarding relinking of Oracle, but that is a Oracle-Linux issue, not FreeBSD specific as far as I understand it. Creating the SAP/R3 environment Creating the necessary filesystems and mountpoints For a simple installation, it is sufficient to create the following filesystems: mountpoint size in GB /compat/linux/oracle 45 GB /compat/linux/sapmnt 2 GB /compat/linux/usr/sap 2 GB I also created some links, so FreeBSD will also find the correct path: &prompt.root; ln -s /compat/linux/oracle /oracle &prompt.root; ln -s /compat/linux/sapmnt /sapmnt &prompt.root; ln -s /compat/linux/usr/sap /usr/sap Creating users and directories SAP R/3 needs two users and three groups. The usernames depend on the SAP system id (SID) which consists of three letters. Some of these SIDs are reserved by SAP (for example SAP and NIX. For a complete list please see the SAP documentation). For the IDES installation I used IDS. We have therefore the following groups (group ids might differ, these are just the values I used with my installation): group id group name description 100 dba Data Base Administrator 101 sapsys SAP System 102 oper Data Base Operator For a default Oracle-Installation, only group dba is used. As oper-group, one also uses group dba (see Oracle- and SAP-documentation for further information). We also need the following users: user id username generic name group additional groups description 1000 idsadm <sid>adm sapsys oper SAP Administrator 1002 oraids ora<sid> dba oper DB Administrator Adding the users with adduser requires the following (please note shell and home directory) entries for SAP-Administrator: Name: idsadm <sid>adm Password: ****** Fullname: SAP IDES Administrator Uid: 1000 Gid: 101 (sapsys) Class: Groups: sapsys dba HOME: /home/idsadm /home/<sid>adm Shell: /bin/sh and for Database-Administrator: Name: oraids ora<sid> Password: ****** Fullname: Oracle IDES Administrator Uid: 1002 Gid: 100 (dba) Class: Groups: dba HOME: /oracle/IDS /oracle/<sid> Shell: /bin/sh This should also include group oper in case you are using both groups dba and oper. Creating directories These directories are usually created as separate filesystems. This depends entirely on your requirements. I choose to create them as simple directories, as they are all located on the same RAID 5 anyway: First we'll set owners and right of some directories (as user root): &prompt.root; chmod 775 /oracle &prompt.root; chmod 777 /sapmnt &prompt.root; chown root:dba /oracle &prompt.root; chown idsadm:sapsys /compat/linux/usr/sap &prompt.root; chmow 775 /compat/linux/usr/sap Second we'll create directories as user ora<sid>. These will all be subdirectories of /oracle/IDS: &prompt.root; su - oraids &prompt.root; mkdir mirrlogA mirrlogB origlogA origlogB &prompt.root; mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6 &prompt.root; mkdir saparch sapreorg &prompt.root; exit In the third step we create directories as user idsadm (<sid>adm): &prompt.root; su - idsadm &prompt.root; cd /usr/sap &prompt.root; mkdir IDS &prompt.root; mkdir trans &prompt.root; exit Entries in /etc/services SAP R/3 requires some entries in file /etc/services , which will not be set correctly during installation under FreeBSD. Please add the following entries (you need at least those entries corresponding to the instance number - in this case, 00. It'll do no harm adding all entries from 00 to 99 for dp, gw, sp and ms); sapdp00 3200/tcp # SAP Dispatcher. 3200 + Instance-Number sapgw00 3300/tcp # SAP Gateway. 3300 + Instance-Number sapsp00 3400/tcp # 3400 + Instance-Number sapms00 3500/tcp # 3500 + Instance-Number sapmsIDS 3600/tcp # SAP Message Server. 3600 + Instance-Number Necessary locales locale SAP requires at least two locales that aren't part of the default RedHat installation. SAP offers the required - RPMs as download from their ftp-server (which is only + RPMs as download from their FTP-server (which is only accessible if you are a customer with OSS-access). See note 0171356 for a list of RPMs you need. It is also possible to just create appropriate links (for example from de_DE and en_US ), but I wouldn't recommend this for a production system (so far it worked with the IDES system without any problems, though). The following locales are needed: de_DE.ISO-8859-1 en_US.ISO-8859-1 If they are not present, there will be some problems during the installation. If these are then subsequently ignored (eg by setting the status of the offending steps to OK in file CENTRDB.R3S), it will be impossible to log onto the SAP-system without some additional effort. Kernel Tuning kernel tuning SAP R/3 Systems need a lot of resources. I therefore added the following parameters to my kernel config-file: # Set these for memory pigs (SAP and Oracle): options MAXDSIZ="(1024*1024*1024)" options DFLDSIZ="(1024*1024*1024)" # System V options needed. options SYSVSHM #SYSV-style shared memory options SHMMAXPGS=262144 #max amount of shared mem. pages options SHMMNI=256 #max number of shared memory ident if. options SHMSEG=100 #max shared mem.segs per process options SYSVMSG #SYSV-style message queues options MSGSEG=32767 #max num. of mes.segments in system options MSGSSZ=32 #size of msg-seg. MUST be power of 2 options MSGMNB=65535 #max char. per message queue options MSGTQL=2046 #max amount of msgs in system options SYSVSEM #SYSV-style semaphores options SEMMNU=256 #number of semaphore UNDO structures options SEMMNS=1024 #number of semaphores in system options SEMMNI=520 #number of semaphore indentifiers options SEMUME=100 #number of UNDO keys The minimum values are specified in the documentation that comes from SAP. As there is no description for Linux, see the HP-UX-section (32-bit) for further information. Installing SAP R/3 Preparing SAP CDROMs There are lots of CDROMs to mount and unmount during installation. Assuming you have enough CDROM-drives, you can just mount them all. I decided to copy the CDROM contents to corresponding directories: /oracle/IDS/sapreorg/<cd-name> where <cd-name> was one of KERNEL, RDBMS, EXPORT1, EXPORT2, EXPORT3, EXPORT4, EXPORT5 and EXPORT6. All the filenames should be in capital letters, otherwise use the -g option for mounting. So use the following commands: &prompt.root; mount_cd9660 -g /dev/cd0a /mnt &prompt.root; cp -R /mnt/* /oracle/IDS/sapreorg/<cd-name> &prompt.root; umount /mnt Running the install-script First we need to prepare an install-directory: &prompt.root; cd /oracle/IDS/sapreorg &prompt.root; mkdir install &prompt.root; cd install Then the install-script is started, which will copy nearly all the relevant files into the install-directory: /oracle/IDS/sapreorg/KERNEL/UNIX/INSTTOOL.SH As this is an IDES-Installation with a fully customized SAP R/3 Demo-System, we have six instead of just three EXPORT-CDs. At this point the installation template CENTRDB.R3S is for installing a standard central instance (R/3 and Database), not an IDES central instance, so copy the corresponding CENTRDB.R3S from the EXPORT1 directory, otherwise R3SETUP will only ask for three EXPORT-CDs. Start R3SETUP Make sure LD_LIBRARY_PATH is set correctly: &prompt.root; export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/lib Start R3SETUP as user root from installation directory: &prompt.root; cd /oracle/IDS/sapreorg/install &prompt.root; ./R3SETUP -f CENTRDB.R3S The script then asks some questions (defaults in brackets, followed by actual input): Question Default Input Enter SAP System ID [C11] IDS<ret> Enter SAP Instance Number [00] <ret> Enter SAPMOUNT Directory [/sapmnt] <ret> Enter name of SAP central host [troubadix.domain.de] <ret> Enter name of SAP db host [troubadix] <ret> Select character set [1] (WE8DEC) <ret> Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.6 1<ret> Extract Oracle Client archive [1] (Yes, extract) <ret> Enter path to KERNEL CD [/sapcd] /oracle/IDS/sapreorg/KERNEL Enter path to RDBMS CD [/sapcd] /oracle/IDS/sapreorg/RDBMS Enter path to EXPORT1 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT1 Directory to copy EXPORT1 CD [/oracle/IDS/sapreorg/CD4_DIR] <ret> Enter path to EXPORT2 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT2 Directory to copy EXPORT2 CD [/oracle/IDS/sapreorg/CD5_DIR] <ret> Enter path to EXPORT3 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT3 Directory to copy EXPORT3 CD [/oracle/IDS/sapreorg/CD6_DIR] <ret> Enter path to EXPORT4 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT4 Directory to copy EXPORT4 CD [/oracle/IDS/sapreorg/CD7_DIR] <ret> Enter path to EXPORT5 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT5 Directory to copy EXPORT5 CD [/oracle/IDS/sapreorg/CD8_DIR] <ret> Enter path to EXPORT6 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT6 Directory to copy EXPORT6 CD [/oracle/IDS/sapreorg/CD9_DIR] <ret> Enter amount of RAM for SAP + DB 850<ret> (in Megabytes) Service Entry Message Server [3600] <ret> Enter Group-ID of sapsys [101] <ret> Enter Group-ID of oper [102] <ret> Enter Group-ID of dba [100] <ret> Enter User-ID of <sid>adm [1000] <ret> Enter User-ID of ora<sid> [1002] <ret> Number of parallel procs [2] <ret> If I had not copied the CDs to the different locations, then the SAP-Installer can't find the CD needed (identified by the LABEL.ASC-File on CD) and would then ask you to insert / mount the CD and confirm or enter the mountpath. The CENTRDB.R3S might not be error-free. In my case, it requested EXPORT4 again (but indicated the correct key (6_LOCATI ON, then 7_LOCATION etc.), so one can just continue with entering the correct values. Don't get irritated. Apart from some problems mentioned below, everything should go straight throught up to the point where the Oracle database software needs to be installed. Installing Oracle 8.0.5 Please see the corresponding SAP-Notes and Oracle Readmes regarding Linux and Oracle DB for possible problems. Most if not all problems stem from incompatible libraries For more information on installing Oracle, refer to the Installing Oracle chapter. Installing the Oracle 8.0.5 with orainst If Oracle 8.0.5 is to be used, some additional libraries are needed for successfully relinking, as Oracle 8.0.5 was linked with an old glibc (RedHat 6.0), but RedHat 6.1 already uses a new glibc. So you have to install the following additional packages to ensure that linking will work: compat-libs-5.2-2.i386.rpm compat-glibc-5.2-2.0.7.2.i386.rpm compat-egcs-5.2-1.0.3a.1.i386.rpm compat-egcs-c++-5.2-1.0.3a.1.i386.rpm compat-binutils-5.2-2.9.1.0.23.1.i386.rpm See the corresponding SAP-Notes or Oracle Readmes for further information. If this is no option (at the time of installation I didn't have enough time to check this), one could use the original binaries, or use the relinked binaries from an original RedHat System. - For compiling the intelligent agent, the RedHat TCL + For compiling the intelligent agent, the RedHat Tcl package must be installed. If you can't get tcl-8.0.3-20.i386.rpm, a newer one like tcl-8.0.5-30.i386.rpm for RedHat 6.1 should also do. Apart from relinking, the installation is straightforward: &prompt.root; su - oraids &prompt.root; export TERM=xterm &prompt.root; export ORACLE_TERM=xterm &prompt.root; export ORACLE_HOME=/oracle/IDS &prompt.root; cd /ORACLE_HOME/orainst_sap &prompt.root; ./orainst Confirm all Screens with Enter until the software is installed, except that one has to deselect the Oracle On-Line Text Viewer , as this is not currently available for Linux. Oracle then wants to relink with i386-glibc20-linux-gcc instead of the available gcc, egcs or i386-redhat-linux-gcc . Due to time constrains I decided to use the binaries from an Oracle 8.0.5 PreProduction release, after the first attempt at getting the version from the RDBMS-CD working, failed, and finding / accessing the correct RPMs was a nightmare at that time. Installing the Oracle 8.0.5 Pre-Production release for Linux (Kernel 2.0.33) This installation is quite easy. Mount the CD, start the installer. It will then ask for the location of the Oracle home directory, and copy all binaries there. I did not delete the remains of my previous RDBMS-installation tries, though. Afterwards, Oracle Database could be started with no problems. Continue with SAP R/3 installation First check the environment settings of users idsamd (<sid>adm) and oraids (ora<sid>). They should now both have the files .profile , .login and .cshrc which are all using hostname. In case the system's hostname is the fully qualified name, you need to change hostname to hostname -s within all three files. Database load Afterwards, R3SETUP can either be restarted or continued (depending on whether exit was chosen or not). R3SETUP then creates the tablespaces and loads the data from EXPORT1 to EXPORT6 (remember, it is an IDES system, otherwise it would only be EXPORT1 to EXPORT3) with R3load into the database. When the database load is finished (might take a few hours), some passwords are requested. For test installations, one can use the well known default passwords (use different ones if security is an issue!): Question Input Enter Password for sapr3 sap<ret> Confirum Password for sapr3 sap<ret> Enter Password for sys change_on_install<ret> Confirm Password for sys change_on_install<ret> Enter Password for system manager<ret> Confirm Password for system manager<ret> At this point I had a few problems with dipgntab. Listener Start the Oracle-Listener as user oraids (ora<sid>) as follows: umask 0; lsnrctl start Otherwise you might get ORA-12546 as the sockets won't have the correct permissions. See SAP note 072984. Post-installation steps Request SAP R/3 license key This is needed, as the temporary license is only valid for four weeks. Don't forget to enter the correct Operating System: (X) Other: FreeBSD 4.3 Stable. First get the hardware key. Log on as user idsadm and call saplicense: &prompt.root; /sapmnt/IDS/exe/saplicense -get Calling saplicense without options gives a list of options. Upon receiving the license key, it can be installed using &prompt.root; /sapmnt/IDS/exe/saplicense -install You are then required to enter the following values: SAP SYSTEM ID = <SID, 3 chars> CUSTOMER KEY = <hardware key, 11 chars> INSTALLATION NO = <installation, 10 digits> EXPIRATION DATE = <yyyymmdd, usually "99991231"> LICENSE KEY = <license key, 24 chars> Creating Users Create a user within client 000 (for some tasks required to be done within client 000, but with a user different from users sap* and ddic). As a username, I usually choose wartung (or service in English). Profiles required are sap_new and sap_all. For additional safety the passwords of default users within all clients should be changed (this includes users sap* and ddic). Configure Transport System, Profile, Operation Modes, etc. Within client 000, user different from ddic and sap*, do at least the following: Task Transaction Configure Transport System, eg as Stand-Alone Transport Domain Entity STMS Create / Edit Profile for System RZ10 Maintain Operation Modes and Instances RZ04 These and all the other post-installation steps are thoroughly described in SAP installation guides. Edit init<sid>.sap (initIDS.sap) The file /oracle/IDS/dbs/initIDS.sap contains the SAP backup profile. Here the size of the tape to be used, type of compression and so on need to be defined. To get this running with sapdba / brbackup, I changed the following values: compress = hardware archive_function = copy_delete_save cpio_flags = "-ov --format=newc --block-size=128 --quiet" cpio_in_flags = "-iuv --block-size=128 --quiet" tape_size = 38000M tape_address = /dev/nsa0 tape_address_rew = /dev/sa0 Explanations: compress The tape I use is a HP DLT1 which does hardware compression. archive_function This defines the default behaviour for saving Oracle archive logs: New logfiles are saved to tape, already saved logfiles are saved again and are then deleted. This prevents lots of trouble if one needs to recover the database, and one of the archive-tapes has gone bad. cpio_flags Default is to use -B which sets blocksize to 5120 Bytes. For DLT-Tapes, HP recommends at least 32K blocksize, so I used --block-size=128 for 64K. --format=newc is needed I have inode numbers greater than 65535. The last option --quiet is needed as otherwise brbackup complains as soon as cpio outputs the numbers of blocks saved. cpio_in_flags Flags needed for loading data back from tape. Format is reckognized automagically. tape_size This usually gives the raw storage capability of the tape. For security reason (we use hardware compression), the value is slightly lower than the actual value. tape_address The non-rewindable device to be used with cpio. tape_address_rew The rewindable device to be used with cpio. Problems during installation OSUSERSIDADM_IND_ORA during R3SETUP If R3SETUP complains at this stage, edit file CENTRDB.R3S. Locate [OSUSERSIDADM_IND_ORA] and edit the following values: HOME=/home/idsadm (was empty) STATUS=OK (had status ERROR) Then you can restart R3SETUP with: &prompt.root; ./R3SETUP -f CENTRDB.R3S OSUSERDBSID_IND_ORA during R3SETUP Possibly R3SETUP also complains at this stage. Just edit CENTRDB.R3S. Locate [OSUSERDBSID_IND_ORA] and edit the following value in that section: STATUS=OK Then just restart R3SETUP again: &prompt.root; ./R3SETUP -f CENTRDB.R3S oraview.vrf FILE NOT FOUND during Oracle installation You haven't deselected Oracle On-Line Text Viewer before starting the installation. This is marked for installation even though this option is currently not available for Linux. Deselect this product inside the Oracle installation menu and restart installation. TEXTENV_INVALID during R3SETUP, RFC or SAPGUI start If this error is encountered, the correct locale is missing. SAP note 0171356 lists the necessary RPMs that need be installed (eg saplocales-1.0-3, saposcheck-1.0-1 for RedHat 6.1). In case you ignored all the related errors and set the corresponding status from ERROR to OK (in CENTRDB.R3S) every time R3SETUP complained and just restarted R3SETUP, the SAP-System will not be properly configured and you will then not be able to connect to the system with a sapgui, even though the system can be started. Trying to connect with the old Linux sapgui gave the following messages: Sat May 5 14:23:14 2001 *** ERROR => no valid userarea given [trgmsgo. 0401] Sat May 5 14:23:22 2001 *** ERROR => ERROR NR 24 occured [trgmsgi. 0410] *** ERROR => Error when generating text environment. [trgmsgi. 0435] *** ERROR => function failed [trgmsgi. 0447] *** ERROR => no socket operation allowed [trxio.c 3363] Speicherzugriffsfehler This behaviour is due to SAP R/3 being unable to correctly assign a locale and also not being properly configured itself (missing entries in some database tables). To be able to connect to SAP, add the following entries to file DEFAULT.PFL (see note 0043288): abap/set_etct_env_at_new_mode =0 install/collate/active =0 rscp/TCP0B =TCP0B Restart the SAP system. Now one can connect to the system, even though country-specific language settings might not work as expected. After correcting country-settings (and providing the correct locales), these entries can be removed from DEFAULT.PFL and the SAP system can be restarted. ORA-12546. Start Listener with correct permissions Start the Oracle Listener as user oraids with the following commands: &prompt.root; umask 0; lsnrctl start Otherwise one might get ORA-12546 as the sockets won't have the correct permissions. See SAP note 0072984. [DIPGNTAB_IND_IND] during R3SETUP In general, see SAP note 0130581 (R3SETUP step DIPGNTAB terminates). During this specific installation, for some reasons the installation process was not using the proper SAP system name "IDS", but the empty string "" instead. This lead to some minor problems with accessing directories, as the paths are generated dynamically using <sid> (in this case IDS). So instead of accessing: /usr/sap/IDS/SYS/... /usr/sap/IDS/DVMGS00 the following path were used: /usr/sap//SYS/... /usr/sap/D00i To continue with the installation, I created a link and an additional directory: &prompt.root; pwd /compat/linux/usr/sap &prompt.root; ls -l total 4 drwxr-xr-x 3 idsadm sapsys 512 May 5 11:20 D00 drwxr-x--x 5 idsadm sapsys 512 May 5 11:35 IDS lrwxr-xr-x 1 root sapsys 7 May 5 11:35 SYS -> IDS/SYS drwxrwxr-x 2 idsadm sapsys 512 May 5 13:00 tmp drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans I also found SAP notes (0029227 and 0008401) describing this behaviour. [RFCRSWBOINI_IND_IND] during R3SETUP Set STATUS of the offending step from ERROR to OK (file CENTRDB.R3S) and restart R3SETUP. After installation, you have to execute the report RSWBOINS from transaction SE38. See SAP note 0162266 for additional information about phase RFCRSWBOINI and RFCRADDBDIF. [RFCRADDBDIF_IND_IND] during R3SETUP Set STATUS of the offending step from ERROR to OK (file CENTRDB.R3S) and restart R3SETUP. After installation, you have to execute the report RADDBDIF from transaction SE38. See SAP note 0162266 for further information. Advanced Topics If you are curious as to how the Linux binary compatibility works, this is the section you want to read. Most of what follows is based heavily on an email written to &a.chat; by Terry Lambert tlambert@primenet.com (Message ID: <199906020108.SAA07001@usr09.primenet.com>). How Does It Work? execution class loader FreeBSD has an abstraction called an execution class loader. This is a wedge into the &man.execve.2; system call. What happens is that FreeBSD has a list of loaders, instead of a single loader with a fallback to the #! loader for running any shell interpreters or shell scripts. Historically, the only loader on the Unix platform examined the magic number (generally the first 4 or 8 bytes of the file) to see if it was a binary known to the system, and if so, invoked the binary loader. If it was not the binary type for the system, the &man.execve.2; call returned a failure, and the shell attempted to start executing it as shell commands. The assumption was a default of whatever the current shell is. Later, a hack was made for &man.sh.1; to examine the first two characters, and if they were :\n, then it invoked the &man.csh.1; shell instead (we believe SCO first made this hack). What FreeBSD does now is go through a list of loaders, with a generic #! loader that knows about interpreters as the characters which follow to the next whitespace next to last, followed by a fallback to /bin/sh. ELF For the Linux ABI support, FreeBSD sees the magic number as an ELF binary (it makes no distinction between FreeBSD, Solaris, Linux, or any other OS which has an ELF image type, at this point). Solaris The ELF loader looks for a specialized brand, which is a comment section in the ELF image, and which is not present on SVR4/Solaris ELF binaries. For Linux binaries to function, they must be branded as type Linux; from &man.brandelf.1;: &prompt.root; brandelf -t Linux file When this is done, the ELF loader will see the Linux brand on the file. ELF branding When the ELF loader sees the Linux brand, the loader replaces a pointer in the proc structure. All system calls are indexed through this pointer (in a traditional Unix system, this would be the sysent[] structure array, containing the system calls). In addition, the process flagged for special handling of the trap vector for the signal trampoline code, and sever other (minor) fix-ups that are handled by the Linux kernel module. The Linux system call vector contains, among other things, a list of sysent[] entries whose addresses reside in the kernel module. When a system call is called by the Linux binary, the trap code dereferences the system call function pointer off the proc structure, and gets the Linux, not the FreeBSD, system call entry points. In addition, the Linux mode dynamically reroots lookups; this is, in effect, what the union option to FS mounts (not the unionfs!) does. First, an attempt is made to lookup the file in the /compat/linux/original-path directory, then only if that fails, the lookup is done in the /original-path directory. This makes sure that binaries that require other binaries can run (e.g., the Linux toolchain can all run under Linux ABI support). It also means that the Linux binaries can load and exec FreeBSD binaries, if there are no corresponding Linux binaries present, and that you could place a &man.uname.1; command in the /compat/linux directory tree to ensure that the Linux binaries could not tell they were not running on Linux. In effect, there is a Linux kernel in the FreeBSD kernel; the various underlying functions that implement all of the services provided by the kernel are identical to both the FreeBSD system call table entries, and the Linux system call table entries: file system operations, virtual memory operations, signal delivery, System V IPC, etc… The only difference is that FreeBSD binaries get the FreeBSD glue functions, and Linux binaries get the Linux glue functions (most older OS's only had their own glue functions: addresses of functions in a static global sysent[] structure array, instead of addresses of functions dereferenced off a dynamically initialized pointer in the proc structure of the process making the call). Which one is the native FreeBSD ABI? It does not matter. Basically the only difference is that (currently; this could easily be changed in a future release, and probably will be after this) the FreeBSD glue functions are statically linked into the kernel, and the Linux glue functions can be statically linked, or they can be accessed via a kernel module. Yeah, but is this really emulation? No. It is an ABI implementation, not an emulation. There is no emulator (or simulator, to cut off the next question) involved. So why is it sometimes called Linux emulation? To make it hard to sell FreeBSD! 8-). Really, it is because the historical implementation was done at a time when there was really no word other than that to describe what was going on; saying that FreeBSD ran Linux binaries was not true, if you did not compile the code in or load a module, and there needed to be a word to describe what was being loaded—hence the Linux emulator. diff --git a/en_US.ISO8859-1/books/handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/handbook/policies/chapter.sgml index 360a37c5db..69d33b26be 100644 --- a/en_US.ISO8859-1/books/handbook/policies/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/policies/chapter.sgml @@ -1,400 +1,400 @@ Source Tree Guidelines and Policies Contributed by &a.phk;. This chapter documents various guidelines and policies in force for the FreeBSD source tree. <makevar>MAINTAINER</makevar> on Makefiles ports maintainer June 1996. If a particular portion of the FreeBSD distribution is being maintained by a person or group of persons, they can communicate this fact to the world by adding a MAINTAINER= email-addresses line to the Makefiles covering this portion of the source tree. The semantics of this are as follows: The maintainer owns and is responsible for that code. This means that he is responsible for fixing bugs and answer problem reports pertaining to that piece of the code, and in the case of contributed software, for tracking new versions, as appropriate. Changes to directories which have a maintainer defined shall be sent to the maintainer for review before being committed. Only if the maintainer does not respond for an unacceptable period of time, to several emails, will it be acceptable to commit changes without review by the maintainer. However, it is suggested that you try and have the changes reviewed by someone else if at all possible. It is of course not acceptable to add a person or group as maintainer unless they agree to assume this duty. On the other hand it doesn't have to be a committer and it can easily be a group of people. Contributed Software contributed software Contributed by &a.phk; and &a.obrien;. June 1996. Some parts of the FreeBSD distribution consist of software that is actively being maintained outside the FreeBSD project. For historical reasons, we call this contributed software. Some examples are perl, gcc and patch. Over the last couple of years, various methods have been used in dealing with this type of software and all have some number of advantages and drawbacks. No clear winner has emerged. Since this is the case, after some debate one of these methods has been selected as the official method and will be required for future imports of software of this kind. Furthermore, it is strongly suggested that existing contributed software converge on this model over time, as it has significant advantages over the old method, including the ability to easily obtain diffs relative to the official versions of the source by everyone (even without cvs access). This will make it significantly easier to return changes to the primary developers of the contributed software. Ultimately, however, it comes down to the people actually doing the work. If using this model is particularly unsuited to the package being dealt with, exceptions to these rules may be granted only with the approval of the core team and with the general consensus of the other developers. The ability to maintain the package in the future will be a key issue in the decisions. Because of some unfortunate design limitations with the RCS file format and CVS's use of vendor branches, minor, trivial and/or cosmetic changes are strongly discouraged on files that are still tracking the vendor branch. Spelling fixes are explicitly included here under the cosmetic category and are to be avoided for files with revision 1.1.x.x. The repository bloat impact from a single character change can be rather dramatic. - The TCL embedded programming + The Tcl embedded programming language will be used as example of how this model works: src/contrib/tcl contains the source as distributed by the maintainers of this package. Parts that are entirely not applicable for FreeBSD can be removed. In the case of Tcl, the mac, win and compat subdirectories were eliminated before the import src/lib/libtcl contains only a "bmake style" Makefile that uses the standard bsd.lib.mk makefile rules to produce the library and install the documentation. src/usr.bin/tclsh contains only a bmake style Makefile which will produce and install the tclsh program and its associated man-pages using the standard bsd.prog.mk rules. src/tools/tools/tcl_bmake contains a couple of shell-scripts that can be of help when the tcl software needs updating. These are not part of the built or installed software. The important thing here is that the src/contrib/tcl directory is created according to the rules: It is supposed to contain the sources as distributed (on a proper CVS vendor-branch and without RCS keyword expansion) with as few FreeBSD-specific changes as possible. The 'easy-import' tool on freefall will assist in doing the import, but if there are any doubts on how to go about it, it is imperative that you ask first and not blunder ahead and hope it works out. CVS is not forgiving of import accidents and a fair amount of effort is required to back out major mistakes. Because of the previously mentioned design limitations with CVS's vendor branches, it is required that official patches from the vendor be applied to the original distributed sources and the result re-imported onto the vendor branch again. Official patches should never be patched into the FreeBSD checked out version and "committed", as this destroys the vendor branch coherency and makes importing future versions rather difficult as there will be conflicts. Since many packages contain files that are meant for compatibility with other architectures and environments that FreeBSD, it is permissible to remove parts of the distribution tree that are of no interest to FreeBSD in order to save space. Files containing copyright notices and release-note kind of information applicable to the remaining files shall not be removed. If it seems easier, the bmake Makefiles can be produced from the dist tree automatically by some utility, something which would hopefully make it even easier to upgrade to a new version. If this is done, be sure to check in such utilities (as necessary) in the src/tools directory along with the port itself so that it is available to future maintainers. In the src/contrib/tcl level directory, a file called FREEBSD-upgrade should be added and it should states things like: Which files have been left out Where the original distribution was obtained from and/or the official master site. Where to send patches back to the original authors Perhaps an overview of the FreeBSD-specific changes that have been made. However, please do not import FREEBSD-upgrade with the contributed source. Rather you should cvs add FREEBSD-upgrade ; cvs ci after the initial import. Example wording from src/contrib/cpio is below: This directory contains virgin sources of the original distribution files on a "vendor" branch. Do not, under any circumstances, attempt to upgrade the files in this directory via patches and a cvs commit. New versions or official-patch versions must be imported. Please remember to import with "-ko" to prevent CVS from corrupting any vendor RCS Ids. For the import of GNU cpio 2.4.2, the following files were removed: INSTALL cpio.info mkdir.c Makefile.in cpio.texi mkinstalldirs To upgrade to a newer version of cpio, when it is available: 1. Unpack the new version into an empty directory. [Do not make ANY changes to the files.] 2. Remove the files listed above and any others that don't apply to FreeBSD. 3. Use the command: cvs import -ko -m 'Virgin import of GNU cpio v<version>' \ src/contrib/cpio GNU cpio_<version> For example, to do the import of version 2.4.2, I typed: cvs import -ko -m 'Virgin import of GNU v2.4.2' \ src/contrib/cpio GNU cpio_2_4_2 4. Follow the instructions printed out in step 3 to resolve any conflicts between local FreeBSD changes and the newer version. Do not, under any circumstances, deviate from this procedure. To make local changes to cpio, simply patch and commit to the main branch (aka HEAD). Never make local changes on the GNU branch. All local changes should be submitted to "cpio@gnu.ai.mit.edu" for inclusion in the next vendor release. obrien@FreeBSD.org - 30 March 1997 Encumbered Files It might occasionally be necessary to include an encumbered file in the FreeBSD source tree. For example, if a device requires a small piece of binary code to be loaded to it before the device will operate, and we do not have the source to that code, then the binary file is said to be encumbered. The following policies apply to including encumbered files in the FreeBSD source tree. Any file which is interpreted or executed by the system CPU(s) and not in source format is encumbered. Any file with a license more restrictive than BSD or GNU is encumbered. A file which contains downloadable binary data for use by the hardware is not encumbered, unless (1) or (2) apply to it. It must be stored in an architecture neutral ASCII format (file2c or uuencoding is recommended). Any encumbered file requires specific approval from the Core team before it is added to the CVS repository. Encumbered files go in src/contrib or src/sys/contrib. The entire module should be kept together. There is no point in splitting it, unless there is code-sharing with non-encumbered code. Object files are named arch/filename.o.uu>. Kernel files; Should always be referenced in conf/files.* (for build simplicity). Should always be in LINT, but the Core team decides per case if it should be commented out or not. The Core team can, of course, change their minds later on. The Release Engineer decides whether or not it goes in to the release. User-land files; core team The Core team decides if the code should be part of make world. release engineer The Release Engineer decides if it goes in to the release. Shared Libraries Contributed by &a.asami;, &a.peter;, and &a.obrien; 9 December 1996. If you are adding shared library support to a port or other piece of software that doesn't have one, the version numbers should follow these rules. Generally, the resulting numbers will have nothing to do with the release version of the software. The three principles of shared library building are: Start from 1.0 If there is a change that is backwards compatible, bump minor number (note that ELF systems ignore the minor number) If there is an incompatible change, bump major number For instance, added functions and bugfixes result in the minor version number being bumped, while deleted functions, changed function call syntax etc. will force the major version number to change. Stick to version numbers of the form major.minor (x.y). Our a.out dynamic linker does not handle version numbers of the form x.y.z well. Any version number after the y (ie. the third digit) is totally ignored when comparing shared lib version numbers to decide which library to link with. Given two shared libraries that differ only in the micro revision, ld.so will link with the higher one. Ie: if you link with libfoo.so.3.3.3, the linker only records 3.3 in the headers, and will link with anything starting with libfoo.so.3.(anything >= 3).(highest available). ld.so will always use the highest minor revision. Ie: it will use libc.so.2.2 in preference to libc.so.2.0, even if the program was initially linked with libc.so.2.0. In addition, our ELF dynamic linker does not handle minor version numbers at all. However, one should still specify a major and minor version number as our Makefiles "do the right thing" based on the type of system. For non-port libraries, it is also our policy to change the shared library version number only once between releases. In addition, it is our policy to change the major shared library version number only once between major OS releases. Ie: X.0 to (X+1).0. When you make a change to a system library that requires the version number to be bumped, check the Makefile's commit logs. It is the responsibility of the committer to ensure that the first such change since the release will result in the shared library version number in the Makefile to be updated, and any subsequent changes will not. diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml index 2699644603..1786017cb4 100644 --- a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml @@ -1,2840 +1,2840 @@ PPP and SLIP Restructured, reorganized, and updated by &a.jim;, 1 March 2000. Synopsis PPP SLIP If you are connecting to the Internet via modem, or wish to provide dial-up connections to the Internet for others using FreeBSD, you have the option of using PPP or SLIP. PPPuser PPP PPPkernel PPP PPPover Ethernet This chapter covers three varieties of PPP; user, kernel, and PPPoE (PPP over Ethernet). It also covers setting up a SLIP client and server. The first variety of PPP that will be covered is User PPP. User PPP was introduced into FreeBSD in 2.0.5-RELEASE as an addition to the already existing kernel implementation of PPP. You may be wondering what the main difference is between User PPP and kernel PPP. The answer is simple; user PPP does not run as a daemon, and can run as and when desired. No PPP interface needs to be compiled into their kernel; it runs as a user process, and uses the tunnel device driver (tun) to get data into and out of the kernel. From here on out in this chapter, user ppp will simply be referred to as ppp unless a distinction needs to be made between it and any other PPP software such as pppd. Unless otherwise stated, all of the commands explained in this section should be executed as root. Using User PPP Originally contributed by &a.brian;, with input from &a.nik;, &a.dirkvangulik;, and &a.pjc;. User PPP Assumptions This document assumes you have the following: ISP PPP An account with an Internet Service Provider (ISP) which you connect to using PPP. Further, you have a modem or other device connected to your system and configured correctly, which allows you to connect to your ISP. The dial-up number(s) of your ISP. PAP CHAP Unix login name password Your login name and password. This can be either a regular Unix-style login and password pair, or a PAP or CHAP login and password pair. name server The IP address(es) of one or more name servers. Normally, you will be given two IP addresses by your ISP to use for this. If they have not given you at least one, then you can use the enable dns command in your ppp.conf file to tell ppp to set the name servers for you. The following information may be supplied by your ISP, but is not completely necessary: The IP address of your ISP's gateway. The gateway is the machine to which you will connect and will be set up as your default route. If you do not have this information, we can make one up and your ISP's PPP server will tell us the correct value when we connect. This IP number is referred to as HISADDR by ppp. The netmask you should use. If your ISP has not provided you with one, you can safely use 255.255.255.0. static IP address If your ISP provides you with a static IP address and hostname, you can enter it. Otherwise, we simply let the peer assign whatever IP address it sees fit. If you do not have any of the required information, contact your ISP and make sure they provide it to you. Preparing the Kernel As previously mentioned, ppp uses the tun device, and whichever kernel you are using must have tun configured. The tun device is preconfigured for the default GENERIC kernel that ships with FreeBSD. However, if you have installed a custom kernel, you must make sure your kernel is configured for ppp. kernelcompilation To check, go to your kernel compile directory (/sys/i386/conf or /sys/pc98/conf) and examine your configuration file. It should have the following line somewhere in it: pseudo-device tun 1 If this line is not present, you will need to add it to the configuration file and recompile your kernel. The stock GENERIC kernel has this included, so if you have not installed a custom kernel or do not have a /sys directory, you do not have to change anything. If you do need to recompile your kernel, please refer to the kernel configuration section for more information. You can check how many tunnel devices your current kernel has by typing the following: &prompt.root; ifconfig -a tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500 inet 200.10.100.1 --> 203.10.100.24 netmask 0xffffffff tun1: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 576 tun2: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500 inet 203.10.100.1 --> 203.10.100.20 netmask 0xffffffff tun3: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 In FreeBSD 4.0 and later releases, you will only see any tun devices which have already been used. This means you might not see any tun devices. If this is the case, do not worry; the device should be created dynamically when ppp attempts to use it. This case shows four tunnel devices, two of which are currently configured and being used. It should be noted that the RUNNING flag above indicates that the interface has been used at some point—it is not an error if your interface does not show up as RUNNING. If for some reason you have a kernel that does not have the tun device in it and cannot recompile the kernel, all is not lost. You should be able to dynamically load the code. Please refer to the appropriate &man.modload.8; and &man.lkm.4; man pages for further details. Check the <devicename>tun</devicename> device Under normal circumstances, most users will only require one tun device (/dev/tun0). If you have specified more than one on the pseudo-device line for tun in your kernel configuration file, then alter all references to tun0 below to reflect whichever device number you are using (e.g., tun2). The easiest way to make sure that the tun0 device is configured correctly, is to remake the device. This process is quite easy. To remake the device, do the following: &prompt.root; cd /dev &prompt.root; ./MAKEDEV tun0 If you need 16 tunnel devices in your kernel, you will need to create them. This can be done by executing the following commands: &prompt.root; cd /dev &prompt.root; ./MAKEDEV tun15 To confirm that the kernel is configured correctly, issue the follow command and compare the results: &prompt.root; ifconfig tun0 tun0: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mut 1500 The RUNNING flag may not yet be set, in which case you will see: &prompt.root; ifconfig tun0 tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 Remember from earlier that you might not see the device if it has not been used yet, as tun devices are created on demand in FreeBSD 4.0 and later releases. Name Resolution Configuration resolver hostname hosts The resolver is the part of the system that turns IP addresses into hostnames and vice versa. It can be configured to look for maps that describe IP to hostname mappings in one of two places. The first is a file called /etc/hosts. Read &man.hosts.5; for more information. The second is the Internet Domain Name Service (DNS), a distributed data base, the discussion of which is beyond the scope of this document. The resolver is a set of system calls that do the name mappings, but you have to tell them where to find their information. You do this by first editing the file /etc/host.conf. Do not call this file /etc/hosts.conf (note the extra s) as the results can be confusing. Edit <filename>/etc/host.conf</filename> This file should contain the following two lines (in this order): hosts bind These instruct the resolver to first look in the file /etc/hosts, and then to consult the DNS if the name was not found. Edit <filename>/etc/hosts</filename> This file should contain the IP addresses and names of machines on your network. At a bare minimum it should contain entries for the machine which will be running ppp. Assuming that your machine is called foo.bar.com with the IP address 10.0.0.1, /etc/hosts should contain: 127.0.0.1 localhost.bar.com localhost 127.0.0.1 localhost.bar.com. 10.0.0.1 foo.bar.com foo 10.0.0.1 foo.bar.com. The first two lines define the alias localhost as a synonym for the current machine. Regardless of your own IP address, the IP address for this line should always be 127.0.0.1. The second two lines map the name foo.bar.com (and the shorthand foo) to the IP address 10.0.0.1. If your provider allocates you a static IP address and name, use them in place of the 10.0.0.1 entry. Edit <filename>/etc/resolv.conf</filename> The /etc/resolv.conf file tells the resolver how to behave. If you are running your own DNS, you may leave this file empty. Normally, you will need to enter the following line(s): domain bar.com nameserver x.x.x.x nameserver y.y.y.y The x.x.x.x and y.y.y.y addresses are those given to you by your ISP. Add as many nameserver lines as your ISP provides. The domain line defaults to your hostname's domain, and is probably unnecessary. Refer to the &man.resolv.conf.5; manual page for details of other possible entries in this file. PPP ISP If you are running PPP version 2 or greater, the enable dns command will tell PPP to request that your ISP confirms the nameserver values. If your ISP supplies different addresses (or if there are no nameserver lines in /etc/resolv.conf), PPP will rewrite the file with the ISP-supplied values. <application>PPP</application> Configuration PPPconfiguration Both ppp and pppd (the kernel level implementation of PPP) use the configuration files located in the /usr/share/examples/ppp directory. The sample configuration files provided are a good reference, so do not delete them. Configuring ppp requires that you edit a number of files, depending on your requirements. What you put in them depends to some extent on whether your ISP allocates IP addresses statically (i.e., you get given one IP address, and always use that one) or dynamically (i.e., your IP address changes each time you connect to your ISP). PPP and Static IP Addresses PPPwith static IP addresses You will need to create a configuration file called /etc/ppp/ppp.conf. It should look similar to the example below. Lines that end in a : start in the first column, all other lines should be indented as shown using spaces or tabs. 1 default: 2 set device /dev/cuaa0 3 set speed 115200 4 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0 OK-AT-OK \\dATDT\\TTIMEOUT 40 CONNECT" 5 provider: 6 set phone "(123) 456 7890" 7 set login "TIMEOUT 10 \"\" \"\" gin:--gin: foo word: bar col: ppp" 8 set timeout 300 9 set ifaddr x.x.x.x y.y.y.y 255.255.255.0 0.0.0.0 10 add default HISADDR 11 enable dns Do not include the line numbers, they are just for reference in this discussion. Line 1: Identifies the default entry. Commands in this entry are executed automatically when ppp is run. Line 2: Identifies the device to which the modem is connected. COM1 is /dev/cuaa0 and COM2 is /dev/cuaa1. Line 3: Sets the speed you want to connect at. If 115200 does not work (it should with any reasonably new modem), try 38400 instead. Line 4: PPPuser PPP The dial string. User PPP uses an expect-send syntax similar to the &man.chat.8; program. Refer to the manual page for information on the features of this language. Line 5: Identifies an entry for a provider called provider. Line 6: Sets the phone number for this provider. Multiple phone numbers may be specified using the colon (:) or pipe character (|)as a separator. The difference between the two separators is described in &man.ppp.8;. To summarize, if you want to rotate through the numbers, use a colon. If you want to always attempt to dial the first number first and only use the other numbers if the first number fails, use the pipe character. Always quote the entire set of phone numbers as shown. Line 7: The login string is of the same chat-like syntax as the dial string. In this example, the string works for a service whose login session looks like this: J. Random Provider login: foo password: bar protocol: ppp You will need to alter this script to suit your own needs. When you write this script for the first time, you should enable chat logging to ensure that the conversation is going as expected. PAP CHAP If you are using PAP or CHAP, there will be no login at this point, so your login string can be left blank. See PAP and CHAP authentication for further details. Line 8: timeout Sets the default timeout (in seconds) for the connection. Here, the connection will be closed automatically after 300 seconds of inactivity. If you never want to timeout, set this value to zero. Line 9: ISP Sets the interface addresses. The string x.x.x.x should be replaced by the IP address that your provider has allocated to you. The string y.y.y.y should be replaced by the IP address that your ISP indicated for their gateway (the machine to which you connect). If your ISP hasn't given you a gateway address, use 10.0.0.2/0. If you need to use a guessed address, make sure that you create an entry in /etc/ppp/ppp.linkup as per the instructions for PPP and Dynamic IP addresses. If this line is omitted, ppp cannot run in or mode. Line 10: Adds a default route to your ISP's gateway. The special word HISADDR is replaced with the gateway address specified on line 9. It is important that this line appears after line 9, otherwise HISADDR will not yet be initialized. Line 11: nameserver This line tells PPP to ask your ISP to confirm that your nameserver addresses are correct. If your ISP supports this facility, PPP can then update /etc/resolv.conf with the correct nameserver entries. It is not necessary to add an entry to ppp.linkup when you have a static IP address as your routing table entries are already correct before you connect. You may however wish to create an entry to invoke programs after connection. This is explained later with the sendmail example. Example configuration files can be found in the /usr/share/examples/ppp directory. PPP and Dynamic IP Addresses PPPwith dynamic IP addresses IPCP If your service provider does not assign static IP addresses, ppp can be configured to negotiate the local and remote addresses. This is done by guessing an IP address and allowing ppp to set it up correctly using the IP Configuration Protocol (IPCP) after connecting. The ppp.conf configuration is the same as PPP and Static IP Addresses, with the following change: 9 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0 Again, do not include the line numbers, they are just for reference. Indentation of at least one space is required. Line 9: The number after the / character is the number of bits of the address that ppp will insist on. You may wish to use IP numbers more appropriate to your circumstances, but the above example will always work. The last argument (0.0.0.0) tells PPP to negotiate using address 0.0.0.0 rather than 10.0.0.1. Do not use 0.0.0.0 as the first argument to set ifaddr as it prevents PPP from setting up an initial route in mode. If you are running version 1.x of PPP, you will also need to create an entry in /etc/ppp/ppp.linkup. ppp.linkup is used after a connection has been established. At this point, ppp will know what IP addresses should really be used. The following entry will delete the existing bogus routes, and create correct ones: 1 provider: 2 delete ALL 3 add 0 0 HISADDR Line 1: On establishing a connection, ppp will look for an entry in ppp.linkup according to the following rules: First, try to match the same label as we used in ppp.conf. If that fails, look for an entry for the IP address of our gateway. This entry is a four-octet IP style label. If we still have not found an entry, look for the MYADDR entry. Line 2: This line tells ppp to delete all of the existing routes for the acquired tun interface (except the direct route entry). Line 3: This line tells ppp to add a default route that points to HISADDR. HISADDR will be replaced with the IP number of the gateway as negotiated in the IPCP. See the pmdemand entry in the files /usr/share/examples/ppp/ppp.conf.sample and /usr/share/examples/ppp/ppp.linkup.sample for a detailed example. Version 2 of PPP introduces sticky routes. Any add or delete lines that contain MYADDR or HISADDR will be remembered, and any time the actual values of MYADDR or HISADDR change, the routes will be reapplied. This removes the necessity of repeating these lines in ppp.linkup. Receiving Incoming Calls PPPreceiving incoming calls When you configure ppp to receive incoming calls on a machine connected to a LAN, you must decide if you wish to forward packets to the LAN. If you do, you should allocate the peer an IP number from your LAN's subnet, and use the command enable proxy in your /etc/ppp/ppp.conf file. You should also confirm that the /etc/rc.conf file contains the following: gateway="YES" Which getty? Configuring FreeBSD for Dial-up Services provides a good description on enabling dial-up services using getty. An alternative to getty is mgetty, a smarter version of getty designed with dial-up lines in mind. The advantages of using mgetty is that it actively talks to modems, meaning if port is turned off in /etc/ttys then your modem will not answer the phone. Later versions of mgetty (from 0.99beta onwards) also support the automatic detection of PPP streams, allowing your clients script-less access to your server. Refer to Mgetty and AutoPPP for more information on mgetty. <application>PPP</application> Permissions The ppp command must normally be run as user id 0. If however, you wish to allow ppp to run in server mode as a normal user by executing ppp as described below, that user must be given permission to run ppp by adding them to the network group in /etc/group. You will also need to give them access to one or more sections of the configuration file using the allow command: allow users fred mary If this command is used in the default section, it gives the specified users access to everything. PPP Shells for Dynamic-IP Users PPP shells Create a file called /etc/ppp/ppp-shell containing the following: #!/bin/sh IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'` CALLEDAS="$IDENT" TTY=`tty` if [ x$IDENT = xdialup ]; then IDENT=`basename $TTY` fi echo "PPP for $CALLEDAS on $TTY" echo "Starting PPP for $IDENT" exec /usr/sbin/ppp -direct $IDENT This script should be executable. Now make a symbolic link called ppp-dialup to this script using the following commands: &prompt.root; ln -s ppp-shell /etc/ppp/ppp-dialup You should use this script as the shell for all of your dialup users. This is an example from /etc/password for a dialup PPP user with username pchilds (remember don't directly edit the password file, use vipw). pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup Create a /home/ppp directory that is world readable containing the following 0 byte files: -r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin -r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts which prevents /etc/motd from being displayed. PPP shells for Static-IP Users PPP shells Create the ppp-shell file as above and for each account with statically assigned IPs create a symbolic link to ppp-shell. For example, if you have three dialup customers fred, sam, and mary, that you route class C networks for, you would type the following: &prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred &prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam &prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary Each of these users dialup accounts should have their shell set to the symbolic link created above (i.e., mary's shell should be /etc/ppp/ppp-mary). Setting up ppp.conf for dynamic-IP users The /etc/ppp/ppp.conf file should contain something along the lines of: default: set debug phase lcp chat set timeout 0 ttyd0: set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255 enable proxy ttyd1: set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255 enable proxy The indenting is important. The default: section is loaded for each session. For each dialup line enabled in /etc/ttys create an entry similar to the one for ttyd0: above. Each line should get a unique IP address from your pool of IP addresses for dynamic users. Setting up <filename>ppp.conf</filename> for static-IP users Along with the contents of the sample /usr/share/examples/ppp/ppp.conf above you should add a section for each of the statically assigned dialup users. We will continue with our fred, sam, and mary example. fred: set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255 sam: set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255 mary: set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255 The file /etc/ppp/ppp.linkup should also contain routing information for each static IP user if required. The line below would add a route for the 203.14.101.0 class C via the client's ppp link. fred: add 203.14.101.0 netmask 255.255.255.0 HISADDR sam: add 203.14.102.0 netmask 255.255.255.0 HISADDR mary: add 203.14.103.0 netmask 255.255.255.0 HISADDR More on <command>mgetty</command>, AutoPPP, and MS extensions <command>mgetty</command> and AutoPPP mgetty AutoPPP LCP Configuring and compiling mgetty with the AUTO_PPP option enabled allows mgetty to detect the LCP phase of PPP connections and automatically spawn off a ppp shell. However, since the default login/password sequence does not occur it is necessary to authenticate users using either PAP or CHAP. This section assumes the user has successfully configured, compiled, and installed a version of mgetty with the AUTO_PPP option (v0.99beta or later). Make sure your /usr/local/etc/mgetty+sendfax/login.config file has the following in it: /AutoPPP/ - - /etc/ppp/ppp-pap-dialup This will tell mgetty to run the ppp-pap-dialup script for detected PPP connections. Create a file called /etc/ppp/ppp-pap-dialup containing the following (the file should be executable): #!/bin/sh exec /usr/sbin/ppp -direct pap$IDENT For each dialup line enabled in /etc/ttys, create a corresponding entry in /etc/ppp/ppp.conf. This will happily co-exist with the definitions we created above. pap: enable pap set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40 enable proxy Each user logging in with this method will need to have a username/password in /etc/ppp/ppp.secret file, or alternatively add the following option to authenticate users via PAP from /etc/password file. enable passwdauth If you wish to assign some users a static IP number, you can specify the number as the third argument in /etc/ppp/ppp.secret. See /usr/share/examples/ppp/ppp.secret.sample for examples. MS extensions DNS NetBIOS PPPMicrosoft extensions It is possible to configure PPP to supply DNS and NetBIOS nameserver addresses on demand. To enable these extensions with PPP version 1.x, the following lines might be added to the relevant section of /etc/ppp/ppp.conf. enable msext set ns 203.14.100.1 203.14.100.2 set nbns 203.14.100.5 And for PPP version 2 and above: accept dns set dns 203.14.100.1 203.14.100.2 set nbns 203.14.100.5 This will tell the clients the primary and secondary name server addresses, and a netbios nameserver host. In version 2 and above, if the set dns line is omitted, PPP will use the values found in /etc/resolv.conf. PAP and CHAP authentication PAP CHAP Some ISPs set their system up so that the authentication part of your connection is done using either of the PAP or CHAP authentication mechanisms. If this is the case, your ISP will not give a login: prompt when you connect, but will start talking PPP immediately. PAP is less secure than CHAP, but security is not normally an issue here as passwords, although being sent as plain text with PAP, are being transmitted down a serial line only. There's not much room for crackers to eavesdrop. Referring back to the PPP and Static IP addresses or PPP and Dynamic IP addresses sections, the following alterations must be made: 7 set login … 12 set authname MyUserName 13 set authkey MyPassword As always, do not include the line numbers, they are just for reference in this discussion. Indentation of at least one space is required. Line 7: Your ISP will not normally require that you log into the server if you're using PAP or CHAP. You must therefore disable your set login string. Line 12: This line specifies your PAP/CHAP user name. You will need to insert the correct value for MyUserName. Line 13: password This line specifies your PAP/CHAP password. You will need to insert the correct value for MyPassword. You may want to add an additional line, such as: 15 accept PAP or 15 accept CHAP to make it obvious that this is the intention, but PAP and CHAP are both accepted by default. Changing your <command>ppp</command> configuration on the fly It is possible to talk to the ppp program while it is running in the background, but only if a suitable diagnostic port has been set up. To do this, add the following line to your configuration: set server /var/run/ppp-tun%d DiagnosticPassword 0177 This will tell PPP to listen to the specified unix-domain socket, asking clients for the specified password before allowing access. The %d in the name is replaced with the tun device number that is in use. Once a socket has been set up, the &man.pppctl.8; program may be used in scripts that wish to manipulate the running program. Final system configuration PPPconfiguration You now have ppp configured, but there are a few more things to do before it is ready to work. They all involve editing the /etc/rc.conf file. Working from the top down in this file, make sure the hostname= line is set, e.g.: hostname="foo.bar.com" If your ISP has supplied you with a static IP address and name, it's probably best that you use this name as your host name. Look for the network_interfaces variable. If you want to configure your system to dial your ISP on demand, make sure the tun0 device is added to the list, otherwise remove it. network_interfaces="lo0 tun0" ifconfig_tun0= The ifconfig_tun0 variable should be empty, and a file called /etc/start_if.tun0 should be created. This file should contain the line: ppp -auto mysystem This script is executed at network configuration time, starting your ppp daemon in automatic mode. If you have a LAN for which this machine is a gateway, you may also wish to use the switch. Refer to the manual page for further details. Set the router program to NO with following line in your /etc/rc.conf: router_enable="NO" routed It is important that the routed daemon is not started (it is started by default), as it routed tends to delete the default routing table entries created by ppp. It is probably worth your while ensuring that the sendmail_flags line does not include the option, otherwise sendmail will attempt to do a network lookup every now and then, possibly causing your machine to dial out. You may try: sendmail_flags="-bd" sendmail The downside of this is that you must force sendmail to re-examine the mail queue whenever the ppp link is up by typing: &prompt.root; /usr/sbin/sendmail -q You may wish to use the !bg command in ppp.linkup to do this automatically: 1 provider: 2 delete ALL 3 add 0 0 HISADDR 4 !bg sendmail -bd -q30m SMTP If you don't like this, it is possible to set up a dfilter to block SMTP traffic. Refer to the sample files for further details. Now the only thing left to do is reboot the machine. All that is left is to reboot the machine. After rebooting, you can now either type: &prompt.root; ppp and then dial provider to start the PPP session, or, if you want ppp to establish sessions automatically when there is outbound traffic (and you have not created the start_if.tun0 script), type: &prompt.root; ppp -auto provider Summary To recap, the following steps are necessary when setting up ppp for the first time: Client side: Ensure that the tun device is built into your kernel. Ensure that the tunX device file is available in the /dev directory. Create an entry in /etc/ppp/ppp.conf. The pmdemand example should suffice for most ISPs. If you have a dynamic IP address, create an entry in /etc/ppp/ppp.linkup. Update your /etc/rc.conf file. Create a start_if.tun0 script if you require demand dialing. Server side: Ensure that the tun device is built into your kernel. Ensure that the tunX device file is available in the /dev directory. Create an entry in /etc/passwd (using the &man.vipw.8; program). Create a profile in this users home directory that runs ppp -direct direct-server or similar. Create an entry in /etc/ppp/ppp.conf. The direct-server example should suffice. Create an entry in /etc/ppp/ppp.linkup. Update your /etc/rc.conf file. Using Kernel PPP Parts originally contributed by &a.gena; and &a.rhuff;. Setting up Kernel PPP PPPkernel PPP Before you start setting up PPP on your machine make sure that pppd is located in /usr/sbin and the directory /etc/ppp exists. pppd can work in two modes: As a client, i.e., you want to connect your machine to the outside world via a PPP serial connection or modem line. PPPserver as a server, i.e. your machine is located on the network and used to connect other computers using PPP. In both cases you will need to set up an options file (/etc/ppp/options or ~/.ppprc if you have more than one user on your machine that uses PPP). You also will need some modem/serial software (preferably kermit) so you can dial and establish a connection with the remote host. Using <command>pppd</command> as a client PPPclient Cisco The following /etc/ppp/options might be used to connect to a CISCO terminal server PPP line. crtscts # enable hardware flow control modem # modem control line noipdefault # remote PPP server must supply your IP address. # if the remote host doesn't send your IP during IPCP # negotiation , remove this option passive # wait for LCP packets domain ppp.foo.com # put your domain name here :<remote_ip> # put the IP of remote PPP host here # it will be used to route packets via PPP link # if you didn't specified the noipdefault option # change this line to <local_ip>:<remote_ip> defaultroute # put this if you want that PPP server will be your # default router To connect: kermit modem Dial to the remote host using kermit (or some other modem program), and enter your user name and password (or whatever is needed to enable PPP on the remote host). Exit kermit (without hanging up the line). Enter the following: &prompt.root; /usr/src/usr.sbin/pppd.new/pppd /dev/tty01 19200 Be sure to use the appropriate speed and device name. Now your computer is connected with PPP. If the connection fails, you can add the option to the /etc/ppp/options file and check messages on the console to track the problem. Following /etc/ppp/pppup script will make all 3 stages automatically: #!/bin/sh ps ax |grep pppd |grep -v grep pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` if [ "X${pid}" != "X" ] ; then echo 'killing pppd, PID=' ${pid} kill ${pid} fi ps ax |grep kermit |grep -v grep pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` if [ "X${pid}" != "X" ] ; then echo 'killing kermit, PID=' ${pid} kill -9 ${pid} fi ifconfig ppp0 down ifconfig ppp0 delete kermit -y /etc/ppp/kermit.dial pppd /dev/tty01 19200 kermit /etc/ppp/kermit.dial is a kermit script that dials and makes all necessary authorization on the remote host (an example of such a script is attached to the end of this document). Use the following /etc/ppp/pppdown script to disconnect the PPP line: #!/bin/sh pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` if [ X${pid} != "X" ] ; then echo 'killing pppd, PID=' ${pid} kill -TERM ${pid} fi ps ax |grep kermit |grep -v grep pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` if [ "X${pid}" != "X" ] ; then echo 'killing kermit, PID=' ${pid} kill -9 ${pid} fi /sbin/ifconfig ppp0 down /sbin/ifconfig ppp0 delete kermit -y /etc/ppp/kermit.hup /etc/ppp/ppptest Check to see if PPP is still running by executing /usr/etc/ppp/ppptest, which should look like this: #!/bin/sh pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'` if [ X${pid} != "X" ] ; then echo 'pppd running: PID=' ${pid-NONE} else echo 'No pppd running.' fi set -x netstat -n -I ppp0 ifconfig ppp0 To hang up the modem, execute /etc/ppp/kermit.hup, which should contain: set line /dev/tty01 ; put your modem device here set speed 19200 set file type binary set file names literal set win 8 set rec pack 1024 set send pack 1024 set block 3 set term bytesize 8 set command bytesize 8 set flow none pau 1 out +++ inp 5 OK out ATH0\13 echo \13 exit Here is an alternate method using chat instead of kermit. The following two files are sufficient to accomplish a pppd connection. /etc/ppp/options: /dev/cuaa1 115200 crtscts # enable hardware flow control modem # modem control line connect "/usr/bin/chat -f /etc/ppp/login.chat.script" noipdefault # remote PPP serve must supply your IP address. # if the remote host doesn't send your IP during # IPCP negotiation, remove this option passive # wait for LCP packets domain <your.domain> # put your domain name here : # put the IP of remote PPP host here # it will be used to route packets via PPP link # if you didn't specified the noipdefault option # change this line to <local_ip>:<remote_ip> defaultroute # put this if you want that PPP server will be # your default router /etc/ppp/login.chat.script: The following should go on a single line. ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<phone.number> CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <login-id> TIMEOUT 5 sword: <password> Once these are installed and modified correctly, all you need to do is run pppd, like so: &prompt.root; pppd This sample is based primarily on information provided by: Trev Roydhouse <Trev.Roydhouse@f401.n711.z3.fidonet.org> and used with permission. Using <command>pppd</command> as a server /etc/ppp/options should contain something similar to the following: crtscts # Hardware flow control netmask 255.255.255.0 # netmask ( not required ) 192.114.208.20:192.114.208.165 # ip's of local and remote hosts # local ip must be different from one # you assigned to the ethernet ( or other ) # interface on your machine. # remote IP is ip address that will be # assigned to the remote machine domain ppp.foo.com # your domain passive # wait for LCP modem # modem line The following /etc/ppp/pppserv script will enable tell pppd to behave as a server: #!/bin/sh ps ax |grep pppd |grep -v grep pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` if [ "X${pid}" != "X" ] ; then echo 'killing pppd, PID=' ${pid} kill ${pid} fi ps ax |grep kermit |grep -v grep pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` if [ "X${pid}" != "X" ] ; then echo 'killing kermit, PID=' ${pid} kill -9 ${pid} fi # reset ppp interface ifconfig ppp0 down ifconfig ppp0 delete # enable autoanswer mode kermit -y /etc/ppp/kermit.ans # run ppp pppd /dev/tty01 19200 Use this /etc/ppp/pppservdown script to stop the server: #!/bin/sh ps ax |grep pppd |grep -v grep pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'` if [ "X${pid}" != "X" ] ; then echo 'killing pppd, PID=' ${pid} kill ${pid} fi ps ax |grep kermit |grep -v grep pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'` if [ "X${pid}" != "X" ] ; then echo 'killing kermit, PID=' ${pid} kill -9 ${pid} fi ifconfig ppp0 down ifconfig ppp0 delete kermit -y /etc/ppp/kermit.noans The following kermit script (/etc/ppp/kermit.ans) will enable/disable autoanswer mode on your modem. It should look like this: set line /dev/tty01 set speed 19200 set file type binary set file names literal set win 8 set rec pack 1024 set send pack 1024 set block 3 set term bytesize 8 set command bytesize 8 set flow none pau 1 out +++ inp 5 OK out ATH0\13 inp 5 OK echo \13 out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable ; autoanswer mod inp 5 OK echo \13 exit A script named /etc/ppp/kermit.dial is used for dialing and authenticating on the remote host. You will need to customize it for your needs. Put your login and password in this script; you will also need to change the input statement depending on responses from your modem and remote host. ; ; put the com line attached to the modem here: ; set line /dev/tty01 ; ; put the modem speed here: ; set speed 19200 set file type binary ; full 8 bit file xfer set file names literal set win 8 set rec pack 1024 set send pack 1024 set block 3 set term bytesize 8 set command bytesize 8 set flow none set modem hayes set dial hangup off set carrier auto ; Then SET CARRIER if necessary, set dial display on ; Then SET DIAL if necessary, set input echo on set input timeout proceed set input case ignore def \%x 0 ; login prompt counter goto slhup :slcmd ; put the modem in command mode echo Put the modem in command mode. clear ; Clear unread characters from input buffer pause 1 output +++ ; hayes escape sequence input 1 OK\13\10 ; wait for OK if success goto slhup output \13 pause 1 output at\13 input 1 OK\13\10 if fail goto slcmd ; if modem doesn't answer OK, try again :slhup ; hang up the phone clear ; Clear unread characters from input buffer pause 1 echo Hanging up the phone. output ath0\13 ; hayes command for on hook input 2 OK\13\10 if fail goto slcmd ; if no OK answer, put modem in command mode :sldial ; dial the number pause 1 echo Dialing. output atdt9,550311\13\10 ; put phone number here assign \%x 0 ; zero the time counter :look clear ; Clear unread characters from input buffer increment \%x ; Count the seconds input 1 {CONNECT } if success goto sllogin reinput 1 {NO CARRIER\13\10} if success goto sldial reinput 1 {NO DIALTONE\13\10} if success goto slnodial reinput 1 {\255} if success goto slhup reinput 1 {\127} if success goto slhup if < \%x 60 goto look else goto slhup :sllogin ; login assign \%x 0 ; zero the time counter pause 1 echo Looking for login prompt. :slloop increment \%x ; Count the seconds clear ; Clear unread characters from input buffer output \13 ; ; put your expected login prompt here: ; input 1 {Username: } if success goto sluid reinput 1 {\255} if success goto slhup reinput 1 {\127} if success goto slhup if < \%x 10 goto slloop ; try 10 times to get a login prompt else goto slhup ; hang up and start again if 10 failures :sluid ; ; put your userid here: ; output ppp-login\13 input 1 {Password: } ; ; put your password here: ; output ppp-password\13 input 1 {Entering SLIP mode.} echo quit :slnodial echo \7No dialtone. Check the telephone line!\7 exit 1 ; local variables: ; mode: csh ; comment-start: "; " ; comment-start-skip: "; " ; end: Using <application>PPP</application> over Ethernet (PPPoE) PPPover Ethernet PPPoE (see PPP, over Ethernet) Contributed by &a.jim; (from node.to) 10 Jan 2000. The following describes how to set up PPP over Ethernet, a.k.a, PPPoE. Prerequisites There are a few requirements that your system will need to meet in order for PPPoE to function properly. They are: Kernel source for FreeBSD 3.4 or later ppp from FreeBSD 3.4 or later Kernel Configuration kernelconfiguration You will need to set the following options in your kernel configuration file and then compile a new kernel. options NETGRAPH Optionally, you can add options NETGRAPH_PPPOE options NETGRAPH_SOCKET although if this functionality is not available at runtime, ppp will load the relevant modules on demand Setting up <filename>ppp.conf</filename> Here is an example of a working ppp.conf: default: # or name_of_service_provider set device PPPoE:xl1 # replace xl1 with your ethernet device set mru 1492 set mtu 1492 set authname YOURLOGINNAME set authkey YOURPASSWORD set log Phase tun command # you can add more detailed logging if you wish set dial set login set ifaddr 10.0.0.1/0 10.0.0.2/0 add default HISADDR nat enable yes # if you want to enable nat for your local net papchap: set authname YOURLOGINNAME set authkey YOURPASSWORD Care should be taken when running PPPoE with the option. Running <application>PPP</application> As root, you can run: &prompt.root; ppp -ddial name_of_service_provider Starting <application>PPP</application> at Boot Add the following to your /etc/rc.conf file: ppp_enable="YES" ppp_mode="ddial" ppp_nat="YES" ppp_profile="default" # or your provider PPPoE with a 3Com HomeConnect ADSL Modem Dual Link Contributed by &a.lioux;, 07 Apr 2001. In short, it does not work. It should, but unfortunately, that is not the case. For whatever reason, this modem does not follow RFC 2516 (A Method for transmitting PPP over Ethernet (PPPoE), written by L. Mamakos, K. Lidl, J. Evarts, D. Carrel, D. Simone, and R. Wheeler). Since it does not follow the specification, FreeBSD's PPPoE implementation will not talk to it. It is very likely that it will not work under other unixes for that same reason. Complain to 3Com if you think it should comply with the PPPoE specification. ADSL If you absolutely want to use your ADSL connection with FreeBSD and are stuck with this modem, you can either: DSL Try replacing the modem with a different brand or model if your DSL provider permits you to do so. If you are not sure which brand(s) will work, the &a.questions; is a good place to ask. Try to get it working. Keep in mind that there is no guarantee it will work, your mileage may vary. If you want to try to make it work, you can do the following, but please keep in mind that you do this at your own risk! Just because it worked for me does not mean it will work for you. There are three steps to the process. They are: Make sure you already have ppp.conf set up. See the beginning of this chapter for more details on doing so. Since the modem does not speak the correct protocol, we need to learn how to speak its variant of the protocol. This information was obtained from a DSLreports forum message. The modem speaks 0x3c12 for DISCOVERY, and 0x3c13 for PAYLOAD identifiers instead of 0x8863 and 0x8864 respectively, as mandated by the PPPoE specification. Code RFC's Code Dual Link Modem's Code PAYLOAD 0x8863 0x3c12 PAYLOAD 0x8864 0x3c13 So, now what? You need to recompile the NETGRAPH_PPPOE code with the modem's codes. For this, you should have installed the full kernel sources. Find the /usr/src/sys/netgraph/ng_pppoe.h file. Be careful while editing this file. You have to modify both the little and the big endian entries. For big endian, find the line with 0x8863 in it, and replace the number with 0x3c12. Do the same with 0x8864, replacing it with 0x3c13. For little endian, find the line with 0x6388in it, and replace the number with 0x123c. Do the same with 0x6488, replacing it with 0x133c. Here is a diff of how the new file should look: &prompt.user; diff -u ng_pppoe.h.orig ng_pppoe.h --- ng_pppoe.h.orig Thu Apr 12 13:42:46 2001 +++ ng_pppoe.h Thu Apr 12 13:44:47 2001 @@ -148,8 +148,8 @@ #define PTT_SYS_ERR (0x0202) #define PTT_GEN_ERR (0x0203) -#define ETHERTYPE_PPPOE_DISC 0x8863 /* pppoe discovery packets */ -#define ETHERTYPE_PPPOE_SESS 0x8864 /* pppoe session packets */ +#define ETHERTYPE_PPPOE_DISC 0x3c12 /* pppoe discovery packets */ +#define ETHERTYPE_PPPOE_SESS 0x3c13 /* pppoe session packets */ #else #define PTT_EOL (0x0000) #define PTT_SRV_NAME (0x0101) @@ -162,8 +162,8 @@ #define PTT_SYS_ERR (0x0202) #define PTT_GEN_ERR (0x0302) -#define ETHERTYPE_PPPOE_DISC 0x6388 /* pppoe discovery packets */ -#define ETHERTYPE_PPPOE_SESS 0x6488 /* pppoe session packets */ +#define ETHERTYPE_PPPOE_DISC 0x123c /* pppoe discovery packets */ +#define ETHERTYPE_PPPOE_SESS 0x133c /* pppoe session packets */ #endif struct pppoe_tag { Then do the following as root: &prompt.root; cd /usr/src/sys/modules/netgraph/pppoe &prompt.root; make clean depend all install &prompt.root; make clean Now you can speak the modem's variant of the PPPoE specification. The third step is to figure out the name of the profile your ISP assigned to the modem. The information for this step was obtained from the Roaring Penguin PPPoE program which can be found in the ports collection. If you still are not able to find it, ask your ISP's tech support. If they do not know it either, and you are feeling bold (this may de-program your modem and render it useless, so think twice about doing it). Install the program shipped with the modem by your provider. Then, access the System menu from the program. The name of your profile should be listed there. It is usually ISP. The profile name will be used in the PPPoE configuration inside ppp.conf as the provider parameter. See the &man.ppp.8; manual page for more information. The PPPoE line in your ppp.conf should look like this: set device PPPoE:xl1:ISP Do not forget to change xl1 - to the proper device for your ethernet card. + to the proper device for your Ethernet card. Do not forget to change ISP to the profile you have just found above. For additional information, you can try: Cheaper Broadband with FreeBSD on DSL by Renaud Waldura in Daemon News. Another PPPoE tutorial by Sympatico Users Group. Using SLIP SLIP Originally contributed by &a.asami; and &a.ghelmer;, with input from &a.wilko; and &a.piero;. Setting up a SLIP Client SLIPclient The following is one way to set up a FreeBSD machine for SLIP on a static host network. For dynamic hostname assignments (i.e., your address changes each time you dial up), you probably need to do something much fancier. First, determine which serial port your modem is connected to. I have a symbolic link to /dev/modem from /dev/cuaa1, and only use the modem name in my configuration files. It can become quite cumbersome when you need to fix a bunch of files in /etc and .kermrc's all over the system! /dev/cuaa0 is COM1, cuaa1 is COM2, etc. Make sure you have the following in your kernel configuration file: pseudo-device sl 1 It is included in the GENERIC kernel, so this should not be a problem unless you have deleted it. Things you have to do only once Add your home machine, the gateway and nameservers to your /etc/hosts file. Mine looks like this: 127.0.0.1 localhost loghost 136.152.64.181 silvia.HIP.Berkeley.EDU silvia.HIP silvia 136.152.64.1 inr-3.Berkeley.EDU inr-3 slip-gateway 128.32.136.9 ns1.Berkeley.edu ns1 128.32.136.12 ns2.Berkeley.edu ns2 Make sure you have before in your /etc/host.conf. Otherwise, funny things may happen. Edit the /etc/rc.conf file. Set your hostname by editing the line that says: hostname=myname.my.domain You should give it your full Internet hostname. Add sl0 to the list of network interfaces by changing the line that says: network_interfaces="lo0" to: network_interfaces=lo0 sl0 Set the startup flags of sl0 by adding a line: ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up" default router Designate the default router by changing the line: defaultrouter=NO to: defaultrouter=slip-gateway Make a file /etc/resolv.conf which contains: domain HIP.Berkeley.EDU nameserver 128.32.136.9 nameserver 128.32.136.12 name server domain name As you can see, these set up the nameserver hosts. Of course, the actual domain names and addresses depend on your environment. Set the password for root and toor (and any other accounts that do not have a password). Use passwd or &man.vipw.8;, do not edit the /etc/passwd or /etc/master.passwd files! Reboot your machine and make sure it comes up with the correct hostname. Making a SLIP connection SLIPconnecting with Dial up, type slip at the prompt, enter your machine name and password. The things you need to enter depends on your environment. If you use kermit, you can try a script like this: # kermit setup set modem hayes set line /dev/modem set speed 115200 set parity none set flow rts/cts set terminal bytesize 8 set file type binary # The next macro will dial up and login define slip dial 643-9600, input 10 =>, if failure stop, - output slip\x0d, input 10 Username:, if failure stop, - output silvia\x0d, input 10 Password:, if failure stop, - output ***\x0d, echo \x0aCONNECTED\x0a Of course, you have to change the hostname and password to fit yours. After doing so, you can just type slip from the kermit prompt to get connected. Leaving your password in plain text anywhere in the filesystem is generally a BAD idea. Do it at your own risk. Leave the kermit there (you can suspend it by z) and as root, type: &prompt.root; slattach -h -c -s 115200 /dev/modem If you are able to ping hosts on the other side of the router, you are connected! If it does not work, you might want to try instead of as an argument to slattach. How to shutdown the connection Do the following: &prompt.root; kill -INT `cat /var/run/slattach.modem.pid` to kill slattach. Keep in mind you must be root to do the above. Then go back to kermit (fg if you suspended it) and exit from it (q). The slattach man page says you have to use ifconfig sl0 down to mark the interface down, but this does not seem to make any difference for me. (ifconfig sl0 reports the same thing.) Some times, your modem might refuse to drop the carrier (mine often does). In that case, simply start kermit and quit it again. It usually goes out on the second try. Troubleshooting If it does not work, feel free to ask me. The things that people tripped over so far: Not using or in slattach (I have no idea why this can be fatal, but adding this flag solved the problem for at least one person). Using instead of (might be hard to see the difference on some fonts). Try ifconfig sl0 to see your interface status. For example, you might get: &prompt.root; ifconfig sl0 sl0: flags=10<POINTOPOINT> inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00 Also, netstat -r will give the routing table, in case you get the no route to host messages from ping. Mine looks like: &prompt.root; netstat -r Routing tables Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks: (root node) (root node) Route Tree for Protocol Family inet: (root node) => default inr-3.Berkeley.EDU UG 8 224515 sl0 - - localhost.Berkel localhost.Berkeley UH 5 42127 lo0 - 0.438 inr-3.Berkeley.E silvia.HIP.Berkele UH 1 0 sl0 - - silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438 (root node) This is after transferring a bunch of files, your numbers should be smaller). Setting up a SLIP Server SLIPserver This document provides suggestions for setting up SLIP Server services on a FreeBSD system, which typically means configuring your system to automatically startup connections upon login for remote SLIP clients. The author has written this document based on his experience; however, as your system and needs may be different, this document may not answer all of your questions, and the author cannot be responsible if you damage your system or lose data due to attempting to follow the suggestions here. Prerequisites TCP/IP This document is very technical in nature, so background knowledge is required. It is assumed that you are familiar with the TCP/IP network protocol, and in particular, network and node addressing, network address masks, subnetting, routing, and routing protocols, such as RIP. Configuring SLIP services on a dial-up server requires a knowledge of these concepts, and if you are not familiar with them, please read a copy of either Craig Hunt's TCP/IP Network Administration published by O'Reilly & Associates, Inc. (ISBN Number 0-937175-82-X), or Douglas Comer's books on the TCP/IP protocol. modem It is further assumed that you have already setup your modem(s) and configured the appropriate system files to allow logins through your modems. If you have not prepared your system for this yet, please see the tutorial for configuring dialup services; if you have a World-Wide Web browser available, browse the list of tutorials at http://www.FreeBSD.org/. You may also want to check the manual pages for &man.sio.4; for information on the serial port device driver and &man.ttys.5;, &man.gettytab.5;, &man.getty.8;, & &man.init.8; for information relevant to configuring the system to accept logins on modems, and perhaps &man.stty.1; for information on setting serial port parameters (such as clocal for directly-connected serial interfaces). Quick Overview In its typical configuration, using FreeBSD as a SLIP server works as follows: a SLIP user dials up your FreeBSD SLIP Server system and logs in with a special SLIP login ID that uses /usr/sbin/sliplogin as the special user's shell. The sliplogin program browses the file /etc/sliphome/slip.hosts to find a matching line for the special user, and if it finds a match, connects the serial line to an available SLIP interface and then runs the shell script /etc/sliphome/slip.login to configure the SLIP interface. An Example of a SLIP Server Login For example, if a SLIP user ID were Shelmerg, Shelmerg's entry in /etc/master.passwd would look something like this (except it would be all on one line): Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin When Shelmerg logs in, sliplogin will search /etc/sliphome/slip.hosts for a line that had a matching user ID; for example, there may be a line in /etc/sliphome/slip.hosts that reads: Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp sliplogin will find that matching line, hook the serial line into the next available SLIP interface, and then execute /etc/sliphome/slip.login like this: /etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp If all goes well, /etc/sliphome/slip.login will issue an ifconfig for the SLIP interface to which sliplogin attached itself (slip interface 0,in the above example, which was the first parameter in the list given to slip.login) to set the local IP address (dc-slip), remote IP address (sl-helmer), network mask for the SLIP interface (0xfffffc00), and any additional flags (autocomp). If something goes wrong, sliplogin usually logs good informational messages via the daemon syslog facility, which usually goes into /var/log/messages (see the manual pages for &man.syslogd.8; and &man.syslog.conf.5; and perhaps check /etc/syslog.conf to see to which files syslogd is logging). OK, enough of the examples — let us dive into setting up the system. Kernel Configuration kernelconfiguration FreeBSD's default kernels usually come with two SLIP interfaces defined (sl0 and sl1); you can use netstat -i to see whether these interfaces are defined in your kernel. Sample output from netstat -i: Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll ed0 1500 <Link>0.0.c0.2c.5f.4a 291311 0 174209 0 133 ed0 1500 138.247.224 ivory 291311 0 174209 0 133 lo0 65535 <Link> 79 0 79 0 0 lo0 65535 loop localhost 79 0 79 0 0 sl0* 296 <Link> 0 0 0 0 0 sl1* 296 <Link> 0 0 0 0 0 The sl0 and sl1 interfaces shown in netstat -i's output indicate that there are two SLIP interfaces built into the kernel. (The asterisks after the sl0 and sl1 indicate that the interfaces are down.) However, FreeBSD's default kernels do not come configured to forward packets (ie, your FreeBSD machine will not act as a router) due to Internet RFC requirements for Internet hosts (see RFCs 1009 [Requirements for Internet Gateways], 1122 [Requirements for Internet Hosts — Communication Layers], and perhaps 1127 [A Perspective on the Host Requirements RFCs]), so if you want your FreeBSD SLIP Server to act as a router, you will have to edit the /etc/rc.conf file and change the setting of the gateway_enable variable to . You will then need to reboot for the new settings to take effect. You will notice that near the end of the default kernel configuration file (/sys/i386/conf/GENERIC) is a line that reads: pseudo-device sl 2 SLIP This is the line that defines the number of SLIP devices available in the kernel; the number at the end of the line is the maximum number of SLIP connections that may be operating simultaneously. Please refer to Configuring the FreeBSD Kernel for help in reconfiguring your kernel. Sliplogin Configuration As mentioned earlier, there are three files in the /etc/sliphome directory that are part of the configuration for /usr/sbin/sliplogin (see &man.sliplogin.8; for the actual manual page for sliplogin): slip.hosts, which defines the SLIP users & their associated IP addresses; slip.login, which usually just configures the SLIP interface; and (optionally) slip.logout, which undoes slip.login's effects when the serial connection is terminated. <filename>slip.hosts</filename> Configuration /etc/sliphome/slip.hosts contains lines which have at least four items, separated by whitespace: SLIP user's login ID Local address (local to the SLIP server) of the SLIP link Remote address of the SLIP link Network mask The local and remote addresses may be host names (resolved to IP addresses by /etc/hosts or by the domain name service, depending on your specifications in /etc/host.conf), and the network mask may be a name that can be resolved by a lookup into /etc/networks. On a sample system, /etc/sliphome/slip.hosts looks like this: # # login local-addr remote-addr mask opt1 opt2 # (normal,compress,noicmp) # Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp At the end of the line is one or more of the options. — no header compression — compress headers — compress headers if the remote end allows it — disable ICMP packets (so any ping packets will be dropped instead of using up your bandwidth) Note that sliplogin under early releases of FreeBSD 2 ignored the options that FreeBSD 1.x recognized, so the options , , , and had no effect until support was added in FreeBSD 2.2 (unless your slip.login script included code to make use of the flags). SLIP TCP/IP Your choice of local and remote addresses for your SLIP links depends on whether you are going to dedicate a TCP/IP subnet or if you are going to use proxy ARP on your SLIP server (it is not true proxy ARP, but that is the terminology used in this document to describe it). If you are not sure which method to select or how to assign IP addresses, please refer to the TCP/IP books referenced in the slips-prereqs section and/or consult your IP network manager. gated If you are going to use a separate subnet for your SLIP clients, you will need to allocate the subnet number out of your assigned IP network number and assign each of your SLIP client's IP numbers out of that subnet. Then, you will probably either need to configure a static route to the SLIP subnet via your SLIP server on your nearest IP router, or install gated on your FreeBSD SLIP server and configure it to talk the appropriate routing protocols to your other routers to inform them about your SLIP server's route to the SLIP subnet. Ethernet Otherwise, if you will use the proxy ARP method, you will need to assign your SLIP client's IP addresses out of your SLIP server's Ethernet subnet, and you will also need to adjust your /etc/sliphome/slip.login and /etc/sliphome/slip.logout scripts to use &man.arp.8; to manage the proxy-ARP entries in the SLIP server's ARP table. <filename>slip.login</filename> Configuration The typical /etc/sliphome/slip.login file looks like this: #!/bin/sh - # # @(#)slip.login 5.1 (Berkeley) 7/1/90 # # generic login file for a slip line. sliplogin invokes this with # the parameters: # 1 2 3 4 5 6 7-n # slipunit ttyspeed loginname local-addr remote-addr mask opt-args # /sbin/ifconfig sl$1 inet $4 $5 netmask $6 This slip.login file merely ifconfig's the appropriate SLIP interface with the local and remote addresses and network mask of the SLIP interface. If you have decided to use the proxy ARP method (instead of using a separate subnet for your SLIP clients), your /etc/sliphome/slip.login file will need to look something like this: #!/bin/sh - # # @(#)slip.login 5.1 (Berkeley) 7/1/90 # # generic login file for a slip line. sliplogin invokes this with # the parameters: # 1 2 3 4 5 6 7-n # slipunit ttyspeed loginname local-addr remote-addr mask opt-args # /sbin/ifconfig sl$1 inet $4 $5 netmask $6 # Answer ARP requests for the SLIP client with our Ethernet addr /usr/sbin/arp -s $5 00:11:22:33:44:55 pub The additional line in this slip.login, arp -s $5 00:11:22:33:44:55 pub, creates an ARP entry in the SLIP server's ARP table. This ARP entry causes the SLIP server to respond with the SLIP server's Ethernet MAC address whenever a another IP node on the Ethernet asks to speak to the SLIP client's IP address. EthernetMAC address When using the example above, be sure to replace the Ethernet MAC address (00:11:22:33:44:55) with the MAC address of your system's Ethernet card, or your proxy ARP will definitely not work! You can discover your SLIP server's Ethernet MAC address by looking at the results of running netstat -i; the second line of the output should look something like: ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116 This indicates that this particular system's Ethernet MAC address is 00:02:c1:28:5f:4a — the periods in the Ethernet MAC address given by netstat -i must be changed to colons and leading zeros should be added to each single-digit hexadecimal number to convert the address into the form that &man.arp.8; desires; see the manual page on &man.arp.8; for complete information on usage. When you create /etc/sliphome/slip.login and /etc/sliphome/slip.logout, the execute bit (ie, chmod 755 /etc/sliphome/slip.login /etc/sliphome/slip.logout) must be set, or sliplogin will be unable to execute it. <filename>slip.logout</filename> Configuration /etc/sliphome/slip.logout is not strictly needed (unless you are implementing proxy ARP), but if you decide to create it, this is an example of a basic slip.logout script: #!/bin/sh - # # slip.logout # # logout file for a slip line. sliplogin invokes this with # the parameters: # 1 2 3 4 5 6 7-n # slipunit ttyspeed loginname local-addr remote-addr mask opt-args # /sbin/ifconfig sl$1 down If you are using proxy ARP, you will want to have /etc/sliphome/slip.logout remove the ARP entry for the SLIP client: #!/bin/sh - # # @(#)slip.logout # # logout file for a slip line. sliplogin invokes this with # the parameters: # 1 2 3 4 5 6 7-n # slipunit ttyspeed loginname local-addr remote-addr mask opt-args # /sbin/ifconfig sl$1 down # Quit answering ARP requests for the SLIP client /usr/sbin/arp -d $5 The arp -d $5 removes the ARP entry that the proxy ARP slip.login added when the SLIP client logged in. It bears repeating: make sure /etc/sliphome/slip.logout has the execute bit set for after you create it (ie, chmod 755 /etc/sliphome/slip.logout). Routing Considerations SLIProuting If you are not using the proxy ARP method for routing packets between your SLIP clients and the rest of your network (and perhaps the Internet), you will probably either have to add static routes to your closest default router(s) to route your SLIP client subnet via your SLIP server, or you will probably need to install and configure gated on your FreeBSD SLIP server so that it will tell your routers via appropriate routing protocols about your SLIP subnet. Static Routes static routes Adding static routes to your nearest default routers can be troublesome (or impossible, if you do not have authority to do so...). If you have a multiple-router network in your organization, some routers, such as Cisco and Proteon, may not only need to be configured with the static route to the SLIP subnet, but also need to be told which static routes to tell other routers about, so some expertise and troubleshooting/tweaking may be necessary to get static-route-based routing to work. Running <command>gated</command> gated An alternative to the headaches of static routes is to install gated on your FreeBSD SLIP server and configure it to use the appropriate routing protocols (RIP/OSPF/BGP/EGP) to tell other routers about your SLIP subnet. You can use gated from the ports collection or retrieve and build it yourself from the - GateD anonymous ftp site; the current version + GateD anonymous FTP site; the current version as of this writing is gated-R3_5Alpha_8.tar.Z, which includes support for FreeBSD out-of-the-box. Complete information and documentation on gated is available on the Web starting at the Merit GateD Consortium. Compile and install it, and then write a /etc/gated.conf file to configure your gated; here is a sample, similar to what the author used on a FreeBSD SLIP server: # # gated configuration file for dc.dsu.edu; for gated version 3.5alpha5 # Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface # # # tracing options # traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ; rip yes { interface sl noripout noripin ; interface ed ripin ripout version 1 ; traceoptions route ; } ; # # Turn on a bunch of tracing info for the interface to the kernel: kernel { traceoptions remnants request routes info interface ; } ; # # Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP # export proto rip interface ed { proto direct { xxx.xxx.yy mask 255.255.252.0 metric 1; # SLIP connections } ; } ; # # Accept routes from RIP via ed Ethernet interfaces import proto rip interface ed { all ; } ; RIP The above sample gated.conf file broadcasts routing information regarding the SLIP subnet xxx.xxx.yy via RIP onto the Ethernet; if you are using a different Ethernet driver than the ed driver, you will need to change the references to the ed interface appropriately. This sample file also sets up tracing to /var/tmp/gated.output for debugging gated's activity; you can certainly turn off the tracing options if gated works OK for you. You will need to change the xxx.xxx.yy's into the network address of your own SLIP subnet (be sure to change the net mask in the proto direct clause as well). When you get gated built and installed and create a configuration file for it, you will need to run gated in place of routed on your FreeBSD system; change the routed/gated startup parameters in /etc/netstart as appropriate for your system. Please see the manual page for gated for information on gated's command-line parameters. diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml index 8f6ce0868f..96aa6b4e04 100644 --- a/en_US.ISO8859-1/books/handbook/security/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/security/chapter.sgml @@ -1,3037 +1,3037 @@ Security security Much of this chapter has been taken from the &man.security.7; man page, originally written by &a.dillon;. Synopsis The following chapter will provide a basic introduction to system security concepts, some general good rules of thumb, and some advanced topics such as S/Key, OpenSSL, Kerberos, and others. Introduction Security is a function that begins and ends with the system administrator. While all BSD Unix multi-user systems have some inherent security, the job of building and maintaining additional security mechanisms to keep those users honest is probably one of the single largest undertakings of the sysadmin. Machines are only as secure as you make them, and security concerns are ever competing with the human necessity for convenience. Unix systems, in general, are capable of running a huge number of simultaneous processes and many of these processes operate as servers – meaning that external entities can connect and talk to them. As yesterday's mini-computers and mainframes become today's desktops, and as computers become networked and internetworked, security becomes an ever bigger issue. Security is best implemented through a layered onion approach. In a nutshell, what you want to do is to create as many layers of security as are convenient and then carefully monitor the system for intrusions. You do not want to overbuild your security or you will interfere with the detection side, and detection is one of the single most important aspects of any security mechanism. For example, it makes little sense to set the schg flags (see &man.chflags.1;) on every system binary because while this may temporarily protect the binaries, it prevents an attacker who has broken in from making an easily detectable change that may result in your security mechanisms not detecting the attacker at all. System security also pertains to dealing with various forms of attack, including attacks that attempt to crash or otherwise make a system unusable but do not attempt to break root. Security concerns can be split up into several categories: Denial of service attacks. User account compromises. Root compromise through accessible servers. Root compromise via user accounts. Backdoor creation. DOS attacks security DOS attacks Denial of Service A denial of service attack is an action that deprives the machine of needed resources. Typically, D.O.S. attacks are brute-force mechanisms that attempt to crash or otherwise make a machine unusable by overwhelming its servers or network stack. Some D.O.S. attacks try to take advantages of bugs in the networking stack to crash a machine with a single packet. The latter can only be fixed by applying a bug fix to the kernel. Attacks on servers can often be fixed by properly specifying options to limit the load the servers incur on the system under adverse conditions. Brute-force network attacks are harder to deal with. A spoofed-packet attack, for example, is nearly impossible to stop short of cutting your system off from the Internet. It may not be able to take your machine down, but it can saturate your Internet connection. security account compromises A user account compromise is even more common than a D.O.S. attack. Many sysadmins still run standard telnetd, rlogind, rshd, and ftpd servers on their machines. These servers, by default, do not operate over encrypted connections. The result is that if you have any moderate-sized user base, one or more of your users logging into your system from a remote location (which is the most common and convenient way to login to a system) will have his or her password sniffed. The attentive system admin will analyze his remote access logs looking for suspicious source addresses even for successful logins. One must always assume that once an attacker has access to a user account, the attacker can break root. However, the reality is that in a well secured and maintained system, access to a user account does not necessarily give the attacker access to root. The distinction is important because without access to root the attacker cannot generally hide his tracks and may, at best, be able to do nothing more than mess with the user's files or crash the machine. User account compromises are very common because users tend not to take the precautions that sysadmins take. security backdoors System administrators must keep in mind that there are potentially many ways to break root on a machine. The attacker may know the root password, the attacker may find a bug in a root-run server and be able to break root over a network connection to that server, or the attacker may know of a bug in an suid-root program that allows the attacker to break root once he has broken into a user's account. If an attacker has found a way to break root on a machine, the attacker may not have a need to install a backdoor. Many of the root holes found and closed to date involve a considerable amount of work by the attacker to cleanup after himself, so most attackers install backdoors. Backdoors provide the attacker with a way to easily regain root access to the system, but it also gives the smart system administrator a convenient way to detect the intrusion. Making it impossible for an attacker to install a backdoor may actually be detrimental to your security because it will not close off the hole the attacker found to break in the first place. Security remedies should always be implemented with a multi-layered onion peel approach and can be categorized as follows: Securing root and staff accounts. Securing root – root-run servers and suid/sgid binaries. Securing user accounts. Securing the password file. Securing the kernel core, raw devices, and filesystems. Quick detection of inappropriate changes made to the system. Paranoia. The next section of this chapter will cover the above bullet items in greater depth. security securing Securing FreeBSD The sections that follow will cover the methods of securing your FreeBSD system that were mentioned in the last section of this chapter. Securing the root account and staff accounts su First off, do not bother securing staff accounts if you have not secured the root account. Most systems have a password assigned to the root account. The first thing you do is assume that the password is always compromised. This does not mean that you should remove the password. The password is almost always necessary for console access to the machine. What it does mean is that you should not make it possible to use the password outside of the console or possibly even with the &man.su.1; command. For example, make sure that your pty's are specified as being unsecure in the /etc/ttys file so that direct root logins via telnet or rlogin are disallowed. If using other login services such as sshd, make sure that direct root logins are disabled there as well. Consider every access method – services such as FTP often fall through the cracks. Direct root logins should only be allowed via the system console. wheel Of course, as a sysadmin you have to be able to get to root, so we open up a few holes. But we make sure these holes require additional password verification to operate. One way to make root accessible is to add appropriate staff accounts to the wheel group (in /etc/group). The staff members placed in the wheel group are allowed to su to root. You should never give staff members native wheel access by putting them in the wheel group in their password entry. Staff accounts should be placed in a staff group, and then added to the wheel group via the /etc/group file. Only those staff members who actually need to have root access should be placed in the wheel group. It is also possible, when using an authentication method such as kerberos, to use kerberos' .k5login file in the root account to allow a &man.ksu.1; to root without having to place anyone at all in the wheel group. This may be the better solution since the wheel mechanism still allows an intruder to break root if the intruder has gotten hold of your password file and can break into a staff account. While having the wheel mechanism is better than having nothing at all, it is not necessarily the safest option. An indirect way to secure staff accounts, and ultimately root access is to use an alternative login access method and do what is known as *'ing out the crypted password for the staff accounts. Using the &man.vipw.8; command, one can replace each instance of a crypted password with a single * character. This command will update the /etc/master.passwd file and user/password database to disable password-authenticated logins. A staff account entry such as: foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh Should be changed to this : foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh This change will prevent normal logins from occurring, since the encrypted password will never match *. With this done, staff members must use another mechanism to authenticate themselves such as &man.kerberos.1; or &man.ssh.1; using a public/private key pair. When using something like kerberos, one generally must secure the machines which run the kerberos servers and your desktop workstation. When using a public/private key pair with ssh, one must generally secure the machine used to login from (typically one's workstation). An additional layer of protection can be added to the key pair by password protecting the key pair when creating it with &man.ssh-keygen.1;. Being able to * out the passwords for staff accounts also guarantees that staff members can only login through secure access methods that you have setup. This forces all staff members to use secure, encrypted connections for all of their sessions which closes an important hole used by many intruders: That of sniffing the network from an unrelated, less secure machine. The more indirect security mechanisms also assume that you are logging in from a more restrictive server to a less restrictive server. For example, if your main box is running all sorts of servers, your workstation should not be running any. In order for your workstation to be reasonably secure you should run as few servers as possible, up to and including no servers at all, and you should run a password-protected screen blanker. Of course, given physical access to a workstation an attacker can break any sort of security you put on it. This is definitely a problem that you should consider but you should also consider the fact that the vast majority of break-ins occur remotely, over a network, from people who do not have physical access to your workstation or servers. Kerberos Using something like kerberos also gives you the ability to disable or change the password for a staff account in one place and have it immediately effect all the machine the staff member may have an account on. If a staff member's account gets compromised, the ability to instantly change his password on all machines should not be underrated. With discrete passwords, changing a password on N machines can be a mess. You can also impose re-passwording restrictions with kerberos: not only can a kerberos ticket be made to timeout after a while, but the kerberos system can require that the user choose a new password after a certain period of time (say, once a month). Securing Root-run Servers and SUID/SGID Binaries ntalk comsat finger sandboxes sshd telnetd rshd rlogind The prudent sysadmin only runs the servers he needs to, no more, no less. Be aware that third party servers are often the most bug-prone. For example, running an old version of imapd or popper is like giving a universal root ticket out to the entire world. Never run a server that you have not checked out carefully. Many servers do not need to be run as root. For example, the ntalk, comsat, and finger daemons can be run in special user sandboxes. A sandbox isn't perfect unless you go to a large amount of trouble, but the onion approach to security still stands: If someone is able to break in through a server running in a sandbox, they still have to break out of the sandbox. The more layers the attacker must break through, the lower the likelihood of his success. Root holes have historically been found in virtually every server ever run as root, including basic system servers. If you are running a machine through which people only login via sshd and never login via telnetd or rshd or rlogind, then turn off those services! FreeBSD now defaults to running ntalkd, comsat, and finger in a sandbox. Another program which may be a candidate for running in a sandbox is &man.named.8;. /etc/defaults/rc.conf includes the arguments necessary to run named in a sandbox in a commented-out form. Depending on whether you are installing a new system or upgrading an existing system, the special user accounts used by these sandboxes may not be installed. The prudent sysadmin would research and implement sandboxes for servers whenever possible. sendmail There are a number of other servers that typically do not run in sandboxes: sendmail, popper, imapd, ftpd, and others. There are alternatives to some of these, but installing them may require more work than you are willing to perform (the convenience factor strikes again). You may have to run these servers as root and rely on other mechanisms to detect break-ins that might occur through them. The other big potential root hole in a system are the suid-root and sgid binaries installed on the system. Most of these binaries, such as rlogin, reside in /bin, /sbin, /usr/bin, or /usr/sbin. While nothing is 100% safe, the system-default suid and sgid binaries can be considered reasonably safe. Still, root holes are occasionally found in these binaries. A root hole was found in Xlib in 1998 that made xterm (which is typically suid) vulnerable. It is better to be safe than sorry and the prudent sysadmin will restrict suid binaries that only staff should run to a special group that only staff can access, and get rid of (chmod 000) any suid binaries that nobody uses. A server with no display generally does not need an xterm binary. Sgid binaries can be almost as dangerous. If an intruder can break an sgid-kmem binary the intruder might be able to read /dev/kmem and thus read the crypted password file, potentially compromising any passworded account. Alternatively an intruder who breaks group kmem can monitor keystrokes sent through pty's, including pty's used by users who login through secure methods. An intruder that breaks the tty group can write to almost any user's tty. If a user is running a terminal program or emulator with a keyboard-simulation feature, the intruder can potentially generate a data stream that causes the user's terminal to echo a command, which is then run as that user. Securing User Accounts User accounts are usually the most difficult to secure. While you can impose Draconian access restrictions on your staff and * out their passwords, you may not be able to do so with any general user accounts you might have. If you do have sufficient control then you may win out and be able to secure the user accounts properly. If not, you simply have to be more vigilant in your monitoring of those accounts. Use of ssh and kerberos for user accounts is more problematic due to the extra administration and technical support required, but still a very good solution compared to a crypted password file. Securing the Password File The only sure fire way is to * out as many passwords as you can and use ssh or kerberos for access to those accounts. Even though the crypted password file (/etc/spwd.db) can only be read by root, it may be possible for an intruder to obtain read access to that file even if the attacker cannot obtain root-write access. Your security scripts should always check for and report changes to the password file (see Checking file integrity below). Securing the Kernel Core, Raw Devices, and Filesystems If an attacker breaks root he can do just about anything, but there are certain conveniences. For example, most modern kernels have a packet sniffing device driver built in. Under FreeBSD it is called the bpf device. An intruder will commonly attempt to run a packet sniffer on a compromised machine. You do not need to give the intruder the capability and most systems should not have the bpf device compiled in. sysctl But even if you turn off the bpf device, you still have /dev/mem and /dev/kmem to worry about. For that matter, the intruder can still write to raw disk devices. Also, there is another kernel feature called the module loader, &man.kldload.8;. An enterprising intruder can use a KLD module to install his own bpf device or other sniffing device on a running kernel. To avoid these problems you have to run the kernel at a higher secure level, at least securelevel 1. The securelevel can be set with a sysctl on the kern.securelevel variable. Once you have set the securelevel to 1, write access to raw devices will be denied and special chflags flags, such as schg, will be enforced. You must also ensure that the schg flag is set on critical startup binaries, directories, and script files – everything that gets run up to the point where the securelevel is set. This might be overdoing it, and upgrading the system is much more difficult when you operate at a higher secure level. You may compromise and run the system at a higher secure level but not set the schg flag for every system file and directory under the sun. Another possibility is to simply mount / and /usr read-only. It should be noted that being too draconian in what you attempt to protect may prevent the all-important detection of an intrusion. Checking File Integrity: Binaries, Configuration Files, Etc. When it comes right down to it, you can only protect your core system configuration and control files so much before the convenience factor rears its ugly head. For example, using chflags to set the schg bit on most of the files in / and /usr is probably counterproductive because while it may protect the files, it also closes a detection window. The last layer of your security onion is perhaps the most important – detection. The rest of your security is pretty much useless (or, worse, presents you with a false sense of safety) if you cannot detect potential incursions. Half the job of the onion is to slow down the attacker rather than stop him in order to give the detection side of the equation a chance to catch him in the act. The best way to detect an incursion is to look for modified, missing, or unexpected files. The best way to look for modified files is from another (often centralized) limited-access system. Writing your security scripts on the extra-secure limited-access system makes them mostly invisible to potential attackers, and this is important. In order to take maximum advantage you generally have to give the limited-access box significant access to the other machines in the business, usually either by doing a read-only NFS export of the other machines to the limited-access box, or by setting up ssh key-pairs to allow the limit-access box to ssh to the other machines. Except for its network traffic, NFS is the least visible method – allowing you to monitor the filesystems on each client box virtually undetected. If your limited-access server is connected to the client boxes through a switch, the NFS method is often the better choice. If your limited-access server is connected to the client boxes through a hub or through several layers of routing, the NFS method may be too insecure (network-wise) and using ssh may be the better choice even with the audit-trail tracks that ssh lays. Once you give a limit-access box at least read access to the client systems it is supposed to monitor, you must write scripts to do the actual monitoring. Given an NFS mount, you can write scripts out of simple system utilities such as &man.find.1; and &man.md5.1;. It is best to physically md5 the client-box files boxes at least once a day, and to test control files such as those found in /etc and /usr/local/etc even more often. When mismatches are found relative to the base md5 information the limited-access machine knows is valid, it should scream at a sysadmin to go check it out. A good security script will also check for inappropriate suid binaries and for new or deleted files on system partitions such as / and /usr. When using ssh rather than NFS, writing the security script is much more difficult. You essentially have to scp the scripts to the client box in order to run them, making them visible, and for safety you also need to scp the binaries (such as find) that those scripts use. The ssh daemon on the client box may already be compromised. All in all, using ssh may be necessary when running over unsecure links, but it's also a lot harder to deal with. A good security script will also check for changes to user and staff members access configuration files: .rhosts, .shosts, .ssh/authorized_keys and so forth… files that might fall outside the purview of the MD5 check. If you have a huge amount of user disk space it may take too long to run through every file on those partitions. In this case, setting mount flags to disallow suid binaries and devices on those partitions is a good idea. The nodev and nosuid options (see &man.mount.8;) are what you want to look into. You should probably scan them anyway at least once a week, since the object of this layer is to detect a break-in whether or not the break-in is effective. Process accounting (see &man.accton.8;) is a relatively low-overhead feature of the operating system which might help as a post-break-in evaluation mechanism. It is especially useful in tracking down how an intruder has actually broken into a system, assuming the file is still intact after the break-in occurs. Finally, security scripts should process the log files and the logs themselves should be generated in as secure a manner as possible – remote syslog can be very useful. An intruder tries to cover his tracks, and log files are critical to the sysadmin trying to track down the time and method of the initial break-in. One way to keep a permanent record of the log files is to run the system console to a serial port and collect the information on a continuing basis through a secure machine monitoring the consoles. Paranoia A little paranoia never hurts. As a rule, a sysadmin can add any number of security features as long as they do not effect convenience, and can add security features that do effect convenience with some added thought. Even more importantly, a security administrator should mix it up a bit – if you use recommendations such as those given by this document verbatim, you give away your methodologies to the prospective attacker who also has access to this document. Denial of Service Attacks DOS attacks This section covers Denial of Service attacks. A DOS attack is typically a packet attack. While there is not much you can do about modern spoofed packet attacks that saturate your network, you can generally limit the damage by ensuring that the attacks cannot take down your servers. Limiting server forks. Limiting springboard attacks (ICMP response attacks, ping broadcast, etc.). Kernel Route Cache. A common DOS attack is against a forking server that attempts to cause the server to eat processes, file descriptors, and memory until the machine dies. Inetd (see &man.inetd.8;) has several options to limit this sort of attack. It should be noted that while it is possible to prevent a machine from going down it is not generally possible to prevent a service from being disrupted by the attack. Read the inetd manual page carefully and pay specific attention to the , , and options. Note that spoofed-IP attacks will circumvent the option to inetd, so typically a combination of options must be used. Some standalone servers have self-fork-limitation parameters. Sendmail has its option which tends to work much better than trying to use sendmail's load limiting options due to the load lag. You should specify a MaxDaemonChildren parameter when you start sendmail high enough to handle your expected load but no so high that the computer cannot handle that number of sendmails without falling on its face. It is also prudent to run sendmail in queued mode () and to run the daemon (sendmail -bd) separate from the queue-runs (sendmail -q15m). If you still want real-time delivery you can run the queue at a much lower interval, such as , but be sure to specify a reasonable MaxDaemonChildren option for that sendmail to prevent cascade failures. Syslogd can be attacked directly and it is strongly recommended that you use the option whenever possible, and the option otherwise. You should also be fairly careful with connect-back services such as tcpwrapper's reverse-identd, which can be attacked directly. You generally do not want to use the reverse-ident feature of tcpwrappers for this reason. It is a very good idea to protect internal services from external access by firewalling them off at your border routers. The idea here is to prevent saturation attacks from outside your LAN, not so much to protect internal services from network-based root compromise. Always configure an exclusive firewall, i.e., firewall everything except ports A, B, C, D, and M-Z. This way you can firewall off all of your low ports except for certain specific services such as named (if you are primary for a zone), ntalkd, sendmail, and other Internet-accessible services. If you try to configure the firewall the other way – as an inclusive or permissive firewall, there is a good chance that you will forget to close a couple of services or that you will add a new internal service and forget to update the firewall. You can still open up the high-numbered port range on the firewall to allow permissive-like operation without compromising your low ports. Also take note that FreeBSD allows you to control the range of port numbers used for dynamic binding via the various net.inet.ip.portrange sysctl's (sysctl -a | fgrep portrange), which can also ease the complexity of your firewall's configuration. For example, you might use a normal first/last range of 4000 to 5000, and a hiport range of 49152 to 65535, then block everything under 4000 off in your firewall (except for certain specific Internet-accessible ports, of course). ICMP_BANDLIM Another common DOS attack is called a springboard attack – to attack a server in a manner that causes the server to generate responses which then overload the server, the local network, or some other machine. The most common attack of this nature is the ICMP ping broadcast attack. The attacker spoofs ping packets sent to your LAN's broadcast address with the source IP address set to the actual machine they wish to attack. If your border routers are not configured to stomp on ping's to broadcast addresses, your LAN winds up generating sufficient responses to the spoofed source address to saturate the victim, especially when the attacker uses the same trick on several dozen broadcast addresses over several dozen different networks at once. Broadcast attacks of over a hundred and twenty megabits have been measured. A second common springboard attack is against the ICMP error reporting system. By constructing packets that generate ICMP error responses, an attacker can saturate a server's incoming network and cause the server to saturate its outgoing network with ICMP responses. This type of attack can also crash the server by running it out of mbuf's, especially if the server cannot drain the ICMP responses it generates fast enough. The FreeBSD kernel has a new kernel compile option called ICMP_BANDLIM which limits the effectiveness of these sorts of attacks. The last major class of springboard attacks is related to certain internal inetd services such as the udp echo service. An attacker simply spoofs a UDP packet with the source address being server A's echo port, and the destination address being server B's echo port, where server A and B are both on your LAN. The two servers then bounce this one packet back and forth between each other. The attacker can overload both servers and their LANs simply by injecting a few packets in this manner. Similar problems exist with the internal chargen port. A competent sysadmin will turn off all of these inetd-internal test services. Spoofed packet attacks may also be used to overload the kernel route cache. Refer to the net.inet.ip.rtexpire, rtminexpire, and rtmaxcache sysctl parameters. A spoofed packet attack that uses a random source IP will cause the kernel to generate a temporary cached route in the route table, viewable with netstat -rna | fgrep W3. These routes typically timeout in 1600 seconds or so. If the kernel detects that the cached route table has gotten too big it will dynamically reduce the rtexpire but will never decrease it to less than rtminexpire. There are two problems: The kernel does not react quickly enough when a lightly loaded server is suddenly attacked. The rtminexpire is not low enough for the kernel to survive a sustained attack. If your servers are connected to the Internet via a T3 or better it may be prudent to manually override both rtexpire and rtminexpire via &man.sysctl.8;. Never set either parameter to zero (unless you want to crash the machine :-). Setting both parameters to 2 seconds should be sufficient to protect the route table from attack. Access Issues with Kerberos and SSH SSH Kerberos There are a few issues with both kerberos and ssh that need to be addressed if you intend to use them. Kerberos V is an excellent authentication protocol but there are bugs in the kerberized telnet and rlogin applications that make them unsuitable for dealing with binary streams. Also, by default kerberos does not encrypt a session unless you use the option. ssh encrypts everything by default. ssh works quite well in every respect except that it forwards encryption keys by default. What this means is that if you have a secure workstation holding keys that give you access to the rest of the system, and you ssh to an unsecure machine, your keys becomes exposed. The actual keys themselves are not exposed, but ssh installs a forwarding port for the duration of your login and if a attacker has broken root on the unsecure machine he can utilize that port to use your keys to gain access to any other machine that your keys unlock. We recommend that you use ssh in combination with kerberos whenever possible for staff logins. ssh can be compiled with kerberos support. This reduces your reliance on potentially exposable ssh keys while at the same time protecting passwords via kerberos. ssh keys should only be used for automated tasks from secure machines (something that kerberos is unsuited to). We also recommend that you either turn off key-forwarding in the ssh configuration, or that you make use of the from=IP/DOMAIN option that ssh allows in its authorized_keys file to make the key only usable to entities logging in from specific machines. DES, MD5, and Crypt security crypt crypt DES MD5 Parts rewritten and updated by &a.unfurl;, 21 March 2000. Every user on a Unix system has a password associated with their account. It seems obvious that these passwords need to be known only to the user and the actual operating system. In order to keep these passwords secret, they are encrypted with what is known as a one-way hash, that is, they can only be easily encrypted but not decrypted. In other words, what we told you a moment ago was obvious is not even true: the operating system itself does not really know the password. It only knows the encrypted form of the password. The only way to get the plain-text password is by a brute force search of the space of possible passwords. Unfortunately the only secure way to encrypt passwords when Unix came into being was based on DES, the Data Encryption Standard. This is not such a problem for users that live in the US, but since the source code for DES could not be exported outside the US, FreeBSD had to find a way to both comply with US law and retain compatibility with all the other Unix variants that still use DES. The solution was to divide up the encryption libraries so that US users could install the DES libraries and use DES but international users still had an encryption method that could be exported abroad. This is how FreeBSD came to use MD5 as its default encryption method. MD5 is believed to be more secure than DES, so installing DES is offered primarily for compatibility reasons. Recognizing your crypt mechanism It is pretty easy to identify which encryption method FreeBSD is set up to use. Examining the encrypted passwords in the /etc/master.passwd file is one way. Passwords encrypted with the MD5 hash are longer than those with encrypted with the DES hash and also begin with the characters $1$. DES password strings do not have any particular identifying characteristics, but they are shorter than MD5 passwords, and are coded in a 64-character alphabet which does not include the $ character, so a relatively short string which does not begin with a dollar sign is very likely a DES password. The libraries can identify the passwords this way as well. As a result, the DES libraries are able to identify MD5 passwords, and use MD5 to check passwords that were encrypted that way, and DES for the rest. They are able to do this because the DES libraries also contain MD5. Unfortunately, the reverse is not true, so the MD5 libraries cannot authenticate passwords that were encrypted with DES. Identifying which library is being used by the programs on your system is easy as well. Any program that uses crypt is linked against libcrypt which for each type of library is a symbolic link to the appropriate implementation. For example, on a system using the DES versions: &prompt.user; ls -l /usr/lib/libcrypt* lrwxr-xr-x 1 root wheel 13 Mar 19 06:56 libcrypt.a -> libdescrypt.a lrwxr-xr-x 1 root wheel 18 Mar 19 06:56 libcrypt.so.2.0 -> libdescrypt.so.2.0 lrwxr-xr-x 1 root wheel 15 Mar 19 06:56 libcrypt_p.a -> libdescrypt_p.a On a system using the MD5-based libraries, the same links will be present, but the target will be libscrypt rather than libdescrypt. If you have installed the DES-capable crypt library libdescrypt (e.g. by installing the "crypto" distribution), then which password format will be used for new passwords is controlled by the passwd_format login capability in /etc/login.conf, which takes values of either des or md5. See the &man.login.conf.5; manpage for more information about login capabilities. S/Key S/Key security S/Key S/Key is a one-time password scheme based on a one-way hash function. FreeBSD uses the MD4 hash for compatibility but other systems have used MD5 and DES-MAC. S/Key has been part of the FreeBSD base system since version 1.1.5 and is also used on a growing number of other operating systems. S/Key is a registered trademark of Bell Communications Research, Inc. There are three different sorts of passwords which we will talk about in the discussion below. The first is your usual Unix-style or Kerberos password; we will call this a Unix password. The second sort is the one-time password which is generated by the S/Key key program and accepted by the keyinit program and the login prompt; we will call this a one-time password. The final sort of password is the secret password which you give to the key program (and sometimes the keyinit program) which it uses to generate one-time passwords; we will call it a secret password or just unqualified password. The secret password does not have anything to do with your Unix password; they can be the same but this is not recommended. S/Key secret passwords are not limited to 8 characters like Unix passwords, they can be as long as you like. Passwords of six or seven word long phrases are fairly common. For the most part, the S/Key system operates completely independently of the Unix password system. Besides the password, there are two other pieces of data that are important to S/Key. One is what is known as the seed or key and consists of two letters and five digits. The other is what is called the iteration count and is a number between 1 and 100. S/Key creates the one-time password by concatenating the seed and the secret password, then applying the MD4 hash as many times as specified by the iteration count and turning the result into six short English words. These six English words are your one-time password. The login and su programs keep track of the last one-time password used, and the user is authenticated if the hash of the user-provided password is equal to the previous password. Because a one-way hash is used it is impossible to generate future one-time passwords if a successfully used password is captured; the iteration count is decremented after each successful login to keep the user and the login program in sync. When the iteration count gets down to 1 S/Key must be reinitialized. There are four programs involved in the S/Key system which we will discuss below. The key program accepts an iteration count, a seed, and a secret password, and generates a one-time password. The keyinit program is used to initialized S/Key, and to change passwords, iteration counts, or seeds; it takes either a secret password, or an iteration count, seed, and one-time password. The keyinfo program examines the /etc/skeykeys file and prints out the invoking user's current iteration count and seed. Finally, the login and su programs contain the necessary logic to accept S/Key one-time passwords for authentication. The login program is also capable of disallowing the use of Unix passwords on connections coming from specified addresses. There are four different sorts of operations we will cover. The first is using the keyinit program over a secure connection to set up S/Key for the first time, or to change your password or seed. The second operation is using the keyinit program over an insecure connection, in conjunction with the key program over a secure connection, to do the same. The third is using the key program to log in over an insecure connection. The fourth is using the key program to generate a number of keys which can be written down or printed out to carry with you when going to some location without secure connections to anywhere. Secure connection initialization To initialize S/Key for the first time, change your password, or change your seed while logged in over a secure connection (e.g., on the console of a machine or via ssh), use the keyinit command without any parameters while logged in as yourself: &prompt.user; keyinit Adding unfurl: Reminder - Only use this method if you are directly connected. If you are using telnet or rlogin exit with no password and use keyinit -s. Enter secret password: Again secret password: ID unfurl s/key is 99 to17757 DEFY CLUB PRO NASH LACE SOFT At the Enter secret password: prompt you should enter a password or phrase. Remember, this is not the password that you will use to login with, this is used to generate your one-time login keys. The ID line gives the parameters of your particular S/Key instance; your login name, the iteration count, and seed. When logging in with S/Key, the system will remember these parameters and present them back to you so you do not have to remember them. The last line gives the particular one-time password which corresponds to those parameters and your secret password; if you were to re-login immediately, this one-time password is the one you would use. Insecure connection initialization To initialize S/Key or change your secret password over an insecure connection, you will need to already have a secure connection to some place where you can run the key program; this might be in the form of a desk accessory on a Macintosh, or a shell prompt on a machine you trust. You will also need to make up an iteration count (100 is probably a good value), and you may make up your own seed or use a randomly-generated one. Over on the insecure connection (to the machine you are initializing), use the keyinit -s command: &prompt.user; keyinit -s Updating unfurl: Old key: to17758 Reminder you need the 6 English words from the key command. Enter sequence count from 1 to 9999: 100 Enter new key [default to17759]: s/key 100 to 17759 s/key access password: To accept the default seed (which the keyinit program confusingly calls a key), press return. Then before entering an access password, move over to your secure connection or S/Key desk accessory, and give it the same parameters: &prompt.user; key 100 to17759 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: <secret password> CURE MIKE BANE HIM RACY GORE Now switch back over to the insecure connection, and copy the one-time password generated by key over to the keyinit program: s/key access password:CURE MIKE BANE HIM RACY GORE ID unfurl s/key is 100 to17759 CURE MIKE BANE HIM RACY GORE The rest of the description from the previous section applies here as well. Generating a single one-time password Once you've initialized S/Key, when you login you will be presented with a prompt like this: &prompt.user; telnet example.com Trying 10.0.0.1... Connected to example.com Escape character is '^]'. FreeBSD/i386 (example.com) (ttypa) login: <username> s/key 97 fw13894 Password: As a side note, the S/Key prompt has a useful feature (not shown here): if you press return at the password prompt, the login program will turn echo on, so you can see what you are typing. This can be extremely useful if you are attempting to type in an S/Key by hand, such as from a printout. Also, if this machine were configured to disallow Unix passwords over a connection from the source machine, the prompt would have also included the annotation (s/key required), indicating that only S/Key one-time passwords will be accepted. MS-DOS Windows MacOS At this point you need to generate your one-time password to answer this login prompt. This must be done on a trusted system that you can run the key command on. (There are versions of the key program for MS-DOS, Windows and MacOS as well.) The key program needs both the iteration count and the seed as command line options. You can cut-and-paste these right from the login prompt on the machine that you are logging in to. On the trusted system: &prompt.user; key 97 fw13894 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: WELD LIP ACTS ENDS ME HAAG Now that you have your one-time password you can continue logging in: login: <username> s/key 97 fw13894 Password: <return to enable echo> s/key 97 fw13894 Password [echo on]: WELD LIP ACTS ENDS ME HAAG Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ... This is the easiest mechanism if you have a trusted machine. There is a Java S/Key key applet, The Java OTP Calculator, that you can download and run locally on any Java supporting browser. Generating multiple one-time passwords Sometimes you have to go places where you do not have access to a trusted machine or secure connection. In this case, it is possible to use the key command to generate a number of one-time passwords before hand to be printed out and taken with you. For example: &prompt.user; key -n 5 30 zz99999 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: <secret password> 26: SODA RUDE LEA LIND BUDD SILT 27: JILT SPY DUTY GLOW COWL ROT 28: THEM OW COLA RUNT BONG SCOT 29: COT MASH BARR BRIM NAN FLAG 30: CAN KNEE CAST NAME FOLK BILK The requests five keys in sequence, the specifies what the last iteration number should be. Note that these are printed out in reverse order of eventual use. If you are really paranoid, you might want to write the results down by hand; otherwise you can cut-and-paste into lpr. Note that each line shows both the iteration count and the one-time password; you may still find it handy to scratch off passwords as you use them. Restricting use of Unix passwords Restrictions can be placed on the use of Unix passwords based on the host name, user name, terminal port, or IP address of a login session. These restrictions can be found in the configuration file /etc/skey.access. The &man.skey.access.5; manual page has more info on the complete format of the file and also details some security cautions to be aware of before depending on this file for security. If there is no /etc/skey.access file (this is the FreeBSD default), then all users will be allowed to use Unix passwords. If the file exists, however, then all users will be required to use S/Key unless explicitly permitted to do otherwise by configuration statements in the skey.access file. In all cases, Unix passwords are permitted on the console. Here is a sample configuration file which illustrates the three most common sorts of configuration statements: permit internet 192.168.0.0 255.255.0.0 permit user fnord permit port ttyd0 The first line (permit internet) allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use Unix passwords. This should not be considered a security mechanism, but rather, a means to remind authorized users that they are using an insecure network and need to use S/Key for authentication. The second line (permit user) allows the specified username, in this case fnord, to use Unix passwords at any time. Generally speaking, this should only be used for people who are either unable to use the key program, like those with dumb terminals, or those who are uneducable. The third line (permit port) allows all users logging in on the specified terminal line to use Unix passwords; this would be used for dial-ups. Kerberos Kerberos Contributed by &a.markm; (based on contribution by &a.md;). Kerberos is a network add-on system/protocol that allows users to authenticate themselves through the services of a secure server. Services such as remote login, remote copy, secure inter-system file copying and other high-risk tasks are made considerably safer and more controllable. The following instructions can be used as a guide on how to set up Kerberos as distributed for FreeBSD. However, you should refer to the relevant manual pages for a complete description. 4.4BSD-Lite In FreeBSD, the Kerberos is not that from the original 4.4BSD-Lite, distribution, but eBones, which had been previously ported to FreeBSD 1.1.5.1, and was sourced from outside the USA/Canada, and was thus available to system owners outside those countries during the era of restrictive export controls on cryptographic code from the USA. Creating the initial database This is done on the Kerberos server only. First make sure that you do not have any old Kerberos databases around. You should change to the directory /etc/kerberosIV and check that only the following files are present: &prompt.root; cd /etc/kerberosIV &prompt.root; ls README krb.conf krb.realms If any additional files (such as principal.* or master_key) exist, then use the kdb_destroy command to destroy the old Kerberos database, of if Kerberos is not running, simply delete the extra files. You should now edit the krb.conf and krb.realms files to define your Kerberos realm. In this case the realm will be GRONDAR.ZA and the server is grunt.grondar.za. We edit or create the krb.conf file: &prompt.root; cat krb.conf GRONDAR.ZA GRONDAR.ZA grunt.grondar.za admin server CS.BERKELEY.EDU okeeffe.berkeley.edu ATHENA.MIT.EDU kerberos.mit.edu ATHENA.MIT.EDU kerberos-1.mit.edu ATHENA.MIT.EDU kerberos-2.mit.edu ATHENA.MIT.EDU kerberos-3.mit.edu LCS.MIT.EDU kerberos.lcs.mit.edu TELECOM.MIT.EDU bitsy.mit.edu ARC.NASA.GOV trident.arc.nasa.gov In this case, the other realms do not need to be there. They are here as an example of how a machine may be made aware of multiple realms. You may wish to not include them for simplicity. The first line names the realm in which this system works. The other lines contain realm/host entries. The first item on a line is a realm, and the second is a host in that realm that is acting as a key distribution center. The words admin server following a hosts name means that host also provides an administrative database server. For further explanation of these terms, please consult the Kerberos man pages. Now we have to add grunt.grondar.za to the GRONDAR.ZA realm and also add an entry to put all hosts in the .grondar.za domain in the GRONDAR.ZA realm. The krb.realms file would be updated as follows: &prompt.root; cat krb.realms grunt.grondar.za GRONDAR.ZA .grondar.za GRONDAR.ZA .berkeley.edu CS.BERKELEY.EDU .MIT.EDU ATHENA.MIT.EDU .mit.edu ATHENA.MIT.EDU Again, the other realms do not need to be there. They are here as an example of how a machine may be made aware of multiple realms. You may wish to remove them to simplify things. The first line puts the specific system into the named realm. The rest of the lines show how to default systems of a particular subdomain to a named realm. Now we are ready to create the database. This only needs to run on the Kerberos server (or Key Distribution Center). Issue the kdb_init command to do this: &prompt.root; kdb_init Realm name [default ATHENA.MIT.EDU ]: GRONDAR.ZA You will be prompted for the database Master Password. It is important that you NOT FORGET this password. Enter Kerberos master key: Now we have to save the key so that servers on the local machine can pick it up. Use the kstash command to do this. &prompt.root; kstash Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! This saves the encrypted master password in /etc/kerberosIV/master_key. Making it all run Two principals need to be added to the database for each system that will be secured with Kerberos. Their names are kpasswd and rcmd These two principals are made for each system, with the instance being the name of the individual system. These daemons, kpasswd and rcmd allow other systems to change Kerberos passwords and run commands like rcp, rlogin and rsh. Now let's add these entries: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: passwd Instance: grunt <Not found>, Create [y] ? y Principal: passwd, Instance: grunt, kdc_key_ver: 1 New Password: <---- enter RANDOM here Verifying password New Password: <---- enter RANDOM here Random password [y] ? y Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: rcmd Instance: grunt <Not found>, Create [y] ? Principal: rcmd, Instance: grunt, kdc_key_ver: 1 New Password: <---- enter RANDOM here Verifying password New Password: <---- enter RANDOM here Random password [y] ? Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Creating the server file We now have to extract all the instances which define the services on each machine. For this we use the ext_srvtab command. This will create a file which must be copied or moved by secure means to each Kerberos client's /etc/kerberosIV directory. This file must be present on each server and client, and is crucial to the operation of Kerberos. &prompt.root; ext_srvtab grunt Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Generating 'grunt-new-srvtab'.... Now, this command only generates a temporary file which must be renamed to srvtab so that all the server can pick it up. Use the mv command to move it into place on the original system: &prompt.root; mv grunt-new-srvtab srvtab If the file is for a client system, and the network is not deemed safe, then copy the client-new-srvtab to removable media and transport it by secure physical means. Be sure to rename it to srvtab in the client's /etc/kerberosIV directory, and make sure it is mode 600: &prompt.root; mv grumble-new-srvtab srvtab &prompt.root; chmod 600 srvtab Populating the database We now have to add some user entries into the database. First let's create an entry for the user jane. Use the kdb_edit command to do this: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: jane Instance: <Not found>, Create [y] ? y Principal: jane, Instance: , kdc_key_ver: 1 New Password: <---- enter a secure password here Verifying password New Password: <---- re-enter the password here Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Testing it all out First we have to start the Kerberos daemons. NOTE that if you have correctly edited your /etc/rc.conf then this will happen automatically when you reboot. This is only necessary on the Kerberos server. Kerberos clients will automagically get what they need from the /etc/kerberosIV directory. &prompt.root; kerberos & Kerberos server starting Sleep forever on error Log file is /var/log/kerberos.log Current Kerberos master key version is 1. Master key entered. BEWARE! Current Kerberos master key version is 1 Local realm: GRONDAR.ZA &prompt.root; kadmind -n & KADM Server KADM0.0A initializing Please do not use 'kill -9' to kill this job, use a regular kill instead Current Kerberos master key version is 1. Master key entered. BEWARE! Now we can try using the kinit command to get a ticket for the id jane that we created above: &prompt.user; kinit jane MIT Project Athena (grunt.grondar.za) Kerberos Initialization for "jane" Password: Try listing the tokens using klist to see if we really have them: &prompt.user; klist Ticket file: /tmp/tkt245 Principal: jane@GRONDAR.ZA Issued Expires Principal Apr 30 11:23:22 Apr 30 19:23:22 krbtgt.GRONDAR.ZA@GRONDAR.ZA Now try changing the password using passwd to check if the kpasswd daemon can get authorization to the Kerberos database: &prompt.user; passwd realm GRONDAR.ZA Old password for jane: New Password for jane: Verifying password New Password for jane: Password changed. Adding <command>su</command> privileges Kerberos allows us to give each user who needs root privileges their own separate supassword. We could now add an id which is authorized to su to root. This is controlled by having an instance of root associated with a principal. Using kdb_edit we can create the entry jane.root in the Kerberos database: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: jane Instance: root <Not found>, Create [y] ? y Principal: jane, Instance: root, kdc_key_ver: 1 New Password: <---- enter a SECURE password here Verifying password New Password: <---- re-enter the password here Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? 12 <--- Keep this short! Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Now try getting tokens for it to make sure it works: &prompt.root; kinit jane.root MIT Project Athena (grunt.grondar.za) Kerberos Initialization for "jane.root" Password: Now we need to add the user to root's .klogin file: &prompt.root; cat /root/.klogin jane.root@GRONDAR.ZA Now try doing the su: &prompt.user; su Password: and take a look at what tokens we have: &prompt.root; klist Ticket file: /tmp/tkt_root_245 Principal: jane.root@GRONDAR.ZA Issued Expires Principal May 2 20:43:12 May 3 04:43:12 krbtgt.GRONDAR.ZA@GRONDAR.ZA Using other commands In an earlier example, we created a principal called jane with an instance root. This was based on a user with the same name as the principal, and this is a Kerberos default; that a <principal>.<instance> of the form <username>.root will allow that <username> to su to root if the necessary entries are in the .klogin file in root's home directory: &prompt.root; cat /root/.klogin jane.root@GRONDAR.ZA Likewise, if a user has in their own home directory lines of the form: &prompt.user; cat ~/.klogin jane@GRONDAR.ZA jack@GRONDAR.ZA This allows anyone in the GRONDAR.ZA realm who has authenticated themselves to jane or jack (via kinit, see above) access to rlogin to jane's account or files on this system (grunt) via rlogin, rsh or rcp. For example, Jane now logs into another system, using Kerberos: &prompt.user; kinit MIT Project Athena (grunt.grondar.za) Password: &prompt.user; rlogin grunt Last login: Mon May 1 21:14:47 from grumble Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 Or Jack logs into Jane's account on the same machine (Jane having set up the .klogin file as above, and the person in charge of Kerberos having set up principal jack with a null instance: &prompt.user; kinit &prompt.user; rlogin grunt -l jane MIT Project Athena (grunt.grondar.za) Password: Last login: Mon May 1 21:16:55 from grumble Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 Firewalls firewalls security firewalls Contributed by &a.gpalmer; and Alex Nash. Firewalls are an area of increasing interest for people who are connected to the Internet, and are even finding applications on private networks to provide enhanced security. This section will hopefully explain what firewalls are, how to use them, and how to use the facilities provided in the FreeBSD kernel to implement them. People often think that having a firewall between your internal network and the Big Bad Internet will solve all your security problems. It may help, but a poorly setup firewall system is more of a security risk than not having one at all. A firewall can add another layer of security to your systems, but it cannot stop a really determined cracker from penetrating your internal network. If you let internal security lapse because you believe your firewall to be impenetrable, you have just made the crackers job that much easier. What is a firewall? There are currently two distinct types of firewalls in common use on the Internet today. The first type is more properly called a packet filtering router, where the kernel on a multi-homed machine chooses whether to forward or block packets based on a set of rules. The second type, known as a proxy server, relies on daemons to provide authentication and to forward packets, possibly on a multi-homed machine which has kernel packet forwarding disabled. Sometimes sites combine the two types of firewalls, so that only a certain machine (known as a bastion host) is allowed to send packets through a packet filtering router onto an internal network. Proxy services are run on the bastion host, which are generally more secure than normal authentication mechanisms. FreeBSD comes with a kernel packet filter (known as IPFW), which is what the rest of this section will concentrate on. Proxy servers can be built on FreeBSD from third party software, but there is such a variety of proxy servers available that it would be impossible to cover them in this document. Packet filtering routers A router is a machine which forwards packets between two or more networks. A packet filtering router has an extra piece of code in its kernel which compares each packet to a list of rules before deciding if it should be forwarded or not. Most modern IP routing software has packet filtering code within it that defaults to forwarding all packets. To enable the filters, you need to define a set of rules for the filtering code so it can decide if the packet should be allowed to pass or not. To decide whether a packet should be passed on, the code looks through its set of rules for a rule which matches the contents of this packets headers. Once a match is found, the rule action is obeyed. The rule action could be to drop the packet, to forward the packet, or even to send an ICMP message back to the originator. Only the first match counts, as the rules are searched in order. Hence, the list of rules can be referred to as a rule chain. The packet matching criteria varies depending on the software used, but typically you can specify rules which depend on the source IP address of the packet, the destination IP address, the source port number, the destination port number (for protocols which support ports), or even the packet type (UDP, TCP, ICMP, etc). Proxy servers Proxy servers are machines which have had the normal system daemons (telnetd, ftpd, etc) replaced with special servers. These servers are called proxy servers as they normally only allow onward connections to be made. This enables you to run (for example) a proxy telnet server on your firewall host, and people can telnet in to your firewall from the outside, go through some authentication mechanism, and then gain access to the internal network (alternatively, proxy servers can be used for signals coming from the internal network and heading out). Proxy servers are normally more secure than normal servers, and often have a wider variety of authentication mechanisms available, including one-shot password systems so that even if someone manages to discover what password you used, they will not be able to use it to gain access to your systems as the password instantly expires. As they do not actually give users access to the host machine, it becomes a lot more difficult for someone to install backdoors around your security system. Proxy servers often have ways of restricting access further, so that only certain hosts can gain access to the servers, and often they can be set up so that you can limit which users can talk to which destination machine. Again, what facilities are available depends largely on what proxy software you choose. What does IPFW allow me to do? ipfw IPFW, the software supplied with FreeBSD, is a packet filtering and accounting system which resides in the kernel, and has a user-land control utility, &man.ipfw.8;. Together, they allow you to define and query the rules currently used by the kernel in its routing decisions. There are two related parts to IPFW. The firewall section allows you to perform packet filtering. There is also an IP accounting section which allows you to track usage of your router, based on similar rules to the firewall section. This allows you to see (for example) how much traffic your router is getting from a certain machine, or how much WWW (World Wide Web) traffic it is forwarding. As a result of the way that IPFW is designed, you can use IPFW on non-router machines to perform packet filtering on incoming and outgoing connections. This is a special case of the more general use of IPFW, and the same commands and techniques should be used in this situation. Enabling IPFW on FreeBSD ipfw enabling As the main part of the IPFW system lives in the kernel, you will need to add one or more options to your kernel configuration file, depending on what facilities you want, and recompile your kernel. See reconfiguring the kernel for more details on how to recompile your kernel. There are currently three kernel configuration options relevant to IPFW: options IPFIREWALL Compiles into the kernel the code for packet filtering. options IPFIREWALL_VERBOSE Enables code to allow logging of packets through &man.syslogd.8;. Without this option, even if you specify that packets should be logged in the filter rules, nothing will happen. options IPFIREWALL_VERBOSE_LIMIT=10 Limits the number of packets logged through &man.syslogd.8; on a per entry basis. You may wish to use this option in hostile environments in which you want to log firewall activity, but do not want to be open to a denial of service attack via syslog flooding. When a chain entry reaches the packet limit specified, logging is turned off for that particular entry. To resume logging, you will need to reset the associated counter using the &man.ipfw.8; utility: &prompt.root; ipfw zero 4500 Where 4500 is the chain entry you wish to continue logging. Previous versions of FreeBSD contained an IPFIREWALL_ACCT option. This is now obsolete as the firewall code automatically includes accounting facilities. Configuring IPFW ipfw configuring The configuration of the IPFW software is done through the &man.ipfw.8; utility. The syntax for this command looks quite complicated, but it is relatively simple once you understand its structure. There are currently four different command categories used by the utility: addition/deletion, listing, flushing, and clearing. Addition/deletion is used to build the rules that control how packets are accepted, rejected, and logged. Listing is used to examine the contents of your rule set (otherwise known as the chain) and packet counters (accounting). Flushing is used to remove all entries from the chain. Clearing is used to zero out one or more accounting entries. Altering the IPFW rules The syntax for this form of the command is: ipfw -N command index action log protocol addresses options There is one valid flag when using this form of the command: -N Resolve addresses and service names in output. The command given can be shortened to the shortest unique form. The valid commands are: add Add an entry to the firewall/accounting rule list delete Delete an entry from the firewall/accounting rule list Previous versions of IPFW used separate firewall and accounting entries. The present version provides packet accounting with each firewall entry. If an index value is supplied, it used to place the entry at a specific point in the chain. Otherwise, the entry is placed at the end of the chain at an index 100 greater than the last chain entry (this does not include the default policy, rule 65535, deny). The log option causes matching rules to be output to the system console if the kernel was compiled with IPFIREWALL_VERBOSE. Valid actions are: reject Drop the packet, and send an ICMP host or port unreachable (as appropriate) packet to the source. allow Pass the packet on as normal. (aliases: pass and accept) deny Drop the packet. The source is not notified via an ICMP message (thus it appears that the packet never arrived at the destination). count Update packet counters but do not allow/deny the packet based on this rule. The search continues with the next chain entry. Each action will be recognized by the shortest unambiguous prefix. The protocols which can be specified are: all Matches any IP packet icmp Matches ICMP packets tcp Matches TCP packets udp Matches UDP packets The address specification is: from address/maskport to address/maskport via interface You can only specify port in conjunction with protocols which support ports (UDP and TCP). The is optional and may specify the IP address or domain name of a local IP interface, or an interface name (e.g. ed0) to match only packets coming through this interface. Interface unit numbers can be specified with an optional wildcard. For example, ppp* would match all kernel PPP interfaces. The syntax used to specify an address/mask is: address or address/mask-bits or address:mask-pattern A valid hostname may be specified in place of the IP address. is a decimal number representing how many bits in the address mask should be set. e.g. specifying 192.216.222.1/24 will create a mask which will allow any address in a class C subnet (in this case, 192.216.222) to be matched. is an IP address which will be logically AND'ed with the address given. The keyword any may be used to specify any IP address. The port numbers to be blocked are specified as: port,port,port… to specify either a single port or a list of ports, or port-port to specify a range of ports. You may also combine a single range with a list, but the range must always be specified first. The options available are: frag Matches if the packet is not the first fragment of the datagram. in Matches if the packet is on the way in. out Matches if the packet is on the way out. ipoptions spec Matches if the IP header contains the comma separated list of options specified in spec. The supported list of IP options are: ssrr (strict source route), lsrr (loose source route), rr (record packet route), and ts (time stamp). The absence of a particular option may be denoted with a leading !. established Matches if the packet is part of an already established TCP connection (i.e. it has the RST or ACK bits set). You can optimize the performance of the firewall by placing established rules early in the chain. setup Matches if the packet is an attempt to establish a TCP connection (the SYN bit set is set but the ACK bit is not). tcpflags flags Matches if the TCP header contains the comma separated list of flags. The supported flags are fin, syn, rst, psh, ack, and urg. The absence of a particular flag may be indicated by a leading !. icmptypes types Matches if the ICMP type is present in the list types. The list may be specified as any combination of ranges and/or individual types separated by commas. Commonly used ICMP types are: 0 echo reply (ping reply), 3 destination unreachable, 5 redirect, 8 echo request (ping request), and 11 time exceeded (used to indicate TTL expiration as with &man.traceroute.8;). Listing the IPFW rules The syntax for this form of the command is: ipfw -a -t -N l There are three valid flags when using this form of the command: -a While listing, show counter values. This option is the only way to see accounting counters. -t Display the last match times for each chain entry. The time listing is incompatible with the input syntax used by the &man.ipfw.8; utility. -N Attempt to resolve given addresses and service names. Flushing the IPFW rules The syntax for flushing the chain is: ipfw flush This causes all entries in the firewall chain to be removed except the fixed default policy enforced by the kernel (index 65535). Use caution when flushing rules, the default deny policy will leave your system cut off from the network until allow entries are added to the chain. Clearing the IPFW packet counters The syntax for clearing one or more packet counters is: ipfw zero index When used without an index argument, all packet counters are cleared. If an index is supplied, the clearing operation only affects a specific chain entry. Example commands for ipfw This command will deny all packets from the host evil.crackers.org to the telnet port of the host nice.people.org: &prompt.root ipfw add deny tcp from evil.crackers.org to nice.people.org 23 The next example denies and logs any TCP traffic from the entire crackers.org network (a class C) to the nice.people.org machine (any port). &prompt.root; ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org If you do not want people sending X sessions to your internal network (a subnet of a class C), the following command will do the necessary filtering: &prompt.root; ipfw add deny tcp from any to my.org/28 6000 setup To see the accounting records: &prompt.root; ipfw -a list or in the short form &prompt.root; ipfw -a l You can also see the last time a chain entry was matched with: &prompt.root; ipfw -at l Building a packet filtering firewall The following suggestions are just that: suggestions. The requirements of each firewall are different and we cannot tell you how to build a firewall to meet your particular requirements. When initially setting up your firewall, unless you have a test bench setup where you can configure your firewall host in a controlled environment, it is strongly recommend you use the logging version of the commands and enable logging in the kernel. This will allow you to quickly identify problem areas and cure them without too much disruption. Even after the initial setup phase is complete, I recommend using the logging for `deny' as it allows tracing of possible attacks and also modification of the firewall rules if your requirements alter. If you use the logging versions of the accept command, it can generate large amounts of log data as one log line will be generated for every packet that passes - through the firewall, so large ftp/http transfers, etc, will really + through the firewall, so large FTP/http transfers, etc, will really slow the system down. It also increases the latencies on those packets as it requires more work to be done by the kernel before the packet can be passed on. syslogd with also start using up a lot more processor time as it logs all the extra data to disk, and it could quite easily fill the partition /var/log is located on. You should enable your firewall from /etc/rc.conf.local or /etc/rc.conf. The associated man page explains which knobs to fiddle and lists some preset firewall configurations. If you do not use a preset configuration, ipfw list will output the current ruleset into a file that you can pass to rc.conf. If you do not use /etc/rc.conf.local or /etc/rc.conf to enable your firewall, it is important to make sure your firewall is enabled before any IP interfaces are configured. The next problem is what your firewall should actually do! This is largely dependent on what access to your network you want to allow from the outside, and how much access to the outside world you want to allow from the inside. Some general rules are: Block all incoming access to ports below 1024 for TCP. This is where most of the security sensitive services are, like finger, SMTP (mail) and telnet. Block all incoming UDP traffic. There are very few useful services that travel over UDP, and what useful traffic there is normally a security threat (e.g. Suns RPC and NFS protocols). This has its disadvantages also, since UDP is a connectionless protocol, denying incoming UDP traffic also blocks the replies to outgoing UDP traffic. This can cause a problem for people (on the inside) using external archie (prospero) servers. If you want to allow access to archie, you'll have to allow packets coming from ports 191 and 1525 to any internal UDP port through the firewall. ntp is another service you may consider allowing through, which comes from port 123. Block traffic to port 6000 from the outside. Port 6000 is the port used for access to X11 servers, and can be a security threat (especially if people are in the habit of doing xhost + on their workstations). X11 can actually use a range of ports starting at 6000, the upper limit being how many X displays you can run on the machine. The upper limit as defined by RFC 1700 (Assigned Numbers) is 6063. Check what ports any internal servers use (e.g. SQL servers, etc). It is probably a good idea to block those as well, as they normally fall outside the 1-1024 range specified above. Another checklist for firewall configuration is available from CERT at http://www.cert.org/tech_tips/packet_filtering.html As stated above, these are only guidelines. You will have to decide what filter rules you want to use on your firewall yourself. We cannot accept ANY responsibility if someone breaks into your network, even if you follow the advice given above. OpenSSL security OpenSSL OpenSSL As of FreeBSD 4.0, the OpenSSL toolkit is a part of the base system. OpenSSL provides a general-purpose cryptography library, as well as the Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1 (TLSv1) network security protocols. However, one of the algorithms (specifically IDEA) included in OpenSSL is protected by patents in the USA and elsewhere, and is not available for unrestricted use. IDEA is included in the OpenSSL sources in FreeBSD, but it is not built by default. If you wish to use it, and you comply with the license terms, enable the MAKE_IDEA switch in /etc/make.conf and rebuild your sources using 'make world'. Today, the RSA algorithm is free for use in USA and other countries. In the past it was protected by a patent. OpenSSL install Source Code Installations OpenSSL is part of the src-crypto and src-secure cvsup collections. See the Obtaining FreeBSD section for more information about obtaining and updating FreeBSD source code. IPsec IPsec security IPsec Contributed by &a.shin;, 5 March 2000. The IPsec mechanism provides secure communication either for IP layer and socket layer communication. This section should explain how to use them. For implementation details, please refer to The Developers' Handbook. The current IPsec implementation supports both transport mode and tunnel mode. However, tunnel mode comes with some restrictions. http://www.kame.net/newsletter/ has more comprehensive examples. Please be aware that in order to use this functionality, you must have the following options compiled into your kernel: options IPSEC #IP security options IPSEC_ESP #IP security (crypto; define w/IPSEC) Transport mode example with IPv4 Let's setup security association to deploy a secure channel between HOST A (10.2.3.4) and HOST B (10.6.7.8). Here we show a little complicated example. From HOST A to HOST B, only old AH is used. From HOST B to HOST A, new AH and new ESP are combined. Now we should choose algorithm to be used corresponding to "AH"/"new AH"/"ESP"/"new ESP". Please refer to the &man.setkey.8; man page to know algorithm names. Our choice is MD5 for AH, new-HMAC-SHA1 for new AH, and new-DES-expIV with 8 byte IV for new ESP. Key length highly depends on each algorithm. For example, key length must be equal to 16 bytes for MD5, 20 for new-HMAC-SHA1, and 8 for new-DES-expIV. Now we choose "MYSECRETMYSECRET", "KAMEKAMEKAMEKAMEKAME", "PASSWORD", respectively. OK, let's assign SPI (Security Parameter Index) for each protocol. Please note that we need 3 SPIs for this secure channel since three security headers are produced (one for from HOST A to HOST B, two for from HOST B to HOST A). Please also note that SPI MUST be greater than or equal to 256. We choose, 1000, 2000, and 3000, respectively. (1) HOST A ------> HOST B (1)PROTO=AH ALG=MD5(RFC1826) KEY=MYSECRETMYSECRET SPI=1000 (2.1) HOST A <------ HOST B <------ (2.2) (2.1) PROTO=AH ALG=new-HMAC-SHA1(new AH) KEY=KAMEKAMEKAMEKAMEKAME SPI=2000 (2.2) PROTO=ESP ALG=new-DES-expIV(new ESP) IV length = 8 KEY=PASSWORD SPI=3000 Now, let's setup security association. Execute &man.setkey.8; on both HOST A and B: &prompt.root; setkey -c add 10.2.3.4 10.6.7.8 ah-old 1000 -m transport -A keyed-md5 "MYSECRETMYSECRET" ; add 10.6.7.8 10.2.3.4 ah 2000 -m transport -A hmac-sha1 "KAMEKAMEKAMEKAMEKAME" ; add 10.6.7.8 10.2.3.4 esp 3000 -m transport -E des-cbc "PASSWORD" ; ^D Actually, IPsec communication doesn't process until security policy entries will be defined. In this case, you must setup each host. At A: &prompt.root; setkey -c spdadd 10.2.3.4 10.6.7.8 any -P out ipsec ah/transport/10.2.3.4-10.6.7.8/require ; ^D At B: &prompt.root; setkey -c spdadd 10.6.7.8 10.2.3.4 any -P out ipsec esp/transport/10.6.7.8-10.2.3.4/require ; spdadd 10.6.7.8 10.2.3.4 any -P out ipsec ah/transport/10.6.7.8-10.2.3.4/require ; ^D HOST A --------------------------------------> HOST E 10.2.3.4 10.6.7.8 | | ========== old AH keyed-md5 ==========> <========= new AH hmac-sha1 =========== <========= new ESP des-cbc ============ Transport mode example with IPv6 Another example using IPv6. ESP transport mode is recommended for TCP port number 110 between Host-A and Host-B. ============ ESP ============ | | Host-A Host-B fec0::10 -------------------- fec0::11 Encryption algorithm is blowfish-cbc whose key is "kamekame", and authentication algorithm is hmac-sha1 whose key is "this is the test key". Configuration at Host-A: &prompt.root; setkey -c <<EOF spdadd fec0::10[any] fec0::11[110] tcp -P out ipsec esp/transport/fec0::10-fec0::11/use ; spdadd fec0::11[110] fec0::10[any] tcp -P in ipsec esp/transport/fec0::11-fec0::10/use ; add fec0::10 fec0::11 esp 0x10001 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; add fec0::11 fec0::10 esp 0x10002 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; EOF and at Host-B: &prompt.root; setkey -c <<EOF spdadd fec0::11[110] fec0::10[any] tcp -P out ipsec esp/transport/fec0::11-fec0::10/use ; spdadd fec0::10[any] fec0::11[110] tcp -P in ipsec esp/transport/fec0::10-fec0::11/use ; add fec0::10 fec0::11 esp 0x10001 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; add fec0::11 fec0::10 esp 0x10002 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; EOF Note the direction of SP. Tunnel mode example with IPv4 Tunnel mode between two security gateways Security protocol is old AH tunnel mode, i.e. specified by RFC1826, with keyed-md5 whose key is "this is the test" as authentication algorithm. ======= AH ======= | | Network-A Gateway-A Gateway-B Network-B 10.0.1.0/24 ---- 172.16.0.1 ----- 172.16.0.2 ---- 10.0.2.0/24 Configuration at Gateway-A: &prompt.root; setkey -c <<EOF spdadd 10.0.1.0/24 10.0.2.0/24 any -P out ipsec ah/tunnel/172.16.0.1-172.16.0.2/require ; spdadd 10.0.2.0/24 10.0.1.0/24 any -P in ipsec ah/tunnel/172.16.0.2-172.16.0.1/require ; add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any -A keyed-md5 "this is the test" ; add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any -A keyed-md5 "this is the test" ; EOF If port number field is omitted such above then "[any]" is employed. `-m' specifies the mode of SA to be used. "-m any" means wild-card of mode of security protocol. You can use this SA for both tunnel and transport mode. and at Gateway-B: &prompt.root; setkey -c <<EOF spdadd 10.0.2.0/24 10.0.1.0/24 any -P out ipsec ah/tunnel/172.16.0.2-172.16.0.1/require ; spdadd 10.0.1.0/24 10.0.2.0/24 any -P in ipsec ah/tunnel/172.16.0.1-172.16.0.2/require ; add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any -A keyed-md5 "this is the test" ; add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any -A keyed-md5 "this is the test" ; EOF Making SA bundle between two security gateways AH transport mode and ESP tunnel mode is required between Gateway-A and Gateway-B. In this case, ESP tunnel mode is applied first, and AH transport mode is next. ========== AH ========= | ======= ESP ===== | | | | | Network-A Gateway-A Gateway-B Network-B fec0:0:0:1::/64 --- fec0:0:0:1::1 ---- fec0:0:0:2::1 --- fec0:0:0:2::/64 Tunnel mode example with IPv6 Encryption algorithm is 3des-cbc, and authentication algorithm for ESP is hmac-sha1. Authentication algorithm for AH is hmac-md5. Configuration at Gateway-A: &prompt.root; setkey -c <<EOF spdadd fec0:0:0:1::/64 fec0:0:0:2::/64 any -P out ipsec esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ah/transport/fec0:0:0:1::1-fec0:0:0:2::1/require ; spdadd fec0:0:0:2::/64 fec0:0:0:1::/64 any -P in ipsec esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ah/transport/fec0:0:0:2::1-fec0:0:0:1::1/require ; add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10001 -m tunnel -E 3des-cbc "kamekame12341234kame1234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:1::1 fec0:0:0:2::1 ah 0x10001 -m transport -A hmac-md5 "this is the test" ; add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10001 -m tunnel -E 3des-cbc "kamekame12341234kame1234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:2::1 fec0:0:0:1::1 ah 0x10001 -m transport -A hmac-md5 "this is the test" ; EOF Making SAs with the different end ESP tunnel mode is required between Host-A and Gateway-A. Encryption algorithm is cast128-cbc, and authentication algorithm for ESP is hmac-sha1. ESP transport mode is recommended between Host-A and Host-B. Encryption algorithm is rc5-cbc, and authentication algorithm for ESP is hmac-md5. ================== ESP ================= | ======= ESP ======= | | | | | Host-A Gateway-A Host-B fec0:0:0:1::1 ---- fec0:0:0:2::1 ---- fec0:0:0:2::2 Configuration at Host-A: &prompt.root; setkey -c <<EOF spdadd fec0:0:0:1::1[any] fec0:0:0:2::2[80] tcp -P out ipsec esp/transport/fec0:0:0:1::1-fec0:0:0:2::2/use esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ; spdadd fec0:0:0:2::1[80] fec0:0:0:1::1[any] tcp -P in ipsec esp/transport/fec0:0:0:2::2-fec0:0:0:l::1/use esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ; add fec0:0:0:1::1 fec0:0:0:2::2 esp 0x10001 -m transport -E cast128-cbc "12341234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10002 -E rc5-cbc "kamekame" -A hmac-md5 "this is the test" ; add fec0:0:0:2::2 fec0:0:0:1::1 esp 0x10003 -m transport -E cast128-cbc "12341234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10004 -E rc5-cbc "kamekame" -A hmac-md5 "this is the test" ; EOF OpenSSH OpenSSH security OpenSSH Contributed by &a.chern;, April 21, 2001. Secure shell is a set of network connectivity tools used to access remote machines securely. It can be used as a direct replacement for rlogin, rsh, rcp, and telnet. Additionally, any other TCP/IP connections can be tunneled/forwarded securely through ssh. ssh encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and other network-level attacks. OpenSSH is maintained by the OpenBSD project, and is based upon SSH v1.2.12 with all the recent bug fixes and updates. It is compatible with both SSH protocols 1 and 2. OpenSSH has been in the base system since FreeBSD 4.0. Advantages of using OpenSSH Normally, when using &man.telnet.1; or &man.rlogin.1;, data is sent over the network in an clear, un-encrypted form. Network sniffers anywhere in between the client and server can steal your user/password information or data transferred in your session. OpenSSH offers a variety of authentication and encryption methods to prevent this from happening. Enabling sshd OpenSSH enabling Be sure to make the following additions to your rc.conf file: sshd_enable="YES" This will load the ssh daemon the next time your system initializes. Alternatively, you can simply run the sshd daemon. SSH client OpenSSH client The &man.ssh.1; utility works similarly to &man.rlogin.1;. &prompt.root ssh user@foobardomain.com Host key not found from the list of known hosts. Are you sure you want to continue connecting (yes/no)? yes Host 'foobardomain.com' added to the list of known hosts. user@foobardomain.com's password: ******* The login will continue just as it would have if a session was created using rlogin or telnet. SSH utilizes a key fingerprint system for verifying the authenticity of the server when the client connects. The user is prompted to enter 'yes' only during the first time connecting. Future attempts to login are all verified against the saved fingerprint key. The SSH client will alert you if the saved fingerprint differs from the received fingerprint on future login attempts. The fingerprints are saved in ~/.ssh/known_hosts Secure copy OpenSSH secure copy scp The scp command works similarly to rcp; it copies a file to or from a remote machine, except in a secure fashion. &prompt.root scp user@foobardomain.com:/COPYRIGHT COPYRIGHT user@foobardomain.com's password: COPYRIGHT 100% |*****************************| 4735 00:00 &prompt.root Since the fingerprint was already saved for this host in the previous example, it is verified when using scp here. Configuration OpenSSH configuration The system-wide configuration files for both the OpenSSH daemon and client reside within the /etc/ssh directory. ssh_config configures the client settings, while sshd_config configures the daemon. ssh-keygen Instead of using passwords, &man.ssh-keygen.1; can be used to generate RSA keys to authenticate a user. &prompt.user ssh-keygen Initializing random number generator... Generating p: .++ (distance 66) Generating q: ..............................++ (distance 498) Computing the keys... Key generation complete. Enter file in which to save the key (/home/user/.ssh/identity): Enter passphrase: Enter the same passphrase again: Your identification has been saved in /home/user/.ssh/identity. ... &man.ssh-keygen.1; will create a public and private key pair for use in authentication. The private key is stored in ~/.ssh/identity, whereas the public key is stored in ~/.ssh/identity.pub. The public key must be placed in ~/.ssh/authorized_keys of the remote machine in order for the setup to work. This will allow connection to the remote machine based upon RSA authentication instead of passwords. If a passphrase is used in &man.ssh-keygen.1;, the user will be prompted for a password each time in order to use the private key. &man.ssh-agent.1; and &man.ssh-add.1; are utilities used in managing multiple passworded private keys. SSH Tunneling OpenSSH tunneling OpenSSH has the ability to create a tunnel to encapsulate another protocol in an encrypted session. The following command tells &man.ssh.1; to create a tunnel for telnet. &prompt.user; ssh -2 -N -f -L 5023:localhost:23 user@foo.bar.com &prompt.user; -2 this forces &man.ssh.1 to use version 2 of the protocol. (Do not use if you are working with older ssh servers) -N indicates no command, or tunnel only. If omitted, &man.ssh.1; would initiate a normal session. -f forces &man.ssh.1; to run in the background. -L indicates a local tunnel in localport:localhost:remoteport fashion. foo.bar.com is the remote/target SSH server. An SSH tunnel works by creating a listen socket on the specified local host and port. It then forwards any connection to the local host/port via the SSH connection to the remote machine on the specified remote port. In the example, port 5023 on localhost is being forwarded to port 23 on the remote machine. Since 23 is telnet, this would create a secure telnet session through an SSH tunnel. This can be used to wrap any number of insecure TCP protocols such as smtp, pop3, ftp, etc. A typical SSH Tunnel &prompt.user; ssh -2 -N -f -L 5025:localhost:25 user@mailserver.foobar.com user@mailserver.foobar.com's password: ***** &prompt.user; telnet localhost 5025 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. 220 mailserver.foobar.com ESMTP This can be used in conjunction with an &man.ssh-keygen.1; and additional user accounts to create a more seamless/hassle-free SSH tunneling environment. Keys can be used in place of typing a password, and the tunnels can be run as a separate user. Further Reading OpenSSH &man.ssh.1; &man.scp.1; &man.ssh-keygen.1; &man.ssh-agent.1; &man.ssh-add.1; &man.sshd.8; &man.sftp-server.8; diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml index 622059a188..1b3a3a9166 100644 --- a/en_US.ISO8859-1/books/porters-handbook/book.sgml +++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml @@ -1,4510 +1,4510 @@ %man; %bookinfo; %authors; %mailing-lists; ]> FreeBSD Porter's Handbook The FreeBSD Documentation Project April 2000 2000 The FreeBSD Documentation Project &bookinfo.legalnotice; Making a port yourself So, now you are interested in making your own port or upgrading an existing one? Great! What follows are some guidelines for creating a new port for FreeBSD. If you want to upgrade an existing port, you should read this and then read . When this document is not sufficiently detailed, you should refer to /usr/ports/Mk/bsd.port.mk, which all port Makefiles include. Even if you do not hack Makefiles daily, it is well commented, and you will still gain much knowledge from it. Additionally, you may send specific questions to the &a.ports;. Only a fraction of the variables (VAR) that can be overridden are mentioned in this document. Most (if not all) are documented at the start of bsd.port.mk. This file uses a non-standard tab setting. Emacs and Vim should recognize the setting on loading the file. Both vi and ex can be set to use the correct value by typing :set tabstop=4 once the file has been loaded. Quick Porting This section tells you how to do a quick port. In many cases, it is not enough, but we will see. First, get the original tarball and put it into DISTDIR, which defaults to /usr/ports/distfiles. The following assumes that the software compiled out-of-the-box, i.e., there was absolutely no change required for the port to work on your FreeBSD box. If you needed to change something, you will have to refer to the next section too. Writing the <filename>Makefile</filename> The minimal Makefile would look something like this: # New ports collection makefile for: oneko # Date created: 5 December 1994 # Whom: asami # # $FreeBSD$ # PORTNAME= oneko PORTVERSION= 1.1b CATEGORIES= games MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ MAINTAINER= asami@FreeBSD.org MAN1= oneko.1 MANCOMPRESSED= yes USE_IMAKE= yes .include <bsd.port.mk> See if you can figure it out. Do not worry about the contents of the $FreeBSD$ line, it will be filled in automatically by CVS when the port is imported to our main ports tree. You can find a more detailed example in the sample Makefile section. Writing the description files There are three description files that are required for any port, whether they actually package or not. They are pkg-comment, pkg-descr, and pkg-plist, and their pkg- prefix distinguishes them from other files. <filename>pkg-comment</filename> This is the one-line description of the port. Please do not include the package name (or version number of the software) in the comment. The comment should begin with a capital, and end without a period. Here is an example: A cat chasing a mouse all over the screen <filename>pkg-descr</filename> This is a longer description of the port. One to a few paragraphs concisely explaining what the port does is sufficient. This is not a manual or an in-depth description on how to use or compile the port! Please be careful if you are copying from the README or manpage; too often they are not a concise description of the port or are in an awkward format (e.g., manpages have justified spacing). If the ported software has an official WWW homepage, you should list it here. Prefix one of the websites with WWW: so that automated tools will work correctly. It is recommended that you sign your name at the end of this file, as in: This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (etc.) WWW: http://www.oneko.org/ - Satoshi asami@cs.berkeley.edu <filename>pkg-plist</filename> This file lists all the files installed by the port. It is also called the “packing list” because the package is generated by packing the files listed here. The pathnames are relative to the installation prefix (usually /usr/local or /usr/X11R6). If you are using the MANn variables (as you should be), do not list any manpages here. Here is a small example: bin/oneko lib/X11/app-defaults/Oneko lib/X11/oneko/cat1.xpm lib/X11/oneko/cat2.xpm lib/X11/oneko/mouse.xpm @dirrm lib/X11/oneko Refer to the &man.pkg.create.1; man page for details on the packing list. You should list all the files, but not the name directories, in the list. Also, if the port creates directories for itself during installation, make sure to add @dirrm lines as necessary to remove them when the port is deleted. It is recommended that you keep all the filenames in this file sorted alphabetically. It will make verifying the changes when you upgrade the port much easier. Creating a packing list manually can be a very tedious task. If the port installs a large numbers of files, creating the packing list automatically might save time. Creating the checksum file Just type make makesum. The ports make rules will automatically generate the file distinfo. Testing the port You should make sure that the port rules do exactly what you want them to do, including packaging up the port. These are the important points you need to verify. pkg-plist does not contain anything not installed by your port pkg-plist contains everything that is installed by your port Your port can be installed multiple times using the reinstall target Your port cleans up after itself upon deinstall Recommended test ordering make install make package make deinstall pkg_add package-name make deinstall make reinstall make package Make sure that there are not any warnings issued in any of the package and deinstall stages. After step 3, check to see if all the new directories are correctly deleted. Also, try using the software after step 4, to ensure that it works correctly when installed from a package. Checking your port with <command>portlint</command> Please use portlint to see if your port conforms to our guidelines. The portlint program is part of the ports collection. In particular, you may want to check if the Makefile is in the right shape and the package is named appropriately. Submitting the port First, make sure you have read the DOs and DON'Ts section. Now that you are happy with your port, the only thing remaining is to put it in the main FreeBSD ports tree and make everybody else happy about it too. We do not need your work directory or the pkgname.tgz package, so delete them now. Next, simply include the output of shar `find port_dir` in a bug report and send it with the &man.send-pr.1; program (see Bug Reports and General Commentary for more information about &man.send-pr.1;. If the uncompressed port is larger than 20KB, you should compress it into a tarfile and use &man.uuencode.1; before including it in the bug report (uuencoded tarfiles are acceptable even if the bug report is smaller than 20KB but are not preferred). Be sure to classify the bug report as category ports and class change-request (Do not mark the report confidential!). Also add a short description of the program you ported to the Description field of the PR and the shar or uuencoded tarfile to the Fix field. The latter one helps the committers a lot, who use scripts for the ports-work. One more time, do not include the original source distfile, the work directory, or the package you built with make package. In the past, we asked you to upload new port submissions in - our ftp site (ftp.FreeBSD.org). This + our FTP site (ftp.FreeBSD.org). This is no longer recommended as read access is turned off on the incoming/ directory of that site due to the large amount of pirated software showing up there. We will look at your port, get back to you if necessary, and put it in the tree. Your name will also appear in the list of “Additional FreeBSD contributors” in the FreeBSD Handbook and other files. Isn't that great?!? :-) You can make our work a lot easier, if you use a good description in the synopsis of the problem report. We prefer something like “New port: <short description of the port>” for new ports and “Update port: <category>/<port> <short description of the update>” for port updates. If you stick to this scheme, the chance that one takes a look at your PR soon is much bigger. Slow Porting Ok, so it was not that simple, and the port required some modifications to get it to work. In this section, we will explain, step by step, how to modify it to get it to work with the ports paradigm. How things work First, this is the sequence of events which occurs when the user first types make in your port's directory. You may find that having bsd.port.mk in another window while you read this really helps to understand it. But do not worry if you do not really understand what bsd.port.mk is doing, not many people do... :-> The fetch target is run. The fetch target is responsible for making sure that the tarball exists locally in DISTDIR. If fetch cannot find the required files in DISTDIR it will look up the URL MASTER_SITES, which is - set in the Makefile, as well as our main ftp site at ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/, where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with FETCH, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in DISTDIR for future use and proceed. The extract target is run. It looks for your port's distribution file (typically a gzip'd tarball) in DISTDIR and unpacks it into a temporary subdirectory specified by WRKDIR (defaults to work). The patch target is run. First, any patches defined in PATCHFILES are applied. Second, if any patch files named patch-* are found in PATCHDIR (defaults to the files subdirectory), they are applied at this time in alphabetical order. The configure target is run. This can do any one of many different things. If it exists, scripts/configure is run. If HAS_CONFIGURE or GNU_CONFIGURE is set, WRKSRC/configure is run. If USE_IMAKE is set, XMKMF (default: xmkmf -a) is run. The build target is run. This is responsible for descending into the port's private working directory (WRKSRC) and building it. If USE_GMAKE is set, GNU make will be used, otherwise the system make will be used. The above are the default actions. In addition, you can define targets pre-something or post-something, or put scripts with those names, in the scripts subdirectory, and they will be run before or after the default actions are done. For example, if you have a post-extract target defined in your Makefile, and a file pre-build in the scripts subdirectory, the post-extract target will be called after the regular extraction actions, and the pre-build script will be executed before the default build rules are done. It is recommended that you use Makefile targets if the actions are simple enough, because it will be easier for someone to figure out what kind of non-default action the port requires. The default actions are done by the bsd.port.mk targets do-something. For example, the commands to extract a port are in the target do-extract. If you are not happy with the default target, you can fix it by redefining the do-something target in your Makefile. The “main” targets (e.g., extract, configure, etc.) do nothing more than make sure all the stages up to that one are completed and call the real targets or scripts, and they are not intended to be changed. If you want to fix the extraction, fix do-extract, but never ever touch extract! Now that you understand what goes on when the user types make, let us go through the recommended steps to create the perfect port. Getting the original sources Get the original sources (normally) as a compressed tarball (foo.tar.gz or foo.tar.Z) and copy it into DISTDIR. Always use mainstream sources when and where you can. - If you cannot find a ftp/http site that is well-connected to the + If you cannot find a FTP/http site that is well-connected to the net, or can only find sites that have irritatingly non-standard - formats, you might want to put a copy on a reliable ftp or http + formats, you might want to put a copy on a reliable FTP or http server that you control (e.g., your home page). Make sure you set MASTER_SITES to reflect your choice. If you cannot find somewhere convenient and reliable to put the distfile we can “house” it ourselves on ftp.FreeBSD.org. The distfile must be placed into ~/public_distfiles/ of someone's freefall account. Ask the person who commits your port to do this. This person will also set MASTER_SITES to MASTER_SITE_LOCAL and MASTER_SITE_SUBDIR to their freefall username. If your port's distfile changes all the time for no good reason, consider putting the distfile in your home page and listing it as the first MASTER_SITES. This will prevent users from getting checksum mismatch errors, and - also reduce the workload of maintainers of our ftp site. Also, if + also reduce the workload of maintainers of our FTP site. Also, if there is only one master site for the port, it is recommended that you house a backup at your site and list it as the second MASTER_SITES. If your port requires some additional `patches' that are available on the Internet, fetch them too and put them in DISTDIR. Do not worry if they come from a site other than where you got the main source tarball, we have a way to handle these situations (see the description of PATCHFILES below). Modifying the port Unpack a copy of the tarball in a private directory and make whatever changes are necessary to get the port to compile properly under the current version of FreeBSD. Keep careful track of everything you do, as you will be automating the process shortly. Everything, including the deletion, addition, or modification of files should be doable using an automated script or patch file when your port is finished. If your port requires significant user interaction/customization to compile or install, you should take a look at one of Larry Wall's classic Configure scripts and perhaps do something similar yourself. The goal of the new ports collection is to make each port as “plug-and-play” as possible for the end-user while using a minimum of disk space. Unless explicitly stated, patch files, scripts, and other files you have created and contributed to the FreeBSD ports collection are assumed to be covered by the standard BSD copyright conditions. Patching In the preparation of the port, files that have been added or changed can be picked up with a recursive diff for later feeding to patch. Each set of patches you wish to apply should be collected into a file named patch-* where * denotes the sequence in which the patches will be applied — these are done in alphabetical order, thus aa first, ab second and so on. If you wish, you can use names that indicate the pathnames of the files that are patched, such as patch-Imakefile or patch-src-config.h. These files should be stored in PATCHDIR, from where they will be automatically applied. All patches should be relative to WRKSRC (generally the directory your port's tarball unpacks itself into, that being where the build is done). To make fixes and upgrades easier, you should avoid having more than one patch fix the same file (e.g., patch-aa and patch-ab both changing WRKSRC/foobar.c). Configuring Include any additional customization commands in your configure script and save it in the scripts subdirectory. As mentioned above, you can also do this with Makefile targets and/or scripts with the name pre-configure or post-configure. Handling user input If your port requires user input to build, configure, or install, then set IS_INTERACTIVE in your Makefile. This will allow “overnight builds” to skip your port if the user sets the variable BATCH in his environment (and if the user sets the variable INTERACTIVE, then only those ports requiring interaction are built). It is also recommended that if there are reasonable default answers to the questions, you check the PACKAGE_BUILDING variable and turn off the interactive script when it is set. This will allow us to build the - packages for CDROMs and ftp. + packages for CDROMs and FTP. Configuring the Makefile Configuring the Makefile is pretty simple, and again we suggest that you look at existing examples before starting. Also, there is a sample Makefile in this handbook, so take a look and please follow the ordering of variables and sections in that template to make your port easier for others to read. Now, consider the following problems in sequence as you design your new Makefile: The original source Does it live in DISTDIR as a standard gzip'd tarball named something like foozolix-1.2.tar.gz? If so, you can go on to the next step. If not, you should look at overriding any of the DISTNAME, EXTRACT_CMD, EXTRACT_BEFORE_ARGS, EXTRACT_AFTER_ARGS, EXTRACT_SUFX, or DISTFILES variables, depending on how alien a format your port's distribution file is. (The most common case is EXTRACT_SUFX=.tar.Z, when the tarball is condensed by regular compress, not gzip.) In the worst case, you can simply create your own do-extract target to override the default, though this should be rarely, if ever, necessary. <makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar> You should set PORTNAME to the base name of your port, and PORTVERSION to the version number of the port. <makevar>PORTREVISION</makevar> and <makevar>PORTEPOCH</makevar> <makevar>PORTREVISION</makevar> The PORTREVISION variable is a monotonically increasing value which is reset to 0 with every increase of PORTVERSION (i.e. every time a new official vendor release is made), and appended to the package name if non-zero. PORTREVISION is increased each time a change is made to the FreeBSD port which significantly affects the content or stucture of the derived package. Examples of when PORTREVISION should be bumped: Addition of patches to correct security vulnerabilities, bugs, or to add new functionality to the FreeBSD port. Changes to the port makefile to enable or disable compile-time options in the package. Changes in the packing list or the install-time behaviour of the package (e.g. change to a script which generates initial data for the package, like ssh host keys). Version bump of a port's shared library dependency (in this case, someone trying to install the old package after installing a newer version of the dependency will fail since it will look for the old libfoo.x instead of libfoo.(x+1)). Silent changes to the port distfile which have significant functional differences, i.e. changes to the distfile requiring a correction to distinfo with no corresponding change to PORTVERSION, where a diff -ru of the old and new versions shows non-trivial changes to the code. Examples of changes which do not require a PORTREVISION bump: Style changes to the port skeleton with no functional change to what appears in the resulting package. Changes to MASTER_SITES or other functional changes to the port which do not effect the resulting package. Trivial patches to the distfile such as correction of typos, which are not important enough that users of the package should go to the trouble of upgrading. Build fixes which cause a package to become compilable where it was previously failing (as long as the changes do not introduce any functional change on any other platforms on which the port did previously build). Since PORTREVISION reflects the content of the package, if no package was previously buildable then there is no need to increase PORTREVISION to mark a change. A rule of thumb is to ask yourself whether a change committed to a port is something which someone, somewhere, would benefit from having (either because of an enhancement, fix, or by virtue that the new package will actually work for them). If yes, the PORTREVISION should be bumped so that automated tools (e.g. pkg_version) will highlight the fact that a new package is available. <makevar>PORTEPOCH</makevar> From time to time a software vendor or FreeBSD porter will do something silly and release a version of their software which is actually numerically less than the previous version. An example of this is a port which goes from foo-20000801 to foo-1.0 (the former will be incorrectly treated as a newer version since 20000801 is a numerically greater value than 1). In situations such as this, the PORTEPOCH version should be increased. If PORTEPOCH is nonzero it is appended to the package name as described in section 0 above. PORTEPOCH is never decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail (i.e. the package would not be detected as out of date): the new version number (e.g. 1.0,1 in the above example) is still numerically less than the previous version (2000801), but the ,1 suffix is treated specially by automated tools and found to be greater than the implied suffix ",0" on the earlier package) It is expected that PORTEPOCH will not be used for the majority of ports, and that sensible use of PORTVERSION can often pre-empt it becoming necessary if a future release of the software should change the version structure. However, care is needed by FreeBSD porters when a vendor release is made without an official version number - such as a code "snapshot" release. The temptation is to label the release with the release date, which will cause problems as in the example above when a new "official" release is made. For example, if a snapshot release is made on the date 20000917, and the previous version of the software was version 1.2, the snapshot release should be given a PORTVERSION of 1.2.20000917 or similar, not 20000917, so that the succeeding release, say 1.3, is still a numerically greater value. Example of <makevar>PORTREVISION</makevar> and <makevar>PORTEPOCH</makevar> usage The gtkmumble port, version 0.10, is committed to the ports collection. PORTNAME= gtkmumble PORTVERSION= 0.10 PKGNAME becomes gtkmumble-0.10. A security hole is discovered which requires a local FreeBSD patch. PORTREVISION is bumped accordingly. PORTNAME= gtkmumble PORTVERSIOn= 0.10 PORTREVISION= 1 PKGNAME becomes gtkmumble-0.10_1 A new version is released by the vendor, numbered 0.2 (it turns out the author actually intended 0.10 to actually mean 0.1.0, not what comes after 0.9 - oops, too late now). Since the new minor version 2 is numerically less than the previous version 10 the PORTEPOCH must be bumped to manually force the new package to be detected as "newer". Since it is a new vendor release of the code, PORTREVISION is reset to 0 (or removed from the makefile). PORTNAME= gtkmumble PORTVERSION= 0.2 PORTEPOCH= 1 PKGNAME becomes gtkmumble-0.2,1 The next release is 0.3. Since PORTEPOCH never decreases, the version variables are now: PORTNAME= gtkmumble PORTVERSION= 0.3 PORTEPOCH= 1 PKGNAME becomes gtkmumble-0.3,1 If PORTEPOCH were reset to 0 with this upgrade, someone who had installed the gtkmumble-0.10_1 package would not detect the gtkmumble-0.3 package as newer, since 3 is still numerically less than 10. <makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar> Two optional variables, PKGNAMEPREFIX and PKGNAMESUFFIX, are combined with PORTNAME and PORTVERSION to form PKGNAME as ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure this conforms to our guidelines for a good package name. In particular, you are not allowed to use a hyphen (-) in PORTVERSION. Also, if the package name has the language- or the compiled.specifics part, use PKGNAMEPREFIX and PKGNAMESUFFIX, respectively. Do not make them part of PORTNAME. <makevar>DISTNAME</makevar> DISTNAME is the name of the port as called by the authors of the software. DISTNAME defaults to ${PORTNAME}-${PORTVERSION}, so override it if necessary. DISTNAME is only used in two places. First, the distribution file list (DISTFILES) defaults to ${DISTNAME}${EXTRACT_SUFX}. Second, the distribution file is expected to extract into a subdirectory named WRKSRC, which defaults to work/${DISTNAME}. PKGNAMEPREFIX and PKGNAMESUFFIX do not affect DISTNAME. Also note that when WRKSRC is equal to work/${PORTNAME}-${PORTVERSION} while the original source archive is named something other than ${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}, you should probably leave DISTNAME alone— you are better off defining DISTFILES than having to set both DISTNAME and WRKSRC (and possibly EXTRACT_SUFX). <makevar>CATEGORIES</makevar> When a package is created, it is put under /usr/ports/packages/All and links are made from one or more subdirectories of /usr/ports/packages. The names of these subdirectories are specified by the variable CATEGORIES. It is intended to make life easier for the user when he is wading through the pile of packages on the - ftp site or the CDROM. Please take a look at the existing categories and pick the ones that are suitable for your port. This list also determines where in the ports tree the port is imported. If you put more than one category here, it is assumed that the port files will be put in the subdirectory with the name in the first category. See the categories section for more discussion about how to pick the right categories. If your port truly belongs to something that is different from all the existing ones, you can even create a new category name. In that case, please send mail to the &a.ports; to propose a new category. <makevar>MASTER_SITES</makevar> - Record the directory part of the ftp/http-URL pointing at the + Record the directory part of the FTP/http-URL pointing at the original tarball in MASTER_SITES. Do not forget the trailing slash (/)! The make macros will try to use this specification for grabbing the distribution file with FETCH if they cannot find it already on the system. It is recommended that you put multiple sites on this list, preferably from different continents. This will safeguard against wide-area network problems, and we are even planning to add support for automatically determining the closest master site and fetching from there! If the original tarball is part of one of the popular archives such as X-contrib, GNU, or Perl CPAN, you may be able refer to those sites in an easy compact form using MASTER_SITE_* (e.g., MASTER_SITE_XCONTRIB and MASTER_SITE_PERL_GNU). Simply set MASTER_SITES to one of these variables and MASTER_SITE_SUBDIR to the path within the archive. Here is an example: MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications These variables are defined in /usr/ports/Mk/bsd.sites.mk. There are new archives added all the time, so make sure to check the latest version of this file before submitting a port. The user can also set the MASTER_SITE_* variables in /etc/make.conf to override our choices, and use their favorite mirrors of these popular archives instead. <makevar>PATCHFILES</makevar> If your port requires some additional patches that are available - by ftp or http, set PATCHFILES to the names of + by FTP or http, set PATCHFILES to the names of the files and PATCH_SITES to the URL of the directory that contains them (the format is the same as MASTER_SITES). If the patch is not relative to the top of the source tree (i.e., WRKSRC) because it contains some extra pathnames, set PATCH_DIST_STRIP accordingly. For instance, if all the pathnames in the patch have an extra foozolix-1.0/ in front of the filenames, then set PATCH_DIST_STRIP=-p1. Do not worry if the patches are compressed; they will be decompressed automatically if the filenames end with .gz or .Z. If the patch is distributed with some other files, such as documentation, in a gzip'd tarball, you cannot just use PATCHFILES. If that is the case, add the name and the location of the patch tarball to DISTFILES and MASTER_SITES. Then, use the EXTRA_PATCHES variable to point to those files and bsd.port.mk will automatically apply them for you. In particular, do not copy patch files into the PATCHDIR directory—that directory may not be writable. Note that the tarball will have been extracted alongside the regular source by then, so there is no need to explicitly extract it if it is a regular gzip'd or compress'd tarball. If you do the latter, take extra care not to overwrite something that already exists in that directory. Also, do not forget to add a command to remove the copied patch in the pre-clean target. <makevar>MAINTAINER</makevar> Set your mail-address here. Please. :-) For a detailed description of the responsibilities of maintainers, refer to the MAINTAINER on Makefiles section. Dependencies Many ports depend on other ports. There are five variables that you can use to ensure that all the required bits will be on the user's machine. There are also some pre-supported dependency variables for common cases, plus a few more to control the behaviour of dependencies. <makevar>LIB_DEPENDS</makevar> This variable specifies the shared libraries this port depends on. It is a list of lib:dir:target tuples where lib is the name of the shared library, dir is the directory in which to find it in case it is not available, and target is the target to call in that directory. For example, LIB_DEPENDS= jpeg.9:${PORTSDIR}/graphics/jpeg:install will check for a shared jpeg library with major version 9, and descend into the graphics/jpeg subdirectory of your ports tree to build and install it if it is not found. The target part can be omitted if it is equal to DEPENDS_TARGET (which defaults to install). The lib part is an argument given to ldconfig -r | grep -wF. There shall be no regular expressions in this variable. The dependency is checked twice, once from within the extract target and then from within the install target. Also, the name of the dependency is put into the package so that pkg_add will automatically install it if it is not on the user's system. <makevar>RUN_DEPENDS</makevar> This variable specifies executables or files this port depends on during run-time. It is a list of path:dir:target tuples where path is the name of the executable or file, dir is the directory in which to find it in case it is not available, and target is the target to call in that directory. If path starts with a slash (/), it is treated as a file and its existence is tested with test -e; otherwise, it is assumed to be an executable, and which -s is used to determine if the program exists in the user's search path. For example, RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ wish8.0:${PORTSDIR}/x11-toolkits/tk80 will check if the file or directory /usr/local/etc/innd exists, and build and install it from the news/inn subdirectory of the ports tree if it is not found. It will also see if an executable called wish8.0 is in your search path, and descend into the x11-toolkits/tk80 subdirectory of your ports tree to build and install it if it is not found. In this case, innd is actually an executable; if an executable is in a place that is not expected to be in a normal user's search path, you should use the full pathname. The dependency is checked from within the install target. Also, the name of the dependency is put in to the package so that pkg_add will automatically install it if it is not on the user's system. The target part can be omitted if it is the same as DEPENDS_TARGET. <makevar>BUILD_DEPENDS</makevar> This variable specifies executables or files this port requires to build. Like RUN_DEPENDS, it is a list of path:dir:target tuples. For example, BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip will check for an executable called unzip, and descend into the archivers/unzip subdirectory of your ports tree to build and install it if it is not found. “build” here means everything from extraction to compilation. The dependency is checked from within the extract target. The target part can be omitted if it is the same as DEPENDS_TARGET <makevar>FETCH_DEPENDS</makevar> This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of path:dir:target tuples. For example, FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 will check for an executable called ncftp2, and descend into the net/ncftp2 subdirectory of your ports tree to build and install it if it is not found. The dependency is checked from within the fetch target. The target part can be omitted if it is the same as DEPENDS_TARGET. <makevar>DEPENDS</makevar> If there is a dependency that does not fall into either of the above four categories, or your port requires having the source of the other port extracted in addition to having it installed, then use this variable. This is a list of dir:target, as there is nothing to check, unlike the previous four. The target part can be omitted if it is the same as DEPENDS_TARGET. Common dependency variables Define USE_XLIB=yes if your port requires the X Window System to be installed (it is implied by USE_IMAKE). Define USE_GMAKE=yes if your port requires GNU make instead of BSD make. Define USE_AUTOCONF=yes if your port requires GNU autoconf to be run. Define USE_QT=yes if your port uses the latest qt toolkit. Use USE_PERL5=yes if your port requires version 5 of the perl language. (The last is especially important since some versions of FreeBSD have perl5 as part of the base system while others do not.) Notes on dependencies As mentioned above, the default target to call when a dependency is required is DEPENDS_TARGET. It defaults to install. This is a user variable; it is never defined in a port's Makefile. If your port needs a special way to handle a dependency, use the :target part of the *_DEPENDS variables instead of redefining DEPENDS_TARGET. When you type make clean, its dependencies are automatically cleaned too. If you do not wish this to happen, define the variable NOCLEANDEPENDS in your environment. To depend on another port unconditionally, use the variable ${NONEXISTENT} as the first field of BUILD_DEPENDS or RUN_DEPENDS. Use this only when you need to the to get to the source of the other port. You can often save compilation time by specifying the target too. For instance BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract will always descend to the JPEG port and extract it. Do not use DEPENDS unless there is no other way the behaviour you want can be accomplished. It will cause the other port to always be built (and installed, by default), and the dependency will go into the packages as well. If this is really what you need, you should probably write it as BUILD_DEPENDS and RUN_DEPENDS instead—at least the intention will be clear. Optional dependencies Some large applications can be built in a number of configurations, adding functionality if one of a number of libraries or applications is available. Since not all users want those libraries or applications, the ports system provides hooks that the port author can use to decide which configuration should be built. Supporting these properly will make uses happy, and effectively provide 2 or more ports for the price of one. The easiest of these to use is WITHOUT_X11. If the port can be built both with and without X support, then it should normally be built with X support. If WITHOUT_X11 is defined, then the version that does not have X support should be built. Various parts of GNOME have such knobs, though they are slightly more difficult to use. The variables to use in the Makefile are WANT_* and HAVE_*. If the application can be built both with or without one of the dependencies listed below, then the Makefile should set WANT_PKG, and should build the version that uses PKG if HAVE_PKG is defined. The WANT_* variables currently supported this way are WANT_GLIB, WANT_GTK, WANT_ESOUND, WANT_IMLIB, and WANT_GNOME. Building mechanisms If your package uses GNU make, set USE_GMAKE=yes. If your package uses configure, set HAS_CONFIGURE=yes. If your package uses GNU configure, set GNU_CONFIGURE=yes (this implies HAS_CONFIGURE). If you want to give some extra arguments to configure (the default argument list --prefix=${PREFIX} for GNU configure and empty for non-GNU configure), set those extra arguments in CONFIGURE_ARGS. If your package uses GNU autoconf, set USE_AUTOCONF=yes. This implies GNU_CONFIGURE, and will cause autoconf to be run before configure. If your package is an X application that creates Makefiles from Imakefiles using imake, then set USE_IMAKE=yes. This will cause the configure stage to automatically do an xmkmf -a. If the flag is a problem for your port, set XMKMF=xmkmf. If the port uses imake but does not understand the install.man target, NO_INSTALL_MANPAGES=yes should be set. In addition, the author of the original port should be shot. :-> If your port's source Makefile has something else than all as the main build target, set ALL_TARGET accordingly. Same goes for install and INSTALL_TARGET. Special considerations There are some more things you have to take into account when you create a port. This section explains the most common of those. Shared Libraries If your port installs one or more shared libraries, define a INSTALLS_SHLIB make variable, which will instruct a bsd.port.mk to run ${LDCONFIG} -m on the directory where the new library is installed (usually PREFIX/lib) during post-install target to register it into the shared library cache. This variable, when defined, will also facilitate addition of an appropriate @exec /sbin/ldconfig -m and @unexec /sbin/ldconfig -R pair into your pkg-plist file, so that a user who installed the package can start using the shared library immediately and deinstallation will not cause the system to still believe the library is there. If you need, you can override default location where the new library is installed by defining LDCONFIG_DIRS make variable, which should contain a list of directories into which shared libraries are to be installed. For example if your port installs shared libraries into PREFIX/lib/foo and PREFIX/lib/bar directories you could use the following in your Makefile: INSTALLS_SHLIB= yes LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar Note that content of LDCONFIG_DIRS is passed through &man.sed.1; just like the rest of pkg-plist, so PLIST_SUB substitutions also apply here. It is recommended that you use %%PREFIX%% for PREFIX, %%LOCALBASE%% for LOCALBASE and %%X11BASE%% for X11BASE. <makevar>MASTERDIR</makevar> If your port needs to build slightly different versions of packages by having a variable (for instance, resolution, or paper size) take different values, create one subdirectory per package to make it easier for users to see what to do, but try to share as many files as possible between ports. Typically you only need a very short Makefile in all but one of the directories if you use variables cleverly. In the sole Makefiles, you can use MASTERDIR to specify the directory where the rest of the files are. Also, use a variable as part of PKGNAMESUFFIX so the packages will have different names. This will be best demonstrated by an example. This is part of japanese/xdvi300/Makefile; PORTNAME= xdvi PORTVERSION= 17 PKGNAMEPREFIX= ja- PKGNAMESUFFIX= ${RESOLUTION} : # default RESOLUTION?= 300 .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ ${RESOLUTION} != 300 && ${RESOLUTION} != 400 @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" @${ECHO} "Possible values are: 118, 240, 300 (default) and 400." @${FALSE} .endif japanese/xdvi300 also has all the regular patches, package files, etc. If you type make there, it will take the default value for the resolution (300) and build the port normally. As for other resolutions, this is the entire xdvi118/Makefile: RESOLUTION= 118 MASTERDIR= ${.CURDIR}/../xdvi300 .include ${MASTERDIR}/Makefile (xdvi240/Makefile and xdvi400/Makefile are similar). The MASTERDIR definition tells bsd.port.mk that the regular set of subdirectories like FILESDIR and SCRIPTDIR are to be found under xdvi300. The RESOLUTION=118 line will override the RESOLUTION=300 line in xdvi300/Makefile and the port will be built with resolution set to 118. Shared library versions Please read our policy on shared library versioning to understand what to do with shared library versions in general. Do not blindly assume software authors know what they are doing; many of them do not. It is very important that these details are carefully considered, as we have quite a unique situation where we are trying to have dozens of potentially incompatible software pairs co-exist. Careless port imports have caused great trouble regarding shared libraries in the past (ever wondered why the port jpeg-6b has a shared library version of 9?). If in doubt, send a message to the &a.ports;. Most of the time, your job ends by determining the right shared library version and making appropriate patches to implement it. Manpages The MAN[1-9LN] variables will automatically add any manpages to pkg-plist (this means you must not list manpages in the pkg-plist—see generating PLIST for more). It also makes the install stage automatically compress or uncompress manpages depending on the setting of NOMANCOMPRESS in /etc/make.conf. If your port tries to install multiple names for manpages using symlinks or hardlinks, you must use the MLINKS variable to identify these. The link installed by your port will be destroyed and recreated by bsd.port.mk to make sure it points to the correct file. Any manpages listed in MLINKS must not be listed in the pkg-plist. To specify whether the manpages are compressed upon installation, use the MANCOMPRESSED variable. This variable can take three values, yes, no and maybe. yes means manpages are already installed compressed, no means they are not, and maybe means the software already respects the value of NOMANCOMPRESS so bsd.port.mk does not have to do anything special. MANCOMPRESSED is automatically set to yes if USE_IMAKE is set and NO_INSTALL_MANPAGES is not set, and to no otherwise. You do not have to explicitly define it unless the default is not suitable for your port. If your port anchors its man tree somewhere other than PREFIX, you can use the MANPREFIX to set it. Also, if only manpages in certain sections go in a non-standard place, such as some Perl modules ports, you can set individual man paths using MANsectPREFIX (where sect is one of 1-9, L or N). If your manpages go to language-specific subdirectories, set the name of the languages to MANLANG. The value of this variable defaults to "" (i.e., English only). Here is an example that puts it all together. MAN1= foo.1 MAN3= bar.3 MAN4= baz.4 MLINKS= foo.1 alt-name.8 MANLANG= "" ja MAN3PREFIX= ${PREFIX}/share/foobar MANCOMPRESSED= yes This states that six files are installed by this port; ${PREFIX}/man/man1/foo.1.gz ${PREFIX}/man/ja/man1/foo.1.gz ${PREFIX}/share/foobar/man/man3/bar.3.gz ${PREFIX}/share/foobar/man/ja/man3/bar.3.gz ${PREFIX}/man/man4/baz.4.gz ${PREFIX}/man/ja/man4/baz.4.gz Additionally ${PREFIX}/man/man8/alt-name.8.gz may or may not be installed by your port. Regardless, a symlink will be made to join the foo(1) manpage and alt-name(8) manpage. Ports that require Motif There are many programs that require a Motif library (available from several commercial vendors, while there is a free clone reported to be able to run many applications in x11-toolkits/lesstif) to compile. Since it is a popular toolkit and their licenses usually permit redistribution of statically linked binaries, we have made special provisions for handling ports that require Motif in a way that we can easily compile binaries linked either dynamically (for people who are compiling from the port) or statically (for people who distribute packages). <makevar>REQUIRES_MOTIF</makevar> If your port requires Motif, define this variable in the Makefile. This will prevent people who do not own a copy of Motif from even attempting to build it. <makevar>MOTIFLIB</makevar> This variable will be set by bsd.port.mk to be the appropriate reference to the Motif library. Please patch the source to use this wherever the Motif library is referenced in the Makefile or Imakefile. There are two common cases: If the port refers to the Motif library as -lXm in its Makefile or Imakefile, simply substitute ${MOTIFLIB} for it. If the port uses XmClientLibs in its Imakefile, change it to ${MOTIFLIB} ${XTOOLLIB} ${XLIB}. Note that MOTIFLIB (usually) expands to -L/usr/X11R6/lib -lXm or /usr/X11R6/lib/libXm.a, so there is no need to add -L or -l in front. X11 fonts If your port installs fonts for the X Window system, put them in X11BASE/lib/X11/fonts/local. This directory is new to XFree86 release 3.3.3. If it does not exist, please create it, and print out a message urging the user to update their XFree86 to 3.3.3 or newer, or at least add this directory to the font path in /etc/XF86Config. Info files The new version of texinfo (included in 2.2.2-RELEASE and onwards) contains a utility called install-info to add and delete entries to the dir file. If your port installs any info documents, please follow these instructions so your port/package will correctly update the user's PREFIX/info/dir file. (Sorry for the length of this section, but is it imperative to weave all the info files together. If done correctly, it will produce a beautiful listing, so please bear with me! First, this is what you (as a porter) need to know &prompt.user; install-info --help install-info [OPTION]... [INFO-FILE [DIR-FILE]] Install INFO-FILE in the Info directory file DIR-FILE. Options: --delete Delete existing entries in INFO-FILE; don't insert any new entries. : --entry=TEXT Insert TEXT as an Info directory entry. : --section=SEC Put this file's entries in section SEC of the directory. : This program will not actually install info files; it merely inserts or deletes entries in the dir file. Here's a seven-step procedure to convert ports to use install-info. editors/emacs will be used as an example. Look at the texinfo sources and make a patch to insert @dircategory and @direntry statements to files that do not have them. This is part of my patch: --- ./man/vip.texi.org Fri Jun 16 15:31:11 1995 +++ ./man/vip.texi Tue May 20 01:28:33 1997 @@ -2,6 +2,10 @@ @setfilename ../info/vip @settitle VIP +@dircategory The Emacs editor and associated tools +@direntry +* VIP: (vip). A VI-emulation for Emacs. +@end direntry @iftex @finalout : The format should be self-explanatory. Many authors leave a dir file in the source tree that contains all the entries you need, so look around before you try to write your own. Also, make sure you look into related ports and make the section names and entry indentations consistent (we recommend that all entry text start at the 4th tab stop). Note that you can put only one info entry per file because of a bug in install-info --delete that deletes only the first entry if you specify multiple entries in the @direntry section. You can give the dir entries to install-info as arguments ( and ) instead of patching the texinfo sources. This probably is not a good idea for ports because you need to duplicate the same information in three places (Makefile and @exec/@unexec of pkg-plist; see below). However, if you have Japanese (or other multibyte encoding) info files, you will have to use the extra arguments to install-info because makeinfo cannot handle those texinfo sources. (See Makefile and pkg-plist of japanese/skk for examples on how to do this). Go back to the port directory and do a make clean; make and verify that the info files are regenerated from the texinfo sources. Since the texinfo sources are newer than the info files, they should be rebuilt when you type make; but many Makefiles do not include correct dependencies for info files. In emacs' case, it was necessary to patch the main Makefile.in so it would descend into the man subdirectory to rebuild the info pages. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 +++ ./Makefile.in Tue Apr 15 00:15:28 1997 @@ -184,7 +184,7 @@ # Subdirectories to make recursively. `lisp' is not included # because the compiled lisp files are part of the distribution # and you cannot remake them without installing Emacs first. -SUBDIR = lib-src src +SUBDIR = lib-src src man # The makefiles of the directories in $SUBDIR. SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile --- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996 +++ ./man/Makefile.in Tue Apr 15 00:29:52 1997 @@ -66,6 +66,7 @@ ${srcdir}/gnu1.texi \ ${srcdir}/glossary.texi +all: info info: $(INFO_TARGETS) dvi: $(DVI_TARGETS) The second hunk was necessary because the default target in the man subdir is called info, while the main Makefile wants to call all. The installation of the info info file was also removed because we already have one with the same name in /usr/share/info (that patch is not shown here). If there is a place in the Makefile that is installing the dir file, delete it. Your port may not be doing it. Also, remove any commands that are otherwise mucking around with the dir file. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 +++ ./Makefile.in Mon Apr 14 23:38:07 1997 @@ -368,14 +368,8 @@ if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \ then \ (cd ${infodir}; \ - if [ -f dir ]; then \ - if [ ! -f dir.old ]; then mv -f dir dir.old; \ - else mv -f dir dir.bak; fi; \ - fi; \ cd ${srcdir}/info ; \ - (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \ - (cd $${thisdir}; chmod a+r ${infodir}/dir); \ for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \ (cd $${thisdir}; \ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ chmod a+r ${infodir}/$$f); \ (This step is only necessary if you are modifying an existing port.) Take a look at pkg-plist and delete anything that is trying to patch up info/dir. They may be in pkg-install or some other file, so search extensively. Index: pkg-plist =================================================================== RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v retrieving revision 1.15 diff -u -r1.15 pkg-plist --- pkg-plist 1997/03/04 08:04:00 1.15 +++ pkg-plist 1997/04/15 06:32:12 @@ -15,9 +15,6 @@ man/man1/emacs.1.gz man/man1/etags.1.gz man/man1/ctags.1.gz -@unexec cp %D/info/dir %D/info/dir.bak -info/dir -@unexec cp %D/info/dir.bak %D/info/dir info/cl info/cl-1 info/cl-2 Add a post-install target to the Makefile to call install-info with the installed info files. (It is no longer necessary to create the dir file yourself; install-info automatically creates this file if it does not exist.) Index: Makefile =================================================================== RCS file: /usr/cvs/ports/editors/emacs/Makefile,v retrieving revision 1.26 diff -u -r1.26 Makefile --- Makefile 1996/11/19 13:14:40 1.26 +++ Makefile 1997/05/20 10:25:09 1.28 @@ -20,5 +20,8 @@ post-install: .for file in emacs-19.34 emacsclient etags ctags b2m strip ${PREFIX}/bin/${file} .endfor +.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode + install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir +.endfor .include <bsd.port.mk> Edit pkg-plist and add equivalent @exec statements and also @unexec for pkg_delete. Index: pkg-plist =================================================================== RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v retrieving revision 1.15 diff -u -r1.15 pkg-plist --- pkg-plist 1997/03/04 08:04:00 1.15 +++ pkg-plist 1997/05/20 10:25:12 1.17 @@ -16,7 +14,14 @@ man/man1/etags.1.gz man/man1/ctags.1.gz +@unexec install-info --delete %D/info/emacs %D/info/dir : +@unexec install-info --delete %D/info/ccmode %D/info/dir info/cl info/cl-1 @@ -87,6 +94,18 @@ info/viper-3 info/viper-4 +@exec install-info %D/info/emacs %D/info/dir : +@exec install-info %D/info/ccmode %D/info/dir libexec/emacs/19.34/i386--freebsd/cvtmail libexec/emacs/19.34/i386--freebsd/digest-doc The @unexec install-info --delete commands have to be listed before the info files themselves so they can read the files. Also, the @exec install-info commands have to be after the info files and the @exec command that creates the the dir file. Test and admire your work. :-). Check the dir file before and after each step. The <filename>pkg-<replaceable>*</replaceable></filename> files There are some tricks we have not mentioned yet about the pkg-* files that come in handy sometimes. <filename>pkg-message</filename> If you need to display a message to the installer, you may place the message in pkg-message. This capability is often useful to display additional installation steps to be taken after a pkg_add or to display licensing information. The pkg-message file does not need to be added to pkg-plist. Also, it will not get automatically printed if the user is using the port, not the package, so you should probably display it from the post-install target yourself. <filename>pkg-install</filename> If your port needs to execute commands when the binary package is installed with pkg_add you can do this via the pkg-install script. This script will automatically be added to the package, and will be run twice by pkg_add. The first time as ${SH} pkg-install ${PKGNAME} PRE-INSTALL and the second time as ${SH} pkg-install ${PKGNAME} POST-INSTALL. $2 can be tested to determine which mode the script is being run in. The PKG_PREFIX environmental variable will be set to the package installation directory. See &man.pkg.add.1; for additional information. This script is not run automatically if you install the port with make install. If you are depending on it being run, you will have to explicitly call it from your port's Makefile. <filename>pkg-req</filename> If your port needs to determine if it should install or not, you can create a pkg-req “requirements” script. It will be invoked automatically at installation/deinstallation time to determine whether or not installation/deinstallation should proceed. The script will be run at installation time by pkg_add as pkg-req ${PKGNAME} INSTALL. At deinstallation time it will be run by pkg_delete as pkg-req ${PKGNAME} DEINSTALL. Changing <filename>pkg-plist</filename> based on make variables Some ports, particularly the p5- ports, need to change their pkg-plist depending on what options they are configured with (or version of perl, in the case of p5- ports). To make this easy, any instances in the pkg-plist of %%OSREL%%, %%PERL_VER%%, and %%PERL_VERSION%% will be substituted for appropriately. The value of %%OSREL%% is the numeric revision of the operating system (e.g., 2.2.7). %%PERL_VERSION%% is the full version number of perl (e.g., 5.00502) and %%PERL_VER%% is the perl version number minus the patchlevel (e.g., 5.005). If you need to make other substitutions, you can set the PLIST_SUB variable with a list of VAR=VALUE pairs and instances of %%VAR%%' will be substituted with VALUE in the pkg-plist. For instance, if you have a port that installs many files in a version-specific subdirectory, you can put something like OCTAVE_VERSION= 2.0.13 PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} in the Makefile and use %%OCTAVE_VERSION%% wherever the version shows up in pkg-plist. That way, when you upgrade the port, you will not have to change dozens (or in some cases, hundreds) of lines in the pkg-plist. This substitution (as well as addition of any man pages) will be done between the do-install and post-install targets, by reading from PLIST and writing to TMPPLIST (default: WRKDIR/.PLIST.mktmp). So if your port builds PLIST on the fly, do so in or before do-install. Also, if your port needs to edit the resulting file, do so in post-install to a file named TMPPLIST. Changing the names of <filename>pkg-<replaceable>*</replaceable></filename> files All the names of pkg-* files are defined using variables so you can change them in your Makefile if need be. This is especially useful when you are sharing the same pkg-* files among several ports or have to write to one of the above files (see writing to places other than WRKDIR for why it is a bad idea to write directly in to the pkg-* subdirectory). Here is a list of variable names and their default values. (PKGDIR defaults to ${MASTERDIR}.) Variable Default value COMMENT ${PKGDIR}/pkg-comment DESCR ${PKGDIR}/pkg-descr PLIST ${PKGDIR}/pkg-plist PKGINSTALL ${PKGDIR}/pkg-install PKGDEINSTALL ${PKGDIR}/pkg-deinstall PKGREQ ${PKGDIR}/pkg-req PKGMESSAGE ${PKGDIR}/pkg-message Please change these variables rather than overriding PKG_ARGS. If you change PKG_ARGS, those files will not correctly be installed in /var/db/pkg upon install from a port. Licensing Problems Some software packages have restrictive licenses or can be in violation of the law in some countries (such as violating a patent). What we can do with them varies a lot, depending on the exact wordings of the respective licenses. It is your responsibility as a porter to read the licensing terms of the software and make sure that the FreeBSD project will not be held accountable for violating them by redistributing the - source or compiled binaries either via ftp or CDROM. If in doubt, + source or compiled binaries either via FTP or CDROM. If in doubt, please contact the &a.ports;. There are two variables you can set in the Makefile to handle the situations that arise frequently: If the port has a “do not sell for profit” type of license, set the variable NO_CDROM to a string describing the reason why. We will make sure such ports will not go into the CDROM come release time. The distfile and package will - still be available via ftp. + still be available via FTP. If the resulting package needs to be built uniquely for each site, or the resulting binary package cannot be distributed due to licensing; set the variable NO_PACKAGE to a string describing the reason why. We will make sure such packages - will not go on the ftp site, nor into the CDROM come release time. + will not go on the FTP site, nor into the CDROM come release time. The distfile will still be included on both however. If the port has legal restrictions on who can use it (e.g., patented stuff) or has a “no commercial use” license, set the variable RESTRICTED to be the string describing the reason why. For such ports, the distfiles/packages - will not be available even from our ftp sites. + will not be available even from our FTP sites. The GNU General Public License (GPL), both version 1 and 2, should not be a problem for ports. If you are a committer, make sure you update the ports/LEGAL file too. Upgrading When you notice that a port is out of date compared to the latest version from the original authors, first make sure you have the latest port. You can find them in the - ports/ports-current directory of the ftp mirror + ports/ports-current directory of the FTP mirror sites. You may also use CVSup to keep your whole ports collection up-to-date, as described in the Handbook. The next step is to send a mail to the maintainer, if one is listed in the port's Makefile. That person may already be working on an upgrade, or have a reason to not upgrade the port right now (because of, for example, stability problems of the new version). If the maintainer asks you to do the upgrade or there is not any such person to begin with, please make the upgrade and send the recursive diff (either unified or context diff is fine, but port committers appear to prefer unified diff more) of the new and old ports directories to us (e.g., if your modified port directory is called superedit and the original as in our tree is superedit.bak, then send us the result of diff -ruN superedit.bak superedit). Please examine the output to make sure all the changes make sense. The best way to send us the diff is by including it via &man.send-pr.1; (category ports). Please mention any added or deleted files in the message, as they have to be explicitly specified to CVS when doing a commit. If the diff is more than about 20KB, please compress and uuencode it; otherwise, just include it in the PR as is. Once again, please use &man.diff.1; and not &man.shar.1; to send updates to existing ports! <anchor id="porting-dads">Dos and Don'ts Here is a list of common dos and don'ts that you encounter during the porting process.You should check your own port against this list, but you can also check ports in the PR database that others have submitted. Submit any comments on ports you check as described in Bug Reports and General Commentary. Checking ports in the PR database will both make it faster for us to commit them, and prove that you know what you are doing. Strip Binaries Do strip binaries. If the original source already strips the binaries, fine; otherwise you should add a post-install rule to it yourself. Here is an example: post-install: strip ${PREFIX}/bin/xdl Use the &man.file.1; command on the installed executable to check whether the binary is stripped or not. If it does not say not stripped, it is stripped. INSTALL_* macros Do use the macros provided in bsd.port.mk to ensure correct modes and ownership of files in your own *-install targets. INSTALL_PROGRAM is a command to install binary executables. INSTALL_SCRIPT is a command to install executable scripts. INSTALL_DATA is a command to install sharable data. INSTALL_MAN is a command to install manpages and other documentation (it does not compress anything). These are basically the install command with all the appropriate flags. See below for an example on how to use them. <makevar>WRKDIR</makevar> Do not write anything to files outside WRKDIR. WRKDIR is the only place that is guaranteed to be writable during the port build (see compiling ports from CDROM for an example of building ports from a read-only tree). If you need to modify one of the pkg-* files, do so by redefining a variable, not by writing over it. <makevar>WRKDIRPREFIX</makevar> Make sure your port honors WRKDIRPREFIX. Most ports do not have to worry about this. In particular, if you are referring to a WRKDIR of another port, note that the correct location is WRKDIRPREFIXPORTSDIR/subdir/name/work not PORTSDIR/subdir/name/work or .CURDIR/../../subdir/name/work or some such. Also, if you are defining WRKDIR yourself, make sure you prepend ${WRKDIRPREFIX}${.CURDIR} in the front. Differentiating operating systems and OS versions You may come across code that needs modifications or conditional compilation based upon what version of Unix it is running under. If you need to make such changes to the code for conditional compilation, make sure you make the changes as general as possible so that we can back-port code to FreeBSD 1.x systems and cross-port to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD. The preferred way to tell 4.3BSD/Reno (1990) and newer versions of the BSD code apart is by using the BSD macro defined in <sys/param.h>. Hopefully that file is already included; if not, add the code: #if (defined(__unix__) || defined(unix)) && !defined(USG) #include <sys/param.h> #endif to the proper place in the .c file. We believe that every system that defines these two symbols has sys/param.h. If you find a system that does not, we would like to know. Please send mail to the &a.ports;. Another way is to use the GNU Autoconf style of doing this: #ifdef HAVE_SYS_PARAM_H #include <sys/param.h> #endif Do not forget to add -DHAVE_SYS_PARAM_H to the CFLAGS in the Makefile for this method. Once you have sys/param.h included, you may use: #if (defined(BSD) && (BSD >= 199103)) to detect if the code is being compiled on a 4.3 Net2 code base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386 1.1 and below). Use: #if (defined(BSD) && (BSD >= 199306)) to detect if the code is being compiled on a 4.4 code base or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or above). The value of the BSD macro is 199506 for the 4.4BSD-Lite2 code base. This is stated for informational purposes only. It should not be used to distinguish between versions of FreeBSD based only on 4.4-Lite vs. versions that have merged in changes from 4.4-Lite2. The __FreeBSD__ macro should be used instead. Use sparingly: __FreeBSD__ is defined in all versions of FreeBSD. Use it if the change you are making only affects FreeBSD. Porting gotchas like the use of sys_errlist[] vs strerror() are Berkeleyisms, not FreeBSD changes. In FreeBSD 2.x, __FreeBSD__ is defined to be 2. In earlier versions, it is 1. Later versions will bump it to match their major version number. If you need to tell the difference between a FreeBSD 1.x system and a FreeBSD 2.x or 3.x system, usually the right answer is to use the BSD macros described above. If there actually is a FreeBSD specific change (such as special shared library options when using ld) then it is OK to use __FreeBSD__ and #if __FreeBSD__ > 1 to detect a FreeBSD 2.x and later system. If you need more granularity in detecting FreeBSD systems since 2.0-RELEASE you can use the following: #if __FreeBSD__ >= 2 #include <osreldate.h> # if __FreeBSD_version >= 199504 /* 2.0.5+ release specific code here */ # endif #endif Release __FreeBSD_version 2.0-RELEASE 119411 2.1-CURRENT 199501, 199503 2.0.5-RELEASE 199504 2.2-CURRENT before 2.1 199508 2.1.0-RELEASE 199511 2.2-CURRENT before 2.1.5 199512 2.1.5-RELEASE 199607 2.2-CURRENT before 2.1.6 199608 2.1.6-RELEASE 199612 2.1.7-RELEASE 199612 2.2-RELEASE 220000 2.2.1-RELEASE 220000 (no change) 2.2-STABLE after 2.2.1-RELEASE 220000 (no change) 2.2-STABLE after texinfo-3.9 221001 2.2-STABLE after top 221002 2.2.2-RELEASE 222000 2.2-STABLE after 2.2.2-RELEASE 222001 2.2.5-RELEASE 225000 2.2-STABLE after 2.2.5-RELEASE 225001 2.2-STABLE after ldconfig -R merge 225002 2.2.6-RELEASE 226000 2.2.7-RELEASE 227000 2.2-STABLE after 2.2.7-RELEASE 227001 2.2-STABLE after &man.semctl.2; change 227002 2.2.8-RELEASE 228000 2.2-STABLE after 2.2.8-RELEASE 228001 3.0-CURRENT before &man.mount.2; change 300000 3.0-CURRENT after &man.mount.2; change 300001 3.0-CURRENT after &man.semctl.2; change 300002 3.0-CURRENT after ioctl arg changes 300003 3.0-CURRENT after ELF conversion 300004 3.0-RELEASE 300005 3.0-CURRENT after 3.0-RELEASE 300006 3.0-STABLE after 3/4 branch 300007 3.1-RELEASE 310000 3.1-STABLE after 3.1-RELEASE 310001 3.1-STABLE after C++ constructor/destructor order change 310002 3.2-RELEASE 320000 3.2-STABLE 320001 3.2-STABLE after binary-incompatible IPFW and socket changes 320002 3.3-RELEASE 330000 3.3-STABLE 330001 3.3-STABLE after adding &man.mkstemp.3; to libc 330002 3.4-RELEASE 340000 3.4-STABLE 340001 4.0-CURRENT after 3.4 branch 400000 4.0-CURRENT after change in dynamic linker handling 400001 4.0-CURRENT after C++ constructor/destructor order change 400002 4.0-CURRENT after functioning &man.dladdr.3; 400003 4.0-CURRENT after __deregister_frame_info dynamic linker bug fix (also 4.0-CURRENT after EGCS 1.1.2 integration) 400004 4.0-CURRENT after &man.suser.9; API change (also 4.0-CURRENT after newbus) 400005 4.0-CURRENT after cdevsw registration change 400006 4.0-CURRENT after the addition of so_cred for socket level credentials 400007 4.0-CURRENT after the addition of a poll syscall wrapper to libc_r 400008 4.0-CURRENT after the change of the kernel's dev_t type to struct specinfo pointer 400009 4.0-CURRENT after fixing a hole in &man.jail.2; 400010 4.0-CURRENT after the sigset_t datatype change 400011 4.0-CURRENT after the cutover to the GCC 2.95.2 compiler 400012 4.0-CURRENT after adding pluggable linux-mode ioctl handlers 400013 4.0-CURRENT after importing OpenSSL 400014 4.0-CURRENT after the C++ ABI change in GCC 2.95.2 from -fvtable-thunks to -fno-vtable-thunks by default 400015 4.0-CURRENT after importing OpenSSH 400016 4.0-RELEASE 400017 4.0-STABLE after 4.0-RELEASE 400018 4.0-STABLE after merging libxpg4 code into libc. 400020 4.0-STABLE after upgrading Binutils to 2.10.0, ELF branding changes, and tcsh in the base system. 400021 4.1-RELEASE 410000 4.1-STABLE after 4.1-RELEASE 410001 4.1-STABLE after &man.setproctitle.3; moved from libutil to libc. 410002 4.1.1-RELEASE 411000 4.1.1-STABLE after 4.1.1-RELEASE 411001 4.2-RELEASE 420000 4.2-STABLE after combining libgcc.a and libgcc_r.a, and associated GCC linkage changes. 420001 5.0-CURRENT 500000 5.0-CURRENT after adding addition ELF header fields, and changing our ELF binary branding method. 500001 5.0-CURRENT after kld metadata changes. 500002 5.0-CURRENT after buf/bio changes. 500003 5.0-CURRENT after binutils upgrade. 500004 5.0-CURRENT after merging libxpg4 code into libc and after TASKQ interface introduction. 500005 5.0-CURRENT after the addition of AGP interfaces. 500006 5.0-CURRENT after Perl upgrade to 5.6.0 500007 5.0-CURRENT after the update of KAME code to 2000/07 sources. 500008 5.0-CURRENT after ether_ifattach() and ether_ifdetach() changes. 500009 5.0-CURRENT after changing mtree defaults back to original variant, adding -L to follow symlinks. 500010 5.0-CURRENT after kqueue API changed. 500011 5.0-CURRENT after &man.setproctitle.3; moved from libutil to libc. 500012 5.0-CURRENT after the first SMPng commit. 500013 5.0-CURRENT after <sys/select.h> moved to <sys/selinfo.h>. 500014 5.0-CURRENT after combining libgcc.a and libgcc_r.a, and associated GCC linkage changes. 500015 5.0-CURRENT after change allowing libc and libc_r to be linked together, deprecating -pthread option. 500016 5.0-CURRENT after switch from struct ucred to struct xucred to stabilize kernel-exported API for mountd et al. 500017 5.0-CURRENT after addition of CPUTYPE make variable for controlling CPU-specific optimizations. 500018 5.0-CURRENT after moving machine/ioctl_fd.h to sys/fdcio.h 500019 5.0-CURRENT after locale names renaming. 500020 5.0-CURRENT after Bzip2 import. 500021 5.0-CURRENT after SSE support. 500022 Note that 2.2-STABLE sometimes identifies itself as “2.2.5-STABLE” after the 2.2.5-RELEASE. The pattern used to be year followed by the month, but we decided to change it to a more straightforward major/minor system starting from 2.2. This is because the parallel development on several branches made it infeasible to classify the releases simply by their real release dates. If you are making a port now, you do not have to worry about old -CURRENTs; they are listed here just for your reference. In the hundreds of ports that have been done, there have only been one or two cases where __FreeBSD__ should have been used. Just because an earlier port screwed up and used it in the wrong place does not mean you should do so too. Writing something after <filename>bsd.port.mk</filename> Do not write anything after the .include <bsd.port.mk> line. It usually can be avoided by including bsd.port.pre.mk somewhere in the middle of your Makefile and bsd.port.post.mk at the end. You need to include either the pre.mk/post.mk pair or bsd.port.mk only; do not mix these two. bsd.port.pre.mk only defines a few variables, which can be used in tests in the Makefile, bsd.port.post.mk defines the rest. Here are some important variables defined in bsd.port.pre.mk (this is not the complete list, please read bsd.port.mk for the complete list). Variable Description ARCH The architecture as returned by uname -m (e.g., i386) OPSYS The operating system type, as returned by uname -s (e.g., FreeBSD) OSREL The release version of the operating system (e.g., 2.1.5 or 2.2.7) OSVERSION The numeric version of the operating system, same as __FreeBSD_version. PORTOBJFORMAT The object format of the system (aout or elf) LOCALBASE The base of the “local” tree (e.g., /usr/local/) X11BASE The base of the “X11” tree (e.g., /usr/X11R6) PREFIX Where the port installs itself (see more on PREFIX). If you have to define the variables USE_IMAKE, USE_X_PREFIX, or MASTERDIR, do so before including bsd.port.pre.mk. Here are some examples of things you can write after bsd.port.pre.mk: # no need to compile lang/perl5 if perl5 is already in system .if ${OSVERSION} > 300003 BROKEN= perl is in system .endif # only one shlib version number for ELF .if ${PORTOBJFORMAT} == "elf" TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR} .else TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR} .endif # software already makes link for ELF, but not for a.out post-install: .if ${PORTOBJFORMAT} == "aout" ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so .endif Install additional documentation If your software has some documentation other than the standard man and info pages that you think is useful for the user, install it under PREFIX/share/doc. This can be done, like the previous item, in the post-install target. Create a new directory for your port. The directory name should reflect what the port is. This usually means PORTNAME. However, if you think the user might want different versions of the port to be installed at the same time, you can use the whole PKGNAME. Make the installation dependent to the variable NOPORTDOCS so that users can disable it in /etc/make.conf, like this: post-install: .if !defined(NOPORTDOCS) ${MKDIR} ${PREFIX}/share/doc/xv ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv .endif Do not forget to add them to pkg-plist too. (Do not worry about NOPORTDOCS here; there is currently no way for the packages to read variables from /etc/make.conf.) You can also use the pkg-message file to display messages upon installation. See the using pkg-message section for details. pkg-message does not need to be added to pkg-plist. <makevar>DIST_SUBDIR</makevar> Do not let your port clutter /usr/ports/distfiles. If your port requires a lot of files to be fetched, or contains a file that has a name that might conflict with other ports (e.g., Makefile), set DIST_SUBDIR to the name of the port (${PORTNAME} or ${PKGNAMEPREFIX}${PORTNAME} should work fine). This will change DISTDIR from the default /usr/ports/distfiles to /usr/ports/distfiles/DIST_SUBDIR, and in effect puts everything that is required for your port into that subdirectory. It will also look at the subdirectory with the same name on the backup master site at ftp.FreeBSD.org. (Setting DISTDIR explicitly in your Makefile will not accomplish this, so please use DIST_SUBDIR.) This does not affect the MASTER_SITES you define in your Makefile. Package information Do include package information, i.e. pkg-comment, pkg-descr, and pkg-plist. Note that these files are not used only for packaging anymore, and are mandatory now, even if NO_PACKAGE is set. RCS strings Do not put RCS strings in patches. CVS will mangle them when we put the files into the ports tree, and when we check them out again, they will come out different and the patch will fail. RCS strings are surrounded by dollar ($) signs, and typically start with $Id or $RCS. Recursive diff Using the recurse () option to diff to generate patches is fine, but please take a look at the resulting patches to make sure you do not have any unnecessary junk in there. In particular, diffs between two backup files, Makefiles when the port uses Imake or GNU configure, etc., are unnecessary and should be deleted. If you had to edit configure.in and run autoconf to regenerate configure, do not take the diffs of configure (it often grows to a few thousand lines!); define USE_AUTOCONF=yes and take the diffs of configure.in. Also, if you had to delete a file, then you can do it in the post-extract target rather than as part of the patch. Once you are happy with the resulting diff, please split it up into one source file per patch file. <makevar>PREFIX</makevar> Do try to make your port install relative to PREFIX. (The value of this variable will be set to LOCALBASE (default /usr/local), unless USE_X_PREFIX or USE_IMAKE is set, in which case it will be X11BASE (default /usr/X11R6).) Not hard-coding /usr/local or /usr/X11R6 anywhere in the source will make the port much more flexible and able to cater to the needs of other sites. For X ports that use imake, this is automatic; otherwise, this can often be done by simply replacing the occurrences of /usr/local (or /usr/X11R6 for X ports that do not use imake) in the various scripts/Makefiles in the port to read PREFIX, as this variable is automatically passed down to every stage of the build and install processes. Make sure your application isn't installing things in /usr/local instead of PREFIX. A quick test for this is to do this is: &prompt.root; make clean; make package PREFIX=/var/tmp/port-name If anything is installed outside of PREFIX, making the package creation process will complain that it can't find the files. This does not test for the existence of internal references, or correct use of LOCALBASE for references to files from other ports. Testing the installation in /var/tmp/port-name to do that that while you have it installed would do that. Do not set USE_X_PREFIX unless your port truly requires it (i.e., it links against X libs or it needs to reference files in X11BASE). The variable PREFIX can be reassigned in your Makefile or in the user's environment. However, it is strongly discouraged for individual ports to set this variable explicitly in the Makefiles. Also, refer to programs/files from other ports with the variables mentioned above, not explicit pathnames. For instance, if your port requires a macro PAGER to be the full pathname of less, use the compiler flag: -DPAGER=\"${PREFIX}/bin/less\" or -DPAGER=\"${LOCALBASE}/bin/less\" if this is an X port, instead of -DPAGER=\"/usr/local/bin/less\". This way it will have a better chance of working if the system administrator has moved the whole `/usr/local' tree somewhere else. Subdirectories Try to let the port put things in the right subdirectories of PREFIX. Some ports lump everything and put it in the subdirectory with the port's name, which is incorrect. Also, many ports put everything except binaries, header files and manual pages in the a subdirectory of lib, which does not bode well with the BSD paradigm. Many of the files should be moved to one of the following: etc (setup/configuration files), libexec (executables started internally), sbin (executables for superusers/managers), info (documentation for info browser) or share (architecture independent files). See man &man.hier.7; for details, the rules governing /usr pretty much apply to /usr/local too. The exception are ports dealing with USENET “news”. They may use PREFIX/news as a destination for their files. Cleaning up empty directories Do make your ports clean up after themselves when they are deinstalled. This is usually accomplished by adding @dirrm lines for all directories that are specifically created by the port. You need to delete subdirectories before you can delete parent directories. : lib/X11/oneko/pixmaps/cat.xpm lib/X11/oneko/sounds/cat.au : @dirrm lib/X11/oneko/pixmaps @dirrm lib/X11/oneko/sounds @dirrm lib/X11/oneko However, sometimes @dirrm will give you errors because other ports also share the same subdirectory. You can call rmdir from @unexec to remove only empty directories without warning. @unexec rmdir %D/share/doc/gimp 2>/dev/null || true This will neither print any error messages nor cause pkg_delete to exit abnormally even if PREFIX/share/doc/gimp is not empty due to other ports installing some files in there. UIDs If your port requires a certain user to be on the installed system, let the pkg-install script call pw to create it automatically. Look at net/cvsup-mirror for an example. If your port must use the same user/group ID number when it is installed as a binary package as when it was compiled, then you must choose a free UID from 50 to 99 and register it below. Look at japanese/Wnn for an example. Make sure you do not use a UID already used by the system or other ports. This is the current list of UIDs between 50 and 99. majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent pop:*:68:6:Post Office Owner (popper):/nonexistent:/nonexistent wnn:*:69:7:Wnn:/nonexistent:/nonexistent ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent qmaill:*:83:81:QMail user:/var/qmail:/nonexistent qmaild:*:82:81:QMail user:/var/qmail:/nonexistent qmailq:*:85:82:QMail user:/var/qmail:/nonexistent qmails:*:87:82:QMail user:/var/qmail:/nonexistent qmailp:*:84:81:QMail user:/var/qmail:/nonexistent qmailr:*:86:82:QMail user:/var/qmail:/nonexistent msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent Please include a notice when you submit a port (or an upgrade) that reserves a new UID or GID in this range. This allows us to keep the list of reserved IDs up to date. Do things rationally The Makefile should do things simply and reasonably. If you can make it a couple of lines shorter or more readable, then do so. Examples include using a make .if construct instead of a shell if construct, not redefining do-extract if you can redefine EXTRACT* instead, and using GNU_CONFIGURE instead of CONFIGURE_ARGS += --prefix=${PREFIX}. Respect <makevar>CFLAGS</makevar> The port should respect the CFLAGS variable. If it does not, please add NO_PACKAGE=ignores cflags to the Makefile. An example of a Makefile respecting the CFLAGS variable follows. Note the +=: CFLAGS += -Wall -Werror Here is an example which does not respect the CFLAGS variable: CFLAGS = -Wall -Werror The CFLAGS variable is defined on FreeBSD systems in /etc/make.conf. The first example appends additional flags to the CFLAGS variable, preserving any system-wide definitions. The second example clobbers anything previously defined. Configuration files If your port requires some configuration files in PREFIX/etc, do not just install them and list them in pkg-plist. That will cause pkg_delete to delete files carefully edited by the user and a new installation to wipe them out. Instead, install sample files with a suffix (filename.sample will work well) and print out a message pointing out that the user has to copy and edit the file before the software can be made to work. Portlint Do check your work with portlint before you submit or commit it. Feedback Do send applicable changes/patches to the original author/maintainer for inclusion in next release of the code. This will only make your job that much easier for the next release. <filename>README.html</filename> Do not include the README.html file. This file is not part of the cvs collection but is generated using the make readme command. Miscellanea The files pkg-comment, pkg-descr, and pkg-plist should each be double-checked. If you are reviewing a port and feel they can be worded better, do so. Do not copy more copies of the GNU General Public License into our system, please. Please be careful to note any legal issues! Do not let us illegally distribute software! If you are stuck… Do look at existing examples and the bsd.port.mk file before asking us questions! ;-) Do ask us questions if you have any trouble! Do not just beat your head against a wall! :-) A Sample <filename>Makefile</filename> Here is a sample Makefile that you can use to create a new port. Make sure you remove all the extra comments (ones between brackets)! It is recommended that you follow this format (ordering of variables, empty lines between sections, etc.). This format is designed so that the most important information is easy to locate. We recommend that you use portlint to check the Makefile. [the header...just to make it easier for us to identify the ports.] # New ports collection makefile for: xdvi [the "version required" line is only needed when the PORTVERSION variable is not specific enough to describe the port.] # Date created: 26 May 1995 [this is the person who did the original port to FreeBSD, in particular, the person who wrote the first version of this Makefile. Remember, this should not be changed when upgrading the port later.] # Whom: Satoshi Asami <asami@FreeBSD.org> # # $FreeBSD$ [ ^^^^^^^^^ This will be automatically replaced with RCS ID string by CVS when it is committed to our repository. If upgrading a port, do not alter this line back to "$FreeBSD$". CVS deals with it automatically.] # [section to describe the port itself and the master site - PORTNAME and PORTVERSION are always first, followed by CATEGORIES, and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that. Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then EXTRACT_ONLY, as necessary.] PORTNAME= xdvi PORTVERSION= 18.2 CATEGORIES= print [do not forget the trailing slash ("/")! if you are not using MASTER_SITE_* macros] MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications PKGNAMEPREFIX= ja- DISTNAME= xdvi-pl18 [set this if the source is not in the standard ".tar.gz" form] EXTRACT_SUFX= .tar.Z [section for distributed patches -- can be empty] PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz [maintainer; *mandatory*! This is the person (preferably with commit privileges) whom a user can contact for questions and bug reports - this person should be the porter or someone who can forward questions to the original porter reasonably promptly. If you really do not want to have your address here, set it to "ports@FreeBSD.org".] MAINTAINER= asami@FreeBSD.org [dependencies -- can be empty] RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm [this section is for other standard bsd.port.mk variables that do not belong to any of the above] [If it asks questions during configure, build, install...] IS_INTERACTIVE= yes [If it extracts to a directory other than ${DISTNAME}...] WRKSRC= ${WRKDIR}/xdvi-new [If the distributed patches were not made relative to ${WRKSRC}, you may need to tweak this] PATCH_DIST_STRIP= -p1 [If it requires a "configure" script generated by GNU autoconf to be run] GNU_CONFIGURE= yes [If it requires GNU make, not /usr/bin/make, to build...] USE_GMAKE= yes [If it is an X application and requires "xmkmf -a" to be run...] USE_IMAKE= yes [et cetera.] [non-standard variables to be used in the rules below] MY_FAVORITE_RESPONSE= "yeah, right" [then the special rules, in the order they are called] pre-fetch: i go fetch something, yeah post-patch: i need to do something after patch, great pre-install: and then some more stuff before installing, wow [and then the epilogue] .include <bsd.port.mk> Automated package list creation First, make sure your port is almost complete, with only pkg-plist missing. Create an empty pkg-plist. &prompt.root; touch pkg-plist Next, create a new set of directories which your port can be installed, and install any dependencies. &prompt.root; mtree -U -f /etc/mtree/BSD.local.dist -d -e -p /var/tmp/port-name &prompt.root; make depends PREFIX=/var/tmp/port-name Store the directory structure in a new file. &prompt.root; (cd /var/tmp/port-name && find * -type d) > OLD-DIRS If your port honors PREFIX (which it should) you can then install the port and create the package list. &prompt.root; make install PREFIX=/var/tmp/port-name &prompt.root; (cd /var/tmp/port-name && find * \! -type d) > pkg-plist You must also add any newly created directories to the packing list. &prompt.root; (cd /var/tmp/port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm #' >> pkg-plist Finally, you need to tidy up the packing list by hand; it isn't all automated. Manual pages should be listed in the port's Makefile under MANn, and not in the package list. User configuration files should be removed, or installed as filename.sample. The info/dir file should not be listed and appropriate install-info lines should be added as noted in the info files section. Any libraries installed by the port should be listed as specified in the shared libraries section. Package Names The following are the conventions you should follow in naming your packages. This is to have our package directory easy to scan, as there are already lots and lots of packages and users are going to turn away if they hurt their eyes! The package name should look like language_region-name-compiled.specifics-version.numbers. The package name is defined as ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure to set the variables to conform to that format. FreeBSD strives to support the native language of its users. The language- part should be a two letter abbreviation of the natural language defined by ISO-639 if the port is specific to a certain language. Examples are ja for Japanese, ru for Russian, vi for Vietnamese, zh for Chinese, ko for Korean and de for German. If the port is specific to a certain region within the language area, add the two letter country code as well. Examples are en_US for US English and fr_CH for Swiss French. The language- part should be set in the PKGNAMEPREFIX variable. The first letter of name part should be lowercase. (The rest of the name can contain capital letters, so use your own discretion when you are converting a software name that has some capital letters in it.) There is a tradition of naming Perl 5 modules by prepending p5- and converting the double-colon separator to a hyphen; for example, the Data::Dumper module becomes p5-Data-Dumper. If the software in question has numbers, hyphens, or underscores in its name, you may include them as well (like kinput2). If the port can be built with different hardcoded defaults (usually part of the directory name in a family of ports), the -compiled.specifics part should state the compiled-in defaults (the hyphen is optional). Examples are papersize and font units. The compiled.specifics part should be set in the PKGNAMESUFFIX variable. The version string should follow a dash (-) and be a period-separated list of integers and single lowercase alphabetics. In particular, it is not permissible to have another dash inside the version string. The only exception is the string pl (meaning `patchlevel'), which can be used only when there are no major and minor version numbers in the software. If the software version has strings like "alpha", "beta", "rc", or "pre", take the first letter and put it immediately after a period. If the version string continues after those names, the numbers should follow the single alphabet without an extra period between them. The idea is to make it easier to sort ports by looking at the version string. In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the yyyy.mm.dd format, not dd.mm.yyyy or the non-Y2K compliant yy.mm.dd format. Here are some (real) examples on how to convert the name as called by the software authors to a suitable package name: Distribution Name PKGNAMEPREFIX PORTNAME PKGNAMESUFFIX PORTVERSION Reason mule-2.2.2 (empty) mule (empty) 2.2.2 No changes required XFree86-3.3.6 (empty) XFree86 (empty) 3.3.6 No changes required EmiClock-1.0.2 (empty) emiclock (empty) 1.0.2 No uppercase names for single programs rdist-1.3alpha (empty) rdist (empty) 1.3.a No strings like alpha allowed es-0.9-beta1 (empty) es (empty) 0.9.b1 No strings like beta allowed mailman-2.0rc3 (empty) mailman (empty) 2.0.r3 No strings like rc allowed v3.3beta021.src (empty) tiff (empty) 3.3 What the heck was that anyway? tvtwm (empty) tvtwm (empty) pl11 Version string always required piewm (empty) piewm (empty) 1.0 Version string always required xvgr-2.10pl1 (empty) xvgr (empty) 2.10.1 pl allowed only when no major/minor version numbers gawk-2.15.6 ja- gawk (empty) 2.15.6 Japanese language version psutils-1.13 (empty) psutils -letter 1.13 Papersize hardcoded at package build time pkfonts (empty) pkfonts 300 1.0 Package for 300dpi fonts If there is absolutely no trace of version information in the original source and it is unlikely that the original author will ever release another version, just set the version string to 1.0 (like the piewm example above). Otherwise, ask the original author or use the date string (yyyy.mm.dd) as the version. Categories As you already know, ports are classified in several categories. But for this to work, it is important that porters and users understand what each category is for and how we decide what to put in each category. Current list of categories First, this is the current list of port categories. Those marked with an asterisk (*) are virtual categories—those that do not have a corresponding subdirectory in the ports tree. For non-virtual categories, you will find a one-line description in the pkg/COMMENT file in that subdirectory (e.g., archivers/pkg/COMMENT). Category Description afterstep* Ports to support the AfterStep window manager. archivers Archiving tools. astro Astronomical ports. audio Sound support. benchmarks Benchmarking utilities. biology Biology-related software. cad Computer aided design tools. chinese Chinese language support. comms Communication software. Mostly software to talk to your serial port. converters Character code converters. databases Databases. deskutils Things that used to be on the desktop before computers were invented. devel Development utilities. Do not put libraries here just because they are libraries—unless they truly do not belong anywhere else, they should not be in this category. editors General editors. Specialized editors go in the section for those tools (e.g., a mathematical-formula editor will go in math). elisp* Emacs-lisp ports. emulators Emulators for other operating systems. Terminal emulators do not belong here—X-based ones should go to x11 and text-based ones to either comms or misc, depending on the exact functionality. french French language support. ftp FTP client and server utilities. If your port speaks both FTP and HTTP, put it in ftp with a secondary category of www. games Games. german German language support. gnome* Ports from the GNU Object Model Environment (GNOME) Project. graphics Graphics utilities. hebrew Hebrew language support. irc Internet Relay Chat utilities. ipv6* IPv6 related software. japanese Japanese language support. java Java language support. kde* Ports from the K Desktop Environment (KDE) Project. korean Korean language support. lang Programming languages. linux* Linux applications and support utilities. mail Mail software. math Numerical computation software and other utilities for mathematics. mbone MBone applications. misc Miscellaneous utilities—basically things that do not belong anywhere else. This is the only category that should not appear with any other non-virtual category. If you have misc with something else in your CATEGORIES line, that means you can safely delete misc and just put the port in that other subdirectory! net Miscellaneous networking software. news USENET news software. offix* Ports from the OffiX suite. palm Software support for the 3Com Palm(tm) series. perl5* Ports that require perl version 5 to run. picobsd Ports to support PicoBSD. plan9* Various programs from Plan9. print Printing software. Desktop publishing tools (previewers, etc.) belong here too. python* Software written in python. ruby* Software written in ruby. russian Russian language support. science Scientific ports that don't fit into other categories such as astro, biology and math. security Security utilities. shells Command line shells. sysutils System utilities. tcl76* Ports that use Tcl version 7.6 to run. tcl80* Ports that use Tcl version 8.0 to run. tcl81* Ports that use Tcl version 8.1 to run. tcl82* Ports that use Tcl version 8.2 to run. textproc Text processing utilities. It does not include desktop publishing tools, which go to print/. tk42* Ports that use Tk version 4.2 to run. tk80* Ports that use Tk version 8.0 to run. tk81* Ports that use Tk version 8.1 to run. tk82* Ports that use Tk version 8.2 to run. tkstep80* Ports that use TkSTEP version 8.0 to run. ukrainian Ukrainian language support. vietnamese Vietnamese language support. windowmaker* Ports to support the WindowMaker window manager www Software related to the World Wide Web. HTML language support belongs here too. x11 The X window system and friends. This category is only for software that directly supports the window system. Do not put regular X applications here. If your port is an X application, define USE_XLIB (implied by USE_IMAKE) and put it in the appropriate categories. Also, many of them go into other x11-* categories (see below). x11-clocks X11 clocks. x11-fm X11 file managers. x11-fonts X11 fonts and font utilities. x11-servers X11 servers. x11-toolkits X11 toolkits. x11-wm X11 window managers. zope* Zope support. Choosing the right category As many of the categories overlap, you often have to choose which of the categories should be the primary category of your port. There are several rules that govern this issue. Here is the list of priorities, in decreasing order of precedence. Language specific categories always come first. For example, if your port installs Japanese X11 fonts, then your CATEGORIES line would read japanese x11-fonts. Specific categories win over less-specific ones. For instance, an HTML editor should be listed as www editors, not the other way around. Also, you do not need to list net when the port belongs to any of irc, mail, mbone, news, security, or www. x11 is used as a secondary category only when the primary category is a natural language. In particular, you should not put x11 in the category line for X applications. Emacs modes should be placed in the same ports category as the application supported by the mode, not in editors. For example, an Emacs mode to edit source files of some programming language should go into lang. If your port truly does not belong anywhere else, put it in misc. If you are not sure about the category, please put a comment to that effect in your send-pr submission so we can discuss it before we import it. If you are a committer, send a note to the &a.ports; so we can discuss it first—too often new ports are imported to the wrong category only to be moved right away. Changes to this document and the ports system If you maintain a lot of ports, you should consider following the &a.ports;. Important changes to the way ports work will be announced there. You can always find more detailed information on the latest changes by looking at the bsd.port.mk CVS log. That is It, Folks! Boy, this sure was a long tutorial, wasn't it? Thanks for following us to here, really. Now that you know how to do a port, have at it and convert everything in the world into ports! That is the easiest way to start contributing to the FreeBSD Project! :-)