1.2.1. What is FreeBSD?

In general, FreeBSD is a state-of-the-art operating system based on 4.4BSD-Lite2. It runs on computer systems based on the Intel architecture (x86), and also the DEC Alpha architecture.

FreeBSD is used to power some of the biggest sites on the Internet, including:

• Yahoo!

• Hotmail

• Apache

• Be, Inc.

• Blue Mountain Arts

• Pair Networks

• Whistle Communications

• Walnut Creek CDROM

and many more.

1.2.2. What can FreeBSD do?

FreeBSD has many noteworthy features. Some of these are:

• Preemptive multitasking with dynamic priority adjustment to ensure smooth and fair sharing of the computer between applications and users, even under the heaviest of loads.

• Multi-user facilities which allow many people to use a FreeBSD system simultaneously for a variety of things. This means, for example, that system peripherals such as printers and tape drives are properly shared between all users on the system or the network and that individual resource limits can be placed on users or groups of users, protecting critical system resources from over-use.

• Strong TCP/IP networking with support for industry standards such as SLIP, PPP, NFS, DHCP, and NIS. This means that your FreeBSD machine can inter-operate easily with other systems as well as act as an enterprise server, providing vital functions such as NFS (remote file access) and e-mail services or putting your organization on the Internet with WWW, FTP, routing and firewall (security) services.

• Memory protection ensures that applications (or users) cannot interfere with each other. One application crashing will not affect others in any way.

• FreeBSD is a 32-bit operating system (64-bit on the Alpha) and was designed as such from the ground up.

• The industry standard X Window System (X11R6) provides a graphical user interface (GUI) for the cost of a common VGA card and monitor and comes with full sources.

• Binary compatibility with many programs built for Linux, SCO, SVR4, BSDI and NetBSD.

• Thousands of ready-to-run applications are available from the FreeBSD ports and packages collection. Why search the net when you can find it all right here?

• Thousands of additional and easy-to-port applications are available on the Internet. FreeBSD is source code compatible with most popular commercial Unix systems and thus most applications require few, if any, changes to compile.

• Demand paged virtual memory and ``merged VM/buffer cache'' design efficiently satisfies applications with large appetites for memory while still maintaining interactive response to other users.

• SMP support for machines with multiple CPUs (Intel only).

• A full complement of C, C++, Fortran, and Perl development tools. Many additional languages for advanced research and development are also available in the ports and packages collection.

• Source code for the entire system means you have the greatest degree of control over your environment. Why be locked into a proprietary solution at the mercy of your vendor when you can have a truly Open System?

• Extensive on-line documentation.

• And many more!

FreeBSD is based on the 4.4BSD-Lite2 release from Computer Systems Research Group (CSRG) at the University of California at Berkeley, and carries on the distinguished tradition of BSD systems development. In addition to the fine work provided by CSRG, the FreeBSD Project has put in many thousands of hours in fine tuning the system for maximum performance and reliability in real-life load situations. As many of the commercial giants struggle to field PC operating systems with such features, performance and reliability, FreeBSD can offer them now!

The applications to which FreeBSD can be put are truly limited only by your own imagination. From software development to factory automation, inventory control to azimuth correction of remote satellite antennae; if it can be done with a commercial UNIX product then it is more than likely that you can do it with FreeBSD, too! FreeBSD also benefits significantly from the literally thousands of high quality applications developed by research centers and universities around the world, often available at little to no cost. Commercial applications are also available and appearing in greater numbers every day.

Because the source code for FreeBSD itself is generally available, the system can also be customized to an almost unheard of degree for special applications or projects, and in ways not generally possible with operating systems from most major commercial vendors. Here is just a sampling of some of the applications in which people are currently using FreeBSD:

• Internet Services: The robust TCP/IP networking built into FreeBSD makes it an ideal platform for a variety of Internet services such as:

  • FTP servers

  • World Wide Web servers (standard or secure [SSL])

  • Firewalls and NAT (``IP masquerading'') gateways.

  • Electronic Mail servers

  • USENET News or Bulletin Board Systems

  • And more...

  With FreeBSD, you can easily start out small with an inexpensive 386 class PC and upgrade all the way up to a quad-processor Xeon with RAID storage as your enterprise grows.

• Education: Are you a student of computer science or a related engineering field? There is no better way of learning about operating systems, computer architecture and networking than the hands on, under the hood experience that FreeBSD can provide. A number of freely available CAD, mathematical and graphic design packages also make it highly useful to those whose primary interest in a computer is to get other work done!

• Research: With source code for the entire system available, FreeBSD is an excellent platform for research in operating systems as well as other branches of computer science. FreeBSD's freely available nature also makes it possible for remote groups to collaborate on ideas or shared development without having to worry about special licensing agreements or limitations on what may be discussed in open forums.

• Networking: Need a new router? A name server (DNS)? A firewall to keep people out of your internal network? FreeBSD can easily turn that unused 386 or 486 PC sitting in the corner into an advanced router with sophisticated packet-filtering capabilities.

• X Window workstation: FreeBSD is a fine choice for an inexpensive X terminal solution, either using the freely available XFree86 server or one of the excellent commercial servers provided by X Inside. Unlike an X terminal, FreeBSD allows many applications to be run locally, if desired, thus relieving the burden on a central server. FreeBSD can even boot ``diskless'', making individual workstations even cheaper and easier to administer.

• Software Development: The basic FreeBSD system comes with a full complement of development tools including the renowned GNU C/C++ compiler and debugger.

FreeBSD is available in both source and binary form on CDROM and via anonymous FTP. See Obtaining FreeBSD for more details.

1.3.1. A Brief History of FreeBSD

Contributed by Jordan K. Hubbard <jkh@FreeBSD.org>.

The FreeBSD project had its genesis in the early part of 1993, partially as an outgrowth of the ``Unofficial 386BSD Patchkit'' by the patchkit's last 3 coordinators: Nate Williams, Rod Grimes and myself.

Our original goal was to produce an intermediate snapshot of 386BSD in order to fix a number of problems with it that the patchkit mechanism just was not capable of solving. Some of you may remember the early working title for the project being ``386BSD 0.5'' or ``386BSD Interim'' in reference to that fact.

386BSD was Bill Jolitz's operating system, which had been up to that point suffering rather severely from almost a year's worth of neglect. As the patchkit swelled ever more uncomfortably with each passing day, we were in unanimous agreement that something had to be done and decided to try and assist Bill by providing this interim ``cleanup'' snapshot. Those plans came to a rude halt when Bill Jolitz suddenly decided to withdraw his sanction from the project without any clear indication of what would be done instead.

It did not take us long to decide that the goal remained worthwhile, even without Bill's support, and so we adopted the name ``FreeBSD'', coined by David Greenman. Our initial objectives were set after consulting with the system's current users and, once it became clear that the project was on the road to perhaps even becoming a reality, I contacted Walnut Creek CDROM with an eye towards improving FreeBSD's distribution channels for those many unfortunates without easy access to the Internet. Walnut Creek CDROM not only supported the idea of distributing FreeBSD on CD but also went so far as to provide the project with a machine to work on and a fast Internet connection. Without Walnut Creek CDROM's almost unprecedented degree of faith in what was, at the time, a completely unknown project, it is quite unlikely that FreeBSD would have gotten as far, as fast, as it has today.

The first CDROM (and general net-wide) distribution was FreeBSD 1.0, released in December of 1993. This was based on the 4.3BSD-Lite (``Net/2'') tape from U.C. Berkeley, with many components also provided by 386BSD and the Free Software Foundation. It was a fairly reasonable success for a first offering, and we followed it with the highly successful FreeBSD 1.1 release in May of 1994.

Around this time, some rather unexpected storm clouds formed on the horizon as Novell and U.C. Berkeley settled their long-running lawsuit over the legal status of the Berkeley Net/2 tape. A condition of that settlement was U.C. Berkeley's concession that large parts of Net/2 were ``encumbered'' code and the property of Novell, who had in turn acquired it from AT&T some time previously. What Berkeley got in return was Novell's ``blessing'' that the 4.4BSD-Lite release, when it was finally released, would be declared unencumbered and all existing Net/2 users would be strongly encouraged to switch. This included FreeBSD, and the project was given until the end of July 1994 to stop shipping its own Net/2 based product. Under the terms of that agreement, the project was allowed one last release before the deadline, that release being FreeBSD 1.1.5.1.

FreeBSD then set about the arduous task of literally re-inventing itself from a completely new and rather incomplete set of 4.4BSD-Lite bits. The ``Lite'' releases were light in part because Berkeley's CSRG had removed large chunks of code required for actually constructing a bootable running system (due to various legal requirements) and the fact that the Intel port of 4.4 was highly incomplete. It took the project until November of 1994 to make this transition, at which point it released FreeBSD 2.0 to the net and on CDROM (in late December). Despite being still more than a little rough around the edges, the release was a significant success and was followed by the more robust and easier to install FreeBSD 2.0.5 release in June of 1995.

We released FreeBSD 2.1.5 in August of 1996, and it appeared to be popular enough among the ISP and commercial communities that another release along the 2.1-STABLE branch was merited. This was FreeBSD 2.1.7.1, released in February 1997 and capping the end of mainstream development on 2.1-STABLE. Now in maintenance mode, only security enhancements and other critical bug fixes will be done on this branch (RELENG_2_1_0).

