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 @@ + + + +DES, MD5, and Crypt + +

Contributed by &a.wollman;24 September 1995. + +

History + +

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

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 `libcrypt' +because the name of the C function to implement it is +`crypt'. 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. + +

Meanwhile, work was also underway on the DES-based password hash +function. First, a version of the `crypt' 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 `libcrypt' contains only the code involved in performing +the one-way password hash, and a separate `libcipher' 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. + +

Recognizing your `crypt' mechanism + +

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 +`$1$'. DES password strings do not have +any particular identifying characteristics, but they are shorter +than MD5 passwords, and are coded in a 64-character alphabet +which does not include the `$' character, so a +relatively short string which doesn't begin with a dollar sign is +very likely a DES password. + +

Determining which library is being used on your system is fairly +easy for most programs, except for those like `init' 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 +`crypt' are linked against `libcrypt', which for +each type of library is a symbolic link to the appropriate +implementation. For example, on a system using the DES versions: + + +$ 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 + + +On a system using the MD5-based libraries, the same links will be +present, but the target will be `libscrypt' rather than +`libdescrypt'. 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 @@ + + + +PC DMA + +

Contributed by &a.uhclem;. + 31 August 1995. + +Posted to : + +

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

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). + + +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 +(-DACK%d && TC && DEVICE_DMA_ACTIVE) and then +latch an IRQ%d 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 DRQ%d when idle and only +honoring -DACK%d 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 DRQ%d. + +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 @@ + + + + + + ESDI hard disks and FreeBSD + +

Copyright © 1995, &a.wilko;.24 September 1995. + + ESDI is an acronym that means Enhanced Small Device Interface. + It is loosely based on the good old ST506/412 interface originally + devised by Seagate Technology, the makers of the first affordable + 5.25" winchester disk. + + The acronym says Enhanced, and rightly so. In the first place + the speed of the interface is higher, 10 or 15 Mbits/second + instead of the 5 Mbits/second of ST412 interfaced drives. + Secondly some higher level commands are added, making the ESDI + interface somewhat 'smarter' to the operating system driver + writers. It is by no means as smart as SCSI by the way. ESDI + is 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. + + Concepts of ESDI +

+ Physical connections +

+ 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. + + Device addressing +

+ On each command cable a maximum of 7 devices and 1 controller + can be present. To enable the controller to uniquely + identify which drive it addresses, each ESDI device is equipped + with jumpers or switches to select the devices address. + + On PC type controllers the first drive is set to address 0, + the second disk to address 1. Always make sure you + set each disk to an unique address! So, on a PC with it's + two drives/controller maximum the first drive is drive 0, the + second is drive 1. + + Termination +

+ The daisy chained command cable (the 34 pin cable remember?) + needs to be terminated at the last drive on the chain. + For this purpose ESDI drives come with a termination resistor + network that can be removed or disabled by a jumper when it + is not used. + + So, one and only one drive, the one at + the 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 not in the middle. + + Using ESDI disks with FreeBSD +

+ Why is ESDI such a pain to get working in the first place? + + People who tried ESDI disks with FreeBSD are known to have + developed a profound sense of frustration. A combination of + factors works against you to produce effects that are + hard to understand when you have never seen them before. + + This has also led to the popular legend ESDI and FreeBSD + is a plain NO-GO. + The following sections try to list all the pitfalls and + solutions. + + ESDI speed variants +

+ As briefly mentioned before, ESDI comes in two speed 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 and drive + documentation to see if things match. + + Stay on track +

+ Mainstream ESDI drives use 34 to 36 sectors per track. + Most (older) controllers cannot handle more than this + number of sectors. + Newer, higher capacity, drives use higher numbers of sectors + per track. For instance, I own a 670 Mb drive that has + 54 sectors per track. + + In my case, the controller could not handle this number + of sectors. It proved to work well except that it only + used 35 sectors on each track. This meant losing a + lot of 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. + + Hard or soft sectoring +

+ Most ESDI drives allow hard or soft sectoring to be + selected using a jumper. Hard sectoring means that the + drive will produce a sector pulse on the start of each + new sector. The controller uses this pulse to tell when + it should start to write or read. + + Hard sectoring allows a selection of sector size (normally + 256, 512 or 1024 bytes per formatted sector). FreeBSD uses + 512 byte sectors. The number of sectors per track also varies + while still using the same number of bytes per formatted sector. + The number of unformatted bytes per sector varies, + dependent on your controller it needs more or less overhead + bytes to work correctly. Pushing more sectors on a track + of course gives you more usable space, but might give + problems if your controller needs more bytes than the + drive offers. + + In case of soft sectoring, the controller itself determines + where to start/stop reading or writing. For ESDI + hard sectoring is the default (at least on everything + I came across). I never felt the urge to try soft sectoring. + + In general, experiment with sector settings before you install + FreeBSD because you need to re-run the low-level format + after each change. + + Low level formatting +

+ ESDI drives need to be low level formatted before they + are usable. A reformat is needed whenever you figgle + with the number of sectors/track jumpers or the + physical orientation of the drive (horizontal, vertical). + So, first think, then format. + The format time must not be underestimated, for big + disks it can take hours. + + After a low level format, a surface scan is done to + find and flag bad sectors. Most disks have a + manufacturer bad block list listed on a piece of paper + or adhesive sticker. In addition, on most disks the + list is also written onto the disk. + Please use the manufacturer's list. It is much easier + to remap a defect now than after FreeBSD is installed. + + Stay away from low-level formatters that mark all + sectors of a track as bad as soon as they find one + bad sector. Not only does this waste space, it also + and more importantly causes you grief with bad144 + (see the section on bad144). + + Translations +

+ Translations, although not exclusively a ESDI-only problem, + might give you real trouble. + Translations come in multiple 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 all disk I/O) by using + translation. For instance, a big drive might be presented + to the system as having 32 heads and 64 sectors/track. + The result is that the number of cylinders is reduced to + something below 1024 and is therefore usable by the system + without problems. + It is noteworthy to know that FreeBSD 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). + + Whatever you do to translations after reading this document, + keep in mind that if you have multiple operating systems on the + same disk, all must use the same translation + + While on the subject of translations, I'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. + + Spare sectoring +

+ Most ESDI controllers offer the possibility to remap bad sectors. + During/after the low-level format of the disk bad sectors are + marked as such, and a replacement sector is put in place + (logically of course) of the bad one. + + In most cases the remapping is done by using N-1 sectors on + each track for actual 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 bad to good + is performed by the BIOS of the ESDI controller. FreeBSD, + being a true 32 bit operating system, does not use the BIOS + after it has been booted. Instead, it has device drivers that + talk directly to the hardware. + + So: don't use spare sectoring, bad block remapping or + whatever it may be called by the controller manufacturer when you + want to use the disk for FreeBSD. + + Bad block handling +

+ The preceding section leaves us with a problem. The controller's + bad block handling is not usable and still FreeBSD's filesystems + assume perfect media without any flaws. + To solve this problem, FreeBSD use the bad144 tool. + Bad144 (named after a Digital Equipment standard for bad block + handling) scans a FreeBSD slice for bad blocks. Having found + these bad blocks, it writes a table with the offending block + numbers to the end of the FreeBSD slice. + + When the disk is in operation, the 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 every sector of a track as bad when + they find a flaw on the track. As you can imagine, the + 126 limit is quickly reached when the low-level format is done + this way. + + Second, if the slice contains the root filesystem, the slice + should be within the 1024 cylinder BIOS limit. During the + boot process the bad144 list is read using the BIOS and this + only succeeds when the list is within the 1024 cylinder limit. + Note that the restriction is not that only the root + filesystem must be within the 1024 cylinder limit, but + rather the entire slice that contains the root filesystem. + + + Kernel configuration +

+ ESDI disks are handled by the same wddriver as + IDE and ST412 MFM disks. The wd driver should work + for all WD1003 compatible interfaces. + + Most hardware is jumperable for one of two different I/O + address ranges and IRQ lines. This allows you to have + two wd type controllers in one system. + + When your hardware allows non-standard strappings, you + can use these with FreeBSD as long as you enter the + correct info into the kernel config file. + An example from the kernel config file (they live in + /sys/i386/conf BTW). + + +# First WD compatible controller +controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr +disk wd0 at wdc0 drive 0 +disk wd1 at wdc0 drive 1 + +# Second WD compatible controller +controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr +disk wd2 at wdc1 drive 0 +disk wd3 at wdc1 drive 1 + + + + + Particulars on ESDI hardware +

+ Adaptec 2320 controllers +

+ I 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 + (ftpable from www.adaptec.com) and answered NO + to the question whether the disk should be formatted with a + spare sector on each track. The BIOS on the ACD-2320 was + disabled. I used the 'free configurable' option in the system + BIOS to allow the BIOS to boot it. + + Before using NEFMT.EXE I tried to format the disk using the + ACB-2320 BIOS 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. + + Western Digital WD1007 controllers +

+ 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. + + Ultrastor U14F controllers +

+ According to multiple reports from the net, Ultrastor ESDI + boards work OK with FreeBSD. I lack any further info on + particular settings. + + + + Further reading

+ If you intend to do some serious ESDI hacking, you might want to + have the official standard at hand: + + The latest ANSI X3T10 committee document is: + +Enhanced Small Device Interface (ESDI) [X3.170-1990/X3.170a-1991] + [X3T10/792D Rev 11] + + On Usenet the newsgroup 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 . + For info on Western Digital controllers see . + + Thanks to... +

