diff options
| author | Doc Manager <doceng@FreeBSD.org> | 1995-10-14 21:49:55 +0000 |
|---|---|---|
| committer | Doc Manager <doceng@FreeBSD.org> | 1995-10-14 21:49:55 +0000 |
| commit | 31383071dd9ceef62f654a0e7f77aa2f1e3ad584 (patch) | |
| tree | c26463a81e96eee0a21cd24b07333351eeb78645 /handbook | |
| parent | 4c0228d53f2f7c53cd84a06d3ff1d2575ff2cad9 (diff) | |
| download | doc-31383071dd9ceef62f654a0e7f77aa2f1e3ad584.tar.gz doc-31383071dd9ceef62f654a0e7f77aa2f1e3ad584.zip | |
Create branch 'RELENG_2_1_0'.
Notes
Notes:
svn path=/branches/RELENG_2_1_0/; revision=122
Diffstat (limited to 'handbook')
| -rw-r--r-- | handbook/crypt.sgml | 80 | ||||
| -rw-r--r-- | handbook/dma.sgml | 105 | ||||
| -rw-r--r-- | handbook/esdi.sgml | 421 | ||||
| -rw-r--r-- | handbook/firewalls.sgml | 525 | ||||
| -rw-r--r-- | handbook/kernelconfig.sgml | 1206 | ||||
| -rw-r--r-- | handbook/printing.sgml | 3877 | ||||
| -rw-r--r-- | handbook/routing.sgml | 279 | ||||
| -rw-r--r-- | handbook/skey.sgml | 302 |
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&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>$1$</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>$</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 && TC && 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 © 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) [X3.170-1990/X3.170a-1991] + [X3T10/792D Rev 11] + </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> +[<bf>from</bf> <<em>address/mask</em>>[<em>port</em>]] [<bf>to</bf> + <<em>address/mask</em>>[<em>port</em>]] [<bf>via</bf> <<em>interface</em>>] +</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><address/mask></tt> is: +<tscreen> +<address> +</tscreen> +or +<tscreen> +<address>/mask-bits +</tscreen> +or +<tscreen> +<address>: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[,port[,port[...]]] +</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 [-ans] <em>command</em> [<em>argument</em>] +</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&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 | 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 | 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#<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>˜><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#<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#<it/clear-bits/</tt>/ + + Clears the flag bits <it/clear-bits/ in the + <tt/sgttyb/ structure after opening the device. + + <tag/<tt>fs#<it/set-bits/</tt>/ + + Sets the flag bits <it/set-bits/ in the <tt/sgttyb/ + structure. + + <tag/<tt>xc#<it/clear-bits/</tt>/ + + Clears local mode bits <it/clear-bits/ after opening + the device. + + <tag/<tt>xs#<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/-# <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/%!/ (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 -#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/-#/ option + to <tt/lpr/ by adding the <tt/sc/ capability to the + <tt>/etc/printcap</tt> file. When users submit jobs + with the <tt/-#/ 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 -#/, 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/<deischen@iworks.interworks.org>// + + For providing a plethora of HP filter programs for perusal. + + <tag/Jake Hamby <tt/<jehamby@lightside.com>// + + For the Ghostscript-to-HP filter. + + <tag/My wife, Mary Kelly <tt/<urquhart@argyre.colorado.edu>// + + 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#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>=></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#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. + |