FreeBSD 2.2 was branched from the development mainline (``-CURRENT'') in November 1996 as the RELENG_2_2 branch, and the first full release (2.2.1) was released in April 1997. Further releases along the 2.2 branch were done in the summer and fall of '97, the last of which (2.2.8) appeared in November 1998. The first official 3.0 release appeared in October 1998 and spelled the beginning of the end for the 2.2 branch.

The tree branched again on Jan 20, 1999, leading to the 4.0-CURRENT and 3.X-STABLE branches. From 3.X-STABLE, 3.1 was released on February 15, 1999, 3.2 on May 15, 1999, and 3.3 on September 16, 1999. The most current release on this branch is 3.4, which was released on December 20, 1999.

There was another branch on March 13, 2000, which saw the emergence of the 5.0-CURRENT and 4.X-STABLE branches. The only release from this branch so far is 4.0-RELEASE.

Long-term development projects continue to take place in the 5.0-CURRENT branch, and SNAPshot releases of 5.0 on CDROM (and, of course, on the net) are continually made available as work progresses.

1.3.2. FreeBSD Project Goals

Contributed by Jordan K. Hubbard <jkh@FreeBSD.org>.

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, I 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 Library General Public License (LGPL) comes with slightly more strings attached, though at least on the side of enforced access rather than the usual opposite. Due to the additional complexities that can evolve in the commercial use of GPL software we do, however, prefer software submitted under the more relaxed BSD copyright when it's a reasonable option to do so.

1.3.3. The FreeBSD Development Model

Contributed by Satoshi Asami <asami@FreeBSD.org>.

The development of FreeBSD is a very open and flexible process, FreeBSD being literally built from the contributions of hundreds of people around the world, as can be seen from our list of contributors. We are constantly on the lookout for new developers and ideas, and those interested in becoming more closely involved with the project need simply contact us at the FreeBSD technical discussions mailing list <freebsd-hackers@FreeBSD.org>. The FreeBSD announcements mailing list <freebsd-announce@FreeBSD.org> is also available to those wishing to make other FreeBSD users aware of major areas of work.

Useful things to know about the FreeBSD project and its development process, whether working independently or in close cooperation:

In summary, our development model is organized as a loose set of concentric circles. The centralized model is designed for the convenience of the users of FreeBSD, who are thereby provided with an easy way of tracking one central code base, not to keep potential contributors out! Our desire is to present a stable operating system with a large set of coherent application programs that the users can easily install and use, and this model works very well in accomplishing that.

All we ask of those who would join us as FreeBSD developers is some of the same dedication its current people have to its continued success!

1.3.4. The Current FreeBSD Release

FreeBSD is a freely available, full source 4.4BSD-Lite2 based release for Intel i386, i486, Pentium, Pentium Pro, Celeron, Pentium II, Pentium III (or compatible) and DEC Alpha based computer systems. It is based primarily on software from U.C. Berkeley's CSRG group, with some enhancements from NetBSD, OpenBSD, 386BSD, and the Free Software Foundation.

Since our release of FreeBSD 2.0 in late 94, the performance, feature set, and stability of FreeBSD has improved dramatically. The largest change is a revamped virtual memory system with a merged VM/file buffer cache that not only increases performance, but also reduces FreeBSD's memory footprint, making a 5MB configuration a more acceptable minimum. Other enhancements include full NIS client and server support, transaction TCP support, dial-on-demand PPP, integrated DHCP support, an improved SCSI subsystem, ISDN support, support for ATM, FDDI, Fast and Gigabit Ethernet (1000Mbit) adapters, improved support for the latest Adaptec controllers, and many hundreds of bug fixes.

We have also taken the comments and suggestions of many of our users to heart and have attempted to provide what we hope is a more sane and easily understood installation process. Your feedback on this (constantly evolving) process is especially welcome!

In addition to the base distributions, FreeBSD offers a ported software collection with thousands of commonly sought-after programs. By mid-January 2000, there were nearly 3000 ports! The list of ports ranges from http (WWW) servers, to games, languages, editors, and almost everything in between. The entire ports collection requires approximately 50MB of storage, all ports being expressed as ``deltas'' to their original sources. This makes it much easier for us to update ports, and greatly reduces the disk space demands made by the older 1.0 ports collection. To compile a port, you simply change to the directory of the program you wish to install, type make install, and let the system do the rest. The full original distribution for each port you build is retrieved dynamically off the CDROM or a local FTP site, so you need only enough disk space to build the ports you want. Almost every port is also provided as a pre-compiled ``package'', which can be installed with a simple command (pkg_add) by those who do not wish to compile their own ports from source.

A number of additional documents which you may find very helpful in the process of installing and using FreeBSD may now also be found in the /usr/share/doc directory on any machine running FreeBSD 2.1 or later. You may view the locally installed manuals with any HTML capable browser using the following URLs:

You can also view the master (and most frequently updated) copies at http://www.FreeBSD.org/.

The core of FreeBSD does not contain DES code which would inhibit its being exported outside the United States. There is an add-on package to the core distribution, for use only in the United States, which contains the programs that normally use DES. The auxiliary packages provided separately can be used by anyone. A freely (from outside the U.S.) exportable European distribution of DES for our non-U.S. users also exists and is described in the FreeBSD FAQ.

If password security for FreeBSD is all you need, and you have no requirement for copying encrypted passwords from different hosts (Suns, DEC machines, etc) into FreeBSD password entries, then FreeBSD's MD5 based security may be all you require! We feel that our default security model is more than a match for DES, and avoids dealing with any messy export issues. If you are outside (or even inside) the U.S., give it a try!

2.2.1. 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.. The list should include their IRQs and IO port addresses.

    # mount /cdrom

    # umount /cdrom

    ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent

    # fdformat -f 1440 fd0.1440
    # disklabel -w -r fd0.1440 floppy3
    # newfs -t 2 -u 18 -l 1 -i 65536 /dev/rfd0

    C:\> md c:\FreeBSD
    C:\> xcopy e:\bin c:\FreeBSD\bin\ /s
    C:\> xcopy e:\manpages c:\FreeBSD\manpages\ /s

    # cd /freebsd/distdir
    # tar cvf /dev/rwt0 dist1 ... dist2

    ftp://209.55.82.20/pub/FreeBSD/4.0-RELEASE

2.2.2. 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 on the boot floppy for a list of possible solutions.

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 FreeBSD documentation project mailing list <freebsd-doc@FreeBSD.org>. 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:

1. 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 on the floppy for possible causes.

2. 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.

3. Select the Options item and set any special preferences you may have.

4. 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.

5. 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.

2.3.1. 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.

  Note: 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.

• 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 CD-ROM 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

  Note: 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 CD-ROM interface (all models)

2.3.2. 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'' EN1027D (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 (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

2.3.3. 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

• Logictech 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)

2.3.4. ISDN (European DSS1 [Q.921/Q.931] protocol)

• 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)

2.3.5. Sound Devices

The following soundcards or codecs are supported (devices marked 'experimental' are only supported in FreeBSD-CURRENT and might work only unstably):

• 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)

2.3.6. 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)

  Note: 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.

FreeBSD currently does NOT support IBM's microchannel (MCA) bus.

2.4.1. 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.

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.

2.4.2. MS-DOS User's Questions and Answers

Many users wish to install FreeBSD on PCs inhabited by MS-DOS. Here are some commonly asked questions about installing FreeBSD on such systems.

    # mount -t msdos /dev/ad0s5 /dos_d

3.4.1. Changing your shell

The easiest way to change your shell is to use the chsh command. Running chsh will place you into the editor that is in your EDITOR environment variable; if it is not set, you will be placed in vi. Change the ``Shell:'' line accordingly.

You can also give chsh the -s option; this will set your shell for you, without requiring you to enter an editor. For example, if you wanted to change your shell to bash, the following should do the trick:

    % chsh -s /usr/local/bin/bash

Running chsh with no parameters and editing the shell from there would work also.

3.6.1. Manual pages

The most comprehensive documentation on FreeBSD is in the form of man pages. Nearly every program on the system comes with a short reference manual explaining the basic operation and various arguments. These manuals can be viewed with the man command. Use of the man command is simple:

% man command

command is the name of the command you wish to learn about. For example, to learn more about ls command type:

% man ls

The online manual is divided up into numbered sections:

1. User commands.

2. System calls and error numbers.

3. Functions in the C libraries.

4. Device drivers.

5. File formats.

6. Games and other diversions.

7. Miscellaneous information.

8. System maintenance and operation commands.

9. Kernel developers.

In some cases, the same topic may appear in more than one section of the online manual. For example, there is a chmod user command and a chmod() system call. In this case, you can tell the man command which one you want by specifying the section:

% man 1 chmod

This will display the manual page for the user command chmod. References to a particular section of the online manual are traditionally placed in parenthesis in written documentation, so chmod(1) refers to the chmod user command and chmod(2) refers to the system call.

This is fine if you know the name of the command and simply wish to know how to use it, but what if you cannot recall the command name? You can use man to search for keywords in the command descriptions by using the -k switch:

% man -k mail

With this command you will be presented with a list of commands that have the keyword ``mail'' in their descriptions. This is actually functionally equivalent to using the apropos command.

So, you are looking at all those fancy commands in /usr/bin but do not have the faintest idea what most of them actually do? Simply do a % cd /usr/bin; man -f * or % cd /usr/bin; whatis * which does the same thing.