+ 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 @@ + + + +Firewalls + +

Contributed by &a.gpalmer;.4th of October 1995 + +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. + +Note: 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. + +What is a firewall? + +

There are currently two distinct types of firewalls in common +use on the Internet today. The first type is more properly called +a packet filtering router, where the kernel on a +multi-homed machine chooses whether to forward or block packets +based on a set of rules. The second type, known as proxy +servers, rely on daemons to provide authentication and to +forward packets, possibly on a multi-homed machine which has +kernel packet forwarding disabled. + +

Sometimes sites combine the two types of firewalls, so that only a +certain machine (known as a bastion host) is allowed to send +packets through a packet filtering router onto an internal +network. Proxy services are run on the bastion host, which are +generally more secure than normal authentication mechanisms. + +

FreeBSD comes with a kernel packet filter (known as IPFW), +which is what the rest of this section will concentrate on. Proxy +servers can be built on FreeBSD from third party software, but there +is such a vareity of proxy servers available that it would be +impossible to cover them in this document. + +Packet filtering routers + +

A router is a machine which forwards packets between two or more +networks. A packet filtering router has an extra piece of code in 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. + +

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

The packet matching criteria varies depending on the software used, +but typically you can specify rules which depend on the source IP +address of the packet, the destination IP address, the source port +number, the destination port number (for protocols which support +ports), or even the packet type (UDP, TCP, ICMP, etc). + +Proxy servers + +

Proxy servers are machines which have had the normal system daemons +(telnetd, ftpd, etc) replaced with special servers. These servers are +called proxy servers as they normally only allow onward +connections to be made. This enables you to run (for example) a proxy +telnet server on your firewall host, and people can telnet in to your +firewall from the outside, go through some authentication mechanism, +and then gain access to the internal network (alternatively, proxy +servers can be used for signals coming from the internal network and +heading out). + +

Proxy servers are normally more secure than normal servers, and +often have a wider variety of authentication mechanisms available, +including ``one-shot'' password systems so that even if someone +manages to discover what password you used, they will not be able to use +it to gain access to your systems as the password instantly +expires. As they do not actually give users access to the host machine, +it becomes a lot more difficult for someone to install backdoors +around your security system. + +

Proxy servers often have ways of restricting access further, so +that only certain hosts can gain access to the servers, and often they +can be set up so that you can limit which users can talk to which +destination machine. Again, what facilities are available depends +largely on what proxy software you choose. + +What does IPFW allow me to do? + +

IPFW, the software supplied with FreeBSD, is a packet +filtering and accounting system which resides in the kernel, and has a +user-land control utility, ipfw(8). Together, they +allow you to define and query the rules currently used by the kernel +in its routing decisions. + +

There are two related parts to IPFW. The firewall section +allows you to perform packet filtering. There is also an IP accounting +section which allows you to track usage of your router, based on +similar rules to the firewall section. This allows you to see (for +example) how much traffic your router is getting from a certain +machine, or how much WWW (World Wide Web) traffic it is forwarding. + +

As a result of the way that IPFW is designed, you can use +IPFW on non-router machines to perform packet filtering on +incoming and outgoing connections. This is a special case of the more +general use of IPFW, and the same commands and techniques +should be used in this situation. + +Enabling IPFW on FreeBSD + +

As the main part of the IPFW system lives in the kernel, you will +need to add one or more options to your kernel configuration +file, depending on what facilities you want, and recompile your kernel. See + for more +details on how to recompile your kernel. + +

There are currently three kernel configuration options +relevant to IPFW: + + +syslogd. Without this option, even if you +specify that packets should be logged in the filter rules, nothing +will happen. + + + +Configuring IPFW + +

The configuration of the IPFW software is done through the +ipfw(8) utility. The syntax for this command looks +quite complicated, but it is relatively simple once you understand +it's structure. + +

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. + +Altering the IPFW rules + +

The syntax for this form of the command is: + +ipfw [-n] command action protocol addresses + + +

There is one valid flag when using this form of the command: + + + + +The command given can be shortened to the shortest unique +form. The valid commands are: + + + + + +If no command is given, it will default addfirewall or +addaccounting depending on the arguments given. + +

Currently, the firewall support in the kernel applies a set of +weights to the rule being added. This means that the rules will +not 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. + +

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 list command, as that command lists the rules in +the order that they are evaluated, not the order that they were fed to +the system. + +

The actions available depend on which rule chain the +entry is destined for. For the firewall chain, valid +actions are: + + + +reject, but also log the packet details. + +deny, but also log the packet details. + +accept. + + + +For the accounting chain, valid actions are: + + + + + +

Each action will be recognized by the shortest unambigious +prefix. + +The protocols which can be specified are: + + + + + +

The address specification is: + +[from <address/mask>[port]] [to + <address/mask>[port]] [via <interface>] + + +

You can only specify port in conjunction with +protocols which support ports (UDP, TCP and SYN). + +

The order of the from, to, and +via keywords is unimportant. Any of them can be omitted, +in which case a default entry for that keyword will be supplied which +matches everything. + +

The via is optional and may specify the IP address or +domain name of a local IP interface, or an interface name (e.g. +ed0) to match only packets coming through this interface. The +keyword via can be substituted by on, for +readability reasons. + +

The syntax used to specify an <address/mask> is: + +<address> + +or + +<address>/mask-bits + +or + +<address>:mask-pattern + + +

A valid hostname may be specified in place of the IP +address. mask-bits is a decimal number representing how many +bits in the address mask should be set. e.g. specifying + +192.216.222.1/24 + +will create a mask which will allow any address in a class C subnet +(in this case, 192.216.222) to be matched. mask-pattern is an IP +address which will be logically AND'ed with the address given. The +keyword any may be used to specify ``any IP address''. +

The port numbers to be blocked are specified as: + +port[,port[,port[...]]] + +to specify either a single port or a list of ports, or + +port:port + +to specify a range of ports. The name of a service (from +/etc/services) can be used instead of a numeric port value. + +Listing/flushing the IPFW rules + +

The syntax for this form of the command is: + +ipfw [-ans] command [argument] + + +

There are three valid flags when using this form of the command: + + + +-s. + +-a +to see accounting counters. The short form listing is incompatible +with the input syntax used by the ipfw(8) utility. + + + +The command given can be shortened to the shortest unique +form. The valid commands are: + + + +-s flag is +given, the format is compatable with the command line syntax. + + + +The list and flush commands may optionally be passed +an argument to specify which chain to flush. Valid arguments are: + + + + + +

The policy command can be given one of two arguments: + + + + + +As usual, the arguments can be shortened to the shortest unique form +(in this case, the first letter). + +Example commands for ipfw + +

This command will deny all packets from the host +evil.hacker.org to the telnet port of the host +nice.people.org by being forwarded by the router: + + +ipfw addf deny tcp from evil.hacker.org to nice.people.org telnet + + +

The next example denies and logs any TCP traffic from the entire +hacker.org network (a class C) to the nice.people.org +machine (any port). + + +ipfw addf ldeny tcp from evil.hacker.org/24 to nice.people.org + + +If you do not want people sending X sessions to your internal network +(a subnet of a class C), the following command will do the necessary +filtering: + + +ipfw addf deny syn to my.org/28 6000 + + +To allow access to the SUP server on sup.FreeBSD.ORG, use the +following command: + + +ipfw addf accept syn to sup.FreeBSD.ORG supfilesrv + + +To see the accounting records: + +ipfw -sa list accounting + +or in the short form + +ipfw -sa l a + + +Building a packet filtering firewall + +

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

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. + +Note: If you use the logging versions of the +accept command, it can generate large 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 +/var/log is located on. + +

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 /etc/netstart 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. + +

The actual script used to load the rules is entirely up to +you. There is currently no support in the ipfw utility for +loading multiple rules in the one command. The system I use is to use +the command: + + +# ipfw list + + +to write a list of the current rules out to a file, and then use a +text editor to prepend ``ipfw '' 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. + +

The next problem is what your firewall should actually DO! +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: + + + + 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. + + 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. + + Block all incoming UDP traffic. There are very few +useful services that travel over UDP, and what useful traffic there is +is normally a security threat (e.g. Suns RPC and NFS protocols). This +has its disadvantages also, since UDP is a connectionless protocol, +denying incoming UDP traffic also blocks the replies to 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. + + 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 xhost + on +their workstations). X11 can actually use a range of ports starting at +6000, the upper limit being how many X displays you can run on the +machine. The upper limit as defined by RFC 1700 (Assigned Numbers) is +6063. + + Check what ports any internal servers use (e.g. SQL servers, +etc). It's probably a good idea to block those as well, as they +normally fall outside the 1-1024 range specified above. + + + +

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

As I said above, these are only guidelines. You will have +to decide what filter rules you want to use on your firewall +yourself. I cannot accept ANY responsibility if someone breaks into +your network, even if you follow the advice given above. 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 @@ + + + + Configuring the FreeBSD Kernel + +

Contributed by &a.jehamby;.6 October 1995. + + 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. + + Why build a custom kernel? + +

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 your PC's hardware. This has a number of + benefits: + + + + It will take less time to boot because it does not + have to spend time probing for hardware which you + do not have. + + 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. + + 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 not present + in the GENERIC kernel. + +

