aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--handbook/crypt.sgml80
-rw-r--r--handbook/dma.sgml105
-rw-r--r--handbook/esdi.sgml421
-rw-r--r--handbook/firewalls.sgml525
-rw-r--r--handbook/kernelconfig.sgml1206
-rw-r--r--handbook/printing.sgml3877
-rw-r--r--handbook/routing.sgml279
-rw-r--r--handbook/skey.sgml302
8 files changed, 6795 insertions, 0 deletions
diff --git a/handbook/crypt.sgml b/handbook/crypt.sgml
new file mode 100644
index 0000000000..5fba49f7a0
--- /dev/null
+++ b/handbook/crypt.sgml
@@ -0,0 +1,80 @@
+<!-- $Id: crypt.sgml,v 1.1 1995-09-25 04:53:28 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<sect><heading>DES, MD5, and Crypt<label id="crypt"></heading>
+
+<p><em>Contributed by &a.wollman;<newline>24 September 1995.</em>
+
+<p><bf>History</bf>
+
+<p>In order to protect the security of passwords on UN*X systems from
+being easily exposed, passwords have traditionally been scrambled in
+some way. Starting with Bell Labs' Seventh Edition Unix, passwords
+were encrypted using what the security people call a ``one-way hash
+function''. That is to say, the password is transformed in such a way
+that the original password cannot be regained except by brute-force
+searching the space of possible passwords. Unfortunately, the only
+secure method that was available to the AT&amp;T researchers at the
+time was based on DES, the Data Encryption Standard. This causes only
+minimal difficulty for commercial vendors, but is a serious problem
+for an operating system like FreeBSD where all the source code is
+freely available, because national governments in many places like to
+place restrictions on cross-border transport of DES and other
+encryption software.
+
+<p>So, the FreeBSD team was faced with a dilemma: how could we provide
+compatibility with all those UNIX systems out there while still not
+running afoul of the law? We decided to take a dual-track approach:
+we would make distributions which contained only a non-regulated
+password scrambler, and then provide as a separate add-on library the
+DES-based password hash. The password-scrambling function was moved
+out of the C library to a separate library, called `<tt>libcrypt</tt>'
+because the name of the C function to implement it is
+`<tt>crypt</tt>'. In FreeBSD 1.x and some pre-release 2.0 snapshots,
+the non-regulated scrambler uses an insecure function written by Nate
+Williams; in subsequent releases this was replaced by a mechanism
+using the RSA Data Security, Inc., MD5 one-way hash function. Because
+neither of these functions involve encryption, they are believed to be
+exportable from the US and importable into many other countries.
+
+<p>Meanwhile, work was also underway on the DES-based password hash
+function. First, a version of the `<tt>crypt</tt>' function which was
+written outside the US was imported, thus synchronizing the US and
+non-US code. Then, the library was modified and split into two; the
+DES `<tt>libcrypt</tt>' contains only the code involved in performing
+the one-way password hash, and a separate `<tt>libcipher</tt>' was
+created with the entry points to actually perform encryption. The
+code was partitioned in this way to make it easier to get an export
+license for the compiled library.
+
+<p><bf>Recognizing your `<tt>crypt</tt>' mechanism</bf>
+
+<p>It is fairly easy to recognize whether a particular password
+string was created using the DES- or MD5-based hash function.
+MD5 password strings always begin with the characters
+`<tt>&dollar;1&dollar;</tt>'. 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 `<tt>&dollar;</tt>' character, so a
+relatively short string which doesn't begin with a dollar sign is
+very likely a DES password.
+
+<p>Determining which library is being used on your system is fairly
+easy for most programs, except for those like `<tt>init</tt>' which
+are statically linked. (For those programs, the only way is to try
+them on a known password and see if it works.) Programs which use
+`<tt>crypt</tt>' are linked against `<tt>libcrypt</tt>', which for
+each type of library is a symbolic link to the appropriate
+implementation. For example, on a system using the DES versions:
+
+<tscreen><verb>
+$ cd /usr/lib
+$ ls -l /usr/lib/libcrypt*
+lrwxr-xr-x 1 bin bin 13 Sep 5 12:50 libcrypt.a -> libdescrypt.a
+lrwxr-xr-x 1 bin bin 18 Sep 5 12:50 libcrypt.so.2.0 -> libdescrypt.so.2.0
+lrwxr-xr-x 1 bin bin 15 Sep 5 12:50 libcrypt_p.a -> libdescrypt_p.a
+</verb></tscreen>
+
+On a system using the MD5-based libraries, the same links will be
+present, but the target will be `<tt>libscrypt</tt>' rather than
+`<tt>libdescrypt</tt>'.
diff --git a/handbook/dma.sgml b/handbook/dma.sgml
new file mode 100644
index 0000000000..db63b82b8b
--- /dev/null
+++ b/handbook/dma.sgml
@@ -0,0 +1,105 @@
+<!-- $Id: dma.sgml,v 1.1 1995-09-25 04:53:29 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<sect><heading>PC DMA<label id="dma"></heading>
+
+<p><em>Contributed by &a.uhclem;.<newline>
+ 31 August 1995.</em>
+
+Posted to <htmlurl url="mailto:hackers@freebsd.org"
+ name="freebsd-hackers@freebsd.org">:
+<quote>
+<p><em>Yes, as long as `single mode' is appropriate for you, there's no need
+to worry about TC. TC is intented for continuous mode. Well, i've
+just noticed that the PC DMAC cannot even generate an interrupt when
+ready... hmm, go figure, the Z80 DMAC did it.</em>
+<p><em>And yes, for `single mode', the masking trick will do it. The
+peripheral device will issue a DRQ signal for each transfered
+byte/word, and masking would prevent the DMAC from accepting new DRQs
+for this channel. Aborting a continuous mode transfer would not be so
+easy (or even impossible at all).</em>
+</quote>
+
+Actually, masking is the correct procedure for all transfer modes on the
+8237, even autoinit mode, which is frequently used for audio operations
+since it allows seamless DMA transfers with no under/overruns.
+
+You are generally correct about TC. All the TC signal does is
+when the counter on any channel in the DMA controller goes from
+one to zero, TC is asserted. What the peripherals are supposed
+to if they want to generate an interrupt when the transfer is
+through, is that peripheral device is supposed to look at
+<tt>(-DACK%d &amp;&amp; TC &amp;&amp; DEVICE_DMA_ACTIVE)</tt> and then
+latch an <tt>IRQ%d</tt> for the 8259 interrupt controller. Since there is
+only one TC signal, it is important that only the peripheral who
+is transferring data at that moment honor the TC signal.
+
+The host CPU will eventually investigate the interrupt by having some driver
+poll the hardware associated with the peripheral, NOT the DMA controller.
+If a peripheral doesn't want an interrupt associated with the DMA counter
+reaching zero, it doesn't implement the circuitry to monitor TC.
+
+Some sound cards realize that when the TC hits zero it means the DMA
+is now idle and that is really too late, so they don't use TC and
+instead allow the driver to program in a local counter value, which
+is usually set lower than the value programmed into the DMA. This means
+the peripheral can interrupt the CPU in advance of the DMA "running dry",
+allowing the CPU to be ready to reprogram the DMA the instant it finishes
+what it is doing, rather than incurring the latency later.
+
+This also means that two or more different devices could share a
+DMA channel, by tristating <tt>DRQ%d</tt> when idle and only
+honoring <tt>-DACK%d</tt> when the device knows it is expecting
+the DMA to go active. (Iomega PC2B boards forgot this minor
+point and will transfer data even if they are not supposed to.)
+
+
+So, if you want to abort a 8237 DMA transfer of any kind, simply mask the
+bit for that DMA channel in the 8237. Note: You can't interrupt an individual
+transfer (byte or burst) in progress. Think about it... if the DMA is
+running, how is your OUT instruction going to be performed?
+The CPU has to be bus master for the OUT to be performed.
+
+Since the 8237 DMA re-evaluates DMA channel priorities constantly, even if
+the DMA had already asserted HOLD (to request the bus from the CPU) when
+the OUT actually took place, the processor would still grant the bus to the
+DMA controller. The DMA controller would look for the highest-priority
+DMA source remaining (your interrupt is masked now) at that instant,
+and if none remained, the DMA will release HOLD and the processor will
+get the bus back after a few clocks.
+
+There is a deadly race condition in this area, but if I remember right,
+you can't get into it via mis-programming the DMA, UNLESS you cause the DMA
+controller to be RESET. You should not do this. Effectively the CPU
+can give up the bus and the DMA doesn't do anything, including giving the
+bus back. Very annoying and after 16msec or so, all is over since
+refresh on main memory has started failing.
+
+So, mask the DMA controller, then go do what you have to do to get the
+transfer aborted in the peripheral hardware. In some extremely stupid
+hardware (I could mention a few), you may have to program the DMA to
+transfer one more byte to a garbage target to get the peripheral hardware
+to go back to an idle state. Most hardware these days isn't that
+stupid.
+
+Technically, you are supposed to mask the DMA channel, program the other
+settings (direction, address, length, etc), issue commands to the
+peripheral and then unmask the DMA channel once the peripheral commands have
+been accepted. The last two steps can be done out of order without
+harm, but you must always program the DMA channel while it is masked to
+avoid spraying data all over the place in the event the peripheral
+unexpected asserts <tt>DRQ%d</tt>.
+
+If you need to pad-out an aborted buffer, once you have masked the
+DMA, you can ask it how many bytes it still had to go and what
+address it was to write to next. Your driver can then fill in the
+remaining area or do what needs to be done.
+
+
+Don't forget that the 8237 was designed for use with the 8085 and
+really isn't suited to the job that IBM gave it in the original PC.
+That's why the upper eight bits of DMA addressing appear to be lashed-on.
+They are. Look at the schematics of the original PC and you will
+the upper bits are kept in external latches that are enabled whenever
+the DMA is too. Very kludgy.
+
diff --git a/handbook/esdi.sgml b/handbook/esdi.sgml
new file mode 100644
index 0000000000..5d79f44fd3
--- /dev/null
+++ b/handbook/esdi.sgml
@@ -0,0 +1,421 @@
+<!-- $Id: esdi.sgml,v 1.2 1995-10-07 04:31:20 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<!--
+ <title>An introduction to ESDI hard disks and their use with FreeBSD</title>
+ <author>(c) 1995, Wilko Bulte, <tt/wilko@yedi.iaf.nl/
+ <date>Tue Sep 12 20:48:44 MET DST 1995</date>
+
+ Copyright 1995, Wilko C. Bulte, Arnhem, The Netherlands
+
+ <abstract>
+ This document describes the use of ESDI disks in combination
+ with the FreeBSD operating system. Contrary to popular
+ belief, this is possible and people are using ESDI based
+ systems succesfully! This document tries to explain you
+ how to do this.
+
+ If you find something missing, plain wrong or have useful
+ comments on how to improve
+ the document please send mail to <tt/wilko@yedi.iaf.nl/
+ </abstract>
+-->
+
+ <sect><heading>ESDI hard disks and FreeBSD<label id="esdi"></heading>
+
+ <p><em>Copyright &copy; 1995, &a.wilko;.<newline>24 September 1995.</em>
+
+ ESDI is an acronym that means Enhanced Small Device Interface.
+ It is loosely based on the good old ST506/412 interface originally
+ devised by Seagate Technology, the makers of the first affordable
+ 5.25" winchester disk.
+
+ The acronym says Enhanced, and rightly so. In the first place
+ the speed of the interface is higher, 10 or 15 Mbits/second
+ instead of the 5 Mbits/second of ST412 interfaced drives.
+ Secondly some higher level commands are added, making the ESDI
+ interface somewhat 'smarter' to the operating system driver
+ writers. It is by no means as smart as SCSI by the way. ESDI
+ is standardised by ANSI.
+
+ Capacities of the drives are boosted by putting more sectors
+ on each track. Typical is 35 sectors per track, high capacity
+ drives I've seen were up to 54 sectors/track.
+
+ Although ESDI has been largely obsoleted by IDE and SCSI interfaces,
+ the availability of free or cheap surplus drives makes them
+ ideal for low (or now) budget systems.
+
+ <sect1><heading>Concepts of ESDI</heading>
+ <p>
+ <sect2><heading>Physical connections</heading>
+ <p>
+ The ESDI interface uses two cables connected to each drive.
+ One cable is a 34 pin flatcable edge connector that carries
+ the command and status signals from the controller to the
+ drive and viceversa. The command cable is daisy chained
+ between all the drives. So, it forms a bus onto which all
+ drives are connected.
+
+ The second cable is a a 20 pin flatcable edge connector that
+ carries the data to and from the drive. This cable is radially
+ connected, so each drive has it's own direct connection to the
+ controller.
+
+ To the best of my knowledge PC ESDI controllers are limited
+ to using a maximum of 2 drives per controller. This is
+ compatibility feature(?) left over from the WD1003 standard
+ that reserves only a single bit for device addressing.
+
+ <sect2><heading>Device addressing</heading>
+ <p>
+ On each command cable a maximum of 7 devices and 1 controller
+ can be present. To enable the controller to uniquely
+ identify which drive it addresses, each ESDI device is equipped
+ with jumpers or switches to select the devices address.
+
+ On PC type controllers the first drive is set to address 0,
+ the second disk to address 1. <it>Always make sure</it> you
+ set each disk to an unique address! So, on a PC with it's
+ two drives/controller maximum the first drive is drive 0, the
+ second is drive 1.
+
+ <sect2><heading>Termination</heading>
+ <p>
+ The daisy chained command cable (the 34 pin cable remember?)
+ needs to be terminated at the last drive on the chain.
+ For this purpose ESDI drives come with a termination resistor
+ network that can be removed or disabled by a jumper when it
+ is not used.
+
+ So, one and <it>only</it> one drive, the one at
+ the fartest end of the command
+ cable has it's terminator installed/enabled. The controller
+ automatically terminates the other end of the cable.
+ Please note that this implies that the controller must be
+ at one end of the cable and <it>not</it> in the middle.
+
+ <sect1><heading>Using ESDI disks with FreeBSD</heading>
+ <p>
+ Why is ESDI such a pain to get working in the first place?
+
+ People who tried ESDI disks with FreeBSD are known to have
+ developed a profound sense of frustration. A combination of
+ factors works against you to produce effects that are
+ hard to understand when you have never seen them before.
+
+ This has also led to the popular legend ESDI and FreeBSD
+ is a plain NO-GO.
+ The following sections try to list all the pitfalls and
+ solutions.
+
+ <sect2><heading>ESDI speed variants</heading>
+ <p>
+ As briefly mentioned before, ESDI comes in two speed flavours.
+ The older drives and controllers use a 10 Mbits/second
+ data transfer rate. Newer stuff uses 15 Mbits/second.
+
+ It is not hard to imagine that 15 Mbits/second drive cause
+ problems on controllers laid out for 10 Mbits/second.
+ As always, consult your controller <it>and</it> drive
+ documentation to see if things match.
+
+ <sect2><heading>Stay on track</heading>
+ <p>
+ Mainstream ESDI drives use 34 to 36 sectors per track.
+ Most (older) controllers cannot handle more than this
+ number of sectors.
+ Newer, higher capacity, drives use higher numbers of sectors
+ per track. For instance, I own a 670 Mb drive that has
+ 54 sectors per track.
+
+ In my case, the controller could not handle this number
+ of sectors. It proved to work well except that it only
+ used 35 sectors on each track. This meant losing a
+ lot of diskspace.
+
+ Once again, check the documentation of your hardware for
+ more info. Going out-of-spec like in the example might
+ or might not work. Give it a try or get another more
+ capable controller.
+
+ <sect2><heading>Hard or soft sectoring</heading>
+ <p>
+ Most ESDI drives allow hard or soft sectoring to be
+ selected using a jumper. Hard sectoring means that the
+ drive will produce a sector pulse on the start of each
+ new sector. The controller uses this pulse to tell when
+ it should start to write or read.
+
+ Hard sectoring allows a selection of sector size (normally
+ 256, 512 or 1024 bytes per formatted sector). FreeBSD uses
+ 512 byte sectors. The number of sectors per track also varies
+ while still using the same number of bytes per formatted sector.
+ The number of <em>unformatted</em> bytes per sector varies,
+ dependent on your controller it needs more or less overhead
+ bytes to work correctly. Pushing more sectors on a track
+ of course gives you more usable space, but might give
+ problems if your controller needs more bytes than the
+ drive offers.
+
+ In case of soft sectoring, the controller itself determines
+ where to start/stop reading or writing. For ESDI
+ hard sectoring is the default (at least on everything
+ I came across). I never felt the urge to try soft sectoring.
+
+ In general, experiment with sector settings before you install
+ FreeBSD because you need to re-run the low-level format
+ after each change.
+
+ <sect2><heading>Low level formatting</heading>
+ <p>
+ ESDI drives need to be low level formatted before they
+ are usable. A reformat is needed whenever you figgle
+ with the number of sectors/track jumpers or the
+ physical orientation of the drive (horizontal, vertical).
+ So, first think, then format.
+ The format time must not be underestimated, for big
+ disks it can take hours.
+
+ After a low level format, a surface scan is done to
+ find and flag bad sectors. Most disks have a
+ manufacturer bad block list listed on a piece of paper
+ or adhesive sticker. In addition, on most disks the
+ list is also written onto the disk.
+ Please use the manufacturer's list. It is much easier
+ to remap a defect now than after FreeBSD is installed.
+
+ Stay away from low-level formatters that mark all
+ sectors of a track as bad as soon as they find one
+ bad sector. Not only does this waste space, it also
+ and more importantly causes you grief with bad144
+ (see the section on bad144).
+
+ <sect2><heading>Translations</heading>
+ <p>
+ Translations, although not exclusively a ESDI-only problem,
+ might give you real trouble.
+ Translations come in multiple flavours. Most of them
+ have in common that they attempt to work around the
+ limitations posed upon disk geometries by the original
+ IBM PC/AT design (thanks IBM!).
+
+ First of all there is the (in)famous 1024 cylinder limit.
+ For a system to be able to boot, the stuff (whatever
+ operating system) must be in the first 1024 cylinders
+ of a disk. Only 10 bits are available to encode the
+ cylinder number. For the number of sectors the limit
+ is 64 (0-63).
+ When you combine the 1024 cylinder limit with the 16 head
+ limit (also a design feature) you max out at fairly limited
+ disk sizes.
+
+ To work around this problem, the manufacturers of ESDI
+ PC controllers added a BIOS prom extension on their boards.
+ This BIOS extension handles disk I/O for booting (and for
+ some operating systems <it>all</it> disk I/O) by using
+ translation. For instance, a big drive might be presented
+ to the system as having 32 heads and 64 sectors/track.
+ The result is that the number of cylinders is reduced to
+ something below 1024 and is therefore usable by the system
+ without problems.
+ It is noteworthy to know that FreeBSD after it's kernel has
+ started no longer uses the BIOS. More on this later.
+
+ A second reason for translations is the fact that most
+ older system BIOSes could only handle drives with 17 sectors
+ per track (the old ST412 standard). Newer system BIOSes
+ usually have a user-defined drive type (in most cases this is
+ drive type 47).
+
+ <em>Whatever you do to translations after reading this document,
+ keep in mind that if you have multiple operating systems on the
+ same disk, all must use the same translation</em>
+
+ While on the subject of translations, I've seen one controller
+ type (but there are probably more like this) offer the option
+ to logically split a drive in multiple partitions as a BIOS
+ option. I had select 1 drive == 1 partition because this
+ controller wrote this info onto the disk. On powerup it
+ read the info and presented itself to the system based on
+ the info from the disk.
+
+ <sect2><heading>Spare sectoring</heading>
+ <p>
+ Most ESDI controllers offer the possibility to remap bad sectors.
+ During/after the low-level format of the disk bad sectors are
+ marked as such, and a replacement sector is put in place
+ (logically of course) of the bad one.
+
+ In most cases the remapping is done by using N-1 sectors on
+ each track for actual datastorage, and sector N itself is
+ the spare sector. N is the total number of sectors physically
+ available on the track.
+ The idea behind this is that the operating system sees
+ a 'perfect' disk without bad sectors. In the case of
+ FreeBSD this concept is not usable.
+
+ The problem is that the translation from <it>bad</it> to <it>good</it>
+ is performed by the BIOS of the ESDI controller. FreeBSD,
+ being a true 32 bit operating system, does not use the BIOS
+ after it has been booted. Instead, it has device drivers that
+ talk directly to the hardware.
+
+ <em>So: don't use spare sectoring, bad block remapping or
+ whatever it may be called by the controller manufacturer when you
+ want to use the disk for FreeBSD.</em>
+
+ <sect2><heading>Bad block handling</heading>
+ <p>
+ The preceding section leaves us with a problem. The controller's
+ bad block handling is not usable and still FreeBSD's filesystems
+ assume perfect media without any flaws.
+ To solve this problem, FreeBSD use the <it>bad144</it> tool.
+ Bad144 (named after a Digital Equipment standard for bad block
+ handling) scans a FreeBSD slice for bad blocks. Having found
+ these bad blocks, it writes a table with the offending block
+ numbers to the end of the FreeBSD slice.
+
+ When the disk is in operation, the diskaccesses are checked
+ against the table read from the disk. Whenever a blocknumber
+ is requested that is in the bad144 list, a replacement block
+ (also from the end of the FreeBSD slice) is used.
+ In this way, the bad144 replacement scheme presents 'perfect'
+ media to the FreeBSD filesystems.
+
+ There are a number of potential pitfalls associated with
+ the use of bad144.
+ First of all, the slice cannot have more than 126 bad sectors.
+ If your drive has a high number of bad sectors, you might need
+ to divide it into multiple FreeBSD slices each containing less
+ than 126 bad sectors. Stay away from low-level format programs
+ that mark <em>every</em> sector of a track as bad when
+ they find a flaw on the track. As you can imagine, the
+ 126 limit is quickly reached when the low-level format is done
+ this way.
+
+ Second, if the slice contains the root filesystem, the slice
+ should be within the 1024 cylinder BIOS limit. During the
+ boot process the bad144 list is read using the BIOS and this
+ only succeeds when the list is within the 1024 cylinder limit.
+ <em>Note</em> that the restriction is not that only the root
+ <em>filesystem</em> must be within the 1024 cylinder limit, but
+ rather the entire <em>slice</em> that contains the root filesystem.
+
+
+ <sect2><heading>Kernel configuration</heading>
+ <p>
+ ESDI disks are handled by the same <it>wd</it>driver as
+ IDE and ST412 MFM disks. The <it>wd</it> driver should work
+ for all WD1003 compatible interfaces.
+
+ Most hardware is jumperable for one of two different I/O
+ address ranges and IRQ lines. This allows you to have
+ two wd type controllers in one system.
+
+ When your hardware allows non-standard strappings, you
+ can use these with FreeBSD as long as you enter the
+ correct info into the kernel config file.
+ An example from the kernel config file (they live in
+ <tt>/sys/i386/conf</tt> BTW).
+
+<tscreen><verb>
+# First WD compatible controller
+controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr
+disk wd0 at wdc0 drive 0
+disk wd1 at wdc0 drive 1
+
+# Second WD compatible controller
+controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr
+disk wd2 at wdc1 drive 0
+disk wd3 at wdc1 drive 1
+</verb></tscreen>
+
+<!--
+ <sect2><heading>Tuning your ESDI kernel setup</heading>
+ <p>
+-->
+
+ <sect1><heading>Particulars on ESDI hardware</heading>
+ <p>
+ <sect2><heading>Adaptec 2320 controllers</heading>
+ <p>
+ I succesfully installed FreeBSD onto a ESDI disk controlled by a
+ ACB-2320. No other operating system was present on the disk.
+
+ To do so I low level formatted the disk using NEFMT.EXE
+ (<it>ftp</it>able from <it>www.adaptec.com</it>) and answered NO
+ to the question whether the disk should be formatted with a
+ spare sector on each track. The BIOS on the ACD-2320 was
+ disabled. I used the 'free configurable' option in the system
+ BIOS to allow the BIOS to boot it.
+
+ Before using NEFMT.EXE I tried to format the disk using the
+ ACB-2320 BIOS builtin formatter. This proved to be a showstopper,
+ because it didn't give me an option to disable spare sectoring.
+ With spare sectoring enabled the FreeBSD installation
+ process broke down on the bad144 run.
+
+ Please check carefully which ACB-232xy variant you have. The
+ x is either 0 or 2, indicating a controller without or with
+ a floppy controller on board.
+
+ The y is more interesting. It can either be a blank,
+ a "A-8" or a "D". A blank indicates a plain 10 Mbits/second
+ controller. An "A-8" indicates a 15 Mbits/second controller
+ capable of handling 52 sectors/track.
+ A "D" means a 15 Mbits/second controller that can also
+ handle drives with > 36 sectors/track (also 52 ?).
+
+ All variations should be capable of using 1:1 interleaving. Use 1:1,
+ FreeBSD is fast enough to handle it.
+
+ <sect2><heading>Western Digital WD1007 controllers</heading>
+ <p>
+ I succesfully installed FreeBSD onto a ESDI disk controlled by a
+ WD1007 controller. To be precise, it was a WD1007-WA2. Other
+ variations of the WD1007 do exist.
+
+ To get it to work, I had to disable the sector translation and
+ the WD1007's onboard BIOS. This implied I could not use
+ the low-level formatter built into this BIOS. Instead, I grabbed
+ WDFMT.EXE from www.wdc.com Running this formatted my drive
+ just fine.
+
+ <sect2><heading>Ultrastor U14F controllers</heading>
+ <p>
+ According to multiple reports from the net, Ultrastor ESDI
+ boards work OK with FreeBSD. I lack any further info on
+ particular settings.
+
+<!--
+
+ <sect1><heading>Tracking down problems</heading>
+ <p>
+-->
+
+ <sect1><heading>Further reading<label id="esdi:further-reading"></>
+ <p>
+ If you intend to do some serious ESDI hacking, you might want to
+ have the official standard at hand:
+
+ The latest ANSI X3T10 committee document is:
+ <itemize>
+<item>Enhanced Small Device Interface (ESDI) &lsqb;X3.170-1990/X3.170a-1991&rsqb;
+ &lsqb;X3T10/792D Rev 11&rsqb;
+ </itemize>
+ On Usenet the newsgroup <htmlurl url="news:comp.periphs"
+ name="comp.periphs"> is a noteworthy place to look
+ for more info.
+
+ The World Wide Web (WWW) also proves to be a very handy info source:
+ For info on Adaptec ESDI controllers see <htmlurl
+ url="http://www.adaptec.com/">.
+ For info on Western Digital controllers see <htmlurl
+ url="http://www.wdc.com/">.
+
+ <sect1>Thanks to...
+ <p>
+ Andrew Gordon for sending me an Adaptec 2320 controller and ESDI disk
+ for testing.
+
diff --git a/handbook/firewalls.sgml b/handbook/firewalls.sgml
new file mode 100644
index 0000000000..7cf9288fe3
--- /dev/null
+++ b/handbook/firewalls.sgml
@@ -0,0 +1,525 @@
+<!-- $Id: firewalls.sgml,v 1.1 1995-10-14 21:49:45 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+
+<sect><heading>Firewalls<label id="firewalls"></heading>
+
+<p><em>Contributed by &a.gpalmer;.<newline>4th of October 1995</em>
+
+Firewalls are an area of increasing interest for people who are
+connected to the Internet, and are even finding applications on
+private networks to provide enhanced security. This section will
+hopefully explain what firewalls are, how to use them, and how to use
+the facilities provided in the FreeBSD kernel to impliment them.
+
+<quote><bf>Note</bf>: People often think that having a firewall between
+your companies internal network and the ``Big Bad Internet'' will
+solve all your security problems. It may help, but a poorly setup
+firewall system is more of a security risk than not having one at all.
+A firewall can only add another layer of security to your systems, but
+they will not be able to stop a really determined hacker from
+penetrating your internal network. If you let internal security lapse
+because you believe your firewall to be impenetrable, you have just
+made the hackers job that bit easier.</quote>
+
+<sect1><heading>What is a firewall?</heading>
+
+<p>There are currently two distinct types of firewalls in common
+use on the Internet today. The first type is more properly called
+a <bf>packet filtering router</bf>, 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 <bf>proxy
+servers</bf>, rely on daemons to provide authentication and to
+forward packets, possibly on a multi-homed machine which has
+kernel packet forwarding disabled.
+
+<p>Sometimes sites combine the two types of firewalls, so that only a
+certain machine (known as a <bf>bastion host</bf>) 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.
+
+<p>FreeBSD comes with a kernel packet filter (known as <tt>IPFW</tt>),
+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 vareity of proxy servers available that it would be
+impossible to cover them in this document.
+
+<sect2><heading>Packet filtering routers<label id="firewalls:packet_filters"></heading>
+
+<p>A router is a machine which forwards packets between two or more
+networks. A packet filtering router has an extra piece of code in it's
+kernel, which compares each packet to a list of rules before deciding
+if it should be forwarded or not. Most modern IP routing software has
+packet filtering code in it, which defaults to forwarding all
+packets. To enable the filters, you need to define a set of rules for
+the filtering code, so that it can decide if the packet should be
+allowed to pass or not.
+
+<p>To decide if a packet should be passed on or not, the code looks
+through it's set of rules for a rule which matches the contents of
+this packets headers. Once a match is found, the rule action is
+obeyed. The rule action could be to drop the packet, to forward the
+packet, or even to send an ICMP message back to the originator. Only
+the first match counts, as the rules are searched in order. Hence, the
+list of rules can be referred to as a ``rule chain''.
+
+<p>The packet matching criteria varies depending on the software used,
+but typically you can specify rules which depend on the source IP
+address of the packet, the destination IP address, the source port
+number, the destination port number (for protocols which support
+ports), or even the packet type (UDP, TCP, ICMP, etc).
+
+<sect2><heading>Proxy servers<label id="firewalls:proxy_servers"></heading>
+
+<p>Proxy servers are machines which have had the normal system daemons
+(telnetd, ftpd, etc) replaced with special servers. These servers are
+called <bf>proxy servers</bf> as they normally only allow onward
+connections to be made. This enables you to run (for example) a proxy
+telnet server on your firewall host, and people can telnet in to your
+firewall from the outside, go through some authentication mechanism,
+and then gain access to the internal network (alternatively, proxy
+servers can be used for signals coming from the internal network and
+heading out).
+
+<p>Proxy servers are normally more secure than normal servers, and
+often have a wider variety of authentication mechanisms available,
+including ``one-shot'' password systems so that even if someone
+manages to discover what password you used, they will not be able to use
+it to gain access to your systems as the password instantly
+expires. As they do not actually give users access to the host machine,
+it becomes a lot more difficult for someone to install backdoors
+around your security system.
+
+<p>Proxy servers often have ways of restricting access further, so
+that only certain hosts can gain access to the servers, and often they
+can be set up so that you can limit which users can talk to which
+destination machine. Again, what facilities are available depends
+largely on what proxy software you choose.
+
+<sect1><heading>What does <tt>IPFW</tt> allow me to do?</heading>
+
+<p><tt>IPFW</tt>, the software supplied with FreeBSD, is a packet
+filtering and accounting system which resides in the kernel, and has a
+user-land control utility, <tt>ipfw(8)</tt>. Together, they
+allow you to define and query the rules currently used by the kernel
+in its routing decisions.
+
+<p>There are two related parts to <tt>IPFW</tt>. 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.
+
+<p>As a result of the way that <tt>IPFW</tt> is designed, you can use
+<tt>IPFW</tt> on non-router machines to perform packet filtering on
+incoming and outgoing connections. This is a special case of the more
+general use of <tt>IPFW</tt>, and the same commands and techniques
+should be used in this situation.
+
+<sect1><heading>Enabling <tt>IPFW</tt> on FreeBSD</heading>
+
+<p>As the main part of the <tt>IPFW</tt> 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
+<ref id="kernelconfig" name="reconfiguring the kernel"> for more
+details on how to recompile your kernel.
+
+<p>There are currently three kernel configuration options
+relevant to IPFW:
+
+<descrip>
+<tag/options IPFIREWALL/ Compiles into the kernel the code for packet
+filtering.
+
+<tag/options IPFIREWALL_VERBOSE/ Enables code to allow logging of
+packets through <tt>syslogd</tt>. Without this option, even if you
+specify that packets should be logged in the filter rules, nothing
+will happen.
+
+<tag/options IPACCT/ Turns on the IP accounting facilities.
+
+</descrip>
+
+<sect1><heading>Configuring <tt>IPFW</tt></heading>
+
+<p>The configuration of the <tt>IPFW</tt> software is done through the
+<tt>ipfw(8)</tt> utility. The syntax for this command looks
+quite complicated, but it is relatively simple once you understand
+it's structure.
+
+<p>There are currently two different command line formats for the
+utility, depending on what you are doing. The first form is used when
+adding/deleting entries from the firewall or accounting chains, or
+when clearing the counters for an entry on the accounting chain. The
+second form is used for more general actions, such as flushing the
+rule chains, listing the rule chains or setting the default policy.
+
+<sect2><heading>Altering the <tt>IPFW</tt> rules</heading>
+
+<p>The syntax for this form of the command is:
+<tscreen>
+ipfw [-n] <em>command</em> <em>action</em> <em>protocol</em> <em>addresses</em>
+</tscreen>
+
+<p>There is one valid flag when using this form of the command:
+
+<descrip>
+<tag/-n/Do not attempt to resolve given addresses.
+</descrip>
+
+The <em>command</em> given can be shortened to the shortest unique
+form. The valid <em>commands</em> are:
+
+<descrip>
+
+<tag/addfirewall/Add an entry to the firewall rule list
+
+<tag/delfirewall/Delete an entry from the firewall rule list
+
+<tag/addaccounting/Add an entry to the accounting rule list
+
+<tag/delaccounting/Delete an entry from the accounting rule list
+
+<tag/clraccounting/Clear the counters for an accounting rule entry.
+
+</descrip>
+
+If no command is given, it will default <bf>addfirewall</bf> or
+<bf>addaccounting</bf> depending on the arguments given.
+
+<p>Currently, the firewall support in the kernel applies a set of
+weights to the rule being added. This means that the rules will
+<em>not</em> be evaluated in the order that they are given to the
+system. The weighting system is designed so that rules which are very
+specific are evaluated first, and rules which cover very large ranges
+are evaluated last. In other words, a rule which applies to a specific
+port on a specific host will have a higher priority than a rule which
+applies to that same port, but on a range of hosts, or that host on a
+range of ports.
+
+<p>The weighting system is not perfect, however, and can lead to
+problems. The best way to see what order it has put your rules in is
+to use the <bf>list</bf> command, as that command lists the rules in
+the order that they are evaluated, not the order that they were fed to
+the system.
+
+<p>The <em>actions</em> available depend on which rule chain the
+entry is destined for. For the firewall chain, valid
+<em>actions</em> are:
+
+<descrip>
+
+<tag/reject/Drop the packet, and send an ICMP HOST_UNREACHABLE packet
+to the source.
+
+<tag/lreject/As <bf>reject</bf>, but also log the packet details.
+
+<tag/deny/Drop the packet.
+
+<tag/ldeny/As <bf>deny</bf>, but also log the packet details.
+
+<tag/log/Log the packets details and pass it on as normal.
+
+<tag/accept/Pass the packet on as normal.
+
+<tag/pass/Synonym for <bf>accept</bf>.
+
+</descrip>
+
+For the accounting chain, valid <em>actions</em> are:
+
+<descrip>
+
+<tag/single/Count packets matching the address specifier.
+
+<tag/bidirectional/Count packets matching the address specifier, and
+also packets travelling in the opposite direction (i.e. those going
+from ``destination'' to ``source'').
+
+</descrip>
+
+<p>Each <em>action</em> will be recognized by the shortest unambigious
+prefix.
+
+The <em>protocols</em> which can be specified are:
+
+<descrip>
+
+<tag/all/Matches any IP packet
+
+<tag/icmp/Matches ICMP packets
+
+<tag/tcp/Matches TCP packets
+
+<tag/udp/Matches UDP packets
+
+<tag/syn/Matches the TCP SYN (synchronization) packet used during TCP
+connection negotiation. You can use this to block ``incoming'' TCP
+connections, but allow ``outgoing'' TCP connections.
+</descrip>
+
+<p>The <em>address</em> specification is:
+<tscreen>
+&lsqb;<bf>from</bf> &lt;<em>address/mask</em>&gt;&lsqb;<em>port</em>&rsqb;&rsqb; &lsqb;<bf>to</bf>
+ &lt;<em>address/mask</em>&gt;&lsqb;<em>port</em>&rsqb;&rsqb; &lsqb;<bf>via</bf> &lt;<em>interface</em>&gt;&rsqb;
+</tscreen>
+
+<p>You can only specify <em>port</em> in conjunction with
+<em>protocols</em> which support ports (UDP, TCP and SYN).
+
+<p>The order of the <bf>from</bf>, <bf>to</bf>, and
+<bf>via</bf> keywords is unimportant. Any of them can be omitted,
+in which case a default entry for that keyword will be supplied which
+matches everything.
+
+<p>The <bf>via</bf> is optional and may specify the IP address or
+domain name of a local IP interface, or an interface name (e.g.
+<tt>ed0</tt>) to match only packets coming through this interface. The
+keyword <bf>via</bf> can be substituted by <bf>on</bf>, for
+readability reasons.
+
+<p>The syntax used to specify an <tt>&lt;address/mask&gt;</tt> is:
+<tscreen>
+&lt;address&gt;
+</tscreen>
+or
+<tscreen>
+&lt;address&gt;/mask-bits
+</tscreen>
+or
+<tscreen>
+&lt;address&gt;:mask-pattern
+</tscreen>
+
+<p>A valid hostname may be specified in place of the IP
+address. <tt>mask-bits</tt> is a decimal number representing how many
+bits in the address mask should be set. e.g. specifying
+<tscreen>
+192.216.222.1/24
+</tscreen>
+will create a mask which will allow any address in a class C subnet
+(in this case, 192.216.222) to be matched. <tt>mask-pattern</tt> is an IP
+address which will be logically AND'ed with the address given. The
+keyword <tt>any</tt> may be used to specify ``any IP address''.
+<p>The port numbers to be blocked are specified as:
+<tscreen>
+port&lsqb;,port&lsqb;,port&lsqb;...&rsqb;&rsqb;&rsqb;
+</tscreen>
+to specify either a single port or a list of ports, or
+<tscreen><verb>
+port:port
+</verb></tscreen>
+to specify a range of ports. The name of a service (from
+<em>/etc/services</em>) can be used instead of a numeric port value.
+
+<sect2><heading>Listing/flushing the <tt>IPFW</tt> rules</heading>
+
+<p>The syntax for this form of the command is:
+<tscreen>
+ipfw &lsqb;-ans&rsqb; <em>command</em> &lsqb;<em>argument</em>&rsqb;
+</tscreen>
+
+<p>There are three valid flags when using this form of the command:
+
+<descrip>
+
+<tag/-a/While listing, show counter values. This option is the only
+way to see accounting counters. Works only with <bf>-s</bf>.
+
+<tag/-n/Do not attempt to resolve given addresses.
+
+<tag/-s/Use short listing form. This should be used with <bf>-a</bf>
+to see accounting counters. The short form listing is incompatible
+with the input syntax used by the <tt>ipfw(8)</tt> utility.
+
+</descrip>
+
+The <em>command</em> given can be shortened to the shortest unique
+form. The valid <em>commands</em> are:
+
+<descrip>
+
+<tag/list/List the chain rule entries. Unless the <bf>-s</bf> flag is
+given, the format is compatable with the command line syntax.
+
+<tag/flush/Flush the chain rule entries.
+
+<tag/zero/Clear counters for the entire accounting chain.
+
+<tag/policy/Set or display the default policy for the firewall
+code. Without an argument, the current policy will be displayed.
+
+</descrip>
+
+The <bf>list</bf> and <bf>flush</bf> commands may optionally be passed
+an <em>argument</em> to specify which chain to flush. Valid arguments are:
+
+<descrip>
+
+<tag/firewall/The packet filter chain.
+
+<tag/accounting/The accounting chain.
+
+</descrip>
+
+<p>The <bf>policy</bf> command can be given one of two arguments:
+
+<descrip>
+
+<tag/accept/If a packet is not matched by any rule, pass it on.
+
+<tag/deny/If a packet is not matched by any rule, do not pass it on.
+
+</descrip>
+
+As usual, the arguments can be shortened to the shortest unique form
+(in this case, the first letter).
+
+<sect1><heading>Example commands for ipfw</heading>
+
+<p>This command will deny all packets from the host
+<bf>evil.hacker.org</bf> to the telnet port of the host
+<bf>nice.people.org</bf> by being forwarded by the router:
+
+<tscreen><verb>
+ipfw addf deny tcp from evil.hacker.org to nice.people.org telnet
+</verb></tscreen>
+
+<p>The next example denies and logs any TCP traffic from the entire
+<bf>hacker.org</bf> network (a class C) to the <bf>nice.people.org</bf>
+machine (any port).
+
+<tscreen><verb>
+ipfw addf ldeny tcp from evil.hacker.org/24 to nice.people.org
+</verb></tscreen>
+
+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:
+
+<tscreen><verb>
+ipfw addf deny syn to my.org/28 6000
+</verb></tscreen>
+
+To allow access to the SUP server on <bf>sup.FreeBSD.ORG</bf>, use the
+following command:
+
+<tscreen><verb>
+ipfw addf accept syn to sup.FreeBSD.ORG supfilesrv
+</verb></tscreen>
+
+To see the accounting records:
+<tscreen><verb>
+ipfw -sa list accounting
+</verb></tscreen>
+or in the short form
+<tscreen><verb>
+ipfw -sa l a
+</verb></tscreen>
+
+<sect1><heading>Building a packet filtering firewall</heading>
+
+<p><quote><bf>Note:</bf> The following suggestions are just that:
+suggestions. The requirements of each firewall are different and I
+cannot tell you how to build a firewall to meet your particular
+requirements.</quote>
+
+<p>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 of `deny' as it allows tracing of
+possible attacks and also modification of the firewall rules if your
+requirements alter.
+
+<quote><bf>Note:</BF> If you use the logging versions of the
+<bf>accept</bf> command, it can generate <em>large</em> ammounts
+of log data as one log line will be generated for every packet
+that passes through the firewall, so large ftp/http transfers,
+etc, will really slow the system down. It also increases the
+latencies on those packets as it requires more work to be done by
+the kernel before the packet can be passed on. syslogd with also
+start using up a lot more processor time as it logs all the extra
+data to disk, and it could quite easily fill the partition
+<tt>/var/log</tt> is located on.</quote>
+
+<p>As currently supplied, FreeBSD does not have the ability to
+load firewall rules at boot time. My suggestion is to put a call
+to a shell script in the <tt>/etc/netstart</tt> script. Put the
+call early enough in the netstart file so that the firewall is
+configured before any of the IP interfaces are configured. This
+means that there is no window during which time your network is
+open.
+
+<p>The actual script used to load the rules is entirely up to
+you. There is currently no support in the <tt>ipfw</tt> utility for
+loading multiple rules in the one command. The system I use is to use
+the command:
+
+<tscreen><verb>
+# ipfw list
+</verb></tscreen>
+
+to write a list of the current rules out to a file, and then use a
+text editor to prepend ``<tt>ipfw </tt>'' before all the lines. This
+will allow the script to be fed into /bin/sh and reload the rules into
+the kernel. Perhaps not the most efficient way, but it works.
+
+<p>The next problem is what your firewall should actually <bf>DO</bf>!
+This is largely dependant 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:
+
+<itemize>
+
+ <item>Block all incoming access to ports below 1000 for TCP. This is
+where most of the security sensitive services are, like finger, smtp
+(mail) and telnet.
+
+ <item>Block incoming SYN connections to ports between 1001 and 1024
+(this will allow internal users to rsh/rlogin to the outside). If you
+do not want to allow rsh/rlogin connections from the inside to the
+outside, then extend the above suggestion to cover ports 1-1024.
+
+ <item>Block <bf>all</bf> 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 outoing 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.
+
+ <item>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 habbit of doing <tt>xhost +</tt> 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.
+
+ <item>Check what ports any internal servers use (e.g. SQL servers,
+etc). It's probably a good idea to block those as well, as they
+normally fall outside the 1-1024 range specified above.
+
+</itemize>
+
+<p>Of course, if you want to make sure that no un-authorised traffic
+gets through the firewall, change the default policy to ``deny''. This
+will mean that any traffic which is allowed through has to be
+specified explicitly in an ``accept'' or ``allow'' filter rule. Which
+ports you allow through is again something that you will have to
+decide for yourself. If you do set the default policy to be deny, you
+will probably want to install proxy servers, as no traffic will be
+able to get OUT either unless you allow TCP SYN connections going form
+the inside out.
+
+<p>As I said above, these are only <em>guidelines</em>. 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.
diff --git a/handbook/kernelconfig.sgml b/handbook/kernelconfig.sgml
new file mode 100644
index 0000000000..a565ee4957
--- /dev/null
+++ b/handbook/kernelconfig.sgml
@@ -0,0 +1,1206 @@
+<!-- $Id: kernelconfig.sgml,v 1.1 1995-10-07 04:31:31 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+<!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> -->
+ <chapt><heading>Configuring the FreeBSD Kernel<label id="kernelconfig"></heading>
+
+ <p><em>Contributed by &a.jehamby;.<newline>6 October 1995.</em>
+
+ This large section of the handbook discusses the basics of
+ building your own custom kernel for FreeBSD. This section
+ is appropriate for both novice system administrators and
+ those with advanced Unix experience.
+
+ <sect><heading>Why build a custom kernel?</heading>
+
+ <p>Building a custom kernel is one of the most important
+ rites of passage every Unix system administrator must
+ learn. This process, while time-consuming, will provide
+ many benefits to your FreeBSD system. Unlike the GENERIC
+ kernel, which must support every possible SCSI and
+ network card, along with tons of other rarely used
+ hardware support, a custom kernel only contains support
+ for <em>your</em> PC's hardware. This has a number of
+ benefits:
+
+ <itemize>
+
+ <item>It will take less time to boot because it does not
+ have to spend time probing for hardware which you
+ do not have.
+
+ <item>A custom kernel often uses less memory, which is
+ important because the kernel is the one process which
+ must always be present in memory, and so all of that
+ unused code ties up pages of RAM that your programs
+ would otherwise be able to use. Therefore, on a
+ system with limited RAM, building a custom kernel is
+ of critical importance.
+
+ <item>Finally, there are several kernel options which
+ you can tune to fit your needs, and device driver
+ support for things like sound cards which you can
+ include in your kernel but are <em>not</em> present
+ in the GENERIC kernel.
+
+ </itemize></p>
+
+ <sect><heading>Building and Installing a Custom Kernel</heading>
+
+ <p>First, let us take a quick tour of the kernel build
+ directory. All directories mentioned will be relative to
+ the main <tt>/usr/src/sys</tt> directory, which is also
+ accessible through <tt>/sys</tt>. There are a number of
+ subdirectories here representing different parts of the
+ kernel, but the most important, for our purposes, are
+ <tt>i386/conf</tt>, where you will edit your custom
+ kernel configuration, and <tt>compile</tt>, which is the
+ staging area where your kernel will be built. Notice the
+ logical organization of the directory tree, with each
+ supported device, filesystem, and option in its own
+ subdirectory. Also, anything inside the <tt>i386</tt>
+ directory deals with PC hardware only, while everything
+ outside the <tt>i386</tt> directory is common to all
+ platforms which FreeBSD could potentially be ported to.
+
+ <quote><em/Note:/ If there is <em>not</em> a
+ <tt>/usr/src/sys</tt> directory on your system, then the
+ kernel source has not been been installed. Follow the
+ instructions for installing packages to add this package
+ to your system.</quote>
+
+ Next, move to the <tt>i386/conf</tt> directory and copy
+ the GENERIC configuration file to the name you want to
+ give your kernel. For example:
+<tscreen><verb>
+# cd /usr/src/sys/i386/conf
+# cp GENERIC MYKERNEL
+</verb></tscreen>
+ Traditionally, this name is in all capital letters and,
+ if you are maintaining multiple FreeBSD machines with
+ different hardware, it's a good idea to name it after
+ your machine's hostname. We will call it MYKERNEL for
+ the purpose of this example.
+
+ <quote><em/Note:/ You must execute these and all of the
+ following commands under the root account or you will get
+ ``permission denied'' errors.</quote>
+
+ Now, edit MYKERNEL with your favorite text editor. If
+ you're just starting out, the only editor available will
+ probably be <tt>vi</tt>, which is too complex to explain
+ here, but is covered well in many books in the <ref
+ id="bibliography" name="bibliography">. Feel free to change the comment
+ lines at the top to reflect your configuration or the
+ changes you've made to differentiate it from GENERIC.
+
+ If you've build a kernel under SunOS or some other BSD
+ operating system, much of this file will be very familiar
+ to you. If you're coming from some other operating
+ system such as DOS, on the other hand, the GENERIC
+ configuration file might seem overwhelming to you, so
+ follow the descriptions in the <ref
+ id="kernelconfig:config" name="Configuration File">
+ section slowly and carefully.
+
+ When you're finished, type the following to compile and
+ install your kernel:
+<tscreen><verb>
+# /usr/sbin/config MYKERNEL
+# cd ../../compile/MYKERNEL
+# make
+# make install
+</verb></tscreen>
+ The new kernel will be copied to the root directory as
+ <tt>/kernel</tt> and the old kernel will be moved to
+ <tt>/kernel.old</tt>. Now, shutdown the system and
+ reboot to use your kernel. In case something goes wrong,
+ there are some <ref id="kernelconfig:trouble" name=
+ "troubleshooting"> instructions at the end of this
+ document. Be sure to read the section which explains how
+ to recover in case your new kernel <ref
+ id="kernelconfig:noboot" name="does not boot">.
+
+ <quote><em/Note:/ If you've added any new devices (such
+ as sound cards) you may have to add some <ref
+ id="kernelconfig:nodes" name="device nodes"> to your
+ <tt>/dev</tt> directory before you can use them.</quote>
+
+ <sect><heading>The Configuration File<label id="kernelconfig:config"></heading>
+
+ <p>The general format of a configuration file is quite
+ simple. Each line contains a keyword and one or more
+ arguments. For simplicity, most lines only contain one
+ argument. Anything following a <tt>#</tt> is considered
+ a comment and ignored. The following sections describe
+ each keyword, generally in the order they are listed in
+ GENERIC, although some related keywords have been grouped
+ together in a single section (such as Networking) even
+ though they are actually scattered throughout the GENERIC
+ file. An exhaustive list of options is present in the
+ LINT configuration file, located in the same directory as
+ GENERIC.
+
+ <sect1><heading>Mandatory Keywords</heading>
+
+ <p>These keywords are required in every kernel you build.
+
+ <descrip>
+
+ <tag>machine ``i386''</tag>
+
+ <p>The first keyword is <tt>machine</tt>, which,
+ since FreeBSD only runs on Intel 386 and compatible
+ chips, is i386.
+
+ <quote><em>Note:</em> that any keyword which
+ contains numbers used as text must be enclosed in
+ quotation marks, otherwise <tt>config</tt> gets
+ confused and thinks you mean the actual number
+ 386.</quote>
+
+ <tag>cpu ``<em>cpu_type</em>''</tag>
+
+ <p>The next keyword is <tt>cpu</tt>, which includes
+ support for each CPU supported by FreeBSD. The
+ possible values of <tt><em>cpu_type</em></tt>
+ include:
+ <itemize>
+ <item>I386_CPU
+ <item>I486_CPU
+ <item>I586_CPU
+ </itemize>
+ and multiple instances of the <tt>cpu</tt> line may
+ be present with different values of
+ <tt><em>cpu_type</em></tt> as are present in the
+ GENERIC kernel. For a custom kernel, it is best to
+ specify only the cpu you have. If, for example,
+ you have an Intel Pentium, use <tt>I586_CPU</tt>
+ for <tt><em>cpu_type</em></tt>.
+
+ <tag>ident <em>machine_name</em></tag>
+
+ <p>Next, we have <tt>ident</tt>, which is the
+ identification of the kernel. You should change
+ this from GENERIC to whatever you named your
+ kernel, in this example, MYKERNEL. The value you
+ put in <tt>ident</tt> will print when you boot up
+ the kernel, so it's useful to give a kernel a
+ different name if you want to keep it separate from
+ your usual kernel (if you want to build an
+ experimental kernel, for example). Note that, as
+ with <tt>machine</tt> and <tt> cpu</tt>, enclose
+ your kernel's name in quotation marks if it
+ contains any numbers.
+
+ <tag>maxusers <em>number</em></tag>
+
+ <p>This file sets the size of a number of important
+ system tables. This number is supposed to be
+ roughly equal to the number of simultaneous users
+ you expect to have on your machine. However, under
+ normal circumstances, you will want to set
+ <tt>maxusers</tt> to at least four, especially if
+ you're using X Windows or compiling software. The
+ reason is that the most important table set by
+ <tt>maxusers</tt> is the maximum number of
+ processes, which is set to <bf><tt>20 + 16 *
+ maxusers</tt></bf>, so if you set <tt>maxusers</tt>
+ to one, then you can only have 36 simultaneous
+ processes, including the 18 or so that the system
+ starts up at boot time, and the 15 or so you will
+ probably create when you start X Windows. Even a
+ simple task like reading a <tt>man</tt> page will
+ start up nine processes to filter, decompress, and
+ view it. Setting <tt>maxusers</tt> to 4 will allow
+ you to have up to 84 simultaneous processes, which
+ should be enough for anyone. If, however, you see
+ the dreaded ``proc table full'' error when trying
+ to start another program, or are running a server
+ with a large number of simultaneous users (like
+ Walnut Creek CDROM's FTP site!), you can always
+ increase this number and rebuild.
+
+ <quote><em/Note:/ <tt>maxuser</tt> does
+ <em>not</em> limit the number of users which can
+ log into your machine. It simply sets various
+ table sizes to reasonable values considering the
+ maximum number of users you will likely have on
+ your system and how many processes each of them
+ will be running. One keyword which
+ <em>does</em> limit the number of simultaneous
+ <em>remote logins</em> is <ref
+ id="kernelconfig:ptys" name="pseudo-device pty
+ 16">.</quote>
+
+ <tag>config <em>kernel_name</em> root on <em>root_device</em></tag>
+
+ <p>This line specifies the location and name of the
+ kernel. Traditionally the kernel is called
+ <tt>vmunix</tt> but in FreeBSD, it is aptly named
+ <tt>kernel</tt>. You should always use
+ <tt>kernel</tt> for <em>kernel_name</em> because
+ changing it will render numerous system utilities
+ inoperative. The second part of the line specifies
+ the disk and partition where the root filesystem
+ and kernel can be found. Typically this will be
+ <tt>wd0</tt> for systems with non-SCSI drives, or
+ <tt>sd0</tt> for systems with SCSI drives.
+
+ </descrip>
+
+ <sect1><heading>General Options</heading>
+
+ <p>These lines provide kernel support for various
+ filesystems and other options.
+
+ <descrip>
+
+ <label id="kernelconfig:mathemu">
+
+ <tag>options MATH_EMULATE</tag>
+
+ <p>This line allows the kernel to simulate a math
+ coprocessor if your computer does not have one (386
+ or 486SX). If you have a Pentium, a 486DX, or a
+ 386 or 486SX with a separate 387 or 487 chip, you
+ can comment this line out.
+
+ <quote><em>Note:</em> The normal math coprocessor
+ emulation routines that come with FreeBSD are
+ <em>not</em> very accurate. If you do not have a
+ math coprocessor, and you need the best accuracy,
+ I recommend that you change this option to
+ <tt>GPL_MATH_EMULATE</tt> to use the superior GNU
+ math support, which is not included by default
+ for licensing reasons.</quote>
+
+ <tag>options ``COMPAT_43''</tag>
+
+ <p>Compatibility with BSD 4.3. Leave this in; some
+ programs will act strangely if you comment this
+ out.
+
+ <tag>options BOUNCE_BUFFERS</tag>
+
+ <p>ISA devices and EISA devices operating in an ISA
+ compatibilty mode can only perform DMA (Direct
+ Memory Access) to memory below 16 megabytes. This
+ option enables such devices to work in systems with
+ more than 16 megabytes of memory.
+
+ <tag>options UCONSOLE</tag>
+
+ <p>Allow users to grab the console, useful for X
+ Windows. For example, you can create a console
+ xterm by typing <tt>xterm -C</tt>, which will
+ display any `write', `talk', and other messages you
+ receive.
+
+ <tag>options SYSVSHM</tag>
+
+ <p>This option
+ provides for System V shared memory. The most
+ common use of this is the XSHM extension in X
+ Windows, which many graphics-intensive programs
+ (such as the movie player XAnim, and Linux DOOM)
+ will automatically take advantage of for extra
+ speed. If you use X Windows, you'll definitely
+ want to include this.
+
+ <tag>options SYSVSEM</tag>
+
+ <p>Support for System V
+ semaphores. Less commonly used but only adds a few
+ hundred bytes to the kernel.
+
+ <tag>options SYSVMSG</tag>
+
+ <p>Support for System V
+ messages. Again, only adds a few hundred bytes to
+ the kernel.
+
+ <quote><em/Note:/ The <tt>ipcs(1)</tt> command will
+ tell will list any processes using using each of
+ these System V facilities.</quote>
+
+ </descrip>
+
+ <sect1><heading>Filesystem Options</heading>
+
+ <p>These options add support for various filesystems.
+ You must include at least one of these to support the
+ device you boot from; typically this will be
+ <tt>FFS</tt> if you boot from a hard drive, or
+ <tt>NFS</tt> if you are booting a diskless workstation
+ from Ethernet. You can include other commonly-used
+ filesystems in the kernel, but feel free to comment out
+ support for filesystems you use less often (perhaps the
+ MS-DOS filesystem?), since they will be dynamically
+ loaded from the Loadable Kernel Module directory
+ <tt>/lkm</tt> the first time you mount a partition of
+ that type.
+
+ <descrip>
+
+ <tag>options FFS</tag>
+
+ <p>The basic hard drive
+ filesystem; leave it in if you boot from the hard
+ disk.
+
+ <tag>options NFS</tag>
+
+ <p>Network Filesystem. Unless
+ you plan to mount partitions from a Unix file
+ server over Ethernet, you can comment this out.
+
+ <tag>options MSDOSFS</tag>
+
+ <p>MS-DOS Filesystem. Unless
+ you plan to mount a DOS formatted hard drive
+ partition at boot time, you can safely comment this
+ out. It will be automatically loaded the first
+ time you mount a DOS partition, as described above.
+ Also, the excellent <tt>mtools</tt> software (in
+ the ports collection) allows you to access DOS
+ floppies without having to mount and unmount them
+ (and does not require MSDOSFS at all).
+
+ <tag>options ``CD9660''</tag>
+
+ <p>ISO 9660 filesystem for
+ CD-ROMs. Comment it out if you do not have a
+ CD-ROM drive or only mount data CD's occasionally
+ (since it will be dynamically loaded the first time
+ you mount a data CD). Audio CD's do not need this
+ filesystem.
+
+ <tag>options PROCFS</tag>
+
+ <p>Process filesystem. This
+ is a pretend filesystem mounted on /proc which
+ allows programs like <tt>ps(1)</tt> to give you
+ more information on what processes are running.
+ Leave it in.
+
+ <tag>options MFS</tag>
+
+ <p>Memory-mapped file system.
+ This is basically a RAM disk for fast storage of
+ temporary files, useful if you have a lot of swap
+ space that you want to take advantage of. A
+ perfect place to mount an MFS partition is on the
+ <tt>/tmp</tt> directory, since many programs store
+ temporary data here. To mount an MFS RAM disk on
+ <tt>/tmp</tt>, add the following line to
+ <tt>/etc/fstab</tt> and then reboot or type
+ <tt>mount /tmp</tt>:
+<tscreen><verb>
+/dev/wd1s2b /tmp mfs rw 0 0
+</verb></tscreen>
+
+ <quote><em/Note:/ Replace the <tt>/dev/wd1s2b</tt>
+ with the name of your swap partition, which will
+ be listed in your <tt>/etc/fstab</tt> as follows:
+<tscreen><verb>
+/dev/wd1s2b none swap sw 0 0
+</verb></tscreen>
+ </quote>
+
+ <quote><em/Note:/ <!-- MFS is currently a bit
+ limited (for example, I noticed that two programs
+ ca not access the <tt>/tmp</tt> device
+ simultaneously). As such, you may want to avoid
+ it for now. --> Also, the <tt>MFS</tt> filesystem
+ can <em>not</em> be dynamically loaded, so you
+ <em>must</em> compile it into your kernel if you
+ want to experiment with it.</quote>
+
+ <tag>options QUOTA</tag>
+
+ <p>Enable disk quotas. If you
+ have a public access system, and do not want users
+ to be able to overflow the <tt>/home</tt>
+ partition, you can establish disk quotas for each
+ user. This code is a little buggy, so do not
+ enable it unless you have to. View the manual page
+ for <tt>quota(1)</tt> to learn more about disk
+ quotas.
+
+ </descrip>
+
+ <sect1><heading>Basic Controllers and Devices</heading>
+
+ <p>These sections describe the basic disk, tape, and
+ CD-ROM controllers supported by FreeBSD. There are
+ separate sections for <ref id="kernelconfig:scsi"
+ name="SCSI"> controllers and <ref
+ id="kernelconfig:network" name="network"> cards.
+
+ <descrip>
+
+ <tag>controller isa0</tag>
+
+ <p>All PC's supported by
+ FreeBSD have one of these. If you have an IBM PS/2
+ (Micro Channel Architecture), then you cannot run
+ FreeBSD at this time.
+
+ <tag>controller pci0</tag>
+
+ <p>Include this if you have a
+ PCI motherboard. This enables auto-detection of
+ PCI cards and gatewaying from the PCI to the ISA
+ bus.
+
+ <tag>controller fdc0</tag>
+
+ <p>Floppy drive controller:
+ <tt>fd0</tt> is the ``A:'' floppy drive, and
+ <tt>fd1</tt> is the ``B:'' drive. <tt>ft0</tt> is
+ a QIC-80 tape drive attached to the floppy
+ controller. Comment out any lines corresponding to
+ devices you do not have.
+
+ <quote><em/Note:/ QIC-80 tape support requires a
+ separate filter program called <tt>ft(8)</tt>, see
+ the manual page for details.</quote>
+
+ <tag>controller wdc0</tag>
+
+ <p>This is the primary IDE
+ controller. <tt>wd0</tt> and <tt>wd1</tt> are the
+ master and slave hard drive, respectively.
+ <tt>wdc1</tt> is a secondary IDE controller where
+ you might have a third or fourth hard drive, or an
+ IDE CD-ROM. Comment out the lines which do not
+ apply (if you have a SCSI hard drive, you'll
+ probably want to comment out all six lines, for
+ example).
+
+ <tag>controller wcd0<label id="kernelconfig:atapi"></tag>
+
+ <p>This device
+ provides IDE CD-ROM support. Be sure to leave
+ <tt>wdc1</tt> uncommented if your CD-ROM is on
+ its own controller card. To use this, you must
+ also include the line <tt>options ATAPI</tt>.
+
+ <tag>device npx0 at isa? port ``IO_NPX'' irq 13 vector npxintr</tag>
+
+ <p><tt>npx0</tt> is the interface to the
+ math coprocessor. If you have one then make sure
+ you've commented out <ref id="kernelconfig:mathemu"
+ name="MATH_EMULATE"> above. If you do not have a
+ math coprocessor, you can comment this out.
+
+ <tag>device wt0 at isa? port 0x300 bio irq 5 drq 1 vector wtintr</tag>
+
+ <p>Wangtek and Archive
+ QIC-02/QIC-36 tape drive support
+
+ <tag>Proprietary CD-ROM support</tag>
+
+ <p>The following
+ drivers are for the so-called <em>proprietary</em>
+ CD-ROM drives. These drives have their own
+ controller card or might plug into a sound card
+ such as the Soundblaster 16. They are <em>not</em>
+ IDE or SCSI. Most older single-speed and
+ double-speed CD-ROMs use these interfaces, while
+ newer quad-speeds are likely to be <ref
+ id="kernelconfig:atapi" name="IDE"> or <ref
+ id="kernelconfig:scsi" name="SCSI">.
+
+ <descrip>
+
+ <tag>device mcd0 at isa? port 0x300 bio irq 10 vector mcdintr</tag>
+
+ <p>Mitsumi CD-ROM (LU002,
+ LU005, FX001D).
+
+ <tag>device scd0 at isa? port 0x230 bio</tag>
+
+ <p>Sony CD-ROM (CDU31, CDU33A).
+
+ <tag>controller matcd0 at isa? port ? bio</tag>
+
+ <p>Matsushita/Panasonic CD-ROM (sold by Creative
+ Labs for Soundblaster).
+
+ </descrip>
+
+ </descrip>
+
+ <sect1><heading>SCSI Device Support<label id="kernelconfig:scsi"></heading>
+
+ <p>This section describes the various SCSI controllers
+ and devices supported by FreeBSD.
+
+ <descrip>
+
+ <tag>SCSI Controllers</tag>
+
+ <p>The next ten or so lines include support for
+ different kinds of SCSI controllers. Comment out
+ all except for the one(s) you have:
+
+ <descrip>
+
+ <tag>controller bt0 at isa? port ``IO_BT0'' bio irq ? vector btintr</tag>
+
+ <p>Most Buslogic controllers
+
+ <tag>controller uha0 at isa? port ``IO_UHA0'' bio irq ? drq 5 vector uhaintr</tag>
+
+ <p>UltraStor 14F and 34F
+
+ <tag>controller ahc0</tag>
+
+ <p>Adaptec 274x/284x/294x
+
+ <tag>controller ahb0 at isa? bio irq ? vector ahbintr</tag>
+
+ <p>Adaptec 174x
+
+ <tag>controller aha0 at isa? port ``IO_AHA0'' bio irq ? drq 5 vector ahaintr</tag>
+
+ <p>Adaptec 154x
+
+ <tag>controller aic0 at isa? port 0x340 bio irq 11 vector aicintr
+</tag>
+
+ <p>Adaptec 152x and sound cards using Adaptec AIC-6360 (slow!)
+
+ <tag>controller nca0 at isa? port 0x1f88 bio irq 10 vector ncaintr
+</tag>
+
+ <p>ProAudioSpectrum cards using NCR 5380 or Trantor T130
+
+ <tag>controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr</tag>
+
+ <p>Seagate ST01/02 8 bit controller (slow!)
+
+ <tag>controller wds0 at isa? port 0x350 bio irq 15 drq 6 vector wdsintr</tag>
+
+ <p>Western Digital WD7000 controller
+
+ <tag>controller ncr0</tag>
+
+ <p>NCR 53C810 and 53C825 PCI SCSI controller
+
+ </descrip>
+
+ <tag>options ``SCSI_DELAY=15''</tag>
+
+ <p>This causes the
+ kernel to pause 15 seconds before probing each SCSI
+ device in your system. If you only have IDE hard
+ drives, you can ignore this, otherwise you'll
+ probably want to lower this number, perhaps to 5
+ seconds, to speed up booting. Of course if you do
+ this, and FreeBSD has trouble recognizing your SCSI
+ devices, you'll have to raise it back up.
+
+ <tag>controller scbus0</tag>
+
+ <p>If you have any SCSI
+ controllers, this line provides generic SCSI
+ support. If you do not have SCSI, you can comment
+ this, and the following three lines, out.
+
+ <tag>device sd0</tag>
+
+ <p>Support for SCSI hard
+ drives.
+
+ <tag>device st0</tag>
+
+ <p>Support for SCSI tape
+ drives.
+
+ <tag>device cd0</tag>
+
+ <p>Support for SCSI CD-ROM
+ drives.
+
+ </descrip>
+
+ <sect1><heading>Console, Bus Mouse, and X Server Support</heading>
+
+ <p>You must choose one of these two console types, and, if you plan
+ to use X Windows, enable the XSERVER option and optionally, a bus
+ mouse or PS/2 mouse device.
+
+ <descrip>
+
+ <tag>device sc0 at isa? port ``IO_KBD' tty irq 1 vector scintr</tag>
+
+ <p><tt>sc0</tt> is the default
+ console driver, which resembles an SCO console.
+ Since most full-screen programs access the console
+ through a terminal database library like
+ <em>termcap</em>, it should not matter much whether
+ you use this or <tt>vt0</tt>, the VT220 compatible
+ console driver. When you log in, set your TERM
+ variable to ``scoansi'' if full-screen programs
+ have trouble running under this console.
+
+ <tag>device vt0 at isa? port ``IO_KBD'' tty irq 1 vector pcrint</tag>
+
+ <p>This is a VT220-compatible
+ console driver, backwards compatible to VT100/102.
+ It works well on some laptops which have hardware
+ incompatibilities with <tt>sc0</tt>. Also, set
+ your TERM variable to ``vt220'' when you log in if
+ full-screen programs do not run correctly on this
+ console.
+
+ <descrip>
+
+ <tag>options ``PCVT_FREEBSD=210''</tag>
+
+ <p>Required
+ with the <tt>vt0</tt> console driver.
+
+ <tag>options XSERVER</tag>
+
+ <p>This includes code
+ required to run the <tt>XFree86</tt> X Window
+ Server.
+
+ </descrip>
+
+ <tag>device mse0 at isa? port 0x23c tty irq 5 vector ms</tag>
+
+ <p>Use this device if you have a Logitech or
+ ATI InPort bus mouse card.
+
+ <quote><em/Note:/ If you have a serial mouse,
+ ignore these two lines, and instead, make sure
+ the appropriate <ref id="kernelconfig:serial"
+ name="serial"> port is enabled (probably
+ COM1).</quote>
+
+ <tag>device psm0 at isa? port ``IO_KBD'' conflicts tty irq 12 vector psmintr</tag>
+
+ <p>Use this device if your
+ mouse plugs into the PS/2 mouse port.
+
+ </descrip>
+
+ <sect1><heading>Serial and Parallel Ports</heading>
+
+ <p>Nearly all systems have these. If you are attaching a
+ printer to one of these ports, the <ref id="printing"
+ name="Printing"> section of the handbook is very
+ useful. If you are using modem, <ref id="dialup"
+ name="Dialup access"> provides extensive detail on
+ serial port configuration for use with such devices.
+
+ <descrip>
+
+ <tag>device sio0 at isa? port ``IO_COM1'' tty irq 4 vector siointr<label id="kernelconfig:serial"></tag>
+
+ <p><tt>sio0</tt>
+ through <tt>sio3</tt> are the four serial ports
+ referred to as COM1 through COM4 in the MS-DOS
+ world. Note that if you have an internal modem on
+ COM4 and a serial port at COM2 you will have to
+ change the IRQ of the modem to 2 (for obscure
+ technical reasons IRQ 2 = IRQ 9) in order to access
+ it from FreeBSD. If you have a multiport serial
+ card, check the manual page for <tt>sio(4)</tt> for
+ more information on the proper values for these
+ lines.
+
+ <tag>device lpt0 at isa? port? tty irq 7 vector lptintr</tag>
+
+ <p><tt>lpt0</tt> through <tt>lpt2</tt>
+ are the three printer ports you could conceivably
+ have. Most people just have one, though, so feel
+ free to comment out the other two lines if you do
+ not have them.
+
+ </descrip>
+
+ <sect1><heading>Networking<label id="kernelconfig:network"></heading>
+
+ <p>FreeBSD, as with Unix in general, places a
+ <em>big</em> emphasis on networking. Therefore, even
+ if you do not have an Ethernet card, pay attention to
+ the mandatory options and the dial-up networking
+ support.
+
+ <descrip>
+
+ <tag>options INET</tag>
+ Networking support. Leave it in even if you do not plan
+ to be connected to a network. Most programs require at least
+ loopback networking (i.e. making network connections within your
+ PC) so this is essentially mandatory.
+
+ <tag>Ethernet cards</tag>
+
+ <p>The next lines enable support for various Ethernet
+ cards. If you do not have a network card, you can
+ comment out all of these lines. Otherwise, you'll
+ want to leave in support for your particular
+ Ethernet card(s):
+
+ <descrip>
+
+ <tag>device de0</tag>
+
+ <p>Digital Equipment DC21040 PCI Ethernet adapter
+
+ <tag>device cx0 at isa? port 0x240 net irq 15 drq 7 vector cxintr</tag>
+
+ <p>Cronyx/Sigma multiport
+ sync/async (with Cisco or PPP framing)
+
+ <tag>device ed0 at isa? port 0x280 net irq 5 iomem 0xd8000 vector edintr</tag>
+
+ <p>Western Digital and SMC 80xx; Novell NE1000
+ and NE2000; 3Com 3C503
+
+ <tag>device el0 at isa? port 0x300 net irq 9 vector elintr</tag>
+
+ <p>3Com 3C501 (slow!)
+
+ <tag>device eg0 at isa? port 0x310 net irq 5 vector egintr</tag>
+
+ <p>3Com 3C505
+
+ <tag>device ep0 at isa? port 0x300 net irq 10 vector epintr</tag>
+
+ <p>3Com 3C509 (buggy)
+
+ <tag>device fe0 at isa? port 0x240 net irq ? vector feintr</tag>
+
+ <p>Fujitsu MB86960A/MB86965A Ethernet
+
+ <tag>device fea0 at isa? net irq ? vector feaintr</tag>
+
+ <p>DEC DEFEA EISA FDDI adapter
+
+ <tag>device ie0 at isa? port 0x360 net irq 7 iomem 0xd0000 vector ieintr</tag>
+
+ <p>AT&amp;T StarLAN 10 and EN100; 3Com 3C507;
+ unknown NI5210
+
+ <tag>device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixintr</tag>
+
+ <p>Intel EtherExpress 16
+
+ <tag>device le0 at isa? port 0x300 net irq 5 iomem 0xd0000 vector le_intr</tag>
+
+ <p>Digital Equipment EtherWorks 2 and EtherWorks
+ 3 (DEPCA, DE100, DE101, DE200, DE201, DE202,
+ DE203, DE204, DE205, DE422)
+
+ <tag>device lnc0 at isa? port 0x300 net irq 10 drq 0 vector lncintr</tag>
+
+ <p>Lance/PCnet cards (Isolan, Novell NE2100,
+ NE32-VL)
+
+ <tag>device ze0 at isa? port 0x300 net irq 5 iomem 0xd8000 vector zeintr</tag>
+
+ <p>IBM/National Semiconductor PCMCIA ethernet
+ controller.
+
+ <tag>device zp0 at isa? port 0x300 net irq 10 iomem 0xd8000 vector zpintr</tag>
+
+ <p>3Com PCMCIA Etherlink III
+
+ </descrip>
+
+ <quote><em/Note:/ With certain cards (notably the
+ NE2000) you'll have to change the port and/or IRQ
+ since there is no ``standard'' location for these
+ cards.</quote>
+
+ <tag>pseudo-device loop</tag>
+
+ <p><tt>loop</tt> is the
+ generic loopback device for TCP/IP. If you telnet
+ or FTP to <em>localhost</em>
+ (a.k.a. <tt>127.0.0.1</tt>) it will come back at
+ you through this pseudo-device. Mandatory.
+
+ <tag>pseudo-device ether</tag>
+
+ <p><tt>ether</tt> is only
+ needed if you have an Ethernet card and includes
+ generic Ethernet protocol code.
+
+ <tag>pseudo-device sl <em>number</em></tag>
+
+ <p><tt>sl</tt> is for SLIP (Serial Line Internet
+ Protocol) support. This has been almost entirely
+ supplanted by PPP, which is easier to set up,
+ better suited for modem-to-modem connections, as
+ well as more powerful. The <em>number</em> after
+ <tt>sl</tt> specifies how many simultaneous SLIP
+ sessions to support. This handbook has more
+ information on setting up a SLIP <ref id="slipc"
+ name="client"> or <ref id="slips" name="server">.
+
+ <tag>pseudo-device ppp <em>number</em></tag>
+
+ <p><tt>ppp</tt> is for kernel-mode PPP (Point-to-Point
+ Protocol) support for dial-up Internet connections.
+ There is also version of PPP implemented as a user
+ application that uses the <tt>tun</tt> and offers
+ more flexibility and features such as demand
+ dialing. If you still want to use this PPP driver,
+ read the <ref id="ppp" name="kernel-mode PPP">
+ section of the handbook. As with the <tt>sl</tt>
+ device, <em>number</em> specifies how many
+ simultaneous PPP connections to support.
+
+ <tag>pseudo-device tun <em>number</em></tag>
+
+ <p><tt>tun</tt> is used by the user-mode PPP software.
+ This program is easy to set up and very fast. It
+ also has special features such as automatic
+ dial-on-demand. The number after <tt>tun</tt>
+ specifies the number of simultaneous PPP sessions
+ to support. See the <ref id="userppp"
+ name="user-mode PPP"> section of the handbook for
+ more information.
+
+ <tag>pseudo-device bpfilter <em>number</em></tag>
+
+ <p>Berkeley packet filter. This pseudo-device allows
+ network interfaces to be placed in promiscuous
+ mode, capturing every packet on a broadcast network
+ (e.g. an ethernet). These packets can be captured
+ to disk and/or examined with the
+ <tt>tcpdump(1)</tt> program. Note that
+ implementation of this capability can seriously
+ compromise your overall network security.
+ The <em>number</em> after bpfilter is the number of
+ interfaces that can be examined
+ simultaneously. Optional, not recommended except
+ for those who are fully aware of the potential
+ pitfalls. Not all network cards support this
+ capability.
+
+ </descrip>
+
+ <sect1><heading>Sound cards</heading>
+
+ <p>This is the first section containing lines that are
+ not in the GENERIC kernel. To include sound card
+ support, you'll have to copy the appropriate lines from
+ the LINT kernel (which contains support for
+ <em>every</em> device) as follows:
+
+ <descrip>
+
+ <tag>controller snd0</tag>
+
+ <p>Generic sound driver code.
+ Required for all of the following sound cards
+ except <tt>pca</tt>.
+
+ <tag>device pas0 at isa? port 0x388 irq 10 drq 6 vector pasintr</tag>
+
+ <p>ProAudioSpectrum digital audio and MIDI.
+
+ <tag>device sb0 at isa? port 0x220 irq 7 conflicts drq 1 vector sbintr</tag>
+
+ <p>SoundBlaster digital audio.
+
+ <quote><em/Note:/ If your Soundblaster is on a
+ different IRQ (such as 5), change <tt>irq 7</tt>
+ to, for example, <tt>irq 5</tt> and remove the
+ <tt>conflicts</tt> keyword. Also, you must add
+ the line: <tt>options ``SBC_IRQ=5''</tt></quote>
+
+ <tag>device sbxvi0 at isa? drq 5</tag>
+
+ <p>SoundBlaster 16 digital 16-bit audio.
+
+ <quote><em/Note:/ If your SB16 is on a different
+ 16-bit DMA channel (such as 6 or 7), change the
+ <tt>drq 5</tt> keyword appropriately, and then
+ add the line: <tt>options
+ "SB16_DMA=6"</tt></quote>
+
+ <tag>device sbmidi0 at isa? port 0x330</tag>
+
+ <p>SoundBlaster 16 MIDI interface. If you have a
+ SoundBlaster 16, you must include this line, or the
+ kernel will not compile.
+
+ <tag>device gus0 at isa? port 0x220 irq 10 drq 1 vector gusintr</tag>
+
+ <p>Gravis Ultrasound.
+
+ <tag>device mss0 at isa? port 0x530 irq 10 drq 1 vector adintr</tag>
+
+ <p>Microsoft Sound System.
+
+ <tag>device opl0 at isa? port 0x388 conflicts</tag>
+
+ <p>AdLib FM-synthesis audio. Include this line for
+ AdLib, SoundBlaster, and ProAudioSpectrum users, if
+ you want to play MIDI songs with a program such as
+ <tt>playmidi</tt> (in the ports collection).
+
+ <tag>device mpu0 at isa? port 0x330 irq 6 drq 0</tag>
+
+ <p>Roland MPU-401 stand-alone card.
+
+ <tag>device uart0 at isa? port 0x330 irq 5 vector ``m6850intr''</tag>
+
+ <p>Stand-alone 6850 UART for MIDI.
+
+ <tag>device pca0 at isa? port ``IO_TIMER1'' tty</tag>
+
+ <p>Digital audio through PC speaker. This is going to
+ be very poor sound quality and quite CPU-intensive,
+ so you have been warned (but it does not require a
+ sound card)!
+
+ </descrip>
+
+ <quote><em/Note:/ There is some additional
+ documentation in
+ <tt>/usr/src/sys/i386/isa/sound/sound.doc</tt>.
+ Also, if you add any of these devices, be sure to
+ create the sound <ref id="kernelconfig:nodes"
+ name="device nodes">.</quote>
+
+ <sect1><heading>Pseudo-devices</heading>
+
+ <p>Pseudo-device drivers are parts of the kernel that act
+ like device drivers but do not correspond to any actual
+ hardware in the machine. The <ref
+ id="kernelconfig:network" name="network-related">
+ pseudo-devices are in that section, while the remainder
+ are here.
+
+ <descrip>
+
+ <tag>pseudo-device gzip</tag>
+
+ <p><tt>gzip</tt> allows you to run FreeBSD programs
+ that have been compressed with <tt>gzip</tt>. This
+ is really only useful when you need to compress
+ FreeBSD programs to fit on a boot floppy. You will
+ probably never need to compress programs on your
+ hard drive in this fashion, so you'll probably want
+ to comment out this line.
+ <tag>pseudo-device log</tag>
+
+ <p><tt>log</tt> is used for logging of kernel error
+ messages. Mandatory.
+
+
+ <tag>pseudo-device pty <em>number</em><label id="kernelconfig:ptys"></tag>
+
+ <p><tt>pty</tt> is a ``pseudo-terminal'' or simulated
+ login port. It's used by incoming <bf>telnet</bf>
+ and <bf>rlogin</bf> sessions, xterm, and some other
+ applications such as emacs. The <em>number</em>
+ indicates the number of <tt>pty</tt>s to create.
+ If you need more than GENERIC default of 16
+ simultaneous xterm windows and/or remote logins, be
+ sure to increase this number accordingly, up to a
+ maximum of 64.
+
+ <tag>pseudo-device snp <em>number</em></tag>
+
+ <p>Snoop device. This pseudo-device allows one
+ terminal session to watch another using the
+ <tt>watch(8)</tt> command. Note that
+ implementation of this capability has important
+ security and privacy implications. The
+ <em>number</em> after snp is the total number of
+ simultaneous snoop sessions. Optional.
+
+ <tag>pseudo-device vn</tag>
+
+ <p>Vnode driver. Allows a file to be treated as a
+ device after being set up with the
+ <tt>vnconfig(8)</tt> command. This driver can be
+ useful for manipulating floppy disk images and
+ using a file as a swap device (e.g. an MS Windows
+ swap file). Optional.
+
+ </descrip>
+
+ <sect1><heading>Joystick, PC Speaker, Miscellaneous</heading>
+
+ <p>This section describes some miscellaneous hardware
+ devices supported by FreeBSD. Note that none of these
+ lines are included in the GENERIC kernel, you'll have
+ to copy them from this handbook or the LINT kernel
+ (which contains support for <em>every</em> device):
+
+ <descrip>
+
+ <tag>device joy0 at isa? port ``IO_GAME''</tag>
+
+ <p>PC joystick device.
+
+ <tag>pseudo-device speaker</tag>
+
+ <p>Supports IBM BASIC-style noises through the PC
+ speaker. Some fun programs which use this are
+ <tt>/usr/sbin/spkrtest</tt>, which is a shell
+ script that plays some simple songs, and
+ <tt>/usr/games/piano</tt> which lets you play songs
+ using the keyboard as a simple piano (this file
+ only exists if you've installed the <em>games</em>
+ package). Also, the excellent text role-playing
+ game NetHack (in the ports collection) can be
+ configured to use this device to play songs when
+ you play musical instruments in the game.
+
+ </descrip>
+
+ <sect><heading>Making Device Nodes<label id="kernelconfig:nodes"></heading>
+
+ <p>Almost every device in the kernel has a corresponding
+ ``node'' entry in the <tt>/dev</tt> directory. These
+ nodes look like regular files, but are actually special
+ entries into the kernel which programs use to access the
+ device. The shell script <tt>/dev/MAKEDEV</tt>, which is
+ executed when you first install the operating system,
+ creates nearly all of the device nodes supported.
+ However, it does not create <em>all</em> of them, so when
+ you add support for a new device, it pays to make sure
+ that the appropriate entries are in this directory, and
+ if not, add them. Here is a simple example:
+
+ Suppose you add the IDE CD-ROM support to the kernel.
+ The line to add is:
+<tscreen><verb>
+controller wcd0
+</verb></tscreen>
+ This means that you should look for some entries that
+ start with <tt>wcd0</tt> in the <tt>/dev</tt> directory,
+ possibly followed by a letter, such as `c', or preceded
+ by the letter 'r', which means a `raw' device. It turns
+ out that those files are not there, so I must change to
+ the <tt>/dev</tt> directory and type:
+<tscreen><verb>
+# sh MAKEDEV wcd0
+</verb></tscreen>
+ When this script finishes, you will find that there are
+ now <tt>wcd0c</tt> and <tt>rwcd0c</tt> entries in
+ <tt>/dev</tt> so you know that it executed correctly.
+
+ For sound cards, the command:
+<tscreen><verb>
+# sh MAKEDEV snd0
+</verb></tscreen>
+ creates the appropriate entries. Follow this simple
+ procedure for any other non-GENERIC devices which do not
+ have entries.
+
+ <quote><em/Note:/ All SCSI controllers use the same set
+ of <tt>/dev</tt> entries, so you do not need to create
+ these. Also, network cards and SLIP/PPP pseudo-devices
+ do not have entries in <tt>/dev</tt> at all, so you do
+ not have to worry about these either.</quote>
+
+<sect><heading>If Something Goes Wrong<label id="kernelconfig:trouble"></heading>
+
+ <p>There are four categories of trouble that can occur when
+ building a custom kernel. They are:
+
+ <descrip>
+
+ <tag>Config command fails</tag>
+
+ <p>If the <tt>config</tt>
+ command fails when you give it your kernel
+ description, you've probably made a simple error
+ somewhere. Fortunately, <tt>config</tt> will print
+ the line number that it had trouble with, so you can
+ quickly skip to it with <tt>vi</tt>. For example, if
+ you see:
+<tscreen><verb>
+config: line 17: syntax error
+</verb></tscreen>
+ you can skip to the problem in <tt>vi</tt> by typing
+ ``17G'' in command mode. Make sure the keyword is
+ typed correctly, by comparing it to the GENERIC
+ kernel or another reference.
+
+ <tag>Make command fails</tag>
+
+ <p>If the <tt>make</tt>
+ command fails, it usually signals an error in your
+ kernel description, but not severe enough for
+ <tt>config</tt> to catch it. Again, look over your
+ configuration, and if you still cannot resolve the
+ problem, send mail to <tt><htmlurl
+ url="mailto:questions@freebsd.org"
+ name="questions@FreeBSD.ORG"></tt> with your kernel
+ configuration, and it should be diagnosed very
+ quickly.
+
+ <tag>Kernel will not boot<label id="kernelconfig:noboot"></tag>
+
+ <p>If your new kernel
+ does not boot, or fails to recognize your devices,
+ do not panic! Fortunately, BSD has an excellent
+ mechanism for recovering from incompatible kernels.
+ Simply type the name of the kernel you want to boot
+ from (i.e. ``kernel.old'') at the FreeBSD boot
+ prompt instead of pressing return. When
+ reconfiguring a kernel, it is always a good idea to
+ keep a kernel that is known to work on hand.
+
+ After booting with a good kernel you can check over
+ your configuration file and try to build it again.
+ One helpful resource is the
+ <tt>/var/log/messages</tt> file which records, among
+ other things, all of the kernel messages from every
+ successful boot. Also, the <tt>dmesg(8)</tt> command
+ will print the kernel messages from the current boot.
+
+ <quote><em/Note:/ If you are having trouble building
+ a kernel, make sure to keep a GENERIC, or some
+ other kernel that is known to work on hand as a
+ different name that will not get erased on the next
+ build. You cannot rely on <tt>kernel.old</tt>
+ because when installing a new kernel,
+ <tt>kernel.old</tt> is overwritten with the last
+ installed kernel which may be non-functional.
+ Also, as soon as possible, move the working kernel
+ to the proper ``kernel'' location or commands such
+ as <tt>ps(1)</tt> will not work properly. The
+ proper command to ``unlock'' the kernel file that
+ <tt>make</tt> installs (in order to move another
+ kernel back permanently) is:
+<tscreen><verb>
+# chflags noschg /kernel
+</verb></tscreen>
+ And, if you want to ``lock'' your new kernel into place, or any file
+ for that matter, so that it cannot be moved or tampered with:
+<tscreen><verb>
+# chflags schg /kernel
+</verb></tscreen>
+ </quote>
+
+ <tag>Kernel works, but <tt>ps</tt> does not work any more!</tag>
+
+ <p>If you've installed a different version
+ of the kernel from the one that the system utilities
+ have been built with, for example, an experimental
+ ``2.2.0'' kernel on a 2.1.0-RELEASE system, many
+ system-status commands like <tt>ps(1)</tt> and
+ <tt>vmstat(8)</tt> will not work any more. You must
+ recompile the <tt>libkvm</tt> library as well as
+ these utilities. This is one reason it is not
+ normally a good idea to use a different version of
+ the kernel from the rest of the operating system.
+
+ </descrip>
diff --git a/handbook/printing.sgml b/handbook/printing.sgml
new file mode 100644
index 0000000000..522749b429
--- /dev/null
+++ b/handbook/printing.sgml
@@ -0,0 +1,3877 @@
+<!-- This is an SGML document in the linuxdoc DTD describing
+ Printing with FreeBSD. By Sean Kelly, 1995.
+
+ $Id: printing.sgml,v 1.2 1995-10-01 22:16:19 jfieber Exp $
+
+ The FreeBSD Documentation Project
+
+<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN">
+
+ <article>
+ <title> Printing with FreeBSD
+ <author> Sean Kelly <tt/kelly@fsl.noaa.gov/
+ <date> 30 September 1995, (c) 1995
+
+ <abstract> This document describes printing with FreeBSD. It
+ tells how to set up printer hardware, how to configure FreeBSD
+ to use printers, and how to control the print queue and print
+ a variety of file formats. </abstract>
+
+ <toc>
+-->
+
+ <chapt><heading>Printing<label id="printing"></heading>
+
+ <p><em>Contributed by &a.kelly;<newline>30 September 1995</em>
+
+ In order to use printers with FreeBSD, you'll need to set
+ them up to work with the Berkeley line printer spooling
+ system, also known as the LPD spooling system. It's the
+ standard printer control system in FreeBSD. This section
+ introduces the LPD spooling system, often simply called LPD.
+
+ If you're already familiar with LPD or another printer
+ spooling system, you may wish to skip to section <ref
+ id="printing:intro:setup" name="Setting up the spooling
+ system">.
+
+ <sect><heading>What the Spooler Does<label
+ id="printing:intro:spooler"></heading>
+
+ <p> LPD controls everything about a host's printers. It's
+ responsible for a number of things:
+
+ <itemize>
+ <item>It controls access to attached printers and
+ printers attached to other hosts on the network.
+
+ <item>It enables users to submit files to be printed;
+ these submissions are known as <em/jobs/.
+
+ <item>It prevents multiple users from accessing a printer
+ at the same time by maintaining a <em/queue/ for each
+ printer.
+
+ <item>It can print <em/header pages/ (also known as
+ <em/banner/ or <em/burst/ pages) so users can easily
+ find jobs they've printed in a stack of printouts.
+
+ <item>It takes care of communications parameters for
+ printers connected on serial ports.
+
+ <item>It can send jobs over the network to another LPD
+ spooler on another host.
+
+ <item>It can run special filters to format jobs to be
+ printed for various printer languages or printer
+ capabilities.
+
+ <item>It can account for printer usage.
+ </itemize>
+
+ Through a configuration file, and by providing the special
+ filter programs, you can enable the LPD system to do all or
+ some subset of the above for a great variety of printer
+ hardware.
+
+ <sect><heading>Why You Should Use the Spooler<label
+ id="printing:intro:why"></heading>
+
+ <p> If you're the sole user of your system, you may be
+ wondering why you should bother with the spooler when you
+ don't need access control, header pages, or printer
+ accounting. While it's possible to enable direct access to
+ a printer, you should use the spooler anyway since
+
+ <itemize>
+ <item>LPD prints jobs in the background; you don't have
+ to wait for data to be copied to the printer.
+
+ <item>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 won't have to do
+ these steps manually.
+
+ <item>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'll
+ more easily support other software you may later add or
+ already have.
+ </itemize>
+
+ <sect><heading>Setting Up the Spooling System<label
+ id="printing:intro:setup"></heading>
+
+ <p> To use printers with the LPD spooling system, you'll need
+ to set up both your printer hardware and the LPD software.
+ This document describes two levels of setup:
+
+ <itemize>
+ <item>See section <ref name="Simple Printer Setup"
+ id="printing:simple"> to learn how to connect a
+ printer, tell LPD how to communicate with it, and
+ print plain text files to the printer.
+
+ <item>See section <ref name="Advanced Printer Setup"
+ id="printing:advanced"> to find out how to print a
+ variety of special file formats, to print header
+ pages, to print across a network, to control access to
+ printers, and to do printer accounting.
+ </itemize>
+
+
+ <sect><heading>Simple Printer Setup<label
+ id="printing:simple"></heading>
+
+ <p> This section tells how to configure printer hardware and the
+ LPD software to use the printer. It teaches the basics:
+
+ <itemize>
+ <item>Section <ref id="printing:hardware" name="Hardware
+ Setup"> gives some hints on connecting the printer to a
+ port on your computer.
+
+ <item>Section <ref id="printing:software" name="Software
+ Setup"> shows how to setup the LPD spooler configuration
+ file <tt>/etc/printcap</tt>.
+ </itemize>
+
+ If you're setting up a printer that uses a network protocol
+ to accept data to print instead of a serial or parallel interface,
+ see <ref id="printing:advanced:network:net-if" name="Printers
+ With Networked Data Stream Interaces">.
+
+ Although this section is called ``Simple Printer Setup,'' it's
+ 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.
+
+ <sect1><heading>Hardware Setup<label id="printing:hardware"></heading>
+
+ <p> This section tells about the various ways you can connect a
+ printer to your PC. It talks about the kinds of ports and
+ cables, and also the kernel configuration you may need to
+ enable FreeBSD to speak to the printer.
+
+ If you've already connected your printer and have
+ successfully printed with it under another operating system,
+ you can probably skip to section <ref id="printing:software"
+ name="Software Setup">.
+
+ <sect2><heading>Ports and Cables<label
+ id="printing:ports"></heading>
+
+ <p> Nearly all printers you can get for a PC today support
+ one or both of the following interfaces:
+
+ <itemize>
+ <item><em/Serial/ interfaces use a serial port on your
+ computer to send data to the printer. Serial
+ interfaces are common in the computer industry and
+ cables are readily available and also easy to
+ construct. Serial interfaces sometimes need special
+ cables and might require you to configure somewhat
+ complex communications options.
+
+ <item><em/Parallel/ interfaces use a parallel port on
+ your computer to send data to the printer. Parallel
+ interfaces are common in the PC market. Cables are
+ readily available but more difficult to construct by
+ hand. There are usually no communications options
+ with parallel interfaces, making their configuration
+ exceedingly simple.
+
+ <p> Parallel interfaces are sometimes known as
+ ``Centronics'' interfaces, named after the connector
+ type on the printer.
+ </itemize>
+
+ In general, serial interfaces are slower than parallel
+ interfaces. Parallel interfaces usually offer just
+ one-way communication (computer to printer) while serial
+ gives you two-way. Many newer parallel ports can also
+ receive data from the printer, but only few printers need
+ to send data back to the computer. And FreeBSD doesn't
+ support two-way parallel communication yet.
+
+ Usually, the only time you need two-way communication with
+ the printer is if the printer speaks PostScript.
+ PostScript printers can be very verbose. In fact,
+ PostScript jobs are actually programs sent to the printer;
+ they needn't produce paper at all and may return results
+ directly to the computer. PostScript also uses
+ two-way communication to tell the computer about problems,
+ such as errors in the PostScript program or paper jams.
+ Your users may be appreciative of such information.
+ Furthermore, the best way to do effective accounting with
+ a PostScript printer requires two-way communication: you
+ ask the printer for its page count (how many pages it's
+ printed in its lifetime), then send the user's job, then
+ ask again for its page count. Subtract the two values and
+ you know how much paper to charge the user.
+
+ So, which interface should you use?
+
+ <itemize>
+ <item>If you need two-way communication, use a serial
+ port. FreeBSD does not yet support two-way
+ communication over a parallel port.
+
+ <item>If you don't need two-way communication and can
+ pick parallel or serial, prefer the parallel
+ interface. It keeps a serial port free for other
+ peripherals---such as a terminal or a modem---and is
+ faster most of the time. It's also easier to
+ configure.
+
+ <item>Finally, use whatever works.
+ </itemize>
+
+
+ <sect2><heading>Parallel Ports<label id="printing:parallel"></heading>
+
+ <p> To hook up a printer using a parallel interface, connect
+ the Centronics cable between the printer and the
+ computer. The instructions that came with the printer, the
+ computer, or both should give you complete guidance.
+
+ Remember which parallel port you used on the computer. The
+ first parallel port is /dev/lpt0 to FreeBSD; the second is
+ /dev/lpt1, and so on.
+
+ <sect2><heading>Serial Ports<label id="printing:serial"></heading>
+
+ <p> To hook up a printer using a serial interface, connect
+ the proper serial cable between the printer and the
+ computer. The instructions that came with the printer,
+ the computer, or both should give you complete guidance.
+
+ If you're unsure what the ``proper serial cable'' is, you
+ may wish to try one of the following alternatives:
+ <itemize>
+ <item>A <em/modem/ cable connects each pin of the
+ connector on one end of the cable straight through to
+ its corresponding pin of the connector on the other
+ end. This type of cable is also known as a DTE-to-DCE
+ cable.
+
+ <item>A <em/null-modem/ cable connects some pins
+ straight through, swaps others (send data to receive
+ data, for example), and shorts some internally in each
+ connector hood. This type of cable is also known as a
+ DTE-to-DTE cable.
+
+ <item>A <em/serial printer/ cable, required for some
+ unusual printers, is like the null modem cable, but
+ sends some signals to their counterparts instead of
+ being internally shorted.
+ </itemize>
+
+ You should also set up the communications parameters for
+ the printer, usually through front-panel controls or DIP
+ switches on the printer. Choose the highest bps (bits per
+ second, sometimes <em/baud rate/) rate that both your
+ computer and the printer can support. Choose 7 or 8 data
+ bits; none, even, or odd parity; and 1 or 2 stop bits.
+ Also choose a flow control protocol: either none, or
+ XON/XOFF (also known as <em/in-band/ or <em/software/)
+ flow control. Remember these settings for the software
+ configuration that follows.
+
+ <sect1><heading>Software Setup<label id="printing:software"></heading>
+
+ <p> This section describes the software setup necessary to
+ print with the LPD spooling system in FreeBSD.
+
+ Here's an outline of the steps involved:
+ <enum>
+ <item>Configure your kernel, if necessary, for the port
+ you're using for the printer; section <ref
+ id="printing:kernel" name="Kernel Configuration"> tells
+ you what you need to do.
+
+ <item>Set the communications mode for the parallel port,
+ if you're using a parallel port; section <ref
+ id="printing:parallel-port-mode" name = "Setting the
+ Communication Mode for the Parallel Port"> gives
+ details.
+
+ <item>Test if the operating system can send data to the
+ printer. Section <ref id="printing:testing"
+ name="Checking Printer Communications"> gives some
+ suggestions on how to do this.
+
+ <item>Set up LPD for the printer by modifying the file
+ <tt>/etc/printcap</tt>. Section <ref
+ id="printing:printcap" name="The /etc/printcap File">
+ shows you how.
+ </enum>
+
+ <sect2><heading>Kernel Configuration<label
+ id="printing:kernel"></heading>
+
+ <p> The operating system kernel is compiled to work with a
+ specific set of devices. The serial or parallel interface
+ for your printer is a part of that set. Therefore, it
+ might be necessary to add support for an additional serial
+ or parallel port if your kernel isn't already configured
+ for one.
+
+ To find out if the kernel you're currently using supports a serial
+ interface, type
+<tscreen>
+<tt>dmesg &verbar; grep sio</tt><it/N/
+</tscreen>
+ where <it/N/ is the number of the serial port, starting
+ from zero. If you see output similar to the following
+<tscreen><verb>
+sio2 at 0x3e8-0x3ef irq 5 on isa
+sio2: type 16550A
+</verb></tscreen>
+ then the kernel supports the port.
+
+ To find out if the kernel supports a parallel interface,
+ type
+<tscreen>
+<tt>dmesg &verbar; grep lpt</tt><it/N/
+</tscreen>
+ where <it/N/ is the number of the parallel port, starting
+ from zero. If you see output similar to the following
+<tscreen><verb>
+lpt0 at 0x378-0x37f on isa
+</verb></tscreen>
+ then the kernel supports the port.
+
+ You might have to reconfigure your kernel in order for the
+ operating system to recognize and use the parallel or
+ serial port you're using for the printer.
+
+ To add support for a serial port, see the section on
+ kernel configuration. To add support for a parallel port,
+ see that section <em/and/ the section that follows.
+
+ <sect3><heading>Adding <tt>/dev</tt> Entries for the Ports
+ <label id="printing:dev-ports"></heading>
+
+ <p> Even though the kernel may support communication along
+ a serial or parallel port, you'll still need a software
+ interface through which programs running on the system
+ can send and receive data. That's what entries in the
+ <tt>/dev</tt> directory are for.
+
+ <bf>To add a <tt>/dev</tt> entry for a port:</bf>
+ <enum>
+ <item>Become root with the <tt/su/ command. Enter
+ the root password when prompted.
+
+ <item>Change to the <tt>/dev</tt> directory:
+<tscreen><verb>
+cd /dev
+</verb></tscreen>
+
+ <item>Type
+<tscreen>
+<tt> ./MAKEDEV</tt> <it/port/
+</tscreen>
+ where <it/port/ is the device entry for the port you
+ want to make. Use <tt/lpt0/ for the first parallel
+ port, <tt/lpt1/ for the second, and so on; use
+ <tt/ttyd0/ for the first serial port, <tt/ttyd1/ for
+ the second, and so on.
+
+ <item>Type
+<tscreen>
+<tt>ls -l</tt> <it/port/
+</tscreen>
+ to make sure the device entry got created.
+ </enum>
+
+ <sect3><heading>Setting the Communication Mode for the Parallel Port
+ <label id="printing:parallel-port-mode"></heading>
+
+ <p> When you're using the parallel interface, you can
+ choose whether FreeBSD should use interrupt-driven or
+ polled communication with the printer.
+
+ <itemize>
+ <item>The <em/interrupt-driven/ method is the default
+ with the GENERIC kernel. With this method, the
+ operating system uses an IRQ line to determine when
+ the printer's ready for data.
+
+ <item>The <em/polled/ method directs the operating
+ system to repeatedly ask the printer if it's ready
+ for more data. When it responds ready, the kernel
+ sends more data.
+ </itemize>
+
+ The interrupt-driven method is somewhat faster but uses
+ up a precious IRQ line. You should use whichever one
+ works.
+
+ You can set the communications mode in two ways: by
+ configuring the kernel or by using the <tt/lptcontrol/
+ program.
+
+ <bf>To set the communications mode by configuring the
+ kernel:</bf>
+ <enum>
+ <item>Edit your kernel configuration file. Look for
+ or add an <tt/lpt0/ entry. If you're setting up the
+ second parallel port, use <tt/lpt1/ instead. Use
+ <tt/lpt2/ for the third port, and so on.
+ <itemize>
+ <item>If you want interrupt-driven mode, add the <tt/irq/
+ specifer:
+<tscreen>
+<tt>device lpt0 at isa? port? tty irq <it/N/ vector lptintr</tt>
+</tscreen>
+ where <it/N/ is the IRQ number for your
+ computer's parallel port.
+
+ <item>If you want polled mode, don't add the
+ <tt/irq/ specifier:
+<tscreen>
+<tt>device lpt0 at isa? port? tty vector lptintr</tt>
+</tscreen>
+ </itemize>
+ <item>Save the file. Then configure, build, and
+ install the kernel, then reboot. See <ref id="kernelconfig"
+ name="kernel configuration"> for more details.
+ </enum>
+
+ <bf>To set the communications mode with
+ <tt/lptcontrol/:</bf>
+ <itemize>
+ <item>
+ Type
+<tscreen>
+<tt>lptcontrol -i -u <it/N/</tt>
+</tscreen>
+ to set interrupt-driven mode for <tt/lpt<it/N//.
+
+ <item>
+ Type
+<tscreen>
+<tt>lptcontrol -p -u <it/N/</tt>
+</tscreen>
+ to set polled-mode for <tt/lpt<it/N//.
+ </itemize>
+ You could put these commands in your
+ <tt>/etc/rc.local</tt> file to set the mode each time
+ your system boots. See lptcontrol(8) for more
+ information.
+
+ <sect3><heading>Checking Printer Communications<label
+ id="printing:testing"></heading>
+
+ <p> Before proceeding to configure the spooling system,
+ you should make sure the operating system can
+ successfully send data to your printer. It's a lot
+ easier to debug printer communication and the spooling
+ system separately.
+
+ To test the printer, we'll send some text to it. For
+ printers that can immediately print characters sent to
+ them, the program <tt/lptest/ is perfect: it generates
+ all 96 printable ASCII characters in 96 lines.
+
+ For a PostScript (or other language-based) printer,
+ we'll need a more sophisticated test. A small
+ PostScript program, such as the following, will suffice:
+<code>
+%!PS
+100 100 moveto 300 300 lineto stroke
+310 310 moveto
+/Helvetica findfont 12 scalefont setfont
+(Is this thing working?) show
+showpage
+</code>
+ <em/Note:/ When this document refers to a printer
+ language, I'm assuming a language like PostScript, and
+ not Hewlett Packard's PCL. Although PCL has great
+ functionality, you can intermingle plain text with its
+ escape sequences. PostScript cannot directly print
+ plain text, and that's the kind of printer language for
+ which we must make special accomodations.
+
+ <sect4><heading>Checking a Parallel Printer<label
+ id="printing:checking:parallel"></heading>
+
+ <p> This section tells you how to check if FreeBSD can
+ communicate with a printer connected to a parallel port.
+
+ <bf>To test a printer on a parallel port:</bf>
+ <enum>
+ <item>Become root with <tt/su/.
+ <item>Send data to the printer.
+ <itemize>
+ <item>If the printer can print plain text, then
+ use <tt/lptest/. Type:
+<tscreen>
+<tt>lptest > /dev/lpt<it/N/</tt>
+</tscreen>
+ where <it/N/ is the number of the parallel
+ port, starting from zero.
+
+ <item>If the printer understands PostScript or
+ other printer language, then send a small
+ program to the printer. Type
+<tscreen>
+<tt>cat > /dev/lpt<it/N/</tt>
+</tscreen>
+ Then, line by line, type the program
+ <em/carefully/ as you can't edit a line once
+ you've pressed RETURN or ENTER. When you've
+ finished entering the program, press
+ CONTROL+D, or whatever your end of file key
+ is.
+
+ <p> Alternatively, you can put the program in
+ a file and type
+<tscreen>
+<tt>cat <it/file/ > /dev/lpt<it/N/</tt>
+</tscreen>
+ where <it/file/ is the name of the file
+ containing the program you want to send to
+ the printer.
+ </itemize>
+ </enum>
+
+ You should see something print. Don't worry if the
+ text doesn't look right; we'll fix such things later.
+
+ <sect4><heading>Checking a Serial Printer<label
+ id="printing:checking:serial"></heading>
+
+ <p> This section tells you how to check if FreeBSD can
+ communicate with a printer on a serial port.
+
+ <bf>To test a printer on a serial port:</bf>
+ <enum>
+ <item>Become root with <tt/su/.
+
+ <item>Edit the file <tt>/etc/remote</tt>. Add the
+ following entry:
+<tscreen>
+<tt>printer:dv=/dev/<it/port/:br&num;<it/bps-rate/:pa=<it/parity/</tt>
+</tscreen>
+ where <it/port/ is the device entry for the serial
+ port (<tt/ttyd0/, <tt/ttyd1/, etc.), <it/bps-rate/
+ is the bits-per-second rate at which the printer
+ communicates, and <it/parity/ is the parity
+ required by the printer (either <tt/even/,
+ <tt/odd/, <tt/none/, or <tt/zero/).
+ <p>
+ Here's a sample entry for a printer connected
+ via a serial line to the third serial port at
+ 19200 bps with no parity:
+<code>
+printer:dv=/dev/ttyd2:br#19200:pa=none
+</code>
+
+ <item>Connect to the printer with <tt/tip/. Type:
+<tscreen><verb>
+tip printer
+</verb></tscreen>
+ If this step doesn't work, edit the file
+ <tt>/etc/remote</tt> again and try using
+ <tt>/dev/cuaa<it/N/</tt> instead of
+ <tt>/dev/ttyd<it/N/</tt>.
+
+ <item>Send data to the printer.
+ <itemize>
+ <item>If the printer can print plain text, then
+ use <tt/lptest/. Type:
+<tscreen><verb>
+~$lptest
+</verb></tscreen>
+
+ <item>If the printer understands PostScript or
+ other printer language, then send a small
+ program to the printer. Type the program,
+ line by line, <em/very carefully/ as
+ backspacing or other editing keys may be
+ significant to the printer. You may also need
+ to type a special end-of-file key for the
+ printer so it knows it received the whole
+ program. For PostScript printers, press
+ CONTROL+D.
+
+ <p> Alternatively, you can put the program in
+ a file and type
+<tscreen>
+<tt>&tilde;&gt;<it/file/</tt>
+</tscreen>
+ where <it/file/ is the name of the file
+ containing the program. After <tt/tip/
+ sends the file, press any required
+ end-of-file key.
+ </itemize>
+ </enum>
+
+ You should see something print. Don't worry if the
+ text doesn't look right; we'll fix that later.
+
+ <sect2><heading>Enabling the Spooler: The <tt>/etc/printcap</tt> File
+ <label id="printing:printcap"></heading>
+
+ <p> At this point, your printer should be hooked up, your
+ kernel configured to communicate with it (if necessary),
+ and you've been able to send some simple data to the
+ printer. Now, we're ready to configure LPD to control
+ access to your printer.
+
+ You configure LPD by editing the file
+ <tt>/etc/printcap</tt>. The LPD spooling system reads
+ this file each time the spooler is used, so updates to the
+ file take immediate effect.
+
+ The format of the <tt/printcap/ file is straightforward.
+ Use your favorite text editor to make changes to
+ <tt>/etc/printcap</tt>. The format is identical to other
+ capability files like <tt>/usr/share/misc/termcap</tt> and
+ <tt>/etc/remote</tt>. For complete information about the
+ format, see the cgetent(3).
+
+ The simple spooler configuration consists of the following steps:
+ <enum>
+ <item>Pick a name (and a few convenient aliases) for
+ the printer, and put them in the
+ <tt>/etc/printcap</tt> file; see <ref
+ id="printing:naming" name="Naming the Printer">.
+
+ <item>Turn off header pages (which are on by default)
+ by inserting the <tt/sh/ capability; see <ref
+ id="printing:no-header-pages" name="Suppressing Header
+ Pages">.
+
+ <item>Make a spooling directory, and specify its
+ location with the <tt/sd/ capability; see <ref
+ id="printing:spooldir" name="Making the Spooling
+ Directory">.
+
+ <item>Set the <tt>/dev</tt> entry to use for the
+ printer, and note it in <tt>/etc/printcap</tt> with
+ the <tt/lp/ capability; see <ref id="printing:device"
+ name="Identifying the Printer Device">. Also, if the
+ printer's on a serial port, set up the communication
+ parameters with the <tt/fs/, <tt/fc/, <tt/xs/, and
+ <tt/xc/ capabilities; see <ref id="printing:commparam"
+ name="Configuring Spooler Communications Parameters">.
+
+ <item>Install a plain text input filter; see <ref
+ id="printing:textfilter" name="Installing the Text
+ Filter">
+
+ <item>Test the setup by printing something with the
+ <tt/lpr/ command; see <ref id="printing:trying"
+ name="Trying It Out"> and <ref
+ id="printing:troubleshooting" name="Troubleshooting">.
+ </enum>
+
+ <em/Note:/ Language-based printers, such as PostScript
+ printers, can't directly print plain text. The simple
+ setup outlined above and described in the following
+ sections assumes that if you're installing such a printer
+ you'll print only files that the printer can understand.
+
+ Users often expect that they can print plain text to any
+ of the printers installed on your system. Programs that
+ interface to LPD to do their printing usually make the
+ same assumption. If you're installing such a printer and
+ want to be able to print jobs in the printer language
+ <em/and/ print plain text jobs, you're strongly urged to
+ add an additional step to the simple setup outlined above:
+ install an automatic plain-text--to--PostScript (or other
+ printer language) conversion program. Section <ref
+ id="printing:advanced:if-conversion" name="Accomodating
+ Plain Text Jobs on PostScript Printers"> tells how to do
+ this.
+
+ <sect3><heading>Naming the Printer<label
+ id="printing:naming"></heading>
+
+ <p> The first (easy) step is to pick a name for your
+ printer. It really doesn't matter whether you choose
+ functional or whimsical names since you can also provide
+ a number aliases for the printer.
+
+ At least one of the printers specified in the
+ <tt>/etc/printcap</tt> should have the alias
+ <tt/lp/. This is the default printer's name. If users
+ don't have the PRINTER environment variable nor
+ specify a printer name on the command line of any of the
+ LPD commands, then <tt/lp/ will be the default printer
+ they get to use.
+
+ Also, it's common practice to make the last alias for a
+ printer be a full description of the printer, including
+ make and model.
+
+ Once you've picked a name and some common aliases, put
+ them in the <tt>/etc/printcap</tt> file. The name of
+ the printer should start in the leftmost column.
+ Separate each alias with a vertical bar and put a colon
+ after the last alias.
+
+ In the following example, we start with a skeletal
+ <tt>/etc/printcap</tt> that defines two printers (a
+ Diablo 630 line printer and a Panasonic KX-P4455
+ PostScript laser printer):
+<code>
+#
+# /etc/printcap for host rose
+#
+rattan|line|diablo|lp|Diablo 630 Line Printer:
+
+bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:
+</code>
+ In this example, the first printer is named <tt/rattan/
+ and has as aliases <tt/line/, <tt/diablo/, <tt/lp/, and
+ <tt/Diablo 630 Line Printer/. Since it has the alias
+ <tt/lp/, it's also the default printer. The second is
+ named <tt/bamboo/, and has as aliases <tt/ps/, <tt/PS/,
+ <tt/S/, <tt/panasonic/, and <tt/Panasonic KX-P4455
+ PostScript v51.4/.
+
+ <sect3><heading>Suppressing Header Pages<label
+ id="printing:no-header-pages"></heading>
+
+ <p> The LPD spooling system will by default print a
+ <em/header page/ for each job. The header page contains
+ the user name who requested the job, the host from which
+ the job came, and the name of the job, in nice large
+ letters. Unfortunately, all this extra text gets in the
+ way of debugging the simple printer setup, so we'll
+ suppress header pages.
+
+ To suppress header pages, add the <tt/sh/ capability to
+ the entry for the printer in
+ <tt>/etc/printcap</tt>. Here's the example
+ <tt>/etc/printcap</tt> with <tt/sh/ added:
+<code>
+#
+# /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:
+</code>
+ Note how we used the correct format: the first line
+ starts in the leftmost column, and subsequent lines are
+ indented with a single TAB. Every line in an entry
+ except the last ends in a backslash character.
+
+ <sect3><heading>Making the Spooling Directory<label
+ id="printing:spooldir"></heading>
+
+ <p> The next step in the simple spooler setup is to make a
+ <em/spooling directory/, a directory where print jobs
+ reside until they're printed, and where a number of
+ other spooler support files live.
+
+ Because of the variable nature of spooling directories,
+ it's customary to put these directories under
+ <tt>/var/spool</tt>. It's not necessary to backup the
+ contents of spooling directories, either. Recreating
+ them is as simple as running <tt/mkdir/.
+
+ It's also customary to make the directory with a name
+ that's identical to the name of the printer, as shown
+ below:
+<tscreen>
+<tt>mkdir /var/spool/<it>printer-name</it></tt>
+</tscreen>
+ However, if you have a lot of printers on your network,
+ you might want to put the spooling directories under a
+ single directory that you reserve just for printing with
+ LPD. We'll do this for our two example printers
+ <tt/rattan/ and <tt/bamboo/:
+<tscreen><verb>
+mkdir /var/spool/lpd
+mkdir /var/spool/lpd/rattan
+mkdir /var/spool/lpd/bamboo
+</verb></tscreen>
+
+ <em/Note:/ If you're concerned about the privacy of jobs
+ that users print, you might want to protect the spooling
+ directory so it's not publicly accessible. Spooling
+ directories should be owned and be readable, writable,
+ and searchable by user daemon and group daemon, and no
+ one else. We'll do this for our example printers:
+
+<tscreen><verb>
+chown daemon.daemon /var/spool/lpd/rattan
+chown daemon.daemon /var/spool/lpd/bamboo
+chmod 770 /var/spool/lpd/rattan
+chmod 770 /var/spool/lpd/bamboo
+</verb></tscreen>
+
+ Finally, you need to tell LPD about these directories
+ using the <tt>/etc/printcap</tt> file. You specify the
+ pathname of the spooling directory with the <tt/sd/
+ capability:
+<code>
+#
+# /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:
+</code>
+ Note that the name of the printer starts in the first
+ column but all other entries describing the printer
+ should be indented with a tab and each line escaped with
+ a backslash.
+
+ If you don't specify a spooling directory with <tt/sd/,
+ the spooling system will use <tt>/var/spool/lpd</tt> as
+ a default.
+
+ <sect3><heading>Identifying the Printer Device<label
+ id="printing:device"></heading>
+
+ <p> In section <ref id="printing:dev-ports" name="Adding
+ /dev Entries for the Ports">, we identified which
+ entry in the <tt>/dev</tt> directory FreeBSD will use
+ to communicate with the printer. Now, we tell LPD
+ that information. When the spooling system has a job
+ to print, it will open the specified device on behalf
+ of the filter program (which is responsible for
+ passing data to the printer).
+
+ List the <tt>/dev</tt> entry pathname in the
+ <tt>/etc/printcap</tt> file using the <tt/lp/
+ capability.
+
+ In our running example, let's assume that <tt/rattan/ is
+ on the first parallel port, and <tt/bamboo/ is on a
+ sixth serial port; here are the additions to
+ <tt>/etc/printcap</tt>:
+<code>
+#
+# /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:
+</code>
+
+ If you don't specify the <tt/lp/ capability for a
+ printer in your <tt>/etc/printcap</tt> file, LPD uses
+ <tt>/dev/lp</tt> as a default. <tt>/dev/lp</tt>
+ currently doesn't exist in FreeBSD.
+
+ If the printer you're installing is connected to a
+ parallel port, skip to the section <ref name="Installing
+ the Text Filter" id="printing:textfilter">. Otherwise,
+ be sure to follow the instructions in the next section.
+
+ <sect3><heading>Configuring Spooler Communication
+ Parameters<label id="printing:commparam"></heading>
+
+ <p> For printers on serial ports, LPD can set up the bps
+ rate, parity, and other serial communication parameters
+ on behalf of the filter program that sends data to the
+ printer. This is advantageous since
+ <itemize>
+ <item>It lets you try different communication
+ parameters by simply editing the
+ <tt>/etc/printcap</tt> file; you don't have to
+ recompile the filter program.
+
+ <item>It enables the spooling system to use the same
+ filter program for multiple printers which may have
+ different serial communication settings.
+ </itemize>
+
+ The following <tt>/etc/printcap</tt> capabilities
+ control serial communication parameters of the device
+ listed in the <tt/lp/ capability:
+ <descrip>
+ <tag/<tt>br&num;<it/bps-rate/</tt>/
+
+ Sets the communications speed of the device to
+ <it/bps-rate/, where <it/bps-rate/ can be 50, 75,
+ 110, 134, 150, 200, 300, 600, 1200, 1800, 2400,
+ 4800, 9600, 19200, or 38400 bits-per-second.
+
+ <tag/<tt>fc&num;<it/clear-bits/</tt>/
+
+ Clears the flag bits <it/clear-bits/ in the
+ <tt/sgttyb/ structure after opening the device.
+
+ <tag/<tt>fs&num;<it/set-bits/</tt>/
+
+ Sets the flag bits <it/set-bits/ in the <tt/sgttyb/
+ structure.
+
+ <tag/<tt>xc&num;<it/clear-bits/</tt>/
+
+ Clears local mode bits <it/clear-bits/ after opening
+ the device.
+
+ <tag/<tt>xs&num;<it/set-bits/</tt>/
+
+ Sets local mode bits <it/set-bits/.
+ </descrip>
+ For more information on the bits for the <tt/fc/,
+ <tt/fs/, <tt/xc/, and <tt/xs/ capabilities, see the file
+ <tt>/usr/include/sys/ioctl_compat.h</tt>.
+
+ When LPD opens the device specified by the <tt/lp/
+ capability, it reads the flag bits in the <tt/sgttyb/
+ structure; it clears any bits in the <tt/fc/ capability,
+ then sets bits in the <tt/fs/ capability, then applies
+ the resultant setting. It does the same for the local
+ mode bits as well.
+
+ Let's add to our example printer on the sixth serial
+ port. We'll set the bps rate to 38400. For the flag
+ bits, we'll set the TANDEM, ANYP, LITOUT, FLUSHO, and
+ PASS8 flags. For the local mode bits, we'll set the
+ LITOUT and PASS8 flags:
+<tscreen><verb>
+bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
+ :sh:sd=/var/spool/lpd/bamboo:\
+ :lp=/dev/ttyd5:fs#0x82000c1:xs#0x820:
+</verb></tscreen>
+
+
+ <sect3><heading>Installing the Text Filter<label
+ id="printing:textfilter"></heading>
+
+ <p> We're now ready to tell LPD what text filter to use to
+ send jobs to the printer. A <em/text filter/, also
+ known as an <em/input filter/, is a program that LPD
+ runs when it has a job to print. When LPD runs the text
+ filter for a printer, it sets the filter's standard
+ input to the job to print, and its standard output to
+ the printer device specified with the <tt/lp/
+ capability. The filter is expected to read the job from
+ standard input, peform any necessary translation for the
+ printer, and write the results to standard output, which
+ will get printed. For more information on the text
+ filter, see section <ref id="printing:advanced:filters"
+ name="Filters">.
+
+ For our simple printer setup, the text filter can be a
+ small shell script that just executes <tt>/bin/cat</tt>
+ to send the job to the printer. FreeBSD comes with
+ another filter called <tt/lpf/ that handles backspacing
+ and underlining for printers that might not deal with
+ such character streams well. And, of course, you can
+ use any other filter program you want. The filter
+ <tt/lpf/ is described in detail in section <ref
+ id="printing:advanced:lpf" name="lpf: a Text Filter">.
+
+ First, let's make the shell script
+ <tt>/usr/local/libexec/if-simple</tt> be a simple text
+ filter. Put the following text into that file with your
+ favorite text editor:
+<code>
+#!/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 &ero;&ero; exit 0
+exit 2
+</code>
+ Make the file executable:
+<tscreen><verb>
+chmod 555 /usr/local/libexec/if-simple
+</verb></tscreen>
+
+ And then tell LPD to use it by specifying it with the
+ <tt/if/ capability in <tt>/etc/printcap</tt>. We'll add
+ it to the two printers we have so far in the example
+ <tt>/etc/printcap</tt>:
+<code>
+#
+# /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:
+</code>
+
+ <sect3><heading>Trying It Out<label id="printing:trying"></heading>
+
+ <p> You've reached the end of the simple LPD setup.
+ Unfortunately, congratulations are not quite yet in
+ order, since we've still got to test the setup and
+ correct any problems. To test the setup, try printing
+ something. To print with the LPD system, you use the
+ command <tt/lpr/, which submits a job for printing.
+
+ You can combine <tt/lpr/ with the <tt/lptest/ program,
+ introduced in section <ref id="printing:testing"
+ name="Checking Printer Communications"> to generate some
+ test text.
+
+ <bf>To test the simple LPD setup:</bf>
+
+ <p> Type:
+<tscreen>
+<tt>lptest 20 5 | lpr -P<it/printer-name/</tt>
+</tscreen>
+ where <it/printer-name/ is a the name of a printer (or
+ an alias) specified in <tt>/etc/printcap</tt>. To test
+ the default printer, type <tt/lpr/ without any <tt/-P/
+ argument. Again, if you're testing a printer that
+ expects PostScript, send a PostScript program in that
+ language instead of using <tt/lptest/. You can do so by
+ putting the program in a file and typing <tt/lpr
+ <it/file//.
+
+ For a PostScript printer, you should get the results
+ of the program. If you're using <tt/lptest/, then your
+ results should look like the following:
+
+<tscreen><verb>
+!"#$%&ero;'()*+,-./01234
+"#$%&ero;'()*+,-./012345
+#$%&ero;'()*+,-./0123456
+$%&ero;'()*+,-./01234567
+%&ero;'()*+,-./012345678
+</verb></tscreen>
+
+ To further test the printer, try downloading larger
+ programs (for language-based printers) or running
+ <tt/lptest/ with different arguments. For example,
+ <tt/lptest 80 60/ will produce 60 lines of 80 characters
+ each.
+
+ If the printer didn't work, see the next section, <ref
+ id="printing:troubleshooting" name="Troubleshooting">.
+
+ <sect3><heading>Troubleshooting<label
+ id="printing:troubleshooting"></heading>
+
+ <p> After performing the simple test with <tt/lptest/, you
+ might've gotten one of the following results instead of
+ the correct printout:
+ <descrip>
+ <tag/It worked, after awhile; or, it didn't eject a full sheet./
+
+ The printer printed the above, but it sat for awhile
+ and did nothing. In fact, you might've needed to
+ press a PRINT REMAINING or FORM FEED button on the
+ printer to get any results to appear.
+
+ If this is the case, the printer was probably
+ waiting to see if there was any more data for your
+ job before it printed anything. To fix this
+ problem, you can have the text filter send a FORM
+ FEED character (or whatever is necessary) to the
+ printer. This is usually sufficient to have the
+ printer immediately print any text remaining in its
+ internal buffer. It's also useful to make sure each
+ print job ends on a full sheet, so the next job
+ doesn't start somewhere on the middle of the last
+ page of the previous job.
+
+ The following replacement for the shell script
+ <tt>/usr/local/libexec/if-simple</tt> prints a form
+ feed after it sends the job to the printer:
+<code>
+#!/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.
+# Writes a form feed character (\f) after printing job.
+
+/bin/cat &ero;&ero; printf "\f" &ero;&ero; exit 0
+exit 2
+</code>
+
+ <tag/It produced the ``staircase effect.''/
+
+ You got the following on paper:
+<tscreen><verb>
+!"#$%&ero;'()*+,-./01234
+ "#$%&ero;'()*+,-./012345
+ #$%&ero;'()*+,-./0123456
+ $%&ero;'()*+,-./01234567
+</verb></tscreen>
+ You've become another victim of the <em/staircase
+ effect/, caused by conflicting interpretations of
+ what characters should indicate a new-line.
+ UNIX-style operating systems use a single character:
+ ASCII code 10, the line feed (LF). MS-DOS, OS/2,
+ and others uses a pair of characters, ASCII code 10
+ <em/and/ ASCII code 13 (the carriage return or CR).
+ Many printers use the MS-DOS convention for
+ representing new-lines.
+
+ When you print with FreeBSD, your text used just the
+ line feed character. The printer, upon seeing a
+ line feed character, advanced the paper one line,
+ but maintained the same horizontal position on the
+ page for the next character to print. That's what
+ the carriage return is for: to move the location of
+ the next character to print to the left edge of the
+ paper.
+
+ Here's what FreeBSD wants your printer to do:
+<tscreen><verb>
+Printer received CR Printer prints CR
+Printer received LF Printer prints CR + LF
+</verb></tscreen>
+
+ Here are some ways to achieve this:
+ <itemize>
+ <item>Use the printer's configuration switches or
+ control panel to alter its interpretation of
+ these characters. Check your printer's manual
+ to find out how to do this.
+
+ <p> <em/Note:/ If you boot your system into
+ other operating systems besides FreeBSD, you
+ may have to <em/reconfigure/ the printer to
+ use a an interpretation for CR and LF
+ characters that those other operating systems
+ use. You might prefer one of the other
+ solutions, below.
+
+ <item>Have FreeBSD's serial line driver
+ automatically convert LF to CR+LF. Of course,
+ this works with printers on serial ports
+ <em/only/. To enable this feature, set the
+ CRMOD bit in <tt/fs/ capability in the
+ <tt>/etc/printcap</tt> file for the printer.
+
+ <item>Send an <em/escape code/ to the printer to
+ have it temporarily treat LF characters
+ differently. Consult your printer's manual for
+ escape codes that your printer might support.
+ When you find the proper escape code, modify the
+ text filter to send the code first, then send
+ the print job.
+
+ <p> Here's an example text filter for printers
+ that understand the Hewlett-Packard PCL escape
+ codes. This filter makes the printer treat LF
+ characters as a LF and CR; then it sends the
+ job; then it sends a form feed to eject the
+ last page of the job. It should work with
+ nearly all Hewlett Packard printers.
+
+<code>
+#!/bin/sh
+#
+# hpif - Simple text input filter for lpd for HP-PCL based printers
+# Installed in /usr/local/libexec/hpif
+#
+# Simply copies stdin to stdout. Ignores all filter arguments.
+# Tells printer to treat LF as CR+LF. Writes a form feed character
+# after printing job.
+
+printf "\033&ero;k2G" &ero;&ero; cat &ero;&ero; printf "\f" &ero;&ero; exit 0
+exit 2
+</code>
+
+ Here's an example <tt>/etc/printcap</tt> from
+ a host called orchid. It has a single printer
+ attached to its first parallel port, a Hewlett
+ Packard LaserJet 3Si named <tt/teak/. It's
+ using the above script as its text filter:
+<code>
+#
+# /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:
+</code>
+ </itemize>
+
+ <tag/It overprinted each line./
+
+ The printer never advanced a line. All of the lines
+ of text were printed on top of each other on one
+ line.
+
+ This problem is the ``opposite'' of the staircase
+ effect, described above, and is much rarer.
+ Somewhere, the LF characters that FreeBSD uses to
+ end a line are being treated as CR characters to
+ return the print location to the left edge of the
+ paper, but not also down a line.
+
+ Use the printer's configuration switches or control
+ panel to enforce the following interpretation of LF
+ and CR characters:
+<tscreen><verb>
+Printer received CR Printer prints CR
+Printer received LF Printer prints CR + LF
+</verb></tscreen>
+
+ <tag/The printer lost characters./
+
+ While printing, the printer didn't print a few
+ characters in each line. The problem might've
+ gotten worse as the printer ran, losing more and
+ more characters.
+
+ The problem is that the printer can't keep up with
+ the speed at which the computer sends data over a
+ serial line. (This problem shouldn't occur with
+ printers on parallel ports.) There are two ways to
+ overcome the problem:
+ <itemize>
+ <item>If the printer supports XON/XOFF flow
+ control, have FreeBSD use it by specifying the
+ TANDEM bit in the <tt/fs/ capability.
+
+ <item>If the printer supports carrier flow
+ control, specify the MDMBUF bit in the <tt/fs/
+ capability. Make sure the cable connecting the
+ printer to the computer is correctly wired for
+ carrier flow control.
+
+ <item>If the printer doesn't support any flow
+ control, use some combination of the NLDELAY,
+ TBDELAY, CRDELAY, VTDELAY, and BSDELAY bits in
+ the <tt/fs/ capability to add appropriate delays
+ to the stream of data sent to the printer.
+ </itemize>
+
+ <tag/It printed garbage./
+
+ The printer printed what appeared to be random
+ garbage, but not the desired text.
+
+ This is usually another symptom of incorrect
+ communications parameters with a serial printer.
+ Double-check the bps rate in the <tt/br/ capability,
+ and the parity bits in the <tt/fs/ and <tt/fc/
+ capabilities; make sure the printer is using the
+ same settings as specified in the
+ <tt>/etc/printcap</tt> file.
+
+ <tag/Nothing happened./
+
+ If nothing happened, the problem is probably within
+ FreeBSD and not the hardware. Add the log file
+ (<tt/lf/) capability to the entry for the printer
+ you're debugging in the <tt>/etc/printcap</tt> file.
+ For example, here's the entry for <tt/rattan/, with
+ the <tt/lf/ capability:
+<tscreen><verb>
+rattan|line|diablo|lp|Diablo 630 Line Printer:\
+ :sh:sd=/var/spool/lpd/rattan:\
+ :lp=/dev/lpt0:\
+ :if=/usr/local/libexec/if-simple:\
+ :lf=/var/log/rattan.log
+</verb></tscreen>
+ Then, try printing again. Check the log file (in
+ our example, <tt>/var/log/rattan.log</tt>) to see
+ any error messages that might appear. Based on the
+ messages you see, try to correct the problem.
+
+ If you don't specify a <tt/lf/ capability, LPD uses
+ <tt>/dev/console</tt> as a default.
+ </descrip>
+
+ <sect><heading>Using Printers<label id="printing:using"></heading>
+
+ <p> This section tells you how to use printers you've setup with
+ FreeBSD. Here's an overview of the user-level commands:
+ <descrip>
+ <tag/<tt/lpr//
+ Print jobs
+
+ <tag/<tt/lpq//
+ Check printer queues
+
+ <tag/<tt/lprm//
+ Remove jobs from a printer's queue
+
+ </descrip>
+
+ There's also an administrative command, <tt/lpc/, described in
+ the section <ref id="printing:lpc" name="Administrating the
+ LPD Spooler">, used to control printers and their queues.
+
+ All three of the commands <tt/lpr/, <tt/lprm/, and <tt/lpq/
+ accept an option ``<tt/-P/ <it/printer-name/'' to specify on
+ which printer/queue to operate, as listed in the
+ <tt>/etc/printcap</tt> file. This enables you to submit,
+ remove, and check on jobs for various printers. If you don't
+ use the <tt/-P/ option, then these commands use the printer
+ specified in the PRINTER environment variable. Finally, if
+ you don't have a PRINTER environment variable, these commands
+ default to the printer named <tt/lp/.
+
+ Hereafter, the terminology <em/default printer/ means the
+ printer named in the PRINTER environment variable, or the
+ printer named <tt/lp/ when there's no PRINTER environment
+ variable.
+
+ <sect1><heading>Printing Jobs<label id="printing:lpr"></heading>
+ <p>
+
+ To print files, type
+<tscreen>
+<tt>lpr <it/filename.../</tt>
+</tscreen>
+ This prints each of the listed files to the default printer.
+ If you list no files, <tt/lpr/ reads data to print from
+ standard input. For example, this command prints some
+ important system files:
+<tscreen><verb>
+lpr /etc/host.conf /etc/hosts.equiv
+</verb></tscreen>
+ To select a specific printer, type
+<tscreen>
+<tt>lpr -P <it/printer-name/ <it/filename.../</tt>
+</tscreen>
+ This example prints a long listing of the current directory
+ to the printer named <tt/rattan/:
+<tscreen><verb>
+ls -l | lpr -P rattan
+</verb></tscreen>
+ Because no files were listed for the <tt/lpr/ command,
+ <tt/lpr/ read the data to print from standard input, which
+ was the output of the <tt/ls -l/ command.
+
+ The <tt/lpr/ 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 <ref id="printing:lpr:options"
+ name="Printing Options">.
+
+ <sect1><heading>Checking Jobs<label id="printing:lpq"></heading>
+
+ <p> When you print with <tt/lpr/, the data you wish to print
+ is put together in a package called a <em/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 <tt/lpq/.
+ For a specific printer, use the <tt/-P/ option. For
+ example, the command
+<tscreen><verb>
+lpq -P bamboo
+</verb></tscreen>
+ shows the queue for the printer named <tt/bamboo/. Here's
+ an example of the output of the <tt/lpq/ command:
+<tscreen><verb>
+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
+</verb></tscreen>
+ This shows three jobs in the queue for <tt/bamboo/. The
+ first job, submitted by user kelly, got assigned <em/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'll need it if you want to cancel the job; see section
+ <ref id="printing:lprm" name="Removing Jobs"> for details.
+
+ Job number nine consists of two files; multiple files given
+ on the <tt/lpr/ command line are treated as part of a single
+ job. It's the currently active job (note the word
+ <tt/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
+ <tt/lpr/ command. The third job came from user mary; it's a
+ much larger job. The pathname of the files she's trying to
+ print is too long to fit, so the <tt/lpq/ command just shows
+ three dots.
+
+ The very first line of the output from <tt/lpq/ is also
+ useful: it tells what the printer is currently doing (or at
+ least what LPD thinks the printer is doing).
+
+ The <tt/lpq/ command also support a <tt/-l/ option to
+ generate a detailed long listing. Here's an example of
+ <tt/lpq -l/:
+<tscreen><verb>
+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
+</verb></tscreen>
+
+ <sect1><heading>Removing Jobs<label
+ id="printing:lprm"></heading>
+
+ <p> If you change your mind about printing a job, you can
+ remove the job from the queue with the <tt/lprm/ command.
+ Often, you can even use <tt/lprm/ 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 <tt/lpq/
+ to find the job number. Then type
+<tscreen>
+<tt/lprm <it/job-number//
+</tscreen>
+ To remove the job from a specific printer, add the <tt/-P/
+ option. The following command removes job number 10 from
+ the queue for the printer <tt/bamboo/:
+<tscreen><verb>
+lprm -P bamboo 10
+</verb></tscreen>
+ The <tt/lprm/ command has a few shortcuts:
+ <descrip>
+ <tag/lprm -/
+
+ Removes all jobs (for the default printer) belonging to
+ you.
+
+ <tag/lprm <it/user//
+
+ Removes all jobs (for the default printer) belonging to
+ <it/user/. The superuser can remove other users' jobs;
+ you can remove only your own jobs.
+
+ <tag/lprm/
+
+ With no job number, user name, or ``<tt/-/'' appearing
+ on the command line, <tt/lprm/ removes the currently
+ active job on the default printer, if it belongs to
+ you. The superuser can remove any active job.
+ </descrip>
+
+ Just use the <tt/-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 <tt/rattan/:
+
+<tscreen><verb>
+lprm -P rattan -
+</verb></tscreen>
+
+ <em/Note:/ If you're working in a networked environment,
+ <tt/lprm/ will let you remove jobs only from the host from
+ which the jobs were submitted, even if the same printer is
+ available from other hosts. The following command sequence
+ demonstrates this:
+<code>
+rose% lpr -P rattan myfile
+rose% rlogin orchid
+orchid% lpq -P rattan
+Rank Owner Job Files Total Size
+active seeyan 12 ... 49123 bytes
+2nd kelly 13 myfile 12 bytes
+orchid% lprm -P rattan 13
+rose: Permission denied
+orchid% logout
+rose% lprm -P rattan 13
+dfA013rose dequeued
+cfA013rose dequeued
+rose%
+</code>
+
+ <sect1><heading>Beyond Plain Text: Printing Options<label
+ id="printing:lpr:options"></heading>
+
+ <p> The <tt/lpr/ 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.
+
+ <sect2><heading>Formatting and Conversion Options<label
+ id="printing:lpr:options:format"></heading>
+
+ <p> The following <tt/lpr/ options control formatting of the
+ files in the job. Use these options if the job doesn't
+ contain plain text or if you want plain text formatted
+ through the <tt/pr/ utility.
+
+ For example, the following command prints a DVI file (from
+ the TeX typesetting system) named <tt/fish-report.dvi/
+ to the printer named <tt/bamboo/:
+<tscreen><verb>
+lpr -P bamboo -d fish-report.dvi
+</verb></tscreen>
+ These options apply to every file in the job, so you can't
+ mix (say) DVI and ditroff files together in a job.
+ Instead, submit the files as separate jobs, using a
+ different conversion option for each job.
+
+ <em/Note:/ All of these options except <tt/-p/ and <tt/-T/
+ require conversion filters installed for the destination
+ printer. For example, the <tt/-d/ option requires the DVI
+ conversion filter. Section <ref
+ id="printing:advanced:convfilters" name="Conversion
+ Filters"> gives details.
+
+ <descrip>
+ <tag/<tt/-c// Print cifplot files.
+
+ <tag/<tt/-d// Print DVI files.
+
+ <tag/<tt/-f// Print FORTRAN text files.
+
+ <tag/<tt/-g// Print plot data.
+
+ <tag/<tt/-i <it/number///
+
+ Indent the output by <it/number/ columns; if you omit
+ <it/number/, indent by 8 columns. This option works
+ only with certain conversion filters.
+
+ <em/Note:/ Don't put any space between the <tt/-i/ and
+ the number.
+
+ <tag/<tt/-l//
+
+ Print literal text data, including control characters.
+
+ <tag/<tt/-n// Print ditroff (device indepdendent troff) data.
+
+ <tag/-p/
+
+ Format plain text with <tt/pr/ before printing. See
+ pr(1) for more information.
+
+ <tag/<tt/-T <it/title///
+
+ Use <it/title/ on the <tt/pr/ header instead of the
+ file name. This option has effect only when used with
+ the <tt/-p/ option.
+
+ <tag/<tt/-t// Print troff data.
+
+ <tag/<tt/-v// Print raster data.
+
+ </descrip>
+
+ Here's an example: this command prints a nicely
+ formatted version of the <tt/ls/ manual page on the
+ default printer:
+<tscreen><verb>
+zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t
+</verb></tscreen>
+ The <tt/zcat/ command uncompresses the source of the
+ <tt/ls/ manual page and passes it to the <tt/troff/
+ command, which formats that source and makes GNU troff
+ output and passes it to <tt/lpr/, which submits the job to
+ the LPD spooler. Because we used the <tt/-t/ option to
+ <tt/lpr/, the spooler will convert the GNU troff output
+ into a format the default printer can understand when it
+ prints the job.
+
+ <sect2><heading>Job Handling Options<label
+ id="printing:lpr:options:job-handling"></heading>
+
+ <p> The following options to <tt/lpr/ tell LPD to handle the
+ job specially:
+
+ <descrip>
+ <tag/-&num; <it/copies//
+
+ Produce a number of <it/copies/ of each file in the
+ job instead of just one copy. An administrator may
+ disable this option to reduce printer wear-and-tear
+ and encourage photocopier usage. See section <ref
+ id="printing:advanced:restricting:copies"
+ name="Restricting Multiple Copies">.
+
+ <p> This example prints three copies of <tt/parser.c/
+ followed by three copies of <tt/parser.h/ to the
+ default printer:
+<tscreen><verb>
+lpr -#3 parser.c parser.h
+</verb></tscreen>
+
+ <tag/-m/
+
+ Send mail after completing the print job. With this
+ option, the LPD system will send mail to your account
+ when it finishes handling your job. In its message,
+ it will tell you if the job completed successfully or
+ if there was an error, and (often) what the error was.
+
+ <tag/-s/ Don't copy the files to the spooling directory,
+ but make symbolic links to them instead.
+
+ If you're printing a large job, you probably want to
+ use this option. It saves space in the spooling
+ directory (your job might overflow the free space on
+ the filesystem where the spooling directory resides).
+ It saves time as well since LPD won't have to copy
+ each and every byte of your job to the spooling
+ directory.
+
+ There is a drawback, though: since LPD will refer to
+ the original files directly, you can't modify or
+ remove them until they have been printed.
+
+ <em/Note:/ If you're printing to a remote printer, LPD
+ will eventually have to copy files from the local host
+ to the remote host, so the <tt/-s/ option will save
+ space only on the local spooling directory, not the
+ remote. It's still useful, though.
+
+ <tag/-r/
+
+ Remove the files in the job after copying them to the
+ spooling directory, or after printing them with the
+ <tt/-s/ option. Be careful with this option!
+
+ </descrip>
+
+ <sect2><heading>Header Page Options<label
+ id="printing:lpr:options:misc"></heading>
+
+ <p> These options to <tt/lpr/ adjust the text that normally
+ appears on a job's header page. If header pages are
+ suppressed for the destination printer, these options have
+ no effect. See section <ref name="Header Pages"
+ id="printing:advanced:header-pages"> for information about
+ setting up header pages.
+
+ <descrip>
+ <tag/-C <it/text//
+
+ Replace the hostname on the header page with
+ <it/text/. The hostname is normally the name of the
+ host from which the job was submitted.
+
+ <tag/-J <it/text//
+
+ Replace the job name on the header page with
+ <it/text/. The job name is normally the name of the
+ first file of the job, or ``stdin'' if you're printing
+ standard input.
+
+ <tag/-h/
+
+ Do not print any header page. <em/Note:/ At some
+ sites, this option may have no effect due to the way
+ header pages are generated. See <ref name="Header
+ Pages" id="printing:advanced:header-pages"> for
+ details.
+
+ </descrip>
+
+ <sect1><heading>Administrating Printers<label
+ id="printing:lpc"></heading>
+
+ <p> As an administrator for your printers, you've had to
+ install, set up, and test them. Using the <tt/lpc/ command,
+ you can interact with your printers in yet more ways. With
+ <tt/lpc/, you can
+
+ <itemize>
+ <item>Start and stop the printers
+
+ <item>Enable and disable their queues
+
+ <item>Rearrange the order of the jobs in each queue.
+ </itemize>
+
+ First, a note about terminology: if a printer is
+ <em/stopped/, it won't print anything in its queue. Users
+ can still submit jobs, which will wait in the queue until
+ the printer is <em/started/ or the queue is cleared.
+
+ If a queue is <em/disabled/, no user (except root) can
+ submit jobs for the printer. An <em/enabled/ queue allows
+ jobs to be submitted. A printer can be <em/started/ for a
+ disabled queue, in which case it'll continue to print jobs
+ in the queue until the queue is empty.
+
+ In general, you have to have root privileges to use the
+ <tt/lpc/ command. Ordinary users can use the <tt/lpc/
+ command to get printer status and to restart a hung printer
+ only.
+
+ Here is a summary of the <tt/lpc/ commands. Most of the
+ commands takes a <it/printer-name/ argument to tell on which
+ printer to operate. You can use <tt/all/ for the
+ <it/printer-name/ to mean all printers listed in
+ <tt>/etc/printcap</tt>.
+
+ <descrip>
+ <tag/<tt/abort <it/printer-name///
+
+ Cancel the current job and stop the printer. Users can
+ still submit jobs if the queue's enabled.
+
+ <tag/<tt/clean <it/printer-name///
+
+ Remove old files from the printer's spooling directory.
+ Occasionally, the files that make up a job aren't
+ properly removed by LPD, particularly if there have been
+ errors during printing or a lot of administrative
+ activity. This command finds files that don't belong in
+ the spooling directory and removes them.
+
+ <tag/<tt/disable <it/printer-name///
+
+ Disable queuing of new jobs. If the printer's started,
+ it will continue to print any jobs remaining in the
+ queue. The superuser (root) can always submit jobs,
+ even to a disabled queue.
+
+ This command is useful while you're testing a new
+ printer or filter installation: disable the queue and
+ submit jobs as root. Other users won't be able to
+ submit jobs until you complete your testing and reenable
+ the queue with the <tt/enable/ command.
+
+ <tag/<tt/down <it/printer-name/ <it/message...///
+
+ Take a printer down. Equivalent to <tt/disable/
+ followed by <tt/stop/. The <it/message/ appears as the
+ printer's status whenever a user checks the printer's
+ queue with <tt/lpq/ or status with <tt/lpc status/.
+
+ <tag/<tt/enable <it/printer-name///
+
+ Enable the queue for a printer. Users can submit jobs
+ but the printer won't print anything until it's started.
+
+ <tag/<tt/help <it/command-name///
+
+ Print help on the command <it/command-name/. With no
+ <it/command-name/, print a summary of the commands
+ available.
+
+ <tag/<tt/restart <it/printer-name///
+
+ Start the printer. Ordinary users can use this command
+ if some extraordinary circumstance hangs LPD, but they
+ can't start a printer stopped with either the <tt/stop/
+ or <tt/down/ commands. The <tt/restart/ command is
+ equivalent to <tt/abort/ followed by <tt/start/.
+
+ <tag/<tt/start <it/printer-name///
+
+ Start the printer. The printer will print jobs in its
+ queue.
+
+ <tag/<tt/stop <it/printer-name///
+
+ Stop the printer. The printer will finish the current
+ job and won't print anything else in its queue. Even
+ though the printer is stopped, users can still submit
+ jobs to an enabled queue.
+
+ <tag/<tt/topq <it/printer-name/ <it/job-or-username...///
+
+ Rearrange the queue for <it/printer-name/ by placing the
+ jobs with the listed <it/job/ numbers or the jobs
+ belonging to <it/username/ at the top of the queue. For
+ this command, you can't use <tt/all/ as the
+ <it/printer-name/.
+
+ <tag/<tt/up <it/printer-name///
+
+ Bring a printer up; the opposite of the <tt/down/
+ command. Equivalent to <tt/start/ followed by
+ <tt/enable/.
+
+ </descrip>
+
+ <tt/lpc/ accepts the above commands on the command line. If
+ you don't enter any commands, <tt/lpc/ enters an interactive
+ mode, where you can enter commands until you type <tt/exit/,
+ <tt/quit/, or end-of-file.
+
+ <sect><heading>Advanced Printer Setup<label
+ id="printing:advanced"></heading>
+
+ <p> This section describes filters for printing specially
+ formatted files, header pages, printing across networks, and
+ restricting and accounting for printer usage.
+
+ <sect1><heading>Filters<label
+ id="printing:advanced:filter-intro"></heading>
+
+ <p> Although LPD handles network protocols, queuing, access
+ control, and other aspects of printing, most of the
+ <em/real/ work happens in the <em/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 <ref id="printing:textfilter" name="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 <em/you/ have to provide
+ filters yourself. The good news is that many are generally
+ available; when they're not, they're usually easy to write.
+
+ Also, FreeBSD comes with one, <tt>/usr/libexec/lpr/lpf</tt>,
+ that works with many printers that can print plain text.
+ (It handles backspacing and tabs in the file, and does
+ accounting, but that's about all it does.) There are also
+ several filters and filter components in the FreeBSD ports
+ collection.
+
+ Here's what you'll find in this section:
+
+ <itemize>
+ <item>Section <ref id="printing:advanced:filters"
+ name="How Fitlers 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's 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.
+
+ <item>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 can't directly
+ print plain text. Section <ref
+ id="printing:advanced:if-conversion" name="Accomodating
+ 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.
+
+ <item>PostScript is a popular output format for many
+ programs. Even some people (myself included) write
+ PostScript code directly. But PostScript printers are
+ expensive. Section <ref id="printing:advanced:ps"
+ name="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
+ <em/non-PostScript/ printer. I recommend reading this
+ section if you don't have a PostScript printer.
+
+ <item>Section <ref id="printing:advanced:convfilters"
+ name="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 <tt/lpr -t/ to print troff data, or
+ <tt/lpr -d/ to print TeX DVI data, or <tt/lpr -v/ to
+ print raster image data, and so forth. I recommend
+ reading this section.
+
+ <item>Section <ref id="printing:advanced:of" name="Output
+ Filters"> tells all about a not often used feature of
+ LPD: output filters. Unless you're printing header
+ pages (see <ref id="printing:advanced:header-pages"
+ name="Header Pages">), you can probably skip that
+ section altogether.
+
+ <item>Section <ref id="printing:advanced:lpf" name="lpf:
+ a Text Filter"> describes <tt/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 <tt/lpf/.
+ </itemize>
+
+ <sect2><heading>How Filters Work<label
+ id="printing:advanced:filters"></heading>
+
+ <p> As mentioned before, a filter is an executable program
+ started by LPD to handle the device-dependent part of
+ communicating with the printer.
+
+ When LPD wants to print a file in a job, it starts a
+ filter program. It sets the filter's standard input to
+ the file to print, its standard output to the printer, and
+ its standard error to the error logging file (specified in
+ the <tt/lf/ capability in <tt>/etc/printcap</tt>, or
+ <tt>/dev/console</tt> by default).
+
+ Which filter LPD starts and the filter's arguments depend
+ on what's listed in the <tt>/etc/printcap</tt> file and
+ what arguments the user specified for the job on the
+ <tt/lpr/ command line. For example, if the user typed
+ <tt/lpr -t/, LPD would start the troff filter, listed in
+ the <tt/tf/ capability for the destination printer. If
+ the user wanted to print plain text, it would start the
+ <tt/if/ filter (this is mostly true: see <ref
+ id="printing:advanced:of" name="Output Filters"> for
+ details).
+
+ There are three kinds filters you can specify in
+ <tt>/etc/printcap</tt>:
+ <itemize>
+ <item>The <em/text filter/, confusingly called the
+ <em/input filter/ in LPD documentation, handles
+ regular text printing. Think of it as the default
+ filter. LPD expects every printer to be able to print
+ plain text by default, and it's the text filter's job
+ to make sure backspaces, tabs, or other special
+ characters don't confuse the printer.
+
+ If you're in an environment where you have to account
+ for printer usage, the text filter must also account
+ for pages printed, usually by counting the number of
+ lines printed and comparing that to the number of
+ lines per page the printer supports.
+
+ The text filter is started with the following argument
+ list:
+<tscreen>
+<tt>[-c] -w<it/width/ -l<it/length/ -i<it/indent/ -n <it/login/ -h <it/host/ <it/acct-file/</tt>
+</tscreen>
+ where
+ <descrip>
+ <tag/<tt/-c//
+
+ appears if the job's submitted with <tt/lpr -l/
+
+ <tag/<tt/<it/width///
+
+ is the value from the <tt/pw/ (page width)
+ capability specified in <tt>/etc/printcap</tt>,
+ default 132
+
+ <tag/<tt/<it/length///
+
+ is the value from the <tt/pl/ (page length)
+ capability, default 66
+
+ <tag/<tt/<it/indent///
+
+ is the amount of the indentation from <tt/lpr -i/,
+ default 0
+
+ <tag/<tt/<it/login///
+
+ is the account name of the user printing the file
+
+ <tag/<tt/<it/host///
+
+ is the host name from which the job was submitted
+
+ <tag/<tt/<it/acct-file///
+
+ is the name of the accounting file from the <tt/af/
+ capability.
+
+ </descrip>
+
+ <item>A <em/conversion filter/ converts a specific file
+ format into one the printer can render onto paper.
+ For example, ditroff typesetting data can't be
+ directly printed, but you can install a conversion
+ filter for ditroff files to convert the ditroff data
+ into a form the printer can digest and print. Section
+ <ref id="printing:advanced:convfilters"
+ name="Conversion Filters"> tells all about them.
+ Conversion filters also need to do accounting, if you
+ need printer accounting.
+
+ Conversion filters are started with the following
+ arguments:
+<tscreen>
+<tt>-x<it/pixel-width/ -y<it/pixel-height/ -n <it/login/ -h <it/host/ <it/acct-file/</tt>
+</tscreen>
+ where <it/pixel-width/ is the value from the <tt/px/
+ capability (default 0) and <it/pixel-height/ is the
+ value from the <tt/py/ capability (default 0).
+
+ <item>The <em/output filter/ is used only if there's no
+ text filter, or if header pages are enabled. In my
+ experience, output filters are rarely used. Section
+ <ref id="printing:advanced:of" name="Output Filters">
+ describe them. There are only two arguments to an
+ output filter:
+<tscreen>
+<tt>-w<it/width/ -l<it/length/</tt>
+</tscreen>
+ which are identical to the text filters <tt/-w/ and
+ <tt/-l/ arguments.
+ </itemize>
+
+ Filters should also <em/exit/ with the following exit
+ status:
+ <descrip>
+ <tag/exit 0/
+
+ If the filter printed the file successfully.
+
+ <tag/exit 1/
+
+ If the filter failed to print the file but wants LPD
+ to try to print the file again. LPD will restart a
+ filter if it exits with this status.
+
+ <tag/exit 2/
+
+ If the filter failed to print the file and doesn't
+ want LPD to try again. LPD will throw out the file.
+ </descrip>
+
+ The text filter that comes with the FreeBSD release,
+ <tt>/usr/libexec/lpr/lpf</tt>, takes advantage of the page
+ width and length arguments to determine when to send a
+ form feed and how to account for printer usage. It uses
+ the login, host, and accounting file arguments to make the
+ accounting entries.
+
+ If you're shopping for filters, see if they're
+ LPD-compatible. If they are, they must support the
+ argument lists described above. If you plan on writing
+ filters for general use, then have them support the same
+ argument lists and exit codes.
+
+ <sect2><heading>Accommodating Plain Text Jobs on PostScript Printers
+ <label id="printing:advanced:if-conversion"></heading>
+
+ <p> If you're the only user of your computer and PostScript
+ (or other language-based) printer, and you promise to
+ never send plain text to your printer and to never use
+ features of various programs that will want to send plain
+ text to your printer, then you don't need to worry about
+ this section at all.
+
+ But, if you would like to send both PostScript and plain
+ text jobs to the printer, then you're urged to augment
+ your printer setup. To do so, we have the text filter
+ detect if the arriving job is plain text or PostScript.
+ All PostScript jobs must start with <tt/&percnt;!/ (for
+ other printer languages, see your printer documentation).
+ If those are the first two characters in the job, we have
+ PostScript, and can pass the rest of the job directly. If
+ those aren't the first two characters in the file, then
+ the filter will convert the text into PostScript and print
+ the result.
+
+ How do we do this?
+
+ If you've got a serial printer, a great way to do it is to
+ install <tt/lprps/. <tt/lprps/ is a PostScript printer
+ filter which performs two-way communication with the
+ printer. It updates the printer's status file with
+ verbose information from the printer, so users and
+ administrators can see exactly what the state of the
+ printer is (such as ``toner low'' or ``paper jam''). But
+ more importantly, it includes a program called <tt/psif/
+ which detects whether the incoming job is plain text and
+ calls <tt/textps/ (another program that comes with
+ <tt/lprps/) to convert it to PostScript. It then uses
+ <tt/lprps/ to send the job to the printer.
+
+ <tt/lprps/ should be part of the FreeBSD ports collection
+ (see <ref id="ports" name="The Ports Collection">); if not,
+ it should be shortly. You can fetch, build and install it
+ yourself, of course. After installing <tt/lprps/, just
+ specify the pathname to the <tt/psif/ program that's part
+ of <tt/lprps/. If you installed <tt/lprps/ from the ports
+ collection, use the following in the serial PostScript
+ printer's entry in <tt>/etc/printcap</tt>:
+<tscreen><verb>
+ :if=/usr/local/libexec/psif:
+</verb></tscreen>
+ You should also specify the <tt/rw/ capability; that tells
+ LPD to open the printer in read-write mode.
+
+ If you have a parralel PostScript printer (and therefore
+ can't use two-way communication with the printer, which
+ <tt/lprps/ needs), you can use the following shell script
+ as the text filter:
+<code>
+#!/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 &ero;&ero; cat &ero;&ero; printf "\004" &ero;&ero; exit 0
+ exit 2
+else
+ #
+ # Plain text, convert it, then print it.
+ #
+ ( echo $first_line; cat ) | /usr/local/bin/textps &ero;&ero; printf "\004" &ero;&ero; exit 0
+ exit 2
+fi
+</code>
+ In the above script, <tt/textps/ is a program we installed
+ separately to convert plain text to PostScript. You can
+ use any text-to-PostScript program you wish. The FreeBSD
+ ports collection (see <ref id="ports" name="The Ports
+ Collection">) includes a full featured text-to-PostScript
+ program called <tt/a2ps/ that you might want to
+ investigate.
+
+ <sect2><heading>Simulating PostScript on Non-PostScript Printers
+ <label id="printing:advanced:ps"></heading>
+
+ <p> PostScript is the <it/de facto/ standard for high
+ quality typesetting and printing. PostScript is, however,
+ an <em/expensive/ standard. Thankfully, Alladin
+ Enterprises has a free PostScript workalike called
+ <it/Ghostscript/ that runs with FreeBSD. Ghostscript can
+ read most PostScript files and can render their pages onto
+ a variety of devices, including many brands of
+ non-PostScript printers. By installing Ghostscript and
+ using a special text filter for your printer, you can make
+ your non-PostScript printer act like a real PostScript
+ printer.
+
+ Ghostscript should be in the FreeBSD ports collection, if
+ you'd like to install it from there. You can fetch,
+ build, and install it quite easily yourself, as well.
+
+ To simulate PostScript, we have the text filter detect if
+ it's printing a PostScript file. If it's not, then the
+ filter will pass the file directly to the printer;
+ otherwise, it will use Ghostscript to first convert the
+ file into a format the printer will understand.
+
+ Here's an example: the following script is a text filter
+ for Hewlett Packard DeskJet 500 printers. For other
+ printers, substitute the <tt/-sDEVICE/ argument to the
+ <tt/gs/ (Ghostscript) command. (Type <tt/gs -h/ to get a
+ list of devices the current installation of Ghostscript
+ supports.)
+<code>
+#!/bin/sh
+#
+# ifhp - Print Ghostscript-simulated PostScript on a DesJet 500
+# Installed in /usr/local/libexec/hpif
+
+#
+# Treat LF as CR+LF:
+#
+printf "\033&ero;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's PostScript; use Ghostscript to scan-convert and print it
+ #
+ /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 -sOutputFile=- - \
+ &ero;&ero; 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 &ero;&ero; cat &ero;&ero; printf "\f" &ero;&ero; exit 2
+fi
+
+exit 2
+</code>
+ Finally, you need to notify LPD of the filter via the
+ <tt/if/ capability:
+<tscreen><verb>
+ :if=/usr/local/libexec/hpif:
+</verb></tscreen>
+ That's it. You can type <tt/lpr plain.text/ and <tt/lpr
+ whatever.ps/ and both should print successfully.
+
+
+ <sect2><heading>Conversion Filters<label
+ id="printing:advanced:convfilters"></heading>
+
+ <p> After completing the simple setup described in <ref
+ name="Simple Printer Setup" id="printing:simple">, the
+ first thing you'll probably want to do is install
+ conversion filters for your favorite file formats
+ (besides plain ASCII text).
+
+ <sect3><heading>Why Install Conversion Filters?</heading>
+
+ <p> Conversion filters make printing various kinds of
+ files easy. As an example, suppose we do a lot of work
+ with the TeX typesetting system, and we have a
+ PostScript printer. Every time we generate a DVI file
+ from TeX, we can't print it directly until we convert
+ the DVI file into PostScript. The command sequence
+ goes like this:
+<tscreen><verb>
+dvips seaweed-analysis.dvi
+lpr seaweed-analysis.ps
+</verb></tscreen>
+ By installing a conversion filter for DVI files, we can
+ skip the hand conversion step each time by having LPD do
+ it for us. Now, each time we get a DVI file, we're just
+ one step away from printing it:
+<tscreen><verb>
+lpr -d seaweed-analysis.dvi
+</verb></tscreen>
+ We got LPD to do the DVI file conversion for us by
+ specifying the <tt/-d/ option. Section <ref
+ id="printing:lpr:options:format" name="Formatting and
+ Conversion Options"> lists the conversion options.
+
+ For each of the conversion options you want a printer to
+ support, install a <em/conversion filter/ and specify
+ its pathname in <tt>/etc/printcap</tt>. A conversion
+ filter is like the text filter for the simple printer
+ setup (see section <ref id="printing:textfilter"
+ name="Installing the Text Filter">) except that instead
+ of printing plain text, the filter converts the file
+ into a format the printer can understand.
+
+ <sect3><heading>Which Conversions Filters Should I Install?
+ </heading>
+
+ <p> You should install the conversion filters you expect
+ to use. If you print a lot of DVI data, then a DVI
+ conversion filter is in order. If you've got plenty of
+ troff to print out, then you probably want a troff
+ filter.
+
+ The following table summarizes the filters that LPD
+ works with, their capability entries for the
+ <tt>/etc/printcap</tt> file, and how to invoke them with
+ the <tt/lpr/ command:
+<code>
+ /etc/printcap
+File type Capability lpr option
+------------ ------------- ----------
+cifplot cf -c
+DVI df -d
+plot gf -g
+ditroff nf -n
+FORTRAN text rf -f
+troff tf -t
+raster vf -v
+plain text if none, -p, or -l
+</code>
+
+ In our example, using <tt/lpr -d/ means the printer
+ needs a <tt/df/ capability in its entry in
+ <tt>/etc/printcap</tt>.
+
+ Despite what others might contend, formats like FORTRAN
+ text and plot are probably obsolete. At your site, you
+ can give new meanings to these or any of the formatting
+ options just by installing custom filters. For example,
+ suppose you'd like to directly print Printerleaf files
+ (files from the Interleaf desktop publishing program),
+ but will never print plot files. You could install a
+ Printerleaf conversion filter under the <tt/gf/
+ capability and then educate your users that <tt/lpr -g/
+ mean ``print Printerleaf files.''
+
+ <sect3><heading>Installing Conversion Filters</heading>
+
+ <p> Since conversion filters are programs you install
+ outside of the base FreeBSD installation, they should
+ probably go under <tt>/usr/local</tt>. The directory
+ <tt>/usr/local/libexec</tt> is a popular location, since
+ they they're specialized programs that only LPD will
+ run; regular users shouldn't ever need to run them.
+
+ To enable a conversion filter, specify its pathname
+ under the appropriate capability for the destination
+ printer in <tt>/etc/printcap</tt>.
+
+ In our example, we'll add the DVI conversion filter to
+ the entry for the printer named <tt/bamboo/. Here's the
+ example <tt>/etc/printcap</tt> file again, with the new
+ <tt/df/ capability for the printer <tt/bamboo/
+<code>
+#
+# /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:
+</code>
+ The DVI filter is a shell script named
+ <tt>/usr/local/libexec/psdf</tt>. Here's that script:
+<code>
+#!bin/sh
+#
+# 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 "$@"
+</code>
+ This script runs <tt/dvips/ in filter mode (the <tt/-f/
+ argument) on standard input, which is the job to print.
+ It then starts the PostScript printer filter <tt/lprps/
+ (see section <ref id="printing:advanced:if-conversion"
+ name="Accomodating Plain Text Jobs on PostScript
+ Printers">) with the arguments LPD passed to this script.
+ <tt/lprps/ will use those arguments to account for the
+ pages printed.
+
+ <sect3><heading>More Conversion Filter Examples</heading>
+
+ <p> Since there's no fixed set of steps to install
+ conversion filters, let me instead provide more
+ examples. Use these as guidance to making your own
+ filters. Use them directly, if appropriate.
+
+ This example script is a raster (well, GIF file,
+ actually) conversion filter for a Hewlett Packard
+ LaserJet III-Si printer:
+<code>
+#!/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
+</code>
+ It works by converting the GIF file into a portable
+ anymap, converting that into a portable graymap,
+ converting that into a portable bitmap, and converting
+ that into LaserJet/PCL-compatible data.
+
+ Here's the <tt>/etc/printcap</tt> file with an entry for
+ a printer using the above filter:
+<code>
+#
+# /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:
+</code>
+
+ The following script is a conversion filter for troff
+ data from the groff typesetting system for the
+ PostScript printer named <tt/bamboo/:
+<code>
+#!/bin/sh
+#
+# pstf - Convert groff's troff data into PS, then print.
+# Installed in /usr/local/libexec/pstf
+#
+exec grops | /usr/local/libexec/lprps "$@"
+</code>
+ The above script makes use of <tt/lprps/ again to handle
+ the communication with the printer. If the printer were
+ on a parallel port, we'd use this script instead:
+<code>
+#!/bin/sh
+#
+# pstf - Convert groff's troff data into PS, then print.
+# Installed in /usr/local/libexec/pstf
+#
+exec grops
+</code>
+ That's it. Here's the entry we need to add to
+ <tt>/etc/printcap</tt> to enable the filter:
+<tscreen><verb>
+ :tf=/usr/local/libexec/pstf:
+</verb></tscreen>
+
+ Here's an example that might make old hands at FORTRAN
+ blush. It's a FORTRAN-text filter for any printer that
+ can directly print plain text. We'll install it for the
+ printer <tt/teak/:
+<code>
+#!/bin/sh
+#
+# hprf - FORTRAN text filter for LaserJet 3si:
+# Installed in /usr/local/libexec/hprf
+#
+
+printf "\033&ero;k2G" &ero;&ero; fpr &ero;&ero; printf "\f" &ero;&ero; exit 0
+exit 2
+</code>
+ And we'll add this line to the <tt>/etc/printcap</tt>
+ for the printer <tt/teak/ to enable this filter:
+<tscreen><verb>
+ :rf=/usr/local/libexec/hprf:
+</verb></tscreen>
+
+ Here's one final, somewhat complex example. We'll add a
+ DVI filter to the LaserJet printer <tt/teak/ introduced
+ earlier. First, the easy part: updating
+ <tt>/etc/printcap</tt> with the location of the DVI
+ filter:
+<tscreen><verb>
+ :df=/usr/local/libexec/hpdf:
+</verb></tscreen>
+
+ Now, for the hard part: making the filter. For that, we
+ need a DVI-to-LaserJet/PCL conversion program. The
+ FreeBSD ports collection (see <ref id="ports" name="The
+ Ports Collection">) has one: <tt/dvi2xx/ is the name of
+ the package. Installing this package gives us the
+ program we need, <tt/dvilj2p/, which converts DVI into
+ LaserJet IIp, LaserJet III, and LaserJet 2000 compatible
+ codes.
+
+ <tt/dvilj2p/ makes the filter <tt/hpdf/ quite complex
+ since <tt/dvilj2p/ can't read from standard input. It
+ wants to work with a filename. What's worse, the
+ filename has to end in <tt/.dvi/ so using
+ <tt>/dev/fd/0</tt> for standard input is problematic.
+ We can get around that problem by linking (symbolically)
+ a temporary file name (one that ends in <tt/.dvi/) to
+ <tt>/dev/fd/0</tt>, thereby forcing <tt/dvilj2p/ to read
+ from standard input.
+
+ The only other fly in the ointment is the fact that we
+ can't use /tmp for the temporary link. Symbolic links
+ are owned by user and group <tt/bin/. The filter runs
+ as user <tt/daemon/. And the <tt>/tmp</tt> directory
+ has the sticky bit set. The filter can create the link,
+ but it won't be able clean up when done and remove it
+ since the link will belong to a different user.
+
+ Instead, the filter will make the symbolic link in the
+ current working directory, which is the spooling
+ directory (specified by the <tt/sd/ capability in
+ <tt>/etc/printcap</tt>). This is a perfect place for
+ filters to do their work, especially since there's
+ (sometimes) more free disk space in the spooling directory
+ than under <tt>/tmp</tt>.
+
+ Here, finally, is the filter:
+<code>
+#!/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 don't try to reprint the
+# job.
+#
+fatal() {
+ echo "$@" 1>&ero;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're 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&ero;k2G" || fatal "Cannot initialize printer"
+
+#
+# Convert and print. Return value from dvilj2p doesn't seem to be
+# reliable, so we ignore it.
+#
+dvilj2p -M1 -q -e- dfhp$$.dvi
+
+#
+# Clean up and exit
+#
+cleanup
+exit 0
+</code>
+
+ <sect3><heading>Automated Conversion: An Alternative To Conversion Filters
+ <label id="printing:advanced:autoconv"></heading>
+
+ <p> All these conversion filters accomplish a lot for your
+ printing environment, but at the cost forcing the user
+ to specify (on the <tt/lpr/ command line) which one to
+ use. If your users aren't particularly computer
+ literate, having to specify a filter option will become
+ annoying. What's worse, though, is that an incorrectly
+ specified filter option may run a filter on the wrong
+ type of file and cause your printer to spew out hundreds
+ of sheets of paper.
+
+ Rather than install conversion filters at all, you might
+ want to try having the text filter (since it's the
+ default filter) detect the type of file it's asked to
+ print and then automatically run the right conversion
+ filter. Tools such as <tt/file/ can be of help here.
+ Of course, it'll be hard to determine the differences
+ between <em/some/ file types---and, of course, you can
+ still provide conversion filters just for them.
+
+ The FreeBSD ports collection has a text filter that
+ performs automatic conversion called <tt/apsfilter/. It
+ can detect plain text, PostScript, and DVI files, run
+ the proper conversions, and print.
+
+ <sect2><heading>Output Filters<label
+ id="printing:advanced:of"></heading>
+
+ <p> The LPD spooling system supports one other type of
+ filter that we've not yet explored: an output filter. An
+ output filter is intended for printing plain text only,
+ like the text filter, but with many simplifications. If
+ you're using an output filter but no text filter, then
+ <itemize>
+ <item>LPD starts an output filter once for the entire
+ job instead of once for each file in the job.
+
+ <item>LPD doesn't make any provision to identify the
+ start or the end of files within the job for the
+ output filter.
+
+ <item>LPD doesn't pass the user's login or host to
+ the filter, so it's not intended to do accounting. In
+ fact, it gets only two arguments:
+<tscreen>
+<tt>-w<it/width/ -l<it/length/</tt>
+</tscreen>
+ where <it/width/ is from the <tt/pw/ capability and
+ <it/length/ is from the <tt/pl/ capability for the
+ printer in question.
+ </itemize>
+
+ Don't be seduced by an output filter's simplicity. If
+ you'd like each file in a job to start on a different page
+ an output filter <em/won't work/. Use a text filter (also
+ known as an input filter); see section <ref
+ id="printing:textfilter" name="Installing the Text
+ Filter">. Furthermore, an output filter is actually
+ <em/more complex/ in that it has to examine the byte
+ stream being sent to it for special flag characters and
+ must send signals to itself on behalf of LPD.
+
+ However, an output filter is <em/necessary/ if you want
+ header pages and need to send escape sequences or other
+ initialization strings to be able to print the header
+ page. (But it's also <em/futile/ if you want to charge
+ header pages to the requesting user's account, since LPD
+ doesn't give any user or host information to the output
+ filter.)
+
+ On a single printer, LPD allows both an output filter and
+ text or other filters. In such cases, LPD will start the
+ output filter to print the header page (see section <ref
+ id="printing:advanced:header-pages" name="Header Pages">)
+ only. LPD then expects the output filter to <em/stop
+ itself/ by sending two bytes to the filter: ASCII 031
+ followed by ASCII 001. When an output filter sees these
+ two bytes (031, 001), it should stop by sending SIGSTOP to
+ itself. When LPD's done running other filters, it'll
+ restart the output filter by sending SIGCONT to it.
+
+ If there's an output filter but <em/no/ text filter and
+ LPD is working on a plain text job, LPD uses the output
+ filter to do the job. As stated before, the output filter
+ will print each file of the job in sequence with no
+ intervening form feeds or other paper advancement, and
+ this is probably <em/not/ what you want. In almost all
+ cases, you need a text filter.
+
+ The program <tt/lpf/, whch we introduced earlier as a text
+ filter, can also run as an output filter. If you need a
+ quick-and-dirty output filter but don't want to write the
+ byte detection and signal sending code, try <tt/lpf/. You
+ can also wrap <tt/lpf/ in a shell script to handle any
+ intialization codes the printer might require.
+
+ <sect2><heading><tt/lpf/: a Text Filter<label
+ id="printing:advanced:lpf"></heading>
+
+ <p> The program <tt>/usr/libexec/lpr/lpf</tt> that comes
+ with FreeBSD binary distribution is a text filter (input
+ filter) that can indent output (job submitted with <tt/lpr
+ -i/), allow literal characters to pass (job submitted with
+ <tt/lpr -l/), adjust the printing position for backspaces
+ and tabs in the job, and account for pages printed. It
+ can also act like an output filter.
+
+ <tt/lpf/ is suitable for many printing environments. And
+ although it has no capability to send initialization
+ sequences to a printer, it's easy to write a shell script
+ to do the needed initialization and then execute <tt/lpf/.
+
+ In order for <tt/lpf/ to do page accounting correctly, it
+ needs correct values filled in for the <tt/pw/ and <tt/pl/
+ capabilities in the <tt>/etc/printcap</tt> file. It uses
+ these values to determine how much text can fit on a page
+ and how many pages were in a user's job. For more
+ information on printer accounting, see <ref
+ id="printing:advanced:acct" name="Accounting for Printer
+ Usage">.
+
+ <sect1><heading>Header Pages<label
+ id="printing:advanced:header-pages"></heading>
+
+ <p> If you've got <em/lots/ of users, all of them using
+ various printers, then you probably want to consider
+ <em/header pages/ as a necessary evil.
+
+ Header pages, also known as <em/banner/ or <em/burst pages/
+ identify to whom jobs belong after they're printed. They're
+ 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's 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 <em/if/ your printer can directly print plain
+ text. If you've got a PostScript printer, you'll need an
+ external program to generate the header page; see <ref
+ id="printing:advanced:header-pages:ps" name="Header Pages on
+ PostScript Printers">.
+
+ <sect2><heading>Enabling Header Pages<label
+ id="printing:advanced:header-pages:enabling"></heading>
+
+ <p> In the <ref id="printing:simple" name="Simple Printer
+ Setup">, we turned off header pages by specifying
+ <tt/sh/ (meaning ``suppress header'') in the
+ <tt>/etc/printcap</tt> file. To enable header pages for
+ a printer, just remove the <tt/sh/ capability.
+
+ Sounds too easy, right?
+
+ You're right. You <em/might/ have to provide an output
+ filter to send initialization strings to the printer.
+ Here's an example output filter for Hewlett Packard
+ PCL-compatible printers:
+<code>
+#!/bin/sh
+#
+# hpof - Output filter for Hewlett Packard PCL-compatible printers
+# Installed in /usr/local/libexec/hpof
+
+
+printf "\033&ero;k2G" || exit 2
+exec /usr/libexec/lpr/lpf
+</code>
+ Specify the path to the output filter in the <tt/of/
+ capability. See <ref id="printing:advanced:of"
+ name="Output Filters"> for more information.
+
+ Here's an example <tt>/etc/printcap</tt> file for the printer
+ <tt/teak/ that we introduced earlier; we enabled header
+ pages and added the above output filter:
+<code>
+#
+# /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:
+</code>
+ Now, when users print jobs to <tt/teak/, they get a header
+ page with each job. If users want to spend time searching
+ for their printouts, they can suppress header pages by
+ submitting the job with <tt/lpr -h/; see <ref
+ id="printing:lpr:options:misc" name="Header Page Options">
+ for more <tt/lpr/ options.
+
+ <tt/Note:/ LPD prints a form feed character after the
+ header page. If your printer uses a different character
+ or sequence of characters to eject a page, specify them
+ with the <tt/ff/ capability in <tt>/etc/printcap</tt>.
+
+ <sect2><heading>Controlling Header Pages<label
+ id="printing:advanced:header-pages:controlling"></heading>
+
+ <p> By enabling header pages, LPD will produce a <em/long
+ header/, a full page of large letters identifying the
+ user, host, and job. Here's an example (kelly printed
+ the job named outline from host rose):
+<tscreen><verb>
+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
+</verb></tscreen>
+ LPD appends a form feed after this text so the job starts
+ on a new page (unless you've got <tt/sf/ (suppress form
+ feeds) in the destination printer's entry in
+ <tt>/etc/printcap</tt>).
+
+ If you prefer, LPD can make a <em/short header/; specify
+ <tt/sb/ (short banner) in the <tt>/etc/printcap</tt> file.
+ The header page will look like this:
+<tscreen><verb>
+rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995
+</verb></tscreen>
+ Also by default, LPD prints the header page first, then
+ the job. To reverse that, specify <tt/hl/ (header last)
+ in <tt>/etc/printcap</tt>.
+
+ <sect2><heading>Accounting for Header Pages<label
+ id="printing:advanced:header-pages:accounting"></heading>
+
+ <p> Using LPD's built-in header pages enforces a particular
+ paradigm when it comes to printer accounting: header pages
+ must be <em/free of charge/.
+
+ Why?
+
+ Because the output filter is the only external program
+ that will have control when the header page is printed
+ that could do accounting, and it isn't provided with any
+ <em/user or host/ information or an accounting file, so it
+ has no idea whom to charge for printer use. It's also not
+ enough to just ``add one page'' to the text filter or any
+ of the conversion filters (which do have user and host
+ information) since users can suppress header pages with
+ <tt/lpr -h/. They could still be charged for header pages
+ they didn't print. Basically, <tt/lpr -h/ will be the
+ preferred option of environmentally-minded users, but you
+ can't offer any incentive to use it.
+
+ It's <em/still not enough/ to have each of the filters
+ generate their own header pages (thereby being able to
+ charge for them). If users wanted the option of
+ suppressing the header pages with <tt/lpr -h/, they will
+ still get them and be charged for them since LPD does not
+ pass any knowledge of the <tt/-h/ option to any of the
+ filters.
+
+ So, what are your options?
+
+ You can
+ <itemize>
+ <item>Accept LPD's paradigm and make header pages free.
+
+ <item>Install an alternative to LPD, such as LPDng or
+ PLP. Section <ref name="Alternatives to the Standard
+ Spooler" id="printing:lpd-alternatives"> tells more
+ about other spooling software you can substitute for
+ LPD.
+
+ <item>Write a <em/smart/ output filter. Normally, an
+ output filter isn't meant to do anything more than
+ initialize a printer or do some simple character
+ conversion. It's suited for header pages and plain
+ text jobs (when there's no text (input) filter).
+
+ But, if there is a text filter for the plain text
+ jobs, then LPD will start the output filter only for
+ the header pages. And the output filter can parse the
+ header page text that LPD generates to determine what
+ user and host to charge for the header page. The only
+ other problem with this method is that the output
+ filter still doesn't know what accounting file to use
+ (it's not passed the name of the file from the <tt/af/
+ capability), but if you have a well-known accounting
+ file, you can hard-code that into the output filter.
+
+ To facilitate the parsing step, use the <tt/sh/ (short
+ header) capability in <tt>/etc/printcap</tt>.
+
+ Then again, all that might be too much trouble, and
+ users will certainly appreciate the more generous
+ system administrator who makes header pages free.
+ </itemize>
+
+ <sect2><heading>Header Pages on PostScript Printers<label
+ id="printing:advanced:header-pages:ps"></heading>
+
+ <p> As described above, LPD can generate a plain text header
+ page suitable for many printers. Of course, PostScript
+ can't directly print plain text, so the header page
+ feature of LPD is useless---or mostly so.
+
+ One obvious way to get header pages is to have every
+ conversion filter and the text filter generate the header
+ page. The filters should should use the user and host
+ arguments to generate a suitable header page. The
+ drawback of this method is that users will always get a
+ header page, even if they submit jobs with <tt/lpr -h/.
+
+ Let's explore this method. The following script takes
+ three arguments (user login name, host name, and job name)
+ and makes a simple PostScript header page:
+<code>
+#!/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're using:
+#
+page_width=612
+page_height=792
+border=72
+
+#
+# Check arguments
+#
+if [ $# -ne 3 ]; then
+ echo "Usage: `basename $0` <user> <host> <job>" 1>&ero;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 don't 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's it
+%
+restore
+showpage
+EOF
+</code>
+ Now, each of the conversion filters and the text filter
+ can call this script to first generate the header page,
+ and then print the user's job. Here's the DVI conversion
+ filter from earlier in this document, modified to make a
+ header page:
+<code>
+#!/bin/sh
+#
+# DVI to PostScript printer filter
+# Installed in /usr/local/libexec/psdf
+#
+# Invoked by lpd when user runs lpr -d
+#
+
+orig_args="$@"
+
+fail() {
+ echo "$@" 1>&ero;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>&ero;2
+ exit 2
+ ;;
+ esac
+done
+
+[ "$login" ] || fail "No login name"
+[ "$host" ] || fail "No host name"
+
+( /u/kelly/freebsd/printing/filters/make-ps-header $login $host "DVI File"
+ /usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_args
+</code>
+ Notice how the filter has to parse the argument list in
+ order to determine the user and host name. The parsing
+ for the other conversion filters is identical. The text
+ filter takes a slightly different set of arguments, though
+ (see section <ref id="printing:advanced:filters" name="How
+ Filters Work">).
+
+ As we've mentioned before, the above scheme, though fairly
+ simple, disables the ``suppress header page'' option (the
+ <tt/-h/ option) to <tt/lpr/. If users wanted to save a
+ tree (or a few pennies, if you charge for header pages),
+ they wouldn't be able to do so, since every filter's going
+ to print a header page with every job.
+
+ To allow users to shut off header pages on a per-job
+ basis, you'll need to use the trick introduced in section
+ <ref id="printing:advanced:header-pages:accounting"
+ name="Accounting for Header Pages">: write an output
+ filter that parses the LPD-generated header page and
+ produces a PostScript version. If the user submits the
+ job with <tt/lpr -h/, then LPD won't generate a header
+ page, and neither will your output filter. Otherwise,
+ your output filter will read the text from LPD and send
+ the appropriate header page PostScript code to the
+ printer.
+
+ If you've got a PostScript printer on a serial line, you
+ can make use of <tt/lprps/, which comes with an output
+ filter, <tt/psof/, which does the above. Note that
+ <tt/psof/ doesn't charge for header pages.
+
+ <sect1><heading>Networked Printing<label
+ id="printing:advanced:network-printers"></heading>
+
+ <p> FreeBSD supports networked printing: sending jobs to
+ remote printers. Networked printing generally refers to two
+ different things:
+ <itemize>
+ <item>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 <ref id="printing:advanced:network:rm"
+ name="Printers Installed on Remote Hosts"> tells how to
+ do this.
+
+ <item>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:
+
+ <itemize>
+ <item>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 <ref
+ id="printing:advanced:network:rm" name="Printers
+ Installed on Remote Hosts"> to set up such a
+ printer.
+
+ <item>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 <ref
+ id="printing:advanced:network:net-if" name="Printers
+ with Networked Data Stream Interfaces"> gives some
+ suggestions on installing such printers.
+ </itemize>
+ </itemize>
+
+ <sect2><heading>Printers Installed on Remote Hosts<label
+ id="printing:advanced:network:rm"></heading>
+
+ <p> The LPD spooling system has built-in support for sending
+ jobs to other hosts also running LPD (or are compatible
+ with LPD). This feature enables you to install a printer
+ on one host and make it accessible from other hosts. It
+ also works with printers that have network interfaces that
+ understand the LPD protocol.
+
+ To enable this kind of remote printing, first install a
+ printer on one host, the <em/printer host/, using the
+ simple printer setup described in <ref
+ id="printing:simple" name="Simple Printer Setup">. Do any
+ advanced setup in <ref id="printing:advanced"
+ name="Advanced Printer Setup"> that you need. Make sure
+ to test the printer and see if it works with the features
+ of LPD you've enabled.
+
+ If you're using a printer with a network interface that's
+ compatible with LPD, then the <em/printer host/ in the
+ discussion below is the printer itself, and the
+ <em/printer name/ is the name you configured for the
+ printer. See the documentation that accompanied your
+ printer and/or printer-network interface.
+
+ Then, on the other hosts you want to have access to the
+ printer, make an entry in their <tt>/etc/printcap</tt>
+ files with the following:
+ <enum>
+ <item>Name the entry anything you want. For
+ simplicity, though, you probably want to use the same
+ name and aliases as on the printer host.
+
+ <item>Leave the <tt/lp/ capability blank, explicitly
+ (<tt/:lp=:/).
+
+ <item>Make a spooling directory and specify its
+ location in the <tt/sd/ capability. LPD will store
+ jobs here before they get sent to the printer host.
+
+ <item>Place the name of the printer host in the <tt/rm/
+ capability.
+
+ <item>Place the printer name on the <em/printer host/ in
+ the <tt/rp/ capability.
+ </enum>
+ That's it. You don't need to list conversion filters,
+ page dimensions, or anything else in the
+ <tt>/etc/printcap</tt> file.
+
+ Here's an example. The host rose has two printers,
+ <tt/bamboo/ and <tt/rattan/. We'll enable users on the
+ host orchid to print to those printers. Here's the
+ <tt>/etc/printcap</tt> file for orchid (back from section
+ <ref id="printing:advanced:header-pages:enabling"
+ name="Enabling Header Pages">). It already had the entry
+ for the printer <tt/teak/; we've added entries for the two
+ printers on the host rose:
+<code>
+#
+# /etc/printcap for host orchid - added (remote) printers on rose
+#
+
+#
+# teak is local; it's 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:
+</code>
+ Then, we just need to make spooling directories on orchid:
+<tscreen><verb>
+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
+</verb></tscreen>
+
+ Now, users on orchid can print to <tt/rattan/ and
+ <tt/bamboo/. If, for example, a user on orchid typed
+<tscreen><verb>
+lpr -P bamboo -d sushi-review.dvi
+</verb></tscreen>
+ the LPD system on orchid would copy the job to the
+ spooling directory <tt>/var/spool/lpd/bamboo</tt> and note
+ that it was a DVI job. As soon as the host rose has room
+ in its <tt/bamboo/ spooling directory, the two
+ LPDs would transfer the file to rose. The file would wait
+ in rose's queue until it was finally printed. It would be
+ converted from DVI to PostScript (since bamboo is a
+ PostScript printer) on rose.
+
+ <sect2><heading>Printers with Networked Data Stream Interfaces<label
+ id="printing:advanced:network:net-if"></heading>
+
+ <p> Often, when you buy a network interface card for a
+ printer, you can get two versions: one which emulates a
+ spooler (the more expensive version), or one which just
+ lets you send data to it as if you were using a serial or
+ parallel port (the cheaper version). This section tells
+ how to use the cheaper version. For the more expensive
+ version, see the previous section <ref name="Printers
+ Installed on Remote Hosts" id="printing:advanced:network:rm">.
+
+ The format of the <tt>/etc/printcap</tt> file lets you
+ specify what serial or parallel interface to use, and (if
+ you're using a serial interface), what baud rate, whether
+ to use flow control, delays for tabs, conversion of
+ newlines, and more. But there's no way to specify a
+ connection to a printer that's listening on a TCP/IP or
+ other network port.
+
+ To send data to a networked printer, you need to develop a
+ communications program that can be called by the text and
+ conversion filters. Here's one such example: the script
+ <tt/netprint/ takes all data on standard input and sends
+ it to a network-attached printer. We specify the hostname
+ of the printer as the first argument and the port number
+ to which to connect as the second argument to
+ <tt/netprint/. Note that this supports one-way
+ communication only (FreeBSD to printer); many network
+ printers support two-way communication, and you might want
+ to take advantage of that (to get printer status, perform
+ accounting, etc.).
+<code>
+#!/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', &ero;AF_INET, $printer_port, $address);
+
+socket(PRINTER, &ero;PF_INET, &ero;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;
+</code>
+ We can then use this script in various filters. Suppose
+ we had a Diablo 750-N line printer connected to the
+ network. The printer accepts data to print on port number
+ 5100. The host name of the printer is scrivener. Here's
+ the text filter for the printer:
+<code>
+#!/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
+</code>
+
+
+ <sect1><heading>Restricting Printer Usage<label
+ id="printing:advanced:restricting"></heading>
+
+ <p> 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.
+
+ <sect2><heading>Restricting Multiple Copies<label
+ id="printing:advanced:restricting:copies"></heading>
+
+ <p> The LPD system makes it easy for users to print multiple
+ copies of a file. Users can print jobs with <tt/lpr -&num;5/
+ (for example) and get five copies of each file in the job.
+ Whether this is a good thing is up to you.
+
+ If you feel multiple copies cause unnecessary wear and
+ tear on your printers, you can disable the <tt/-&num;/ option
+ to <tt/lpr/ by adding the <tt/sc/ capability to the
+ <tt>/etc/printcap</tt> file. When users submit jobs
+ with the <tt/-&num;/ option, they'll see
+<tscreen><verb>
+lpr: multiple copies are not allowed
+</verb></tscreen>
+
+ Note that if you've set up access to a printer remotely
+ (see section <ref name="Printers Installed on Remote
+ Hosts" id="printing:advanced:network:rm">), you need the
+ <tt/sc/ capability on the remote <tt>/etc/printcap</tt>
+ files as well, or else users will still be able to submit
+ multiple-copy jobs by using another host.
+
+ Here's an example. This is the <tt>/etc/printcap</tt>
+ file for the host rose. The printer <tt/rattan/ is quite
+ hearty, so we'll allow multiple copies, but the laser
+ printer <tt/bamboo/'s a bit more delicate, so we'll
+ disable multiple copies by adding the <tt/sc/ capability:
+<code>
+#
+# /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:
+</code>
+ Now, we also need to add the <tt/sc/ capability on the
+ host orchid's <tt>/etc/printcap</tt> (and while we're at
+ it, let's disable multiple copies for the printer
+ <tt/teak/):
+<code>
+#
+# /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:
+</code>
+ By using the <tt/sc/ capability, we prevent the use of
+ <tt/lpr -&num;/, but that still doesn't prevent users from
+ running <tt/lpr/ multiple times, or from submitting the
+ same file mutliple times in one job like this:
+<tscreen><verb>
+lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign
+</verb></tscreen>
+ There are many ways to prevent this abuse (including
+ ignoring it) which you are free to explore.
+
+ <sect2><heading>Restricting Access To Printers<label
+ id="printing:advanced:restricting:access"></heading>
+
+ <p> You can control who can print to what printers by using
+ the UNIX group mechanism and the <tt/rg/ capability in
+ <tt>/etc/printcap</tt>. Just place the users you want to
+ have access to a printer in a certain group, and then name
+ that group in the <tt/rg/ capability.
+
+ Users outside the group (including root) will be greeted
+ with
+<tscreen><verb>
+lpr: Not a member of the restricted group
+</verb></tscreen>
+ if they try to print to the controlled printer.
+
+ As with the <tt/sc/ (suppress multiple copies) capability,
+ you need to specify <tt/rg/ on remote hosts that also have
+ access to your printers, if you feel it's appropriate (see
+ section <ref name="Printers Installed on Remote Hosts"
+ id="printing:advanced:network:rm">).
+
+ For example, we'll let anyone access the printer
+ <tt/rattan/, but only those in group <tt/artists/ can use
+ <tt/bamboo/. Here's the familiar <tt>/etc/printcap</tt>
+ for host rose:
+<code>
+#
+# /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:
+</code>
+ Let's leave the other example <tt>/etc/printcap</tt> file
+ (for the host orchid) alone. Of course, anyone on orchid
+ can print to <tt/bamboo/. It might be the case that we
+ only allow certain logins on orchid anyway, and want them
+ to have access to the printer. Or not.
+
+ <em/Note:/ there can be only one restricted group per
+ printer.
+
+ <sect2><heading>Controlling Sizes of Jobs Submitted<label
+ id="printing:advanced:restricting:sizes"></heading>
+
+ <p> If you have many users accessing the printers, you
+ probably need to put an upper limit on the sizes of the
+ files users can submit to print. After all, there's only
+ so much free space on the filesystem that houses the
+ spooling directories, and you also need to make sure
+ there's room for the jobs of other users.
+
+ LPD enables you to limit the maximum byte size a file in a
+ job can be with the <tt/mx/ capability. The units are in
+ BUFSIZ blocks, which are 1024 bytes. If you put a zero
+ for this capability, there'll be no limit on file size.
+ Note that the limit applies to <em/files/ in a job, and
+ <em/not/ the total job size.
+
+ LPD won't refuse a file that's larger than the limit you
+ place on a printer. Instead, it'll queue as much of the
+ file up to the limit, which will then get printed. The
+ rest will be discarded. Whether this is correct behavior
+ is up for debate.
+
+ Let's add limits to our example printers <tt/rattan/ and
+ <tt/bamboo/. Since those artists' PostScript files tend
+ to be large, we'll limit them to five megabytes. We'll
+ put no limit on the plain text line printer:
+<code>
+#
+# /etc/printcap for host rose
+#
+
+#
+# No limit on job size:
+#
+rattan|line|diablo|lp|Diablo 630 Line Printer:\
+ :sh: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:
+</code>
+ Again, the limits apply to the local users only. If
+ you've set up access to your printers remotely, remote
+ users won't get those limits. You'll need to specify the
+ <tt/mx/ capability in the remote <tt>/etc/printcap</tt>
+ files as well. See section <ref name="Printers Installed
+ on Remote Hosts" id="printing:advanced:network:rm"> for
+ more information on remote printing.
+
+ There's another specialized way to limit job sizes from
+ remote printers; see section <ref
+ id="printing:advanced:restricting:remote"
+ name="Restricting Jobs from Remote Printers">.
+
+ <sect2><heading>Restricting Jobs from Remote Printers<label
+ id="printing:advanced:restricting:remote"></heading>
+
+ <p> The LPD spooling system provides several ways to restrict
+ print jobs submitted from remote hosts:
+
+ <descrip>
+ <tag/Host restrictions/
+
+ You can control from which remote hosts a local LPD
+ accepts requests with the files
+ <tt>/etc/hosts.equiv</tt> and <tt>/etc/hosts.lpd</tt>.
+ LPD checks to see if an incoming request is from a
+ host listed in either one of these files. If not, LPD
+ refuses the request.
+
+ The format of these files is simple: one host name per
+ line. Note that the file <tt>/etc/hosts.equiv</tt> is
+ also used by the ruserok(3) protocol, and affects
+ programs like <tt/rsh/ and <tt/rcp/, so be careful.
+
+ For example, here's the <tt>/etc/hosts.lpd</tt> file
+ on the host rose:
+<code>
+orchid
+violet
+madrigal.fishbaum.de
+</code>
+ This means rose will accept requests from the hosts
+ orchid, violet, and madrigal.fishbaum.de. If any
+ other host tries to access rose's LPD, LPD will
+ refuse them.
+
+ <tag/Size restrictions/
+
+ You can control how much free space there needs to
+ remain on the filesystem where a spooling directory
+ resides. Make a file called <tt/minfree/ in the
+ spooling directory for the local printer. Insert in
+ that file a number representing how many disk blocks
+ (512 bytes) of free space there has to be for a remote
+ job to be accepted.
+
+ This lets you insure that remote users won't fill your
+ filesystem. You can also use it to give a certain
+ priority to local users: they'll be able to queue jobs
+ long after the free disk space has fallen below the
+ amount specified in the <tt/minfree/ file.
+
+ For example, let's add a <tt/minfree/ file for the
+ printer <tt/bamboo/. We examine
+ <tt>/etc/printcap</tt> to find the spooling directory
+ for this printer; here's <tt/bamboo/'s entry:
+<tscreen><verb>
+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:mx#5000:\
+ :if=/usr/local/libexec/psif:\
+ :df=/usr/local/libexec/psdf:
+</verb></tscreen>
+ The spooling directory is the given in the <tt/sd/
+ capability. We'll make three megabytes (which is 6144
+ disk blocks) the amount of free disk space that must
+ exist on the filesystem for LPD to accept remote jobs:
+<tscreen><verb>
+echo 6144 > /var/spool/lpd/bamboo/minfree
+</verb></tscreen>
+ <tag/User restrictions/
+
+ You can control which remote users can print to local
+ printers by specifying the <tt/rs/ capability in
+ <tt>/etc/printcap</tt>. When <tt/rs/ appears in the
+ entry for a locally-attached printer, LPD will accept
+ jobs from remote hosts <em/if/ the user submitting the
+ job also has an account of the same login name on the
+ local host. Otherwise, LPD refuses the job.
+
+ This capability is particularly useful in an
+ environment where there are (for example) different
+ departments sharing a network, and some users
+ transcend departmental boundaries. By giving them
+ accounts on your systems, they can use your printers
+ from their own departmental systems. If you'd rather
+ allow them to use <em/only/ your printers and not your
+ compute resources, you can give them ``token''
+ accounts, with no home directory and a useless shell
+ like <tt>/usr/bin/false</tt>.
+ </descrip>
+
+ <sect1><heading>Accounting for Printer Usage<label
+ id="printing:advanced:acct"></heading>
+
+ <p> 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've 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 doesn't
+ provide much help in this department. Accounting is highly
+ dependent on the kind of printer in use, the formats being
+ printed, and <em/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 can't get away
+ with using the simple output filter, since it cannot do
+ accounting. See section <ref name="Filters"
+ id="printing:advanced:filter-intro">.
+
+ Generally, there are two ways to do accounting:
+ <itemize>
+ <item><em/Periodic accounting/ is the more common way,
+ possibly because it's 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.
+
+ <item><em/Timely accounting/ is less common, probably
+ because it's 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.
+ </itemize>
+
+ 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.
+
+ <sect2><heading>Quick and Dirty Printer Accounting</heading>
+
+ <p> FreeBSD comes with two programs that can get you set up
+ with simple periodic accounting right away. They are the
+ text filter <tt/lpf/, described in section <ref
+ id="printing:advanced:lpf" name="lpf: a Text Filter">, and
+ <tt/pac/, a program to gather and total entries from
+ printer accounting files.
+
+ As mentioned in the section on filters (<ref
+ id="printing:advanced:filters" name="Filters">), LPD
+ starts the text and the conversion filters with the name
+ of the accounting file to use on the filter command
+ line. The filters can use this argument to know where
+ to write an accounting file entry. The name of this
+ file comes from the <tt/af/ capability in
+ <tt>/etc/printcap</tt>, and if not specified as an
+ absolute path, is relative to the spooling directory.
+
+ LPD starts <tt/lpf/ with page width and length arguments
+ (from the <tt/pw/ and <tt/pl/ capabilities). <tt/lpf/
+ uses these arguments to determine how much paper will be
+ used. After sending the file to the printer, it then
+ writes an accounting entry in the accounting file. The
+ entries look like this:
+<tscreen><verb>
+ 2.00 rose:andy
+ 3.00 rose:kelly
+ 3.00 orchid:mary
+ 5.00 orchid:mary
+ 2.00 orchid:zhang
+</verb></tscreen>
+ You should use a separate accounting file for each
+ printer, as <tt/lpf/ has no file locking logic built into
+ it, and two <tt/lpf/s might corrupt each other's entries
+ if they were to write to the same file at the same time.
+ A easy way to insure a separate accounting file for each
+ printer is to use <tt/af=acct/ in <tt>/etc/printcap</tt>.
+ Then, each accounting file will be in the spooling directory
+ for a printer, in a file named <tt/acct/.
+
+ When you're ready to charge users for printouts, run the
+ <tt/pac/ program. Just change to the spooling directory
+ for the printer you want to collect on and type <tt/pac/.
+ You'll get a dollar-centric summary like the following:
+<code>
+ 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
+</code>
+ These are the arguments <tt/pac/ expects:
+ <descrip>
+ <tag/<tt/-P<it/printer///
+
+ Which <it/printer/ to summarize. This option works
+ only if there's an absolute path in the <tt/af/
+ capability in <tt>/etc/printcap</tt>.
+
+ <tag/<tt/-c//
+
+ Sort the output by cost instead of alphabetically by
+ user name.
+
+ <tag/<tt/-m//
+
+ Ignore host name in the accounting files. With this
+ option, user smith on host alpha is the same user
+ smith on host gamma. Without, they're different users.
+
+ <tag/<tt/-p<it/price///
+
+ Compute charges with <it/price/ dollars per page or
+ per foot instead of the price from the <tt/pc/
+ capabilty in <tt>/etc/printcap</tt>, or two cents (the
+ default). You can specify <it/price/ as a floating
+ point number.
+
+ <tag/<tt/-r//
+
+ Reverse the sort order.
+
+ <tag/<tt/-s//
+
+ Make an accounting summary file and truncate the
+ accounting file.
+
+ <tag/<tt/<it/names...///
+
+ Print accounting information for the given user
+ <it/names/ only.
+ </descrip>
+
+ In the default summary that <tt/pac/ produces, you see the
+ number of pages printed by each user from various hosts.
+ If, at your site, host doesn't matter (because users can
+ use any host), run <tt/pac -m/, to produce the following
+ summary:
+<code>
+ 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
+</code>
+ To compute the dollar amount due, <tt/pac/ uses the
+ <tt/pc/ capability in the <tt>/etc/printcap</tt> file
+ (default of 200, or 2 cents per page). Specify, in
+ hundreths of cents, the price per page or per foot you
+ want to charge for printouts in this capability. You can
+ override this value when you run <tt/pac/ with the <tt/-p/
+ option. The units for the <tt/-p/ option are in dollars,
+ though, not hundreths of cents. For example,
+<tscreen><verb>
+pac -p1.50
+</verb></tscreen>
+ makes each page cost one dollar and fifty cents. You can
+ really rake in the profits by using this option.
+
+ Finally, running <tt/pac -s/ will save the summary
+ information in a summary accounting file, which is named
+ the same as the printer's accounting file, but with
+ <tt/_sum/ appended to the name. It then truncates the
+ accounting file. When you run <tt/pac/ again, it rereads
+ the summary file to get starting totals, then adds
+ information from the regular accounting file.
+
+
+ <sect2><heading>How Can You Count Pages Printed?</heading>
+
+ <p> In order to perform even remotely accurate accounting,
+ you need to be able to determine how much paper a job
+ uses. This is the essential problem of printer
+ accounting.
+
+ For plain text jobs, the problem's not that hard to solve:
+ you count how many lines are in a job and compare it to
+ how many lines per page your printer supports. Don't
+ forget to take into account backspaces in the file which
+ overprint lines, or long logical lines that wrap onto one
+ or more additional physical lines.
+
+ The text filter <tt/lpf/ (introduced in <ref
+ id="printing:advanced:lpf" name="lpf: a Text Filter">)
+ takes into account these things when it does accounting.
+ If you're writing a text filter which needs to do
+ accounting, you might want to examine <tt/lpf/'s source
+ code.
+
+ How do you handle other file formats, though?
+
+ Well, for DVI-to-LaserJet or DVI-to-PostScript conversion,
+ you can have your filter parse the diagnostic output of
+ <tt/dvilj/ or <tt/dvips/ and look to see how many pages
+ were converted. You might be able to do similar things
+ with other file formats and conversion programs.
+
+ But these methods suffer from the fact that the printer
+ may not actually print all those pages. For example, it
+ could jam, run out of toner, or explode---and the user
+ would still get charged.
+
+ So, what can you do?
+
+ There is only one <em/sure/ way to do <em/accurate/
+ accounting. Get a printer that can tell you how much
+ paper it uses, and attach it via a serial line or a
+ network connection. Nearly all PostScript printers
+ support this notion. Other makes and models do as well
+ (networked Imagen laser printers, for example). Modify
+ the filters for these printers to get the page usage after
+ they print each job and have them log accounting
+ information based on that value <em/only/. There's no
+ line counting nor error-prone file examination required.
+
+ Of course, you can always be generous and make all
+ printouts free.
+
+ <sect><heading>Alternatives to the Standard Spooler<label
+ id="printing:lpd-alternatives"></heading>
+
+ <p> If you've been reading straight through this manual, by now
+ you've learned just about everything there is to know about
+ the LPD spooling system that comes with FreeBSD. You can
+ probably appreciate many of its shortcomings, which naturally
+ leads to the question: ``What other spooling systems are out
+ there (and work with FreeBSD)?''
+
+ Unfortunately, I've located only <em/two/ alternatives---and
+ they're almost identical to each other! They are
+ <descrip>
+ <tag/PLP, the Portable Line Printer Spooler System/
+
+ PLP was based on software developed by Patrick Powell and
+ then maintained by an Internet-wide group of developers.
+ The main site for the software is at <htmlurl
+ url="ftp://ftp.iona.ie/pub/plp"
+ name="ftp://ftp.iona.ie/pub/plp">. There's also a <htmlurl
+ url="http://www.iona.ie:8000/www/hyplan/jmason/plp.html"
+ name="web page">.
+
+ It's quite similar to the BSD LPD spooler, but boasts a
+ host of features, including:
+ <itemize>
+ <item>Better network support, including built-in support
+ for networked printers, NIS-maintained printcaps, and
+ NFS-mounted spooling directories
+
+ <item>Sophisticated queue management, allowing multiple
+ printers on a queue, transfer of jobs between queues,
+ and queue redirection
+
+ <item>Remote printer control functions
+
+ <item>Prioritization of jobs
+
+ <item>Expansive security and access options
+ </itemize>
+
+ <tag/LPRng/
+
+ LPRng, which purportedly means ``LPR: the Next
+ Generation'' is a complete rewrite of PLP. Patrick Powell
+ and Justin Mason (the principal maintainer of PLP)
+ collaborated to make LPRng. The main site for LPRng is
+ <htmlurl url="ftp://dickory.sdsu.edu/pub/LPRng"
+ name="ftp://dickory.sdsu.edu/pub/LPRng">.
+ </descrip>
+
+
+ <sect><heading>Acknowledgments</heading>
+
+ <p> I'd like to thank the following people who've assisted in
+ the development of this document:
+
+ <descrip>
+ <tag/Daniel Eischen <tt/&lt;deischen@iworks.interworks.org&gt;//
+
+ For providing a plethora of HP filter programs for perusal.
+
+ <tag/Jake Hamby <tt/&lt;jehamby@lightside.com&gt;//
+
+ For the Ghostscript-to-HP filter.
+
+ <tag/My wife, Mary Kelly <tt/&lt;urquhart@argyre.colorado.edu&gt;//
+
+ For allowing me to spend more time with FreeBSD than with her.
+
+ </descrip>
diff --git a/handbook/routing.sgml b/handbook/routing.sgml
new file mode 100644
index 0000000000..19f6643c2e
--- /dev/null
+++ b/handbook/routing.sgml
@@ -0,0 +1,279 @@
+<!-- $Id: routing.sgml,v 1.1 1995-10-07 04:31:41 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+<!-- <!DOCTYPE linuxdoc PUBLIC '-//FreeBSD//DTD linuxdoc//EN'> -->
+
+ <sect><heading>Gateways and routes<label id="routing"></heading>
+
+ <p><em>Contributed by &a.gryphon;.<newline>6 October 1995.</em>
+
+ For one machine to be able to find another, there must be a
+ mechanism in place to describe how to get from one to the
+ other. This is called Routing. A ``route'' is a defined
+ pair of addresses: a <bf>destination</bf> and a
+ <bf>gateway</bf>. The pair indicates that if you are
+ trying to get to this <em>destination</em>, send along
+ through this <em>gateway</em>. There are three types of
+ destinations: individual hosts, subnets, and ``default''. The
+ ``default route'' is used if none of the other routes
+ apply. We will talk a little bit more about default routes
+ later on. There are also three types of gateways:
+ individual hosts, interfaces (also called ``links''), and
+ ethernet hardware addresses.
+
+ <sect1><heading>An example</heading>
+
+ <p>To illustrate different aspects of routing, we will use
+ the following example which is the output of the command
+ <tt>netstat -r</tt>:
+
+<tscreen><verb>
+Destination Gateway Flags Refs Use Netif Expire
+
+default outside-gw UGSc 37 418 ppp0
+localhost localhost UH 0 181 lo0
+test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77
+10.20.30.255 link#1 UHLW 1 2421
+foobar.com link#1 UC 0 0
+host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0
+host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 =>
+host2.foobar.com link#1 UC 0 0
+224 link#1 UC 0 0
+</verb></tscreen>
+
+ The first two lines specify the default route (which we
+ will cover in the next section) and the <tt>localhost</tt> route.
+
+ The interface (<tt>Netif</tt> column) that it specifies to use
+ for <tt>localhost</tt> is <tt>lo0</tt>, also known as the
+ loopback device. This says to keep all traffic for this
+ destination internal, rather than sending it out over the
+ LAN, since it will only end up back where it started
+ anyway.
+
+ The next thing that stands out are the
+ ``<tt>0:e0:...</tt>'' addresses. These are ethernet
+ hardware addresses. FreeBSD will automatically identify any
+ hosts (<tt>test0</tt> in the example) on the local ethernet and
+ add a route for that host, directly to it over the ethernet
+ interface, <tt>ed0</tt>. There is also a timeout
+ (<tt>Expire</tt> column) associated with this type of route,
+ which is used if we fail to hear from the host in a
+ specific amount of time. In this case the route will be
+ automatically deleted. These hosts are identified using a
+ mechanism known as RIP (Routing Information Protocol),
+ which figures out routes to local hosts based upon a
+ shortest path determination.
+
+ FreeBSD will also add subnet routes for the local subnet
+ (<tt>10.20.30.255</tt> is the broadcast address for the subnet
+ <tt>10.20.30</tt>, and <tt>foobar.com</tt> is the domain name
+ associated with that subnet). The designation <tt>link&num;1</tt>
+ refers to the first ethernet card in the machine. You'll
+ notice no additional interface is specified for those.
+
+ Both of these groups (local network hosts and local
+ subnets) have their routes automatically configured by a
+ daemon called <tt>routed</tt>. If this is not run, then only
+ routes which are statically defined (ie. entered
+ explicitly) will exist.
+
+ The <tt>host1</tt> line refers to our host, which it knows by
+ ethernet address. Since we are the sending host, FreeBSD
+ knows to use the loopback interface (<tt>lo0</tt>) rather than
+ sending it out over the ethernet interface.
+
+ The two <tt>host2</tt> lines are an example of what happens
+ when we use an ifconfig alias (see the section of ethernet
+ for reasons why we would do this). The <tt>=&gt</tt>
+ symbol after the <tt>lo0</tt> interface says that not only are
+ we using the loopback (since this is address also refers to
+ the local host), but specifically it is an alias. Such
+ routes only show up on the host that supports the alias;
+ all other hosts on the local network will simply have a
+ <tt>link&num;1</tt> line for such.
+
+ The final line (destination subnet <tt>224</tt>) deals with
+ MultiCasting, which will be covered in a another section.
+
+ The other column that we should talk about are the
+ <tt>Flags</tt>. Each route has different attributes that are
+ described in the column. Below is a short table of some of
+ these flags and their meanings:
+
+ <descrip>
+
+ <tag/U/ <bf/Up:/ The route is active.
+
+ <tag/H/ <bf/Host:/ The route destination is a single host.
+
+ <tag/G/ <bf/Gateway:/ Send anything for this destination
+ on to this remote system, which will figure out from
+ there where to send it.
+
+ <tag/S/ <bf/Static:/ This route was configured manually,
+ not automatically generated by the system.
+
+ <tag/C/ <bf/Clone:/ Generates a new route based upon this
+ route for machines we connect to. This type of route is
+ normally used for local networks.
+
+ <tag/W/ <bf/WasCloned/ Indicated a route that was
+ auto-configured based upon a local area network (Clone)
+ route.
+
+ <tag/L/ <bf/Link:/ Route involves references to ethernet
+ hardware.
+
+ </descrip>
+
+
+ <sect1><heading>Default routes</heading>
+
+ <p>When the local system needs to make a connection to
+ remote host, it checks the routing table to determine if
+ a known path exists. If the remote host falls into a
+ subnet that we know how to reach (Cloned routes), then
+ the system checks to see if it can connect along that
+ interface.
+
+ If all known paths fail, the system has one last option:
+ the <bf>default</bf> route. This route is a special type
+ of gateway route (usually the only one present in the
+ system), and is always marked with a ``<tt>c</tt>'' in
+ the flags field. For hosts on a local area network, this
+ gateway is set to whatever machine has a direct
+ connection to the outside world (whether via PPP link, or
+ your hardware device attached to a dedicated data line).
+
+ If you are configuring the default route for a machine
+ which itself is functioning as the gateway to the outside
+ world, then the default route will be the gateway machine
+ at your Internet Service Provider's (ISP) site.
+
+ Let's look at an example of default routes. This is a
+ common configuration:
+<tscreen><verb>
+[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW]
+</verb></tscreen>
+
+ The hosts <tt>Local1</tt> and <tt>Local2</tt> are at your
+ site, with the formed being your PPP connection to your
+ ISP's Terminal Server. Your ISP has a local network at
+ their site, which has, among other things, the server
+ where you connect and a hardware device (T1-GW) attached
+ to the ISP's internet feed.
+
+ The default routes for each of your machines will be:
+
+<tscreen><verb>
+host default gateway interface
+---- --------------- ---------
+Local2 Local1 ethernet
+Local1 T1-GW PPP
+</verb></tscreen>
+
+ A common question is ``Why (or how) would we set the
+ T1-GW to be the default gateway for Local1, rather than
+ the ISP server it is connected to?''.
+
+ Remember, since the PPP interface is using an address on
+ the ISP's local network for your side of the connection,
+ routes for any other machines on the ISP's local network
+ will be automatically generated. Hence, you will already
+ know how to reach the T1-GW machine, so there is no need
+ for the intermediate step of sending traffic to the ISP
+ server.
+
+ As a final note, it is common to use the address ``<tt>...1</tt>''
+ as the gateway address for your local network. So (using
+ the same example), if your local class-C address space
+ was <tt>10.20.30</tt> and your ISP was using <tt>10.9.9</tt> then the
+ default routes would be:
+
+<tscreen><verb>
+Local2 (10.20.30.2) --> Local1 (10.20.30.1)
+Local1 (10.20.30.1, 10.9.9.30) --> T1-GW (10.9.9.1)
+</verb></tscreen>
+
+ <sect1><heading>Dual homed hosts</heading>
+
+ <p>There is one other type of configuration that we should
+ cover, and that is a host that sits on two different
+ networks. Technically, any machine functioning as a
+ gateway (in the example above, using a PPP connection)
+ counts as a dual-homed host. But the term is really only
+ used to refer to a machine that sits on two local-area
+ networks.
+
+ In one case, the machine as two ethernet cards, each
+ having an address on the seperate subnets. Alternately,
+ the machine may only have one ethernet card, and be using
+ ifconfig aliasing. The former is used if two physically
+ separate ethernet networks are in use, the latter if
+ there is one physical network segment, but two logically
+ seperate subnets.
+
+ Either way, routing tables are set up so that each subnet
+ knows that this machine is the defined gateway (inbound
+ route) to the other subnet. This configuration, with the
+ machine acting as a Bridge between the two subnets, is
+ often used when we need to implement packet filtering or
+ firewall security in either or both directions.
+
+ <sect1><heading>Routing propogation</heading>
+
+ <p>We have already talked about how we define our routes to
+ the outside world, but not about how the outside world
+ finds us.
+
+ We already know that routing tables can be set up so that
+ all traffic for a particular address space (in our
+ examples, a class-C subnet) can be sent to a particular
+ host on that network, which will forward the packets
+ inbound.
+
+ When you get an address space assigned to your site, your
+ service provider will set up their routing tables so that
+ all traffic for your subnet will be sent down your PPP
+ link to your site. But how do sites across the country
+ know to send to your ISP?
+
+ There is a system (much like the distributed DNS
+ information) that keeps track of all assigned
+ address-spaces, and defines their point of connection to
+ the Internet Backbone. The ``Backbone'' are the main
+ trunk lines that carry internet traffic across the
+ country, and around the world. Each backbone machine has
+ a copy of a master set of tables, which direct traffic
+ for a particular network to a specific backbone carrier,
+ and from there down the chain of service providers until
+ it reaches your network.
+
+ It is the task of your service provider to advertise to
+ the backbone sites that they are the point of connection
+ (and thus the path inward) for your site. This is known
+ as route propogation.
+
+<!--
+ <sect1><heading>Multicast Routing</heading>
+-->
+
+ <sect1><heading>Troubleshooting</heading>
+
+ <p>Sometimes, there is a problem with routing propogation,
+ and some sites are unable to connect to you. Perhaps the
+ most useful command for trying to figure out where a
+ routing is breaking down is the <tt>traceroute(8)</tt>
+ command. It is equally useful if you cannot seem to make
+ a connection to a remote machine (ie. <tt>ping(8)</tt>
+ fails).
+
+ The <tt>traceroute(8)</tt> command is run with the name
+ of the remote host you are trying to connect to. It will
+ show the gateway hosts along the path of the attempt,
+ eventually either reaching the target host, or
+ terminating because of a lack of connection.
+
+ For more information, see the manual page for
+ <tt>traceroute(8)</tt>.
+
diff --git a/handbook/skey.sgml b/handbook/skey.sgml
new file mode 100644
index 0000000000..4b33dec279
--- /dev/null
+++ b/handbook/skey.sgml
@@ -0,0 +1,302 @@
+<!-- $Id: skey.sgml,v 1.3 1995-10-07 04:31:56 jfieber Exp $ -->
+<!-- The FreeBSD Documentation Project -->
+<!--
+Copyright 1995 Massachusetts Institute of Technology
+
+Permission to use, copy, modify, and distribute this software and
+its documentation for any purpose and without fee is hereby
+granted, provided that both the above copyright notice and this
+permission notice appear in all copies, that both the above
+copyright notice and this permission notice appear in all
+supporting documentation, and that the name of M.I.T. not be used
+in advertising or publicity pertaining to distribution of the
+software without specific, written prior permission. M.I.T. makes
+no representations about the suitability of this software for any
+purpose. It is provided "as is" without express or implied
+warranty.
+
+THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
+ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
+SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.
+-->
+
+<sect><heading>S/Key<label id="skey"></heading>
+
+<p><em>Contributed by &a.wollman;<newline>25 September 1995.</em>
+
+<p>S/Key is a one-time password scheme based on a one-way hash function
+(in our version, this is MD4 for compatibility; other versions have
+used MD5 and DES-MAC). S/Key has been a standard part of all FreeBSD
+distributions since version 1.1.5, and is also implemented on a large
+and growing number of other systems. S/Key is a registered trademark
+of Bell Communications Research, Inc.
+
+<!-- XXX - is there a better word to use than UNIX? -->
+<p>There are three different sorts of passwords which we will talk about
+in the discussion below. The first is your usual UNIX-style or Kerberos
+password; we'll call this a ``UNIX password''. The second sort is the
+one-time password which is generated by the S/Key `<tt/key/' program and
+accepted by the `<tt/keyinit/' program and the login prompt; we'll call
+this a ``one-time password''. The final sort of password is the
+secret password which you give to the `<tt/key/' program (and sometimes the
+`<tt/keyinit/' program) which it uses to generate one-time passwords; we'll
+call it a ``secret password'' or just unqualified ``password''.
+
+<p>The secret password does not necessarily have anything to do with your
+UNIX password (while they can be the same, this is not recommended).
+While UNIX passwords are limited to eight characters in length, your
+S/Key secret password can be as long as you like; I use seven-word
+phrases. In general, the S/Key system operates completely
+independently of the UNIX password system.
+
+<p>There are in addition two other sorts of data involved in the S/Key
+system; one is called the ``seed'' or (confusingly) ``key'', and
+consists of two letters and five digits, and the other is the
+``iteration count'' and is a number between 100 and 1. S/Key
+constructs a one-time password from these components by concatenating
+the seed and the secret password, then applying a one-way hash (the
+RSA Data Security, Inc., MD4 secure hash function) iteration-count
+times, and turning the result into six short English words. The
+`<tt/login/' and `<tt/su/' programs keep track of the last one-time
+password used, and the user is authenticated if the hash of the
+user-provided password is equal to the previous password. Because a
+one-way hash function is used, it is not possible to generate future
+one-time passwords having overheard one which was successfully used;
+the iteration count is decremented after each successful login to keep
+the user and login program in sync. (When you get the iteration count
+down to 1, it's time to reinitialize S/Key.)
+
+<p>There are four programs involved in the S/Key system which we will
+discuss below. The `<tt/key/' program accepts an iteration count, a
+seed, and a secret password, and generates a one-time password. The
+`<tt/keyinit/' program is used to initialized S/Key, and to change
+passwords, iteration counts, or seeds; it takes either a secret
+password, or an iteration count, seed, and one-time password. The
+`<tt/keyinfo/' program examines the <tt>/etc/skeykeys</tt> file and
+prints out the invoking user's current iteration count and seed.
+Finally, the `<tt/login/' and `<tt/su/' programs contain the necessary
+logic to accept S/Key one-time passwords for authentication. The
+`<tt/login/' program is also capable of disallowing the use of UNIX
+passwords on connections coming from specified addresses.
+
+<p>There are four different sorts of operations we will cover. The first
+is using the `<tt/keyinit/' program over a secure connection to set up
+S/Key for the first time, or to change your password or seed. The
+second operation is using the `<tt/keyinit/' program over an insecure
+connection, in conjunction with the `<tt/key/' program over a secure
+connection, to do the same. The third is using the `<tt/key/' program to
+log in over an insecure connection. The fourth is using the `<tt/key/'
+program to generate a number of keys which can be written down or
+printed out to carry with you when going to some location without
+secure connections to anywhere (like at a conference).
+
+<sect1><heading>Secure connection initialization</heading>
+
+<p>To initialize S/Key, change your password, or change your seed while
+logged in over a secure connection (e.g., on the console of a machine),
+use the `<tt/keyinit/' command without any parameters while logged in as
+yourself:
+
+<tscreen><verb>
+$ keyinit
+Updating wollman: ) these will not appear if you
+Old key: ha73895 ) have not used S/Key before
+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: ) I typed my pass phrase here
+Again secret password: ) I typed it again
+
+ID wollman s/key is 99 ha73896 ) discussed below
+SAG HAS FONT GOUT FATE BOOM )
+</verb></tscreen>
+
+<p>There is a lot of information here. At the `Enter secret password:'
+prompt, you should enter some password or phrase (I use phrases of
+minimum seven words) which will be needed to generate login keys. The
+line starting `ID' 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 don't 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.
+
+<sect1><heading>Insecure connection initialization</heading>
+
+<p>To initialize S/Key or change your password or seed over an insecure
+connection, you will need to already have a secure connection to some
+place where you can run the `<tt/key/' program; this might be in the form
+of a desk accessory on a Macintosh, or a shell prompt on a machine you
+trust (we'll show the latter). 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 `<tt/keyinit -s/'
+command:
+
+<tscreen><verb>
+$ keyinit -s
+Updating wollman:
+Old key: kh94741
+Reminder you need the 6 english words from the skey command.
+Enter sequence count from 1 to 9999: 100 ) I typed this
+Enter new key [default kh94742]:
+s/key 100 kh94742
+</verb></tscreen>
+
+To accept the default seed (which the `keyinit' program confusingly
+calls a `key'), press return. Then move over to your secure
+connection or S/Key desk accessory, and give it the same parameters:
+
+<tscreen><verb>
+$ key 100 kh94742
+Reminder - Do not use this program while logged in via telnet or rlogin.
+Enter secret password: ) I typed my secret password
+HULL NAY YANG TREE TOUT VETO
+</verb></tscreen>
+
+Now switch back over to the insecure connection, and copy the one-time
+password generated by `<tt/key/' over to the `<tt/keyinit/' program:
+
+<tscreen><verb>
+s/key access password: HULL NAY YANG TREE TOUT VETO
+
+ID wollman s/key is 100 kh94742
+HULL NAY YANG TREE TOUT VETO
+</verb></tscreen>
+
+The rest of the description from the previous section applies here as
+well.
+
+<sect1><heading>Diversion: a login prompt</heading>
+
+<p>Before explaining how to generate one-time passwords, we should go
+over an S/Key login prompt:
+
+<tscreen><verb>
+$ telnet himalia
+Trying 18.26.0.186...
+Connected to himalia.lcs.mit.edu.
+Escape character is '^]'.
+s/key 92 hi52030
+Password:
+</verb></tscreen>
+
+Note that, before prompting for a password, the login program
+prints out the iteration number and seed which you will need in order
+to generate the appropriate key. You will also find 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.
+
+<p>If this machine were configured to disallow UNIX passwords over a
+connection from my machine, the prompt would have also included the
+annotation `<tt>(s/key required)</tt>', indicating that only S/Key one-time
+passwords will be accepted.
+
+<sect1><heading>Generating a single one-time password</heading>
+
+<p>Now, to generate the one-time password needed to answer this login
+prompt, we use a trusted machine and the `<tt/key/' program. (There are
+versions of the `<tt/key/' program from DOS and Windows machines, and there
+is an S/Key desk accessory for Macintosh computers as well.) The
+command-line `<tt/key/' program takes as its parameters the iteration count
+and seed; you can cut-and-paste right from the login prompt starting
+at ``<tt/key/'' to the end of the line. Thus:
+
+<tscreen><verb>
+$ key 92 hi52030 ) pasted from previous section
+Reminder - Do not use this program while logged in via telnet or rlogin.
+Enter secret password: ) I typed my secret password
+ADEN BED WOLF HAW HOT STUN
+</verb></tscreen>
+
+And in the other window:
+
+<tscreen><verb>
+s/key 92 hi52030 ) from previous section
+Password:
+ (turning echo on)
+Password:ADEN BED WOLF HAW HOT STUN
+Last login: Wed Jun 28 15:31:00 from halloran-eldar.l
+[etc.]
+</verb></tscreen>
+
+This is the easiest mechanism <em/if/ you have a trusted machine.
+
+<sect1><heading>Generating multiple one-time passwords</heading>
+
+<p>Sometimes we have to go places where no trusted machines or
+connections are available. In this case, it is possible to use the
+`<tt/key/' command to generate a number of one-time passwords in the same
+command; these can then be printed out. For example:
+
+<tscreen><verb>
+$ key -n 25 57 zz99999
+Reminder - Do not use this program while logged in via telnet or rlogin.
+Enter secret password:
+33: WALT THY MALI DARN NIT HEAD
+34: ASK RICE BEAU GINA DOUR STAG
+[...]
+56: AMOS BOWL LUG FAT CAIN INCH
+57: GROW HAYS TUN DISH CAR BALM
+</verb></tscreen>
+
+The `<tt/-n 25/' requests twenty-five keys in sequence; the `<tt/57/' indicates
+the <em/ending/ iteration number; and the rest is as before. Note that
+these are printed out in <em/reverse/ order of eventual use. If you're
+really paranoid, you might want to write the results down by hand;
+otherwise you can cut-and-paste into `<tt/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.
+
+<sect1><heading>Restricting use of UNIX passwords</heading>
+
+<p>The configuration file <tt>/etc/skey.access</tt> can be used to
+configure restrictions on the use of UNIX passwords based on the host
+name, user name, terminal port, or IP address of a login session. The
+complete format of the file is documented in the <em/skey.access/(5)
+manual page; there are also some security cautions there which should
+be read before depending on this file for security.
+
+<p>If there is no <tt>/etc/skey.access</tt> file (which is the default
+state as FreeBSD is shipped), 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 <tt/skey.access/ file. In all cases,
+UNIX passwords are permitted on the console.
+
+<p>Here is a sample configuration file which illustrates the three most
+common sorts of configuration statements:
+
+<tscreen><verb>
+permit internet 18.26.0.0 255.255.0.0
+permit user jrl
+permit port ttyd0
+</verb></tscreen>
+
+The first line (`<tt/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.
+
+<p>The second line (`<tt/permit user/') allows the specified user to
+use UNIX passwords at any time. Generally speaking, this should only
+be used for people who are either unable to use the `<tt/key/'
+program, like those with dumb terminls, or those who are uneducable.
+
+<p>The third line (`<tt/permit port/') allows all users logging in on
+the specified terminal line to use UNIX passwords; this would be used
+for dial-ups.
+