3.6.2. GNU Info Files

FreeBSD includes many applications and utilities produced by the Free Software Foundation (FSF). In addition to man pages, these programs come with more extensive hypertext documents called info files which can be viewed with the info command or, if you installed emacs, the info mode of emacs.

To use the info(1) command, simply type:

% info

For a brief introduction, type h. For a quick command reference, type ?.

4.2.1. Installing Ports

The first thing that should be explained when it comes to the Ports collection is what is actually meant by a ``skeleton''. In a nutshell, a port skeleton is a minimal set of files that are needed for a program to compile and install cleanly on FreeBSD. Each port skeleton includes:

• A Makefile. The Makefile contains various statements that specify how the application should be compiled and where it should be installed on your system

• A files directory. The files directory contains a file named md5. This file is named after the MD5 algorithm used to determine ports checksums. A checksum is a number generated by adding up all the data in the file you want to check. If any characters change, the checksum will differ from the original and an error message will be displayed so you are able to investigate the changes.

  The files directory can also contain other files that are required by the port but do not belong elsewhere in the directory structure.

• A patches directory. This directory contains patches to make the program compile and install on your FreeBSD system. Patches are basically small files that specify changes to particular files. They are in plain text format, and basically say ``Remove line 10'' or ``Change line 26 to this ...''. Patches are also known as ``diffs'' because they are generated by the diff program.

• A pkg directory. This directory normally contains three files. Occasionally, there will be more than three, but it depends on the port. Most only require three. The files are:

  • COMMENT. This is a one-line description of the program.

  • DESCR. This is a more detailed, often multiple-line, description of the program.

  • PLIST. This is a list of all the files that will be installed by the port. It also tells the ports system what files to remove upon deinstallation.

Now that you have enough background information to know what the Ports collection is used for, you are ready to install your first port. There are two ways this can be done, and each is explained below.

Before we get into that however, you will need to choose a port to install. There are a few ways to do this, with the easiest method being the ports listing on the FreeBSD web site. You can browse through the ports listed there or use the search function on the site. Each port also includes a description so you can read a bit about each port before deciding to install it.

Another method is to use the whereis command. To use whereis, simply type ``whereis <program you want to install>'' at the prompt, and if it is found on your system, you will be told where it is, like so:

    # whereis xchat
    xchat: /usr/ports/irc/xchat
    #

This tells us that xchat (an irc client) can be found in the /usr/ports/irc/xchat directory.

Yet another way of finding a particular port is by using the Ports collection's built-in search mechanism. To use the search feature, you will need to be in the /usr/ports directory. Once in that directory, run make search key=program-name where ``program-name'' is the name of the program you want to find. For example, if you were looking for xchat:

    # cd /usr/ports
    # make search key=xchat
    Port:   xchat-1.3.8
    Path:   /usr/ports/irc/xchat
    Info:   An X11 IRC client using the GTK+ toolkit, and optionally, GNOME
    Maint:  jim@FreeBSD.org
    Index:  irc
    B-deps: XFree86-3.3.5 bzip2-0.9.5d gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gmake-3.77 gtk-1.2.6
            imlib-1.9.8 jpeg-6b png-1.0.3 tiff-3.5.1
    R-deps: XFree86-3.3.5 gettext-0.10.35 giflib-4.1.0 glib-1.2.6 gtk-1.2.6 imlib-1.9.8 jpeg-6b
            png-1.0.3 tiff-3.5.1

The part of the output you want to pay particular attention to is the ``Path:'' line, since that tells you where to find it. The other information provided is not needed in order to install the port directly, so it will not be covered here.

Now that you have found a port you would like to install, you are ready to do the actual installation.

    # cd /usr/ports/irc/xchat

    # make
    >> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system.
    >> Attempting to fetch from file:/cdrom/ports/distfiles/.
    ===>  Extracting for xchat-1.3.8
    >> Checksum OK for xchat-1.3.8.tar.bz2.
    ===>   xchat-1.3.8 depends on executable: bzip2 - found
    ===>   xchat-1.3.8 depends on executable: gmake - found
    ===>   xchat-1.3.8 depends on shared library: gtk12.2 - found
    ===>   xchat-1.3.8 depends on shared library: Imlib.5 - found
    ===>   xchat-1.3.8 depends on shared library: X11.6 - found
    ===>  Patching for xchat-1.3.8
    ===>  Applying FreeBSD patches for xchat-1.3.8
    ===>  Configuring for xchat-1.3.8
    ...
    [configure output snipped]
    ...
    ===>  Building for xchat-1.3.8
    ...
    [compilation snipped]
    ...
    #

    # make install
    ===>  Installing for xchat-1.3.8
    ===>   xchat-1.3.8 depends on shared library: gtk12.2 - found
    ===>   xchat-1.3.8 depends on shared library: Imlib.5 - found
    ===>   xchat-1.3.8 depends on shared library: X11.6 - found
    ...
    [install routines snipped]
    ...
    ===>   Generating temporary packing list
    ===>   Installing xchat docs in /usr/X11R6/share/doc/xchat
    ===>   Registering installation for xchat-1.3.8
    #

    # make install
    >> xchat-1.3.8.tar.bz2 doesn't seem to exist on this system.
    >> Attempting to fetch from http://xchat.org/files/v1.3/.
    Receiving xchat-1.3.8.tar.bz2 (305543 bytes): 100%
    305543 bytes transferred in 2.9 seconds  (102.81 Kbytes/s)
    ===>  Extracting for xchat-1.3.8
    >> Checksum OK for xchat-1.3.8.tar.bz2.
    ===>   xchat-1.3.8 depends on executable: bzip2 - found
    ===>   xchat-1.3.8 depends on executable: gmake - found
    ===>   xchat-1.3.8 depends on shared library: gtk12.2 - found
    ===>   xchat-1.3.8 depends on shared library: Imlib.5 - found
    ===>   xchat-1.3.8 depends on shared library: X11.6 - found
    ===>  Patching for xchat-1.3.8
    ===>  Applying FreeBSD patches for xchat-1.3.8
    ===>  Configuring for xchat-1.3.8
    ...
    [configure output snipped]
    ...
    ===>  Building for xchat-1.3.8
    ...
    [compilation snipped]
    ...
    ===>  Installing for xchat-1.3.8
    ===>   xchat-1.3.8 depends on shared library: gtk12.2 - found
    ===>   xchat-1.3.8 depends on shared library: Imlib.5 - found
    ===>   xchat-1.3.8 depends on shared library: X11.6 - found
    ...
    [install routines snipped]
    ...
    ===>   Generating temporary packing list
    ===>   Installing xchat docs in /usr/X11R6/share/doc/xchat
    ===>   Registering installation for xchat-1.3.8
    #

4.2.2. Removing Installed Ports

Now that you know how to install ports, you are probably wondering how to remove them, just in case you install one and later on you decide that you installed the wrong port. The next few paragraphs will cover just that.

Now we will remove our previous example (which was xchat for those of you not paying attention). As with installing ports, the first thing you must do is change to the port directory, which if you remember was /usr/ports/irc/xchat. After you change directories, you are ready to uninstall xchat. This is done with the make deinstall command (makes sense right?):

    # cd /usr/ports/irc/xchat
    # make deinstall
    ===>  Deinstalling for xchat-1.3.8
    #

That was easy enough. You have now managed to remove xchat from your system. If you would like to reinstall it, you can do so by running make reinstall from the /usr/ports/irc/xchat directory.

4.3.1. Some Questions and Answers

    % tar tvzf foobar.tar.gz
    % tar xzvf foobar.tar.gz
    % tar tvf foobar.tar
    % tar xvf foobar.tar

    # make install
    >> cku190.tar.gz doesn't seem to exist on this system.
    >> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.

    # make DISTDIR=/where/you/put/it install

    # make PORTSDIR=/u/people/guests/wurzburger/ports install

    # make PREFIX=/u/people/guests/wurzburger/local install

    # make PORTSDIR=../ports PREFIX=../local install

    # cd /usr/ports
    # make fetch

    # cd /usr/ports/directory
    # make fetch

    # cd /usr/ports/directory
    # make MASTER_SITE_OVERRIDE= \
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch

    # make CFLAGS='-O2 -fno-strength-reduce' install

    % cd /usr/ports
    % make search key=lisp

    # pkg_delete grizzle-6.5

    # cd /usr/ports/somewhere/grizzle
    # make deinstall

    # pkg_info -a | grep grizzle
    Information for grizzle-6.5:
    grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
    arcade game.

    # cd /usr/ports
    # make clean

    # cd /usr/ports
    # make install

    # cd /usr/ports
    # make -DBATCH install

    # cd /usr/ports
    # make -DIS_INTERACTIVE install

    # cd /usr/ports/somewhere/frobble
    # make extract
    # cd work/frobble-2.8
    [Apply your patches]
    # cd ../..
    # make package

4.3.2. Help! This port is broken!

If you come across a port that doesn't work for you, there are a few things you can do, including:

1. Fix it! The ``how to make a port'' section should help you do this.

2. Gripe--by email only! Send email to the maintainer of the port first. Type make maintainer or read the Makefile to find the maintainer's email address. Remember to include the name and version of the port (send the $FreeBSD: line from the Makefile) and the output leading up to the error when you email the maintainer. If you do not get a response from the maintainer, you can use send-pr to submit a bug report.