+ + Building and Installing a Custom Kernel + +

First, let us take a quick tour of the kernel build + directory. All directories mentioned will be relative to + the main /usr/src/sys directory, which is also + accessible through /sys. There are a number of + subdirectories here representing different parts of the + kernel, but the most important, for our purposes, are + i386/conf, where you will edit your custom + kernel configuration, and compile, 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 i386 + directory deals with PC hardware only, while everything + outside the i386 directory is common to all + platforms which FreeBSD could potentially be ported to. + + not a + /usr/src/sys 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. + + Next, move to the i386/conf directory and copy + the GENERIC configuration file to the name you want to + give your kernel. For example: + +# cd /usr/src/sys/i386/conf +# cp GENERIC MYKERNEL + + 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. + + + + Now, edit MYKERNEL with your favorite text editor. If + you're just starting out, the only editor available will + probably be vi, which is too complex to explain + here, but is covered well in many books in the . 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 + section slowly and carefully. + + When you're finished, type the following to compile and + install your kernel: + +# /usr/sbin/config MYKERNEL +# cd ../../compile/MYKERNEL +# make +# make install + + The new kernel will be copied to the root directory as + /kernel and the old kernel will be moved to + /kernel.old. Now, shutdown the system and + reboot to use your kernel. In case something goes wrong, + there are some instructions at the end of this + document. Be sure to read the section which explains how + to recover in case your new kernel . + + to your + /dev directory before you can use them. + + The Configuration File + +

The general format of a configuration file is quite + simple. Each line contains a keyword and one or more + arguments. For simplicity, most lines only contain one + argument. Anything following a # is considered + a comment and ignored. The following sections describe + each keyword, generally in the order they are listed in + GENERIC, although some related keywords have been grouped + together in a single section (such as Networking) even + though they are actually scattered throughout the GENERIC + file. An exhaustive list of options is present in the + LINT configuration file, located in the same directory as + GENERIC. + + Mandatory Keywords + +

These keywords are required in every kernel you build. + + + + machine ``i386'' + +

The first keyword is machine, which, + since FreeBSD only runs on Intel 386 and compatible + chips, is i386. + + Note: that any keyword which + contains numbers used as text must be enclosed in + quotation marks, otherwise config gets + confused and thinks you mean the actual number + 386. + + cpu ``cpu_type'' + +

The next keyword is cpu, which includes + support for each CPU supported by FreeBSD. The + possible values of cpu_type + include: + + I386_CPU + I486_CPU + I586_CPU + + and multiple instances of the cpu line may + be present with different values of + cpu_type 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 I586_CPU + for cpu_type. + + ident machine_name + +

Next, we have ident, 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 ident 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 machine and cpu, enclose + your kernel's name in quotation marks if it + contains any numbers. + + maxusers number + +

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 + maxusers to at least four, especially if + you're using X Windows or compiling software. The + reason is that the most important table set by + maxusers is the maximum number of + processes, which is set to 20 + 16 * + maxusers, so if you set maxusers + to 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 man page will + start up nine processes to filter, decompress, and + view it. Setting maxusers 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. + + maxuser does + not limit the number of users which can + log into your machine. It simply sets various + table sizes to reasonable values considering the + maximum number of users you will likely have on + your system and how many processes each of them + will be running. One keyword which + does limit the number of simultaneous + remote logins is . + + config kernel_name root on root_device + +

This line specifies the location and name of the + kernel. Traditionally the kernel is called + vmunix but in FreeBSD, it is aptly named + kernel. You should always use + kernel for kernel_name 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 + wd0 for systems with non-SCSI drives, or + sd0 for systems with SCSI drives. + + + + General Options + +

These lines provide kernel support for various + filesystems and other options. + + + +

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. + + Note: The normal math coprocessor + emulation routines that come with FreeBSD are + not very accurate. If you do not have a + math coprocessor, and you need the best accuracy, + I recommend that you change this option to + GPL_MATH_EMULATE to use the superior GNU + math support, which is not included by default + for licensing reasons. + + options ``COMPAT_43'' + +

Compatibility with BSD 4.3. Leave this in; some + programs will act strangely if you comment this + out. + + options BOUNCE_BUFFERS + +

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. + + options UCONSOLE + +

Allow users to grab the console, useful for X + Windows. For example, you can create a console + xterm by typing xterm -C, which will + display any `write', `talk', and other messages you + receive. + + options SYSVSHM + +

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. + + options SYSVSEM + +

Support for System V + semaphores. Less commonly used but only adds a few + hundred bytes to the kernel. + + options SYSVMSG + +

Support for System V + messages. Again, only adds a few hundred bytes to + the kernel. + + ipcs(1) command will + tell will list any processes using using each of + these System V facilities. + + + + Filesystem Options + +

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 + FFS if you boot from a hard drive, or + NFS 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 + /lkm the first time you mount a partition of + that type. + + + + options FFS + +

The basic hard drive + filesystem; leave it in if you boot from the hard + disk. + + options NFS + +

Network Filesystem. Unless + you plan to mount partitions from a Unix file + server over Ethernet, you can comment this out. + + options MSDOSFS + +

MS-DOS Filesystem. Unless + you plan to mount a DOS formatted hard drive + partition at boot time, you can safely comment this + out. It will be automatically loaded the first + time you mount a DOS partition, as described above. + Also, the excellent mtools software (in + the ports collection) allows you to access DOS + floppies without having to mount and unmount them + (and does not require MSDOSFS at all). + + options ``CD9660'' + +

ISO 9660 filesystem 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. + + options PROCFS + +

Process filesystem. This + is a pretend filesystem mounted on /proc which + allows programs like ps(1) to give you + more information on what processes are running. + Leave it in. + + options MFS + +

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 + /tmp directory, since many programs store + temporary data here. To mount an MFS RAM disk on + /tmp, add the following line to + /etc/fstab and then reboot or type + mount /tmp: + +/dev/wd1s2b /tmp mfs rw 0 0 + + + /dev/wd1s2b + with the name of your swap partition, which will + be listed in your /etc/fstab as follows: + +/dev/wd1s2b none swap sw 0 0 + + + + /tmp device + simultaneously). As such, you may want to avoid + it for now. --> Also, the MFS filesystem + can not be dynamically loaded, so you + must compile it into your kernel if you + want to experiment with it. + + options QUOTA + +

Enable disk quotas. If you + have a public access system, and do not want users + to be able to overflow the /home + 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 quota(1) to learn more about disk + quotas. + + + + Basic Controllers and Devices + +

These sections describe the basic disk, tape, and + CD-ROM controllers supported by FreeBSD. There are + separate sections for controllers and cards. + + + + controller isa0 + +

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. + + controller pci0 + +

Include this if you have a + PCI motherboard. This enables auto-detection of + PCI cards and gatewaying from the PCI to the ISA + bus. + + controller fdc0 + +

Floppy drive controller: + fd0 is the ``A:'' floppy drive, and + fd1 is the ``B:'' drive. ft0 is + a QIC-80 tape drive attached to the floppy + controller. Comment out any lines corresponding to + devices you do not have. + + ft(8), see + the manual page for details. + + controller wdc0 + +

This is the primary IDE + controller. wd0 and wd1 are the + master and slave hard drive, respectively. + wdc1 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). + + controller wcd0 + +

This device + provides IDE CD-ROM support. Be sure to leave + wdc1 uncommented if your CD-ROM is on + its own controller card. To use this, you must + also include the line options ATAPI. + + device npx0 at isa? port ``IO_NPX'' irq 13 vector npxintr + +

npx0 is the interface to the + math coprocessor. If you have one then make sure + you've commented out above. If you do not have a + math coprocessor, you can comment this out. + + device wt0 at isa? port 0x300 bio irq 5 drq 1 vector wtintr + +

Wangtek and Archive + QIC-02/QIC-36 tape drive support + + Proprietary CD-ROM support + +

The following + drivers are for the so-called proprietary + CD-ROM drives. These drives have their own + controller card or might plug into a sound card + such as the Soundblaster 16. They are not + IDE or SCSI. Most older single-speed and + double-speed CD-ROMs use these interfaces, while + newer quad-speeds are likely to be or . + + + + device mcd0 at isa? port 0x300 bio irq 10 vector mcdintr + +

Mitsumi CD-ROM (LU002, + LU005, FX001D). + + device scd0 at isa? port 0x230 bio + +

Sony CD-ROM (CDU31, CDU33A). + + controller matcd0 at isa? port ? bio + +

Matsushita/Panasonic CD-ROM (sold by Creative + Labs for Soundblaster). + + + + + + SCSI Device Support + +

This section describes the various SCSI controllers + and devices supported by FreeBSD. + + + + SCSI Controllers + +

The next ten or so lines include support for + different kinds of SCSI controllers. Comment out + all except for the one(s) you have: + + + + controller bt0 at isa? port ``IO_BT0'' bio irq ? vector btintr + +

Most Buslogic controllers + + controller uha0 at isa? port ``IO_UHA0'' bio irq ? drq 5 vector uhaintr + +

UltraStor 14F and 34F + + controller ahc0 + +

Adaptec 274x/284x/294x + + controller ahb0 at isa? bio irq ? vector ahbintr + +

Adaptec 174x + + controller aha0 at isa? port ``IO_AHA0'' bio irq ? drq 5 vector ahaintr + +