3. Forget about it. This is the easiest route--very few ports can be classified as ``essential''. There's also a good chance any problems will be fixed in the next version when the port is updated.

4. Grab the package from an ftp site near you. The ``master'' package collection is on ftp.FreeBSD.org in the packages directory, but be sure to check your local mirror first! These are more likely to work than trying to compile from source and are a lot faster as well. Use the pkg_add(1) program to install the package on your system.

5.2.1. boot0

There is actually a preceding bootblock, named boot0, which lives on the Master Boot Record, the special part of the disk that the system bootstrap looks for and runs, and it simply shows a list of possible slices to boot from.

boot0 is very simple, since the program in the MBR can only be 512 bytes in size.

It displays something like this:

    F1 DOS
    F2 FreeBSD
    F3 Linux
    F4 ??
    F5 Drive 1
    
    Default: F2

5.2.2. boot1

boot1 is found on the boot sector of the boot slice, which is where boot0, or any other program on the MBR expects to find the program to run to continue the boot process.

boot1 is very simple, since it too can only be 512 bytes in size, and knows just enough about the FreeBSD disklabel, which stores information about the slice, to find and execute boot2.

5.2.3. boot2

boot2 is slightly more sophisticated, and understands the FreeBSD filesystem enough to find files on it, and can provide a simple interface to choose the kernel or loader to run.

Since the loader is much more sophisticated, and provides a nice easy-to-use boot configuration, boot2 usually runs it, but previously it was tasked to run the kernel directly.

    >> FreeBSD/i386 BOOT
    Default: 0:wd(0,a)/kernel
    boot:

5.3.1. Loader Program Flow

During initialization, the loader will probe for a console and for disks, and figure out what disk it is booting from. It will set variables accordingly, and then the interpreter is started, and the easy-to-use commands are explained to it.

loader will then read /boot/loader.rc, which by default reads in /boot/defaults/loader.conf which sets reasonable defaults for variables and reads /boot/loader.conf for local changes to those variables. loader.rc then acts on these variables, loading whichever modules and kernel are selected.

Finally, by default, the loader issues a 10 second wait for keypresses, and boots the kernel if it is interrupted. If interrupted, the user is presented with a prompt which understands the easy-to-use command set, where the user may adjust variables, unload all modules, load modules, and then finally boot or reboot.

A more technical discussion of the process is available in loader(8)

5.3.2. Loader Built-In Commands

The easy-to-use command set comprises of:

5.3.3. Loader Examples

Here are some practical examples of loader usage.

• To simply boot your usual kernel, but in single-user mode:

      boot -s
  

• To unload your usual kernel and modules, and then load just your old (or another) kernel:

      unload
        load kernel.old
  

  You can use kernel.GENERIC to refer to the generic kernel that comes on the install disk, or kernel.old to refer to your previously installed kernel (when you've upgraded or configured your own kernel, for example).

  Note: Use the following to load your usual modules with another kernel:

      unload
      set kernel="kernel.old"
      boot-conf
  

• To load a kernel configuration script (an automated script which does the things you'd normally do in the kernel boot-time configurator):

      load -t userconfig_script
          /boot/kernel.conf
  

5.4.1. Kernel Boot Flags

Here are the more common boot flags:

5.5.1. Automatic Reboot Sequence

The automatic reboot sequence makes sure that the filesystems available on the system are consistent. If they are not, and fsck can not fix the inconsistencies, init drops the system into single-user mode for the system administrator to take care of the problems directly.

5.5.2. Single-User Mode

This mode can be reached through the automatic reboot sequence, or by the user booting with the -s or setting the boot_single variable in loader.

It can also be reached by calling shutdown without the reboot (-r) or halt (-h) options, from multi-user mode.

If the system console console is set to insecure in /etc/ttys, then the system prompts for the root password before initiating single-user mode.

    # name  getty                           type    status          comments
    #
    # This entry needed for asking password when init goes to single-user mode
    # If you want to be asked for password, change "secure" to "insecure" here
    console none                            unknown off insecure

5.5.3. Multi-User Mode

If init finds your filesystems to be in order, or once the user has finished in single-user mode, the system enters multi-user mode, in which it starts the resource configuration of the system.

6.5.1. adduser

adduser is a simple program for adding new users. It creates passwd and group entries for the user, as well as creating their home directory, copy in some default dotfiles from /usr/share/skel, and can optionally mail the user a welcome message.

To create the initial configuration file, use adduser -s -config_create. [1]Next, we configure adduser defaults, and create our first user account, since using root for normal usage is evil and nasty.

    # adduser -v
    Use option ``-silent'' if you don't want to see all warnings and questions.
    Check /etc/shells
    Check /etc/master.passwd
    Check /etc/group
    Enter your default shell: csh date no sh tcsh [sh]: tcsh
    Your default shell is: tcsh -> /usr/local/bin/tcsh
    Enter your default HOME partition: [/home]:
    Copy dotfiles from: /usr/share/skel no [/usr/share/skel]: 
    Send message from file: /etc/adduser.message no 
    [/etc/adduser.message]: no
    Do not send message
    Use passwords (y/n) [y]: y
    
    Write your changes to /etc/adduser.conf? (y/n) [n]: y
    
    Ok, let's go.
    Don't worry about mistakes. I will give you the chance later to correct any input.
    Enter username [a-z0-9_-]: jru
    Enter full name []: J. Random User
    Enter shell csh date no sh tcsh [tcsh]: 
    Enter home directory (full path) [/home/jru]: 
    Uid [1001]: 
    Enter login class: default []: 
    Login group jru [jru]: 
    Login group is ``jru''. Invite jru into other groups: guest no 
    [no]: wheel
    Enter password []: 
    Enter password again []: 
    
    Name:     jru
    Password: ****
    Fullname: J. Random User
    Uid:      1007
    Gid:      1007 (jru)
    Class:    
    Groups:   jru wheel
    HOME:     /home/jru
    Shell:    /usr/local/bin/tcsh
    OK? (y/n) [y]: y
    Added user ``jru''
    Copy files from /usr/share/skel to /home/jru
    Add another user? (y/n) [y]: n
    Goodbye!
    #

In summary, we changed the default shell to tcsh (an additional shell found in packages), and turned off the sending of a welcome mail to added users. We then saved the configuration, and then created an account for jru, and we made sure jru is in wheel group (which we'll see is important later).

6.5.2. rmuser

rmuser removes users from the system, including any traces beyond the user database.

rmuser performs the following steps:

rmuser can't be used to remove superuser accounts, since that is almost always an indication of massive destruction.

By default, an interactive mode is used, which attempts to make sure you know what you're doing.

    # rmuser jru
    Matching password entry:
    jru:*:1000:1000::0:0:J. Random User:/home/jru:/usr/local/bin/tcsh
    Is this the entry you wish to remove? y
    Remove user's home directory (/home/jru)? y
    Updating password file, updating databases, done.
    Updating group file: trusted (removing group jru -- personal group is empty) done.
    Removing user's incoming mail file /var/mail/jru: done.
    Removing files belonging to jru from /tmp: done.
    Removing files belonging to jru from /var/tmp: done.
    Removing files belonging to jru from /var/tmp/vi.recover: done.
    #

6.5.3. pw

pw is a command line utility to create, remove, modify, and display users and groups, and functions as an editor of the system user and group files.

It is designed to be useful both as a directly executed command and for use from shell scripts.

pw(8) has all the information.

6.5.4. chpass

chpass changes user database information such as passwords, shells, and personal information.

Only system administrators, as the superuser, may change other users' information and passwords with chpass.

Passed no options, besides the optional username, chpass displays an editor containing user information, and upon exit from the editor, attempts to change the information in the user database.

    #Changing user database information for jru.
    Login: jru
    Password: *
    Uid [#]: 1000
    Gid [# or name]: 1000
    Change [month day year]:
    Expire [month day year]:
    Class:
    Home directory: /home/jru
    Shell: /usr/local/bin/tcsh
    Full Name: J. Random User
    Office Location:
    Office Phone:
    Home Phone:
    Other information:

The normal user can change only a small subsection of this information, and only for themselves.

    #Changing user database information for jru.
    Shell: /usr/local/bin/tcsh
    Full Name: J. Random User
    Office Location:
    Office Phone:
    Home Phone:
    Other information:

6.5.5. passwd

passwd is the usual way to change your own password as a user, or another user's password as the superuser.

    % passwd
    Changing local password for jru.
    Old password:
    New password:
    Retype new password:
    passwd: updating the database...
    passwd: done
    
    # passwd jru
    Changing local password for jru.
    New password:
    Retype new password:
    passwd: updating the database...
    passwd: done

8.3.1. Securing the root account and staff accounts

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 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.

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 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 then having nothing at all, it is not necessarily the safest option.

An indirect way to secure the root account is to secure your staff accounts by using an alternative login access method and *'ing out the crypted password for the staff accounts. This way an intruder may be able to steal the password file but will not be able to break into any staff accounts (or, indirectly, root, even if root has a crypted password associated with it). Staff members get into their staff accounts through a secure login mechanism such as kerberos(1) or ssh(1) using a private/public key pair. When you use something like kerberos, you generally must secure the machines which run the kerberos servers and your desktop workstation. When you use a public/private key pair with ssh, you must generally secure the machine you are logging in from (typically your workstation), but you can also add an additional layer of protection to the key pair by password protecting the keypair when you create it with 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. You can thus force 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.

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).

8.3.2. Securing Root-run Servers and SUID/SGID Binaries

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 named(8). The default 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.

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 then 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 then 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.

8.3.3. 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.

8.3.4. 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).

8.3.5. 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.

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, 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.

8.3.6. 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 then 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 hackers, 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 keypairs 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 find(1) and 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 then 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 mount(8)) are what you want to look into. I would 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 accton(8)) is a relatively low-overhead feature of the operating system which I recommend using 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.

8.3.7. 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 hacker who also has access to this document.

8.3.8. Denial of Service 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.

1. Limiting server forks.

2. Limiting springboard attacks (ICMP response attacks, ping broadcast, etc.).

3. 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 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 -c, -C, and -R options. Note that spoofed-IP attacks will circumvent the -C option to inetd, so typically a combination of options must be used. Some standalone servers have self-fork-limitation parameters.

Sendmail has its -OMaxDaemonChildren 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 (-ODeliveryMode=queued) 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 -q1m, 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 -s option whenever possible, and the -a 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. I usually 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 my firewall (except for certain specific internet-accessible ports, of course).

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 then rtminexpire. There are two problems:

1. The kernel does not react quickly enough when a lightly loaded server is suddenly attacked.

2. 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 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.

8.3.9. Access Issues with Kerberos and SSH

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 -x 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 hacker 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.

8.4.1. 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:

    % 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.

8.5.1. 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:

    % 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.

8.5.2. 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:

    % 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:

    % 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.

8.5.3. Generating a single one-time password

Once you've initialized S/Key, when you login you will be presented with a prompt like this:

    % 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 my machine, the prompt would have also included the annotation (s/key required), indicating that only S/Key one-time passwords will be accepted.

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 from 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:

    % 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.

8.5.4. Generating multiple one-time passwords

Sometimes you have 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:

    % 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 -n 5 requests five keys in sequence, the 30 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.

8.5.5. 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 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.

8.6.1. 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:

    # cd /etc/kerberosIV
    # 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:

    # 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:

    # 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:

    # 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.

    # 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.

8.6.2. 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:

    # 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

8.6.3. 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.

    # 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:

    # 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:

    # mv grumble-new-srvtab srvtab
    # chmod 600 srvtab

8.6.4. 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:

    # 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

8.6.5. 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.

    # 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
    # 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:

    % 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:

    % 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:

    % passwd
    realm GRONDAR.ZA
    Old password for jane:
    New Password for jane:
    Verifying password
    New Password for jane:
    Password changed.

8.6.6. Adding su 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:

    # 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:

    # 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:

    # cat /root/.klogin
    jane.root@GRONDAR.ZA

Now try doing the su:

    % su
    Password:

and take a look at what tokens we have:

    # 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

8.6.7. 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:

    # cat /root/.klogin
    jane.root@GRONDAR.ZA

Likewise, if a user has in their own home directory lines of the form:

    % 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:

    % 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:

    % kinit
    % 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

8.7.1. 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.

8.7.2. What does IPFW allow me to do?

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, 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.

8.7.3. Enabling IPFW on FreeBSD

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:

Previous versions of FreeBSD contained an IPFIREWALL_ACCT option. This is now obsolete as the firewall code automatically includes accounting facilities.

8.7.4. Configuring IPFW

The configuration of the IPFW software is done through the 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.

    address

    address/mask-bits

    address:mask-pattern

8.7.5. 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:

    # 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).

    # 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:

    # ipfw add deny tcp from any to my.org/28 6000 setup

To see the accounting records:

    # ipfw -a list

    # ipfw -a l

You can also see the last time a chain entry was matched with:

    # ipfw -at l

8.7.6. Building a packet filtering firewall

When initially setting up your firewall, unless you have a test bench setup where you can configure your firewall host in a controlled environment, I 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.

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 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 ftp://ftp.cert.org/pub/tech_tips/packet_filtering

As I said above, these are only guidelines. You will have to decide what filter rules you want to use on your firewall yourself. I cannot accept ANY responsibility if someone breaks into your network, even if you follow the advice given above.

8.8.1. 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.

8.8.2. International (Non-USA) Users

People who are located outside the USA, and who obtain their crypto sources from internat.FreeBSD.org (the International Crypto Repository) or an international mirror site, will build a version of OpenSSL which includes the ``native'' OpenSSL implementation of RSA, but does not include IDEA, because the latter is restricted in certain locations elsewhere in the world. In the future a more flexible geographical identification system may allow building of IDEA in countries for which it is not restricted.

Please be aware of any local restrictions on the import, use and redistribution of cryptography which may exist in your country.

8.8.3. USA Users

As noted above, RSA is patented in the USA, with terms preventing general use without an appropriate license. Therefore the standard OpenSSL RSA code may not be used in the USA, and has been removed from the version of OpenSSL carried on USA mirror sites. The RSA patent is due to expire on September 20, 2000, at which time it is intended to add the ``full'' RSA code back to the USA version of OpenSSL.

However (and fortunately), the RSA patent holder (RSA Security, has provided a ``RSA reference implementation'' toolkit (RSAREF) which is available for certain classes of use, including non-commercial use (see the RSAREF license for their definition of non-commercial).

If you meet the conditions of the RSAREF license and wish to use it in conjunction with OpenSSL to provide RSA support, you can install the rsaref port, which is located in /usr/ports/security/rsaref, or the rsaref-2.0 package. The OpenSSL library will then automatically detect and use the RSAREF libraries. Please obtain legal advice if you are unsure of your compliance with the license terms.

The RSAREF implementation is inferior to the ``native'' OpenSSL implementation (it is much slower, and cannot be used with keys larger than 1024 bits). If you are not located in the USA then you are doing yourself a disadvantage by using RSAREF.

Users who have purchased an appropriate RSA source code license from RSA Security may use the International version of OpenSSL described above to obtain native RSA support.

IDEA code is also removed from the USA version of OpenSSL for patent reasons.

8.8.4. Binary Installations

If your FreeBSD installation was a binary installation (e.g., installed from the Walnut Creek CDROM, or from a snapshot downloaded from ftp.FreeBSD.org) and you selected to install the crypto collection, then the sysinstall utility will automatically select the correct version to install during the installation process. If the international version was selected but could not be installed during sysinstall (e.g. you have not configured network access, and the version must be downloaded from a FTP site) then you can add the international RSA library after installation as a package.

The librsaintl package contains the RSA code for International (non-USA) users. This is not legal for use in the USA, but international users should use this version because the RSA implementation is faster and more flexible. It is available from ftp.internat.FreeBSD.org and does not require RSAREF.

8.9.1. 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 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 setkey(8) on both HOST A and B:

    
    # 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:
    
    # 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:
    
    # 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 ============
    
        

8.9.2. 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:

    
            # 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:

            # 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.

8.9.3. 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:

    
            # 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:

    
            # 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
    
         

8.9.4. 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:

    
            # 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:

    
            # 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
    
         

9.2.1. Why You Should Use the Spooler

If you are the sole user of your system, you may be wondering why you should bother with the spooler when you do not need access control, header pages, or printer accounting. While it is possible to enable direct access to a printer, you should use the spooler anyway since:

• LPD prints jobs in the background; you do not have to wait for data to be copied to the printer.

• LPD can conveniently run a job to be printed through filters to add date/time headers or convert a special file format (such as a TeX DVI file) into a format the printer will understand. You will not have to do these steps manually.

• Many free and commercial programs that provide a print feature usually expect to talk to the spooler on your system. By setting up the spooling system, you will more easily support other software you may later add or already have.

9.3.1. Simple Printer Setup

This section tells how to configure printer hardware and the LPD software to use the printer. It teaches the basics:

• Section Hardware Setup gives some hints on connecting the printer to a port on your computer.

• Section Software Setup shows how to setup the LPD spooler configuration file (/etc/printcap).

If you are setting up a printer that uses a network protocol to accept data to print instead of a serial or parallel interface, see Printers With Networked Data Stream Interfaces.

Although this section is called ``Simple Printer Setup'', it is actually fairly complex. Getting the printer to work with your computer and the LPD spooler is the hardest part. The advanced options like header pages and accounting are fairly easy once you get the printer working.

    # dmesg | grep sioN

    sio2 at 0x3e8-0x3ef irq 5 on isa
    sio2: type 16550A

    # dmesg | grep lptN

    lpt0 at 0x378-0x37f on isa

    %!PS
    100 100 moveto 300 300 lineto stroke
    310 310 moveto /Helvetica findfont 12 scalefont setfont
    (Is this thing working?) show
    showpage

    #
    #  /etc/printcap for host rose
    #
    rattan|line|diablo|lp|Diablo 630 Line Printer:
    
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:

    #
    #  /etc/printcap for host rose - no header pages anywhere
    #
    rattan|line|diablo|lp|Diablo 630 Line Printer:\
            :sh:
    
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :sh:

    # mkdir /var/spool/printer-name

    # mkdir /var/spool/lpd
    # mkdir /var/spool/lpd/rattan
    # mkdir /var/spool/lpd/bamboo

    #
    #  /etc/printcap for host rose - added spooling directories
    #
    rattan|line|diablo|lp|Diablo 630 Line Printer:\
            :sh:sd=/var/spool/lpd/rattan:
    
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :sh:sd=/var/spool/lpd/bamboo:

    #
    #  /etc/printcap for host rose - identified what devices to use
    #
    rattan|line|diablo|lp|Diablo 630 Line Printer:\
            :sh:sd=/var/spool/lpd/rattan:\
            :lp=/dev/lpt0:
    
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :sh:sd=/var/spool/lpd/bamboo:\
            :lp=/dev/ttyd5:

    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :sh:sd=/var/spool/lpd/bamboo:\
            :lp=/dev/ttyd5:fs#0x82000c1:xs#0x820:

    #!/bin/sh
    #
    # if-simple - Simple text input filter for lpd
    # Installed in /usr/local/libexec/if-simple
    #
    # Simply copies stdin to stdout.  Ignores all filter arguments.
    
    /bin/cat && exit 0
    exit 2

    # chmod 555 /usr/local/libexec/if-simple

    #
    #  /etc/printcap for host rose - added text filter
    #
    rattan|line|diablo|lp|Diablo 630 Line Printer:\
            :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\
            :if=/usr/local/libexec/if-simple:
    
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :sh:sd=/var/spool/lpd/bamboo:\
            :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:\
            :if=/usr/local/libexec/if-simple:

    lpd_enable="YES"

    # lpd

    # lptest 20 5 | lpr -Pprinter-name

    !"#$%&'()*+,-./01234
    "#$%&'()*+,-./012345
    #$%&'()*+,-./0123456
    $%&'()*+,-./01234567
    %&'()*+,-./012345678

9.4.1. Filters

Although LPD handles network protocols, queuing, access control, and other aspects of printing, most of the real work happens in the filters. Filters are programs that communicate with the printer and handle its device dependencies and special requirements. In the simple printer setup, we installed a plain text filter--an extremely simple one that should work with most printers (section Installing the Text Filter).

However, in order to take advantage of format conversion, printer accounting, specific printer quirks, and so on, you should understand how filters work. It will ultimately be the filter's responsibility to handle these aspects. And the bad news is that most of the time you have to provide filters yourself. The good news is that many are generally available; when they are not, they are usually easy to write.

Also, FreeBSD comes with one, /usr/libexec/lpr/lpf, that works with many printers that can print plain text. (It handles backspacing and tabs in the file, and does accounting, but that is about all it does.) There are also several filters and filter components in the FreeBSD ports collection.

Here is what you will find in this section:

• Section How Filters Work, tries to give an overview of a filter's role in the printing process. You should read this section to get an understanding of what is happening ``under the hood'' when LPD uses filters. This knowledge could help you anticipate and debug problems you might encounter as you install more and more filters on each of your printers.

• LPD expects every printer to be able to print plain text by default. This presents a problem for PostScript (or other language-based printers) which cannot directly print plain text. Section Accommodating Plain Text Jobs on PostScript Printers tells you what you should do to overcome this problem. I recommend reading this section if you have a PostScript printer.

• PostScript is a popular output format for many programs. Even some people (myself included) write PostScript code directly. But PostScript printers are expensive. Section Simulating PostScript on Non-PostScript Printers tells how you can further modify a printer's text filter to accept and print PostScript data on a non-PostScript printer. I recommend reading this section if you do not have a PostScript printer.

• Section Conversion Filters tells about a way you can automate the conversion of specific file formats, such as graphic or typesetting data, into formats your printer can understand. After reading this section, you should be able to set up your printers such that users can type lpr -t to print troff data, or lpr -d to print TeX DVI data, or lpr -v to print raster image data, and so forth. I recommend reading this section.

• Section Output Filters tells all about a not often used feature of LPD: output filters. Unless you are printing header pages (see Header Pages), you can probably skip that section altogether.

• Section lpf: a Text Filter describes lpf, a fairly complete if simple text filter for line printers (and laser printers that act like line printers) that comes with FreeBSD. If you need a quick way to get printer accounting working for plain text, or if you have a printer which emits smoke when it sees backspace characters, you should definitely consider lpf.

    :if=/usr/local/libexec/psif:

    #!/bin/sh
    #
    #  psif - Print PostScript or plain text on a PostScript printer
    #  Script version; NOT the version that comes with lprps
    #  Installed in /usr/local/libexec/psif
    #
    
    read first_line
    first_two_chars=`expr "$first_line" : '\(..\)'`
    
    if [ "$first_two_chars" = "%!" ]; then
        #
        #  PostScript job, print it.
        #
        echo "$first_line" && cat && printf "\004" && exit 0
        exit 2
    else
        #
        #  Plain text, convert it, then print it.
        #
        ( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0
        exit 2
    fi

    #!/bin/sh
    #
    #  ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500
    #  Installed in /usr/local/libexec/hpif
    
    #
    #  Treat LF as CR+LF:
    #
    printf "\033&k2G" || exit 2
    
    #
    #  Read first two characters of the file
    #
    read first_line
    first_two_chars=`expr "$first_line" : '\(..\)'`
    
    if [ "$first_two_chars" = "%!" ]; then
        #
        #  It is PostScript; use Ghostscript to scan-convert and print it.
        #
        #  Note that PostScript files are actually interpreted programs,
        #  and those programs are allowed to write to stdout, which will
        #  mess up the printed output.  So, we redirect stdout to stderr
        #  and then make descriptor 3 go to stdout, and have Ghostscript
        #  write its output there.  Exercise for the clever reader:
        #  capture the stderr output from Ghostscript and mail it back to
        #  the user originating the print job.
        #
        exec 3>&1 1>&2
        /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \
            -sOutputFile=/dev/fd/3 - && exit 0
    
        #
        /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 -sOutputFile=- - \
            && exit 0
    else
        #
        #  Plain text or HP/PCL, so just print it directly; print a form
        #  at the end to eject the last page.
        #
        echo $first_line && cat && printf "\033&l0H" && 
    exit 0
    fi
    
    exit 2

    :if=/usr/local/libexec/hpif:

    % dvips seaweed-analysis.dvi
    % lpr seaweed-analysis.ps

    % lpr -d seaweed-analysis.dvi

    #
    #  /etc/printcap for host rose - added df filter for bamboo
    #
    rattan|line|diablo|lp|Diablo 630 Line Printer:\
            :sh:sd=/var/spool/lpd/rattan:\
            :lp=/dev/lpt0:\
            :if=/usr/local/libexec/if-simple:
    
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :sh:sd=/var/spool/lpd/bamboo:\
            :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
            :if=/usr/local/libexec/psif:\
            :df=/usr/local/libexec/psdf:

    #!bin/sh
    #
    #  psdf - DVI to PostScript printer filter
    #  Installed in /usr/local/libexec/psdf
    #
    # Invoked by lpd when user runs lpr -d
    #
    exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@"

    #!/bin/sh
    #
    #  hpvf - Convert GIF files into HP/PCL, then print
    #  Installed in /usr/local/libexec/hpvf
                      
    PATH=/usr/X11R6/bin:$PATH; export PATH
    giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \
        && exit 0 \
        || exit 2

    #
    #  /etc/printcap for host orchid
    #
    teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
            :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\
            :if=/usr/local/libexec/hpif:\
            :vf=/usr/local/libexec/hpvf:

    #!/bin/sh
    #
    #  pstf - Convert groff's troff data into PS, then print.
    #  Installed in /usr/local/libexec/pstf
    #
    exec grops | /usr/local/libexec/lprps "$@"

    #!/bin/sh
    #
    #  pstf - Convert groff's troff data into PS, then print.
    #  Installed in /usr/local/libexec/pstf
    #
    exec grops

    :tf=/usr/local/libexec/pstf:

    #!/bin/sh
    #
    # hprf - FORTRAN text filter for LaserJet 3si:
    # Installed in /usr/local/libexec/hprf
    #
    
    printf "\033&k2G" && fpr && printf "\033&l0H" &&
     exit 0
    exit 2

    :rf=/usr/local/libexec/hprf:

    :df=/usr/local/libexec/hpdf:

    #!/bin/sh
    #
    #  hpdf - Print DVI data on HP/PCL printer
    #  Installed in /usr/local/libexec/hpdf
    
    PATH=/usr/local/bin:$PATH; export PATH
    
    #
    #  Define a function to clean up our temporary files.  These exist
    #  in the current directory, which will be the spooling directory
    #  for the printer.
    #
    cleanup() {
       rm -f hpdf$$.dvi
    }
    
    #
    #  Define a function to handle fatal errors: print the given message
    #  and exit 2.  Exiting with 2 tells LPD to do not try to reprint the
    #  job.
    #
    fatal() {
        echo "$@" 1>&2
        cleanup
        exit 2
    }
    
    #
    #  If user removes the job, LPD will send SIGINT, so trap SIGINT
    #  (and a few other signals) to clean up after ourselves.
    #
    trap cleanup 1 2 15 
    
    #
    #  Make sure we are not colliding with any existing files.
    #
    cleanup
    
    #
    #  Link the DVI input file to standard input (the file to print).
    #
    ln -s /dev/fd/0 hpdf$$.dvi || fatal "Cannot symlink /dev/fd/0"
    
    #
    #  Make LF = CR+LF
    #
    printf "\033&k2G" || fatal "Cannot initialize printer"
    
    # 
    #  Convert and print.  Return value from dvilj2p does not seem to be
    #  reliable, so we ignore it.
    #
    dvilj2p -M1 -q -e- dfhp$$.dvi
    
    #
    #  Clean up and exit
    #
    cleanup
    exit 0

9.4.2. Header Pages

If you have lots of users, all of them using various printers, then you probably want to consider header pages as a necessary evil.

Header pages, also known as banner or burst pages identify to whom jobs belong after they are printed. They are usually printed in large, bold letters, perhaps with decorative borders, so that in a stack of printouts they stand out from the real documents that comprise users' jobs. They enable users to locate their jobs quickly. The obvious drawback to a header page is that it is yet one more sheet that has to be printed for every job, their ephemeral usefulness lasting not more than a few minutes, ultimately finding themselves in a recycling bin or rubbish heap. (Note that header pages go with each job, not each file in a job, so the paper waste might not be that bad.)

The LPD system can provide header pages automatically for your printouts if your printer can directly print plain text. If you have a PostScript printer, you will need an external program to generate the header page; see Header Pages on PostScript Printers.

    #!/bin/sh
    #
    #  hpof - Output filter for Hewlett Packard PCL-compatible printers
    #  Installed in /usr/local/libexec/hpof
    
    printf "\033&k2G" || exit 2
    exec /usr/libexec/lpr/lpf

    #
    #  /etc/printcap for host orchid
    #
    teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
            :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
            :if=/usr/local/libexec/hpif:\
            :vf=/usr/local/libexec/hpvf:\
            :of=/usr/local/libexec/hpof:

          k                   ll       ll
          k                    l        l
          k                    l        l
          k   k     eeee       l        l     y    y
          k  k     e    e      l        l     y    y
          k k      eeeeee      l        l     y    y
          kk k     e           l        l     y    y
          k   k    e    e      l        l     y   yy
          k    k    eeee      lll      lll     yyy y
                                                   y
                                              y    y
                                               yyyy
    
    
                                       ll
                              t         l        i
                              t         l
           oooo    u    u   ttttt       l       ii     n nnn     eeee
          o    o   u    u     t         l        i     nn   n   e    e
          o    o   u    u     t         l        i     n    n   eeeeee
          o    o   u    u     t         l        i     n    n   e
          o    o   u   uu     t  t      l        i     n    n   e    e
           oooo     uuu u      tt      lll      iii    n    n    eeee
    
    
    
    
    
    
    
    
    
          r rrr     oooo     ssss     eeee
          rr   r   o    o   s    s   e    e
          r        o    o    ss      eeeeee
          r        o    o      ss    e
          r        o    o   s    s   e    e
          r         oooo     ssss     eeee
    
    
    
    
    
    
    
                                                  Job:  outline
                                                  Date: Sun Sep 17 11:04:58 1995

    rose:kelly  Job: outline  Date: Sun Sep 17 11:07:51 1995

    #!/bin/sh
    #
    #  make-ps-header - make a PostScript header page on stdout
    #  Installed in /usr/local/libexec/make-ps-header
    #
    
    #
    #  These are PostScript units (72 to the inch).  Modify for A4 or
    #  whatever size paper you are using:
    #
    page_width=612
    page_height=792
    border=72
    
    #
    #  Check arguments
    #
    if [ $# -ne 3 ]; then
        echo "Usage: `basename $0` <user> <host> <job>" 1>&2
        exit 1
    fi
    
    #
    #  Save these, mostly for readability in the PostScript, below.
    #
    user=$1
    host=$2
    job=$3
    date=`date`
    
    #
    #  Send the PostScript code to stdout.
    #
    exec cat <<EOF
    %!PS
    
    %
    %  Make sure we do not interfere with user's job that will follow
    %
    save
    
    %
    %  Make a thick, unpleasant border around the edge of the paper.
    %
    $border $border moveto
    $page_width $border 2 mul sub 0 rlineto
    0 $page_height $border 2 mul sub rlineto
    currentscreen 3 -1 roll pop 100 3 1 roll setscreen
    $border 2 mul $page_width sub 0 rlineto closepath
    0.8 setgray 10 setlinewidth stroke 0 setgray
    
    %
    %  Display user's login name, nice and large and prominent
    %
    /Helvetica-Bold findfont 64 scalefont setfont
    $page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto
    ($user) show
    
    %
    %  Now show the boring particulars
    %
    /Helvetica findfont 14 scalefont setfont
    /y 200 def
    [ (Job:) (Host:) (Date:) ] {
    200 y moveto show /y y 18 sub def }
    forall
    
    /Helvetica-Bold findfont 14 scalefont setfont
    /y 200 def
    [ ($job) ($host) ($date) ] {
            270 y moveto show /y y 18 sub def
    } forall
    
    %
    % That is it
    %
    restore
    showpage
    EOF

    #!/bin/sh
    #
    #  psdf - DVI to PostScript printer filter
    #  Installed in /usr/local/libexec/psdf
    #
    #  Invoked by lpd when user runs lpr -d
    #
                    
    orig_args="$@"
    
    fail() {
        echo "$@" 1>&2
        exit 2
    }
    
    while getopts "x:y:n:h:" option; do
        case $option in
            x|y)  ;; # Ignore
            n)    login=$OPTARG ;;
            h)    host=$OPTARG ;;
            *)    echo "LPD started `basename $0` wrong." 1>&2
                  exit 2
                  ;;
        esac
    done
    
    [ "$login" ] || fail "No login name"
    [ "$host" ] || fail "No host name"
    
    ( /usr/local/libexec/make-ps-header $login $host "DVI File"
      /usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_args

9.4.3. Networked Printing

FreeBSD supports networked printing: sending jobs to remote printers. Networked printing generally refers to two different things:

• Accessing a printer attached to a remote host. You install a printer that has a conventional serial or parallel interface on one host. Then, you set up LPD to enable access to the printer from other hosts on the network. Section Printers Installed on Remote Hosts tells how to do this.

• Accessing a printer attached directly to a network. The printer has a network interface in addition (or in place of) a more conventional serial or parallel interface. Such a printer might work as follows:

  • It might understand the LPD protocol and can even queue jobs from remote hosts. In this case, it acts just like a regular host running LPD. Follow the same procedure in section Printers Installed on Remote Hosts to set up such a printer.

  • It might support a data stream network connection. In this case, you ``attach'' the printer to one host on the network by making that host responsible for spooling jobs and sending them to the printer. Section Printers with Networked Data Stream Interfaces gives some suggestions on installing such printers.

    #
    #  /etc/printcap for host orchid - added (remote) printers on rose
    #
    
    #
    #  teak is local; it is connected directly to orchid:
    #
    teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
            :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
            :if=/usr/local/libexec/ifhp:\
            :vf=/usr/local/libexec/vfhp:\
            :of=/usr/local/libexec/ofhp:
    
    #
    #  rattan is connected to rose; send jobs for rattan to rose:
    #
    rattan|line|diablo|lp|Diablo 630 Line Printer:\
            :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
    
    #
    #  bamboo is connected to rose as well:
    #
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:

    # mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo
    # chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo
    # chown daemon.daemon /var/spool/lpd/rattan /var/spool/lpd/bamboo

    % lpr -P bamboo -d sushi-review.dvi

    #!/usr/bin/perl
    #
    #  netprint - Text filter for printer attached to network
    #  Installed in /usr/local/libexec/netprint
    #
    $#ARGV eq 1 || die "Usage: $0 <printer-hostname> <port-number>";
    
    $printer_host = $ARGV[0];
    $printer_port = $ARGV[1];
    
    require 'sys/socket.ph';
    
    ($ignore, $ignore, $protocol) = getprotobyname('tcp');
    ($ignore, $ignore, $ignore, $ignore, $address)
        = gethostbyname($printer_host);
    
    $sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address);
    
    socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol)
        || die "Can't create TCP/IP stream socket: $!";
    connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!";
    while (<STDIN>) { print PRINTER; }
    exit 0;

    #!/bin/sh
    #
    #  diablo-if-net - Text filter for Diablo printer `scrivener' listening
    #  on port 5100.   Installed in /usr/local/libexec/diablo-if-net
    #
    exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100