Adaptec 154x + + controller aic0 at isa? port 0x340 bio irq 11 vector aicintr + + +

Adaptec 152x and sound cards using Adaptec AIC-6360 (slow!) + + controller nca0 at isa? port 0x1f88 bio irq 10 vector ncaintr + + +

ProAudioSpectrum cards using NCR 5380 or Trantor T130 + + controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr + +

Seagate ST01/02 8 bit controller (slow!) + + controller wds0 at isa? port 0x350 bio irq 15 drq 6 vector wdsintr + +

Western Digital WD7000 controller + + controller ncr0 + +

NCR 53C810 and 53C825 PCI SCSI controller + + + + options ``SCSI_DELAY=15'' + +

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. + + controller scbus0 + +

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. + + device sd0 + +

Support for SCSI hard + drives. + + device st0 + +

Support for SCSI tape + drives. + + device cd0 + +

Support for SCSI CD-ROM + drives. + + + + Console, Bus Mouse, and X Server Support + +

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. + + + + device sc0 at isa? port ``IO_KBD' tty irq 1 vector scintr + +

sc0 is the default + console driver, which resembles an SCO console. + Since most full-screen programs access the console + through a terminal database library like + termcap, it should not matter much whether + you use this or vt0, the VT220 compatible + console driver. When you log in, set your TERM + variable to ``scoansi'' if full-screen programs + have trouble running under this console. + + device vt0 at isa? port ``IO_KBD'' tty irq 1 vector pcrint + +

This is a VT220-compatible + console driver, backwards compatible to VT100/102. + It works well on some laptops which have hardware + incompatibilities with sc0. Also, set + your TERM variable to ``vt220'' when you log in if + full-screen programs do not run correctly on this + console. + + + + options ``PCVT_FREEBSD=210'' + +

Required + with the vt0 console driver. + + options XSERVER + +

This includes code + required to run the XFree86 X Window + Server. + + + + device mse0 at isa? port 0x23c tty irq 5 vector ms + +

Use this device if you have a Logitech or + ATI InPort bus mouse card. + + port is enabled (probably + COM1). + + device psm0 at isa? port ``IO_KBD'' conflicts tty irq 12 vector psmintr + +

Use this device if your + mouse plugs into the PS/2 mouse port. + + + + Serial and Parallel Ports + +

Nearly all systems have these. If you are attaching a + printer to one of these ports, the section of the handbook is very + useful. If you are using modem, provides extensive detail on + serial port configuration for use with such devices. + + + + device sio0 at isa? port ``IO_COM1'' tty irq 4 vector siointr + +

sio0 + through sio3 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 sio(4) for + more information on the proper values for these + lines. + + device lpt0 at isa? port? tty irq 7 vector lptintr + +

lpt0 through lpt2 + 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. + + + + Networking + +

FreeBSD, as with Unix in general, places a + big 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. + + + + options INET + 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. + + Ethernet cards + +

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): + + + + device de0 + +

Digital Equipment DC21040 PCI Ethernet adapter + + device cx0 at isa? port 0x240 net irq 15 drq 7 vector cxintr + +

Cronyx/Sigma multiport + sync/async (with Cisco or PPP framing) + + device ed0 at isa? port 0x280 net irq 5 iomem 0xd8000 vector edintr + +

Western Digital and SMC 80xx; Novell NE1000 + and NE2000; 3Com 3C503 + + device el0 at isa? port 0x300 net irq 9 vector elintr + +

3Com 3C501 (slow!) + + device eg0 at isa? port 0x310 net irq 5 vector egintr + +

3Com 3C505 + + device ep0 at isa? port 0x300 net irq 10 vector epintr + +

3Com 3C509 (buggy) + + device fe0 at isa? port 0x240 net irq ? vector feintr + +

Fujitsu MB86960A/MB86965A Ethernet + + device fea0 at isa? net irq ? vector feaintr + +

DEC DEFEA EISA FDDI adapter + + device ie0 at isa? port 0x360 net irq 7 iomem 0xd0000 vector ieintr + +

AT&T StarLAN 10 and EN100; 3Com 3C507; + unknown NI5210 + + device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixintr + +

Intel EtherExpress 16 + + device le0 at isa? port 0x300 net irq 5 iomem 0xd0000 vector le_intr + +

Digital Equipment EtherWorks 2 and EtherWorks + 3 (DEPCA, DE100, DE101, DE200, DE201, DE202, + DE203, DE204, DE205, DE422) + + device lnc0 at isa? port 0x300 net irq 10 drq 0 vector lncintr + +

Lance/PCnet cards (Isolan, Novell NE2100, + NE32-VL) + + device ze0 at isa? port 0x300 net irq 5 iomem 0xd8000 vector zeintr + +

IBM/National Semiconductor PCMCIA ethernet + controller. + + device zp0 at isa? port 0x300 net irq 10 iomem 0xd8000 vector zpintr + +

3Com PCMCIA Etherlink III + + + + + + pseudo-device loop + +

loop is the + generic loopback device for TCP/IP. If you telnet + or FTP to localhost + (a.k.a. 127.0.0.1) it will come back at + you through this pseudo-device. Mandatory. + + pseudo-device ether + +

ether is only + needed if you have an Ethernet card and includes + generic Ethernet protocol code. + + pseudo-device sl number + +

sl 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 number after + sl specifies how many simultaneous SLIP + sessions to support. This handbook has more + information on setting up a SLIP or . + + pseudo-device ppp number + +

ppp 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 tun and offers + more flexibility and features such as demand + dialing. If you still want to use this PPP driver, + read the + section of the handbook. As with the sl + device, number specifies how many + simultaneous PPP connections to support. + + pseudo-device tun number + +

tun 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 tun + specifies the number of simultaneous PPP sessions + to support. See the section of the handbook for + more information. + + pseudo-device bpfilter number + +

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 + tcpdump(1) program. Note that + implementation of this capability can seriously + compromise your overall network security. + The number 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. + + + + Sound cards + +

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 + every device) as follows: + + + + controller snd0 + +

Generic sound driver code. + Required for all of the following sound cards + except pca. + + device pas0 at isa? port 0x388 irq 10 drq 6 vector pasintr + +

ProAudioSpectrum digital audio and MIDI. + + device sb0 at isa? port 0x220 irq 7 conflicts drq 1 vector sbintr + +

SoundBlaster digital audio. + + irq 7 + to, for example, irq 5 and remove the + conflicts keyword. Also, you must add + the line: options ``SBC_IRQ=5'' + + device sbxvi0 at isa? drq 5 + +

SoundBlaster 16 digital 16-bit audio. + + drq 5 keyword appropriately, and then + add the line: options + "SB16_DMA=6" + + device sbmidi0 at isa? port 0x330 + +

SoundBlaster 16 MIDI interface. If you have a + SoundBlaster 16, you must include this line, or the + kernel will not compile. + + device gus0 at isa? port 0x220 irq 10 drq 1 vector gusintr + +

Gravis Ultrasound. + + device mss0 at isa? port 0x530 irq 10 drq 1 vector adintr + +

Microsoft Sound System. + + device opl0 at isa? port 0x388 conflicts + +

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 + playmidi (in the ports collection). + + device mpu0 at isa? port 0x330 irq 6 drq 0 + +

Roland MPU-401 stand-alone card. + + device uart0 at isa? port 0x330 irq 5 vector ``m6850intr'' + +

Stand-alone 6850 UART for MIDI. + + device pca0 at isa? port ``IO_TIMER1'' tty + +

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)! + + + + /usr/src/sys/i386/isa/sound/sound.doc. + Also, if you add any of these devices, be sure to + create the sound . + + Pseudo-devices + +

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 + pseudo-devices are in that section, while the remainder + are here. + + + + pseudo-device gzip + +

gzip allows you to run FreeBSD programs + that have been compressed with gzip. 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. + pseudo-device log + +

log is used for logging of kernel error + messages. Mandatory. + + + pseudo-device pty number + +

pty is a ``pseudo-terminal'' or simulated + login port. It's used by incoming telnet + and rlogin sessions, xterm, and some other + applications such as emacs. The number + indicates the number of ptys to create. + If you need more than GENERIC default of 16 + simultaneous xterm windows and/or remote logins, be + sure to increase this number accordingly, up to a + maximum of 64. + + pseudo-device snp number + +

Snoop device. This pseudo-device allows one + terminal session to watch another using the + watch(8) command. Note that + implementation of this capability has important + security and privacy implications. The + number after snp is the total number of + simultaneous snoop sessions. Optional. + + pseudo-device vn + +

Vnode driver. Allows a file to be treated as a + device after being set up with the + vnconfig(8) 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. + + + + Joystick, PC Speaker, Miscellaneous + +

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 every device): + + + + device joy0 at isa? port ``IO_GAME'' + +

PC joystick device. + + pseudo-device speaker + +

Supports IBM BASIC-style noises through the PC + speaker. Some fun programs which use this are + /usr/sbin/spkrtest, which is a shell + script that plays some simple songs, and + /usr/games/piano which lets you play songs + using the keyboard as a simple piano (this file + only exists if you've installed the games + 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. + + + + Making Device Nodes + +

Almost every device in the kernel has a corresponding + ``node'' entry in the /dev directory. These + nodes look like regular files, but are actually special + entries into the kernel which programs use to access the + device. The shell script /dev/MAKEDEV, which is + executed when you first install the operating system, + creates nearly all of the device nodes supported. + However, it does not create all of them, so when + you add support for a new device, it pays to make sure + that the appropriate entries are in this directory, and + if not, add them. Here is a simple example: + + Suppose you add the IDE CD-ROM support to the kernel. + The line to add is: + +controller wcd0 + + This means that you should look for some entries that + start with wcd0 in the /dev directory, + possibly followed by a letter, such as `c', or preceded + by the letter 'r', which means a `raw' device. It turns + out that those files are not there, so I must change to + the /dev directory and type: + +# sh MAKEDEV wcd0 + + When this script finishes, you will find that there are + now wcd0c and rwcd0c entries in + /dev so you know that it executed correctly. + + For sound cards, the command: + +# sh MAKEDEV snd0 + + creates the appropriate entries. Follow this simple + procedure for any other non-GENERIC devices which do not + have entries. + + /dev entries, so you do not need to create + these. Also, network cards and SLIP/PPP pseudo-devices + do not have entries in /dev at all, so you do + not have to worry about these either. + +If Something Goes Wrong + +

There are four categories of trouble that can occur when + building a custom kernel. They are: + + + + Config command fails + +

If the config + command fails when you give it your kernel + description, you've probably made a simple error + somewhere. Fortunately, config will print + the line number that it had trouble with, so you can + quickly skip to it with vi. For example, if + you see: + +config: line 17: syntax error + + you can skip to the problem in vi by typing + ``17G'' in command mode. Make sure the keyword is + typed correctly, by comparing it to the GENERIC + kernel or another reference. + + Make command fails + +

If the make + command fails, it usually signals an error in your + kernel description, but not severe enough for + config to catch it. Again, look over your + configuration, and if you still cannot resolve the + problem, send mail to with your kernel + configuration, and it should be diagnosed very + quickly. + + Kernel will not boot + +

If your new kernel + does not boot, or fails to recognize your devices, + do not panic! Fortunately, BSD has an excellent + mechanism for recovering from incompatible kernels. + Simply 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 + /var/log/messages file which records, among + other things, all of the kernel messages from every + successful boot. Also, the dmesg(8) command + will print the kernel messages from the current boot. + + kernel.old + because when installing a new kernel, + kernel.old is overwritten with the last + installed kernel which may be non-functional. + Also, as soon as possible, move the working kernel + to the proper ``kernel'' location or commands such + as ps(1) will not work properly. The + proper command to ``unlock'' the kernel file that + make installs (in order to move another + kernel back permanently) is: + +# chflags noschg /kernel + + And, if you want to ``lock'' your new kernel into place, or any file + for that matter, so that it cannot be moved or tampered with: + +# chflags schg /kernel + + + + Kernel works, but ps does not work any more! + +

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 ps(1) and + vmstat(8) will not work any more. You must + recompile the libkvm library as well as + these utilities. This is one reason it is not + normally a good idea to use a different version of + the kernel from the rest of the operating system. + + diff --git a/handbook/printing.sgml b/handbook/printing.sgml new file mode 100644 index 0000000000..522749b429 --- /dev/null +++ b/handbook/printing.sgml @@ -0,0 +1,3877 @@ + + + Printing + +

Contributed by &a.kelly;30 September 1995 + + 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 . + + What the Spooler Does + +

LPD controls everything about a host's printers. It's + responsible for a number of things: + + + It controls access to attached printers and + printers attached to other hosts on the network. + + It enables users to submit files to be printed; + these submissions are known as It prevents multiple users from accessing a printer + at the same time by maintaining a It can print It takes care of communications parameters for + printers connected on serial ports. + + It can send jobs over the network to another LPD + spooler on another host. + + It can run special filters to format jobs to be + printed for various printer languages or printer + capabilities. + + It can account for printer usage. + + + 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. + + Why You Should Use the Spooler + +

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 + + + LPD prints jobs in the background; you don't have + to wait for data to be copied to the printer. + + LPD can conveniently run a job to be printed + through filters to add date/time headers or convert a + special file format (such as a TeX DVI file) into a + format the printer will understand. You won't have to do + these steps manually. + + Many free and commercial programs that provide a + print feature usually expect to talk to the spooler on + your system. By setting up the spooling system, you'll + more easily support other software you may later add or + already have. + + + Setting Up the Spooling System + +

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: + + + See section to learn how to connect a + printer, tell LPD how to communicate with it, and + print plain text files to the printer. + + See section 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. + + + + Simple Printer Setup + +

This section tells how to configure printer hardware and the + LPD software to use the printer. It teaches the basics: + + + Section gives some hints on connecting the printer to a + port on your computer. + + Section shows how to setup the LPD spooler configuration + file /etc/printcap. + + + 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 . + + 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. + + Hardware Setup + +

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 . + + Ports and Cables + +

Nearly all printers you can get for a PC today support + one or both of the following interfaces: + + + Parallel interfaces are sometimes known as + ``Centronics'' interfaces, named after the connector + type on the printer. + + + 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? + + + If you need two-way communication, use a serial + port. FreeBSD does not yet support two-way + communication over a parallel port. + + 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. + + Finally, use whatever works. + + + + Parallel Ports + +

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. + + Serial Ports + +

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: + + A A A + + 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 Software Setup + +

This section describes the software setup necessary to + print with the LPD spooling system in FreeBSD. + + Here's an outline of the steps involved: + + Configure your kernel, if necessary, for the port + you're using for the printer; section tells + you what you need to do. + + Set the communications mode for the parallel port, + if you're using a parallel port; section gives + details. + + Test if the operating system can send data to the + printer. Section gives some + suggestions on how to do this. + + Set up LPD for the printer by modifying the file + /etc/printcap. Section + shows you how. + + + Kernel Configuration + +

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 + +dmesg | grep sio + where +sio2 at 0x3e8-0x3ef irq 5 on isa +sio2: type 16550A + + then the kernel supports the port. + + To find out if the kernel supports a parallel interface, + type + +dmesg | grep lpt + where +lpt0 at 0x378-0x37f on isa + + 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 Adding /dev Entries for the Ports + + +

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 + /dev directory are for. + + To add a /dev entry for a port: + + Become root with the Change to the /dev directory: + +cd /dev + + + Type + + ./MAKEDEV + where Type + +ls -l + to make sure the device entry got created. + + + Setting the Communication Mode for the Parallel Port + + +

When you're using the parallel interface, you can + choose whether FreeBSD should use interrupt-driven or + polled communication with the printer. + + + The The + + 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 To set the communications mode by configuring the + kernel: + + Edit your kernel configuration file. Look for + or add an + If you want interrupt-driven mode, add the +device lpt0 at isa? port? tty irq + + where If you want polled mode, don't add the + +device lpt0 at isa? port? tty vector lptintr + + + Save the file. Then configure, build, and + install the kernel, then reboot. See for more details. + + + To set the communications mode with + + + + Type + +lptcontrol -i -u + + to set interrupt-driven mode for + Type + +lptcontrol -p -u + + to set polled-mode for + You could put these commands in your + /etc/rc.local file to set the mode each time + your system boots. See lptcontrol(8) for more + information. + + Checking Printer Communications + +

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 +%!PS +100 100 moveto 300 300 lineto stroke +310 310 moveto +/Helvetica findfont 12 scalefont setfont +(Is this thing working?) show +showpage + + Checking a Parallel Printer + +

This section tells you how to check if FreeBSD can + communicate with a printer connected to a parallel port. + + To test a printer on a parallel port: + + Become root with Send data to the printer. + + If the printer can print plain text, then + use +lptest > /dev/lpt + + where If the printer understands PostScript or + other printer language, then send a small + program to the printer. Type + +cat > /dev/lpt + + Then, line by line, type the program + Alternatively, you can put the program in + a file and type + +cat /dev/lpt + + where + + + You should see something print. Don't worry if the + text doesn't look right; we'll fix such things later. + + Checking a Serial Printer + +

This section tells you how to check if FreeBSD can + communicate with a printer on a serial port. + + To test a printer on a serial port: + + Become root with Edit the file /etc/remote. Add the + following entry: + +printer:dv=/dev/ + + where + Here's a sample entry for a printer connected + via a serial line to the third serial port at + 19200 bps with no parity: + +printer:dv=/dev/ttyd2:br#19200:pa=none + + + Connect to the printer with +tip printer + + If this step doesn't work, edit the file + /etc/remote again and try using + /dev/cuaa instead of + /dev/ttyd. + + Send data to the printer. + + If the printer can print plain text, then + use +~$lptest + + + If the printer understands PostScript or + other printer language, then send a small + program to the printer. Type the program, + line by line, Alternatively, you can put the program in + a file and type + +˜> + + where + + + You should see something print. Don't worry if the + text doesn't look right; we'll fix that later. + + Enabling the Spooler: The /etc/printcap File + + +

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 + /etc/printcap. 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 /etc/printcap. The format is identical to other + capability files like /usr/share/misc/termcap and + /etc/remote. For complete information about the + format, see the cgetent(3). + + The simple spooler configuration consists of the following steps: + + Pick a name (and a few convenient aliases) for + the printer, and put them in the + /etc/printcap file; see . + + Turn off header pages (which are on by default) + by inserting the . + + Make a spooling directory, and specify its + location with the . + + Set the /dev entry to use for the + printer, and note it in /etc/printcap with + the . Also, if the + printer's on a serial port, set up the communication + parameters with the . + + Install a plain text input filter; see + + Test the setup by printing something with the + and . + + + tells how to do + this. + + Naming the Printer + +

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 + /etc/printcap should have the alias + /etc/printcap 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 + /etc/printcap that defines two printers (a + Diablo 630 line printer and a Panasonic KX-P4455 + PostScript laser printer): + +# +# /etc/printcap for host rose +# +rattan|line|diablo|lp|Diablo 630 Line Printer: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4: + + In this example, the first printer is named Suppressing Header Pages + +

The LPD spooling system will by default print a + /etc/printcap. Here's the example + /etc/printcap with +# +# /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: + + 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. + + Making the Spooling Directory + +

The next step in the simple spooler setup is to make a + /var/spool. It's not necessary to backup the + contents of spooling directories, either. Recreating + them is as simple as running +mkdir /var/spool/printer-name + + 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 + +mkdir /var/spool/lpd +mkdir /var/spool/lpd/rattan +mkdir /var/spool/lpd/bamboo + + + +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 + + + Finally, you need to tell LPD about these directories + using the /etc/printcap file. You specify the + pathname of the spooling directory with the +# +# /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: + + 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 /var/spool/lpd as + a default. + + Identifying the Printer Device + +

In section , we identified which + entry in the /dev 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 /dev entry pathname in the + /etc/printcap file using the /etc/printcap: + +# +# /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: + + + If you don't specify the /etc/printcap file, LPD uses + /dev/lp as a default. /dev/lp + currently doesn't exist in FreeBSD. + + If the printer you're installing is connected to a + parallel port, skip to the section . Otherwise, + be sure to follow the instructions in the next section. + + Configuring Spooler Communication + Parameters + +

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 + + It lets you try different communication + parameters by simply editing the + /etc/printcap file; you don't have to + recompile the filter program. + + It enables the spooling system to use the same + filter program for multiple printers which may have + different serial communication settings. + + + The following /etc/printcap capabilities + control serial communication parameters of the device + listed in the + br#/ + + Sets the communications speed of the device to + fc#/ + + Clears the flag bits fs#/ + + Sets the flag bits xc#/ + + Clears local mode bits xs#/ + + Sets local mode bits + For more information on the bits for the /usr/include/sys/ioctl_compat.h. + + When LPD opens the device specified by the +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=/var/spool/lpd/bamboo:\ + :lp=/dev/ttyd5:fs#0x82000c1:xs#0x820: + + + + Installing the Text Filter + +

We're now ready to tell LPD what text filter to use to + send jobs to the printer. A . + + For our simple printer setup, the text filter can be a + small shell script that just executes /bin/cat + to send the job to the printer. FreeBSD comes with + another filter called . + + First, let's make the shell script + /usr/local/libexec/if-simple be a simple text + filter. Put the following text into that file with your + favorite text editor: + +#!/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 + + Make the file executable: + +chmod 555 /usr/local/libexec/if-simple + + + And then tell LPD to use it by specifying it with the + /etc/printcap. We'll add + it to the two printers we have so far in the example + /etc/printcap: + +# +# /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: + + + Trying It Out + +

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 to generate some + test text. + + To test the simple LPD setup: + +

Type: + +lptest 20 5 | lpr -P + + where /etc/printcap. To test + the default printer, type +!"#$%&ero;'()*+,-./01234 +"#$%&ero;'()*+,-./012345 +#$%&ero;'()*+,-./0123456 +$%&ero;'()*+,-./01234567 +%&ero;'()*+,-./012345678 + + + To further test the printer, try downloading larger + programs (for language-based printers) or running + . + + Troubleshooting + +

After performing the simple test with + /usr/local/libexec/if-simple prints a form + feed after it sends the job to the printer: + +#!/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 + + + +!"#$%&ero;'()*+,-./01234 + "#$%&ero;'()*+,-./012345 + #$%&ero;'()*+,-./0123456 + $%&ero;'()*+,-./01234567 + + You've become another victim of the +Printer received CR Printer prints CR +Printer received LF Printer prints CR + LF + + + Here are some ways to achieve this: + + 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. + +

Have FreeBSD's serial line driver + automatically convert LF to CR+LF. Of course, + this works with printers on serial ports + /etc/printcap file for the printer. + + Send an 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. + + +#!/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 + + + Here's an example /etc/printcap from + a host called orchid. It has a single printer + attached to its first parallel port, a Hewlett + Packard LaserJet 3Si named +# +# /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: + + + + +Printer received CR Printer prints CR +Printer received LF Printer prints CR + LF + + + + If the printer supports XON/XOFF flow + control, have FreeBSD use it by specifying the + TANDEM bit in the If the printer supports carrier flow + control, specify the MDMBUF bit in the If the printer doesn't support any flow + control, use some combination of the NLDELAY, + TBDELAY, CRDELAY, VTDELAY, and BSDELAY bits in + the + + /etc/printcap file. + + /etc/printcap file. + For example, here's the entry for +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 + + Then, try printing again. Check the log file (in + our example, /var/log/rattan.log) 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 /dev/console as a default. + + + Using Printers + +

This section tells you how to use printers you've setup with + FreeBSD. Here's an overview of the user-level commands: + + + + There's also an administrative command, , used to control printers and their queues. + + All three of the commands /etc/printcap file. This enables you to submit, + remove, and check on jobs for various printers. If you don't + use the Printing Jobs +

+ + To print files, type + +lpr + + This prints each of the listed files to the default printer. + If you list no files, +lpr /etc/host.conf /etc/hosts.equiv + + To select a specific printer, type + +lpr -P + + This example prints a long listing of the current directory + to the printer named +ls -l | lpr -P rattan + + Because no files were listed for the . + + Checking Jobs + +

When you print with +lpq -P bamboo + + shows the queue for the printer named +bamboo is ready and printing +Rank Owner Job Files Total Size +active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes +2nd kelly 10 (standard input) 1635 bytes +3rd mary 11 ... 78519 bytes + + This shows three jobs in the queue for for details. + + Job number nine consists of two files; multiple files given + on the +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 + + + Removing Jobs + +

If you change your mind about printing a job, you can + remove the job from the queue with the + + To remove the job from a specific printer, add the +lprm -P bamboo 10 + + The + + + Just use the +lprm -P rattan - + + + +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% + + + Beyond Plain Text: Printing Options + +

The Formatting and Conversion Options + +

The following +lpr -P bamboo -d fish-report.dvi + + 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. + + gives details. + + + + + Here's an example: this command prints a nicely + formatted version of the +zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t + + The Job Handling Options + +

The following options to + . + +

This example prints three copies of +lpr -#3 parser.c parser.h + + + + + Header Page Options + +

These options to for information about + setting up header pages. + + + for + details. + + + + Administrating Printers + +

As an administrator for your printers, you've had to + install, set up, and test them. Using the + Start and stop the printers + + Enable and disable their queues + + Rearrange the order of the jobs in each queue. + + + First, a note about terminology: if a printer is + /etc/printcap. + + + + + Advanced Printer Setup + +

This section describes filters for printing specially + formatted files, header pages, printing across networks, and + restricting and accounting for printer usage. + + Filters + +

Although LPD handles network protocols, queuing, access + control, and other aspects of printing, most of the + ). + + 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 /usr/libexec/lpr/lpf, + that works with many printers that can print plain text. + (It handles backspacing and tabs in the file, and does + accounting, but that'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: + + + Section , 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. + + 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 tells you what + you should do to overcome this problem. I recommend + reading this section if you have a PostScript printer. + + PostScript is a popular output format for many + programs. Even some people (myself included) write + PostScript code directly. But PostScript printers are + expensive. Section + tells how you can further modify a printer's text filter + to accept and print PostScript data on a + Section 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 Section tells all about a not often used feature of + LPD: output filters. Unless you're printing header + pages (see ), you can probably skip that + section altogether. + + Section describes + + How Filters Work + +

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 /etc/printcap, or + /dev/console by default). + + Which filter LPD starts and the filter's arguments depend + on what's listed in the /etc/printcap file and + what arguments the user specified for the job on the + for + details). + + There are three kinds filters you can specify in + /etc/printcap: + + The +[-c] -w + + where + + /etc/printcap, + default 132 + + + + A tells all about them. + Conversion filters also need to do accounting, if you + need printer accounting. + + Conversion filters are started with the following + arguments: + +-x + + where The + describe them. There are only two arguments to an + output filter: + +-w + + which are identical to the text filters + + Filters should also + + + The text filter that comes with the FreeBSD release, + /usr/libexec/lpr/lpf, 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. + + Accommodating Plain Text Jobs on PostScript Printers + + +

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 ); if not, + it should be shortly. You can fetch, build and install it + yourself, of course. After installing /etc/printcap: + + :if=/usr/local/libexec/psif: + + You should also specify the +#!/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 + + In the above script, ) includes a full featured text-to-PostScript + program called Simulating PostScript on Non-PostScript Printers + + +