9.4.4. Restricting Printer Usage

This section gives information on restricting printer usage. The LPD system lets you control who can access a printer, both locally or remotely, whether they can print multiple copies, how large their jobs can be, and how large the printer queues can get.

    lpr: multiple copies are not allowed

    #
    #  /etc/printcap for host rose - restrict multiple copies on bamboo
    #
    rattan|line|diablo|lp|Diablo 630 Line Printer:\
            :sh:sd=/var/spool/lpd/rattan:\
            :lp=/dev/lpt0:\
            :if=/usr/local/libexec/if-simple:
    
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :sh:sd=/var/spool/lpd/bamboo:sc:\
            :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
            :if=/usr/local/libexec/psif:\
            :df=/usr/local/libexec/psdf:

    #
    #  /etc/printcap for host orchid - no multiple copies for local
    #  printer teak or remote printer bamboo
    teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
            :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:sc:\
            :if=/usr/local/libexec/ifhp:\
            :vf=/usr/local/libexec/vfhp:\
            :of=/usr/local/libexec/ofhp:
    
    rattan|line|diablo|lp|Diablo 630 Line Printer:\
            :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
    
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:sc:

    % lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign

    #
    #  /etc/printcap for host rose - restricted group for bamboo
    #
    rattan|line|diablo|lp|Diablo 630 Line Printer:\
            :sh:sd=/var/spool/lpd/rattan:\
            :lp=/dev/lpt0:\
            :if=/usr/local/libexec/if-simple:
    
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:\
            :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
            :if=/usr/local/libexec/psif:\
            :df=/usr/local/libexec/psdf:

    #
    #  /etc/printcap for host rose
    #
    
    #
    #  No limit on job size:
    #
    rattan|line|diablo|lp|Diablo 630 Line Printer:\
            :sh:mx#0:sd=/var/spool/lpd/rattan:\
            :lp=/dev/lpt0:\
            :if=/usr/local/libexec/if-simple:
    
    #
    #  Limit of five megabytes:
    #
    bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
            :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\
            :lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
            :if=/usr/local/libexec/psif:\
            :df=/usr/local/libexec/psdf:

9.4.5. Accounting for Printer Usage

So, you need to charge for printouts. And why not? Paper and ink cost money. And then there are maintenance costs--printers are loaded with moving parts and tend to break down. You have examined your printers, usage patterns, and maintenance fees and have come up with a per-page (or per-foot, per-meter, or per-whatever) cost. Now, how do you actually start accounting for printouts?

Well, the bad news is the LPD spooling system does not provide much help in this department. Accounting is highly dependent on the kind of printer in use, the formats being printed, and your requirements in charging for printer usage.

To implement accounting, you have to modify a printer's text filter (to charge for plain text jobs) and the conversion filters (to charge for other file formats), to count pages or query the printer for pages printed. You cannot get away with using the simple output filter, since it cannot do accounting. See section Filters.

Generally, there are two ways to do accounting:

• Periodic accounting is the more common way, possibly because it is easier. Whenever someone prints a job, the filter logs the user, host, and number of pages to an accounting file. Every month, semester, year, or whatever time period you prefer, you collect the accounting files for the various printers, tally up the pages printed by users, and charge for usage. Then you truncate all the logging files, starting with a clean slate for the next period.

• Timely accounting is less common, probably because it is more difficult. This method has the filters charge users for printouts as soon as they use the printers. Like disk quotas, the accounting is immediate. You can prevent users from printing when their account goes in the red, and might provide a way for users to check and adjust their ``print quotas.'' But this method requires some database code to track users and their quotas.