PostScript is the +#!/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 + + Finally, you need to notify LPD of the filter via the + + :if=/usr/local/libexec/hpif: + + That's it. You can type Conversion Filters + +

After completing the simple setup described in , the + first thing you'll probably want to do is install + conversion filters for your favorite file formats + (besides plain ASCII text). + + Why Install Conversion Filters? + +

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: + +dvips seaweed-analysis.dvi +lpr seaweed-analysis.ps + + 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: + +lpr -d seaweed-analysis.dvi + + We got LPD to do the DVI file conversion for us by + specifying the lists the conversion options. + + For each of the conversion options you want a printer to + support, install a /etc/printcap. A conversion + filter is like the text filter for the simple printer + setup (see section ) except that instead + of printing plain text, the filter converts the file + into a format the printer can understand. + + Which Conversions Filters Should I Install? + + +

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 + /etc/printcap file, and how to invoke them with + the + /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 + + + In our example, using /etc/printcap. + + 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 Installing Conversion Filters + +

Since conversion filters are programs you install + outside of the base FreeBSD installation, they should + probably go under /usr/local. The directory + /usr/local/libexec 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 /etc/printcap. + + In our example, we'll add the DVI conversion filter to + the entry for the printer named /etc/printcap file again, with the new + +# +# /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: + + The DVI filter is a shell script named + /usr/local/libexec/psdf. Here's that script: + +#!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 "$@" + + This script runs ) with the arguments LPD passed to this script. + More Conversion Filter Examples + +

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: + +#!/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 + + 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 /etc/printcap file with an entry for + a printer using the above filter: + +# +# /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: + + + The following script is a conversion filter for troff + data from the groff typesetting system for the + PostScript printer named +#!/bin/sh +# +# pstf - Convert groff's troff data into PS, then print. +# Installed in /usr/local/libexec/pstf +# +exec grops | /usr/local/libexec/lprps "$@" + + The above script makes use of +#!/bin/sh +# +# pstf - Convert groff's troff data into PS, then print. +# Installed in /usr/local/libexec/pstf +# +exec grops + + That's it. Here's the entry we need to add to + /etc/printcap to enable the filter: + + :tf=/usr/local/libexec/pstf: + + + 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 +#!/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 + + And we'll add this line to the /etc/printcap + for the printer + :rf=/usr/local/libexec/hprf: + + + Here's one final, somewhat complex example. We'll add a + DVI filter to the LaserJet printer /etc/printcap with the location of the DVI + filter: + + :df=/usr/local/libexec/hpdf: + + + Now, for the hard part: making the filter. For that, we + need a DVI-to-LaserJet/PCL conversion program. The + FreeBSD ports collection (see ) has one: /dev/fd/0 for standard input is problematic. + We can get around that problem by linking (symbolically) + a temporary file name (one that ends in /dev/fd/0, thereby forcing /tmp 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 /etc/printcap). 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 /tmp. + + Here, finally, is the filter: + +#!/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 + + + Automated Conversion: An Alternative To Conversion Filters + + +