The LPD spooling system supports both methods easily: since you have to provide the filters (well, most of the time), you also have to provide the accounting code. But there is a bright side: you have enormous flexibility in your accounting methods. For example, you choose whether to use periodic or timely accounting. You choose what information to log: user names, host names, job types, pages printed, square footage of paper used, how long the job took to print, and so forth. And you do so by modifying the filters to save this information.

    2.00 rose:andy
    3.00 rose:kelly
    3.00 orchid:mary
    5.00 orchid:mary
    2.00 orchid:zhang

      Login               pages/feet   runs    price
    orchid:kelly                5.00    1   $  0.10
    orchid:mary                31.00    3   $  0.62
    orchid:zhang                9.00    1   $  0.18
    rose:andy                   2.00    1   $  0.04
    rose:kelly                177.00  104   $  3.54
    rose:mary                  87.00   32   $  1.74
    rose:root                  26.00   12   $  0.52
    
    total                     337.00  154   $  6.74

      Login               pages/feet   runs    price
    andy                        2.00    1   $  0.04
    kelly                     182.00  105   $  3.64
    mary                      118.00   35   $  2.36
    root                       26.00   12   $  0.52
    zhang                       9.00    1   $  0.18
    
    total                     337.00  154   $  6.74

    # pac -p1.50

9.5.1. Printing Jobs

To print files, type:

    % lpr filename ...

This prints each of the listed files to the default printer. If you list no files, lpr(1) reads data to print from standard input. For example, this command prints some important system files:

    % lpr /etc/host.conf /etc/hosts.equiv

To select a specific printer, type:

    % lpr -P printer-name filename ...

This example prints a long listing of the current directory to the printer named rattan:

    % ls -l | lpr -P rattan

Because no files were listed for the lpr(1) command, lpr read the data to print from standard input, which was the output of the ls -l command.

The lpr(1) command can also accept a wide variety of options to control formatting, apply file conversions, generate multiple copies, and so forth. For more information, see the section Printing Options.

9.5.2. Checking Jobs

When you print with lpr(1), the data you wish to print is put together in a package called a ``print job'', which is sent to the LPD spooling system. Each printer has a queue of jobs, and your job waits in that queue along with other jobs from yourself and from other users. The printer prints those jobs in a first-come, first-served order.

To display the queue for the default printer, type lpq(1). For a specific printer, use the -P option. For example, the command

    % lpq -P bamboo

    bamboo is ready and printing
    Rank   Owner    Job  Files                              Total Size
    active kelly    9    /etc/host.conf, /etc/hosts.equiv   88 bytes
    2nd    kelly    10   (standard input)                   1635 bytes
    3rd    mary     11   ...                                78519 bytes

This shows three jobs in the queue for bamboo. The first job, submitted by user kelly, got assigned ``job number'' 9. Every job for a printer gets a unique job number. Most of the time you can ignore the job number, but you will need it if you want to cancel the job; see section Removing Jobs for details.

Job number nine consists of two files; multiple files given on the lpr(1) command line are treated as part of a single job. It is the currently active job (note the word active under the ``Rank'' column), which means the printer should be currently printing that job. The second job consists of data passed as the standard input to the lpr(1) command. The third job came from user mary; it is a much larger job. The pathname of the files she's trying to print is too long to fit, so the lpq(1) command just shows three dots.

The very first line of the output from lpq(1) is also useful: it tells what the printer is currently doing (or at least what LPD thinks the printer is doing).

The lpq(1) command also support a -l option to generate a detailed long listing. Here is an example of lpq -l:

    waiting for bamboo to become ready (offline ?)
    kelly: 1st               [job 009rose]
           /etc/host.conf                    73 bytes
           /etc/hosts.equiv                  15 bytes
    
    kelly: 2nd               [job 010rose]
           (standard input)                  1635 bytes
    
    mary: 3rd                                [job 011rose]
          /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes

9.5.3. Removing Jobs

If you change your mind about printing a job, you can remove the job from the queue with the lprm(1) command. Often, you can even use lprm(1) to remove an active job, but some or all of the job might still get printed.

To remove a job from the default printer, first use lpq(1) to find the job number. Then type:

    % lprm job-number

To remove the job from a specific printer, add the -P option. The following command removes job number 10 from the queue for the printer bamboo:

    % lprm -P bamboo 10

The lprm(1) command has a few shortcuts:

Just use the -P option with the above shortcuts to operate on a specific printer instead of the default. For example, the following command removes all jobs for the current user in the queue for the printer named rattan:

    % lprm -P rattan -

9.5.4. Beyond Plain Text: Printing Options

The lpr(1) command supports a number of options that control formatting text, converting graphic and other file formats, producing multiple copies, handling of the job, and more. This section describes the options.

    % lpr -P bamboo -d fish-report.dvi

    % zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t

9.5.5. Administrating Printers

As an administrator for your printers, you have had to install, set up, and test them. Using the lpc(8) command, you can interact with your printers in yet more ways. With lpc(8), you can

• Start and stop the printers

• Enable and disable their queues

• Rearrange the order of the jobs in each queue.

First, a note about terminology: if a printer is stopped, it will not print anything in its queue. Users can still submit jobs, which will wait in the queue until the printer is started or the queue is cleared.

If a queue is disabled, no user (except root) can submit jobs for the printer. An enabled queue allows jobs to be submitted. A printer can be started for a disabled queue, in which case it will continue to print jobs in the queue until the queue is empty.

In general, you have to have root privileges to use the lpc(8) command. Ordinary users can use the lpc(8) command to get printer status and to restart a hung printer only.

Here is a summary of the lpc(8) commands. Most of the commands takes a printer-name argument to tell on which printer to operate. You can use all for the printer-name to mean all printers listed in /etc/printcap.

lpc(8) accepts the above commands on the command line. If you do not enter any commands, lpc(8) enters an interactive mode, where you can enter commands until you type exit, quit, or end-of-file.

10.3.1. Slices and Partitions

Physical disks usually contain slices, unless they are ``dangerously dedicated''. Slice numbers follow the device name, prefixed with an s: ``da0s1''.

Slices, ``dangerously dedicated'' physical drives, and other drives contain partitions, which represented as letters from a to h. b is reserved for swap partitions, and c is an unused partition the size of the entire slice or drive. This is explained in Section 10.5>.

10.4.1. The fstab File

During the boot process, filesystems listed in /etc/fstab are automatically mounted (unless they are listed with noauto).

The /etc/fstab file contains a list of lines of the following format:

    device   /mount-point   fstype   options   dumpfreq   passno

device is a device name (which should exist), as explained in the Disk naming conventions above.

mount-point is a directory (which should exist), on which to mount the filesystem.

fstype is the filesystem type to pass to mount(8). The default FreeBSD filesystem is ufs.

options is either rw for read-write filesystems, or ro for read-only filesystems, followed by any other options that may be needed. A common option is noauto for filesystems not normally mounted during the boot sequence. Other options in the mount(8) manual page.

dumpfreq is the number of days the filesystem should be dumped, and passno is the pass number during which the filesystem is mounted during the boot sequence.

10.4.2. The mount Command

The mount(8) command is what is ultimately used to mount filesystems.

In its most basic form, you use:

    # mount device mountpoint