All these conversion filters accomplish a lot for your + printing environment, but at the cost forcing the user + to specify (on the Output Filters + +

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 + + LPD starts an output filter once for the entire + job instead of once for each file in the job. + + LPD doesn't make any provision to identify the + start or the end of files within the job for the + output filter. + + 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: + +-w + + where + + 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 . Furthermore, an output filter is actually + ) + only. LPD then expects the output filter to + +

The program /usr/libexec/lpr/lpf that comes + with FreeBSD binary distribution is a text filter (input + filter) that can indent output (job submitted with /etc/printcap 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 . + + Header Pages + +

If you've got . + + Enabling Header Pages + +

In the , we turned off header pages by specifying + /etc/printcap file. To enable header pages for + a printer, just remove the +#!/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 + + Specify the path to the output filter in the for more information. + + Here's an example /etc/printcap file for the printer + +# +# /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: + + Now, when users print jobs to + for more /etc/printcap. + + Controlling Header Pages + +

By enabling header pages, LPD will produce a +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 + + LPD appends a form feed after this text so the job starts + on a new page (unless you've got /etc/printcap). + + If you prefer, LPD can make a /etc/printcap file. + The header page will look like this: + +rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995 + + Also by default, LPD prints the header page first, then + the job. To reverse that, specify /etc/printcap. + + Accounting for Header Pages + +

Using LPD's built-in header pages enforces a particular + paradigm when it comes to printer accounting: header pages + must be + Accept LPD's paradigm and make header pages free. + + Install an alternative to LPD, such as LPDng or + PLP. Section tells more + about other spooling software you can substitute for + LPD. + + Write a /etc/printcap. + + Then again, all that might be too much trouble, and + users will certainly appreciate the more generous + system administrator who makes header pages free. + + + Header Pages on PostScript Printers + +

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 +#!/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` " 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 < + 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: + +#!/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 + + 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 ). + + As we've mentioned before, the above scheme, though fairly + simple, disables the ``suppress header page'' option (the + : write an output + filter that parses the LPD-generated header page and + produces a PostScript version. If the user submits the + job with Networked Printing + +

FreeBSD supports networked printing: sending jobs to + remote printers. Networked printing generally refers to two + different things: + + Accessing a printer attached to a remote host. You + install a printer that has a conventional serial or + parallel interface on one host. Then, you set up LPD to + enable access to the printer from other hosts on the + network. Section tells how to + do this. + + Accessing a printer attached directly to a network. + The printer has a network interface in addition (or in + place of) a more conventional serial or parallel + interface. Such a printer might work as follows: + + + It might understand the LPD protocol and can + even queue jobs from remote hosts. In this case, it + acts just like a regular host running LPD. Follow + the same procedure in section to set up such a + printer. + + It might support a data stream network + connection. In this case, you ``attach'' the + printer to one host on the network by making that + host responsible for spooling jobs and sending them + to the printer. Section gives some + suggestions on installing such printers. + + + + Printers Installed on Remote Hosts + +

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 . Do any + advanced setup in 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 /etc/printcap + files with the following: + + Name the entry anything you want. For + simplicity, though, you probably want to use the same + name and aliases as on the printer host. + + Leave the Make a spooling directory and specify its + location in the Place the name of the printer host in the Place the printer name on the + That's it. You don't need to list conversion filters, + page dimensions, or anything else in the + /etc/printcap file. + + Here's an example. The host rose has two printers, + /etc/printcap file for orchid (back from section + ). It already had the entry + for the printer +# +# /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: + + Then, we just need to make spooling directories on orchid: + +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 + + + Now, users on orchid can print to +lpr -P bamboo -d sushi-review.dvi + + the LPD system on orchid would copy the job to the + spooling directory /var/spool/lpd/bamboo and note + that it was a DVI job. As soon as the host rose has room + in its Printers with Networked Data Stream Interfaces + +

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 . + + The format of the /etc/printcap 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 + +#!/usr/bin/perl +# +# netprint - Text filter for printer attached to network +# Installed in /usr/local/libexec/netprint +# + +$#ARGV eq 1 || die "Usage: $0 "; + +$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 () { print PRINTER; } +exit 0; + + 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: + +#!/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 + + + + Restricting Printer Usage + +

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

The LPD system makes it easy for users to print multiple + copies of a file. Users can print jobs with /etc/printcap file. When users submit jobs + with the +lpr: multiple copies are not allowed + + + Note that if you've set up access to a printer remotely + (see section ), you need the + /etc/printcap + 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 /etc/printcap + file for the host rose. The printer +# +# /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: + + Now, we also need to add the /etc/printcap (and while we're at + it, let's disable multiple copies for the printer + +# +# /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: + + By using the +lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign + + There are many ways to prevent this abuse (including + ignoring it) which you are free to explore. + + Restricting Access To Printers + +

You can control who can print to what printers by using + the UNIX group mechanism and the /etc/printcap. Just place the users you want to + have access to a printer in a certain group, and then name + that group in the +lpr: Not a member of the restricted group + + if they try to print to the controlled printer. + + As with the ). + + For example, we'll let anyone access the printer + /etc/printcap + for host rose: + +# +# /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: + + Let's leave the other example /etc/printcap file + (for the host orchid) alone. Of course, anyone on orchid + can print to Controlling Sizes of Jobs Submitted + +

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 +# +# /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: + + 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 + /etc/printcap + files as well. See section for + more information on remote printing. + + There's another specialized way to limit job sizes from + remote printers; see section . + + Restricting Jobs from Remote Printers + +

The LPD spooling system provides several ways to restrict + print jobs submitted from remote hosts: + + + /etc/hosts.equiv and /etc/hosts.lpd. + 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 /etc/hosts.equiv is + also used by the ruserok(3) protocol, and affects + programs like /etc/hosts.lpd file + on the host rose: + +orchid +violet +madrigal.fishbaum.de + + 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. + + /etc/printcap to find the spooling directory + for this printer; here's +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: + + The spooling directory is the given in the +echo 6144 > /var/spool/lpd/bamboo/minfree + + /etc/printcap. When /usr/bin/false. + + + Accounting for Printer Usage + +

So, you need to charge for printouts. And why not? Paper + and ink cost money. And then there are maintenance + costs---printers are loaded with moving parts and tend to + break down. You'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 . + + Generally, there are two ways to do accounting: + + + + 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. + + Quick and Dirty Printer Accounting + +

FreeBSD comes with two programs that can get you set up + with simple periodic accounting right away. They are the + text filter , and + ), 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 /etc/printcap, and if not specified as an + absolute path, is relative to the spooling directory. + + LPD starts + 2.00 rose:andy + 3.00 rose:kelly + 3.00 orchid:mary + 5.00 orchid:mary + 2.00 orchid:zhang + + You should use a separate accounting file for each + printer, as /etc/printcap. + Then, each accounting file will be in the spooling directory + for a printer, in a file named + 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 + + These are the arguments + /etc/printcap. + + /etc/printcap, or two cents (the + default). You can specify + + In the default summary that + 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 + + To compute the dollar amount due, /etc/printcap 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 +pac -p1.50 + + makes each page cost one dollar and fifty cents. You can + really rake in the profits by using this option. + + Finally, running How Can You Count Pages Printed? + +

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 ) + 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 Alternatives to the Standard Spooler + +

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 + . There's also a . + + It's quite similar to the BSD LPD spooler, but boasts a + host of features, including: + + Better network support, including built-in support + for networked printers, NIS-maintained printcaps, and + NFS-mounted spooling directories + + Sophisticated queue management, allowing multiple + printers on a queue, transfer of jobs between queues, + and queue redirection + + Remote printer control functions + + Prioritization of jobs + + Expansive security and access options + + + . + + + + Acknowledgments + +

I'd like to thank the following people who've assisted in + the development of this document: + + + 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 @@ + + + + + Gateways and routes + +

Contributed by &a.gryphon;.6 October 1995. + + For one machine to be able to find another, there must be a + mechanism in place to describe how to get from one to the + other. This is called Routing. A ``route'' is a defined + pair of addresses: a destination and a + gateway. The pair indicates that if you are + trying to get to this destination, send along + through this gateway. There are three types of + destinations: individual hosts, subnets, and ``default''. The + ``default route'' is used if none of the other routes + apply. We will talk a little bit more about default routes + later on. There are also three types of gateways: + individual hosts, interfaces (also called ``links''), and + ethernet hardware addresses. + + An example + +

To illustrate different aspects of routing, we will use + the following example which is the output of the command + netstat -r: + + +Destination Gateway Flags Refs Use Netif Expire + +default outside-gw UGSc 37 418 ppp0 +localhost localhost UH 0 181 lo0 +test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77 +10.20.30.255 link#1 UHLW 1 2421 +foobar.com link#1 UC 0 0 +host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0 +host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 => +host2.foobar.com link#1 UC 0 0 +224 link#1 UC 0 0 + + + The first two lines specify the default route (which we + will cover in the next section) and the localhost route. + + The interface (Netif column) that it specifies to use + for localhost is lo0, also known as the + loopback device. This says to keep all traffic for this + destination internal, rather than sending it out over the + LAN, since it will only end up back where it started + anyway. + + The next thing that stands out are the + ``0:e0:...'' addresses. These are ethernet + hardware addresses. FreeBSD will automatically identify any + hosts (test0 in the example) on the local ethernet and + add a route for that host, directly to it over the ethernet + interface, ed0. There is also a timeout + (Expire column) associated with this type of route, + which is used if we fail to hear from the host in a + specific amount of time. In this case the route will be + automatically deleted. These hosts are identified using a + mechanism known as RIP (Routing Information Protocol), + which figures out routes to local hosts based upon a + shortest path determination. + + FreeBSD will also add subnet routes for the local subnet + (10.20.30.255 is the broadcast address for the subnet + 10.20.30, and foobar.com is the domain name + associated with that subnet). The designation link#1 + refers to the first ethernet card in the machine. You'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 routed. If this is not run, then only + routes which are statically defined (ie. entered + explicitly) will exist. + + The host1 line refers to our host, which it knows by + ethernet address. Since we are the sending host, FreeBSD + knows to use the loopback interface (lo0) rather than + sending it out over the ethernet interface. + + The two host2 lines are an example of what happens + when we use an ifconfig alias (see the section of ethernet + for reasons why we would do this). The => + symbol after the lo0 interface says that not only are + we using the loopback (since this is address also refers to + the local host), but specifically it is an alias. Such + routes only show up on the host that supports the alias; + all other hosts on the local network will simply have a + link#1 line for such. + + The final line (destination subnet 224) deals with + MultiCasting, which will be covered in a another section. + + The other column that we should talk about are the + Flags. Each route has different attributes that are + described in the column. Below is a short table of some of + these flags and their meanings: + + + + + + + Default routes + +

When the local system needs to make a connection to + remote host, it checks the routing table to determine if + a known path exists. If the remote host falls into a + subnet that we know how to reach (Cloned routes), then + the system checks to see if it can connect along that + interface. + + If all known paths fail, the system has one last option: + the default route. This route is a special type + of gateway route (usually the only one present in the + system), and is always marked with a ``c'' in + the flags field. For hosts on a local area network, this + gateway is set to whatever machine has a direct + connection to the outside world (whether via PPP link, or + your hardware device attached to a dedicated data line). + + If you are configuring the default route for a machine + which itself is functioning as the gateway to the outside + world, then the default route will be the gateway machine + at your Internet Service Provider's (ISP) site. + + Let's look at an example of default routes. This is a + common configuration: + +[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW] + + + The hosts Local1 and Local2 are at your + site, with the formed being your PPP connection to your + ISP's Terminal Server. Your ISP has a local network at + their site, which has, among other things, the server + where you connect and a hardware device (T1-GW) attached + to the ISP's internet feed. + + The default routes for each of your machines will be: + + +host default gateway interface +---- --------------- --------- +Local2 Local1 ethernet +Local1 T1-GW PPP + + + A common question is ``Why (or how) would we set the + T1-GW to be the default gateway for Local1, rather than + the ISP server it is connected to?''. + + Remember, since the PPP interface is using an address on + the ISP's local network for your side of the connection, + routes for any other machines on the ISP's local network + will be automatically generated. Hence, you will already + know how to reach the T1-GW machine, so there is no need + for the intermediate step of sending traffic to the ISP + server. + + As a final note, it is common to use the address ``...1'' + as the gateway address for your local network. So (using + the same example), if your local class-C address space + was 10.20.30 and your ISP was using 10.9.9 then the + default routes would be: + + +Local2 (10.20.30.2) --> Local1 (10.20.30.1) +Local1 (10.20.30.1, 10.9.9.30) --> T1-GW (10.9.9.1) + + + Dual homed hosts + +

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. + + Routing propogation + +

We have already talked about how we define our routes to + the outside world, but not about how the outside world + finds us. + + We already know that routing tables can be set up so that + all traffic for a particular address space (in our + examples, a class-C subnet) can be sent to a particular + host on that network, which will forward the packets + inbound. + + When you get an address space assigned to your site, your + service provider will set up their routing tables so that + all traffic for your subnet will be sent down your PPP + link to your site. But how do sites across the country + know to send to your ISP? + + There is a system (much like the distributed DNS + information) that keeps track of all assigned + address-spaces, and defines their point of connection to + the Internet Backbone. The ``Backbone'' are the main + trunk lines that carry internet traffic across the + country, and around the world. Each backbone machine has + a copy of a master set of tables, which direct traffic + for a particular network to a specific backbone carrier, + and from there down the chain of service providers until + it reaches your network. + + It is the task of your service provider to advertise to + the backbone sites that they are the point of connection + (and thus the path inward) for your site. This is known + as route propogation. + + + + Troubleshooting + +

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 traceroute(8) + command. It is equally useful if you cannot seem to make + a connection to a remote machine (ie. ping(8) + fails). + + The traceroute(8) command is run with the name + of the remote host you are trying to connect to. It will + show the gateway hosts along the path of the attempt, + eventually either reaching the target host, or + terminating because of a lack of connection. + + For more information, see the manual page for + traceroute(8). + 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 @@ + + + + +S/Key + +

Contributed by &a.wollman;25 September 1995. + +

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

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

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 +`There are four programs involved in the S/Key system which we will +discuss below. The `/etc/skeykeys file and +prints out the invoking user's current iteration count and seed. +Finally, the `There are four different sorts of operations we will cover. The first +is using the `Secure connection initialization + +

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 ` +$ 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 ) + + +

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. + +Insecure connection initialization + +

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 ` +$ 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 + + +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: + + +$ 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 + + +Now switch back over to the insecure connection, and copy the one-time +password generated by ` +s/key access password: HULL NAY YANG TREE TOUT VETO + +ID wollman s/key is 100 kh94742 +HULL NAY YANG TREE TOUT VETO + + +The rest of the description from the previous section applies here as +well. + +Diversion: a login prompt + +

Before explaining how to generate one-time passwords, we should go +over an S/Key login prompt: + + +$ telnet himalia +Trying 18.26.0.186... +Connected to himalia.lcs.mit.edu. +Escape character is '^]'. +s/key 92 hi52030 +Password: + + +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. + +

If this machine were configured to disallow UNIX passwords over a +connection from my machine, the prompt would have also included the +annotation `(s/key required)', indicating that only S/Key one-time +passwords will be accepted. + +Generating a single one-time password + +

Now, to generate the one-time password needed to answer this login +prompt, we use a trusted machine and the ` +$ 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 + + +And in the other window: + + +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.] + + +This is the easiest mechanism Generating multiple one-time passwords + +

Sometimes we have to go places where no trusted machines or +connections are available. In this case, it is possible to use the +` +$ 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 + + +The `Restricting use of UNIX passwords + +

The configuration file /etc/skey.access 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 If there is no /etc/skey.access 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 Here is a sample configuration file which illustrates the three most +common sorts of configuration statements: + + +permit internet 18.26.0.0 255.255.0.0 +permit user jrl +permit port ttyd0 + + +The first line (`The second line (`The third line (`