diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
index adb4df0e33..b11369b2fb 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,3884 +1,3884 @@
Advanced NetworkingSynopsisThe following chapter will cover some of the more frequently
used network services on Unix systems. This, of course, will
pertain to configuring said services on your FreeBSD system.Gateways and RoutesContributed by &a.gryphon;. 6 October
1995.routeroutinggatewaysubnetFor 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 exampleTo 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 0default routeThe first two lines specify the default route (which we will cover
in the next section) and the localhost route.loopback deviceThe 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.EthernetMAC addressThe 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.subnetFreeBSD will also add subnet routes for the local subnet (10.20.30.255 is the broadcast address for the
subnet 10.20.30, and foobar.com is the domain name associated
with that subnet). The designation link#1 refers
to the first Ethernet card in the machine. You will notice no
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 &man.ifconfig.8; 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:UUp: The route is active.HHost: The route destination is a single host.GGateway: Send anything for this destination on to this
remote system, which will figure out from there where to send
it.SStatic: This route was configured manually, not
automatically generated by the system.CClone: Generates a new route based upon this route for
machines we connect to. This type of route is normally used
for local networks.WWasCloned: Indicated a route that was auto-configured
based upon a local area network (Clone) route.LLink: Route involves references to Ethernet
hardware.Default routesdefault routeWhen the local system needs to make a connection to remote host,
it checks the routing table to determine if a known path exists. If
the remote host falls into a subnet that we know how to reach (Cloned
routes), then the system checks to see if it can connect along that
interface.If all known paths fail, the system has one last option: the
default route. This route is a special type of gateway
route (usually the only one present in the system), and is always
marked with a c in the flags field. For hosts on a
local area network, this gateway is set to whatever machine has a
direct connection to the outside world (whether via PPP link, or your
hardware device attached to a dedicated data line).If you are configuring the default route for a machine which
itself is functioning as the gateway to the outside world, then the
default route will be the gateway machine at your Internet Service
Provider's (ISP) site.Let us look at an example of default routes. This is a common
configuration:
[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW]
The hosts Local1 and Local2 are
at your site, with the formed being your PPP connection to your ISP's
Terminal Server. Your ISP has a local network at their site, which
has, among other things, the server where you connect and a hardware
device (T1-GW) attached to the ISP's Internet feed.The default routes for each of your machines will be:hostdefault gatewayinterfaceLocal2Local1EthernetLocal1T1-GWPPPA 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 hostsdual homed hostsThere 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 separate subnets. Alternately, the machine may only
have one Ethernet card, and be using &man.ifconfig.8; aliasing. The former is
used if two physically separate Ethernet networks are in use, the
latter if there is one physical network segment, but two logically
separate subnets.Either way, routing tables are set up so that each subnet knows
that this machine is the defined gateway (inbound route) to the other
subnet. This configuration, with the machine acting as a Bridge
between the two subnets, is often used when we need to implement
packet filtering or firewall security in either or both
directions.Routing propagationrouting propogationWe have already talked about how we define our routes to the
outside world, but not about how the outside world finds us.We already know that routing tables can be set up so that all
traffic for a particular address space (in our examples, a class-C
subnet) can be sent to a particular host on that network, which will
forward the packets inbound.When you get an address space assigned to your site, your service
provider will set up their routing tables so that all traffic for your
subnet will be sent down your PPP link to your site. But how do sites
across the country know to send to your ISP?There is a system (much like the distributed DNS information) that
keeps track of all assigned address-spaces, and defines their point of
connection to the Internet Backbone. The Backbone are
the main trunk lines that carry Internet traffic across the country,
and around the world. Each backbone machine has a copy of a master
set of tables, which direct traffic for a particular network to a
specific backbone carrier, and from there down the chain of service
providers until it reaches your network.It is the task of your service provider to advertise to the
backbone sites that they are the point of connection (and thus the
path inward) for your site. This is known as route
propagation.TroubleshootingtracerouteSometimes, there is a problem with routing propagation, and some
sites are unable to connect to you. Perhaps the most useful command
for trying to figure out where a routing is breaking down is the
&man.traceroute.8; command. It is equally useful if you cannot seem
to make a connection to a remote machine (i.e. &man.ping.8;
fails).The &man.traceroute.8; command is run with the name of the remote
host you are trying to connect to. It will show the gateway hosts
along the path of the attempt, eventually either reaching the target
host, or terminating because of a lack of connection.For more information, see the manual page for
&man.traceroute.8;.BridgingWritten by Steve Peterson
steve@zpfe.com.IntroductionIP subnetbridgeIt is sometimes useful to divide one physical network (i.e., an
Ethernet segment) into two separate network segments, without having
to create IP subnets and use a router to connect the segments
together. A device that connects two networks together in this
fashion is called a bridge. and a FreeBSD system with two network
interface cards can act as a bridge.The bridge works by learning the MAC layer addresses (i.e.,
Ethernet addresses) of the devices on each of its network interfaces.
It forwards traffic between two networks only when its source and
destination are on different networks.In many respects, a bridge is like an Ethernet switch with very
few ports.Situations where bridging is appropriateThere are two common situations in which a bridge is used
today.High traffic on a segmentSituation one is where your physical network segment is
overloaded with traffic, but you don't want for whatever reason to
subnet the network and interconnect the subnets with a
router.Let's consider an example of a newspaper where the Editorial and
Production departments are on the same subnetwork. The Editorial
users all use server A for file service, and the Production users
are on server B. An Ethernet is used to connect all users together,
and high loads on the network are slowing things down.If the Editorial users could be segregated on one network
segment and the Production users on another, the two network
segments could be connected with a bridge. Only the network traffic
destined for interfaces on the "other" side of the bridge would be
sent to the other network, reducing congestion on each network
segment.Filtering/traffic shaping firewallfirewallIP MasqueradingThe second common situation is where firewall functionality is
needed without IP Masquerading (NAT).An example is a small company that is connected via DSL or ISDN
to their ISP. They have a 13 address global IP allocation for their
ISP and have 10 PCs on their network. In this situation, using a
router-based firewall is difficult because of subnetting
issues.routerDSLISDNA bridge-based firewall can be configured and dropped into the
path just downstream of their DSL/ISDN router without any IP
numbering issues.Configuring a bridgeNetwork interface card selectionA bridge requires at least two network cards to function.
Unfortunately, not all network interface cards as of FreeBSD 4.0
support bridging. Read &man.bridge.4; for details on the cards that
are supported.Install and test the two network cards before continuing.Kernel configuration changeskernel configurationkernel configurationoptions BRIDGETo enable kernel support for bridging, add theoptions BRIDGEstatement to your kernel configuration file, and rebuild your
kernel.Firewall supportfirewallIf you are planning to use the bridge as a firewall, you will
need to add the IPFIREWALL option as well. Read for general information on configuring the
bridge as a firewall.If you need to allow non-IP packets (such as ARP) to flow
through the bridge, there is an undocumented firewall option that
must be set. This option is
IPFIREWALL_DEFAULT_TO_ACCEPT. Note that this
changes the default rule for the firewall to accept any packet.
Make sure you know how this changes the meaning of your ruleset
before you set it.Traffic shaping supportIf you want to use the bridge as a traffic shaper, you will need
to add the DUMMYNET option to your kernel
configuration. Read &man.dummynet.4; for further
information.Enabling the bridgeAdd the linenet.link.ether.bridge=1to /etc/sysctl.conf to enable the bridge at
runtime. If you want the bridged packets to be filtered by &man.ipfw.8;,
you should also addnet.link.ether.bridge_ipfw=1as well.PerformanceMy bridge/firewall is a Pentium 90 with one 3Com 3C900B and one
3C905B. The protected side of the network runs at 10mbps half duplex
and the connection between the bridge and my router (a Cisco 675) runs
at 100mbps full duplex. With no filtering enabled, I've found that
the bridge adds about 0.4 milliseconds of latency to pings from the
protected 10mbps network to the Cisco 675.Other informationIf you want to be able to telnet into the bridge from the network,
it is OK to assign one of the network cards an IP address. The
consensus is that assigning both cards an address is a bad
idea.If you have multiple bridges on your network, there cannot be more
than one path between any two workstations. Technically, this means
that there is no support for spanning tree link management.NFSWritten by &a.unfurl;, 4 March 2000.NFSAmong the many different file systems that FreeBSD supports is
a very unique type, the Network File System or NFS. NFS allows you
to share directories and files on one machine with one or more other
machines via the network they are attached to. Using NFS, users and
programs can access files on remote systems as if they were local
files.NFS has several benefits:Local workstations don't need as much disk space because
commonly used data can be stored on a single machine and still
remain accessible to everyone on the network.There is no need for users to have unique home directories
on every machine on your network. Once they have an established
directory that is available via NFS it can be accessed from
anywhere.Storage devices such as floppies and CDROM drives can be
used by other machines on the network eliminating the need for
extra hardware.How It WorksNFS is composed of two sides – a client side and a
server side. Think of it as a want/have relationship. The client
wants the data that the server side
has. The server shares its data with the
client. In order for this system to function properly a few
processes have to be configured and running properly.The server has to be running the following daemons:NFSserverportmapmountdnfsdnfsd - The NFS Daemon which services
requests from NFS clients.mountd - The NFS Mount Daemon which
actually carries out requests that &man.nfsd.8; passes on to
it.portmap - The
portmapper daemon which allows NFS
clients to find out which port the NFS server is
using.The client side only needs to run a single daemon:NFSclientnfsiodnfsiod - The NFS async I/O Daemon which
services requests from its NFS server.Configuring NFSNFSconfigurationLuckily for us, on a FreeBSD system this setup is a snap. The
processes that need to be running can all be run at boot time with
a few modifications to your /etc/rc.conf
file.On the NFS server make sure you have:portmap_enable="YES"
nfs_server_enable="YES"
nfs_server_flags="-u -t -n 4"
mountd_flags="-r"mountd is automatically run whenever the
NFS server is enabled. The and
flags to nfsd tell it to
serve UDP and TCP clients. The flag tells
nfsd to start 4 copies of itself.On the client, make sure you have:nfs_client_enable="YES"
nfs_client_flags="-n 4"Like nfsd, the tells
nfsiod to start 4 copies of itself.The last configuration step requires that you create a file
called /etc/exports. The exports file
specifies which file systems on your server will be shared
(a.k.a., exported) and with what clients they will
be shared. Each line in the file specifies a file system to be
shared. There are a handful of options that can be used in this
file but only a few will be mentioned here. You can find out
about the rest in the &man.exports.5; man page.Here are a few example /etc/exports
entries:NFSexporting filesystemsThe following line exports /cdrom to
three silly machines that have the same domain name as the server
(hence the lack of a domain name for each) or have entries in your
/etc/hosts file. The
flag makes the shared file system read-only. With this flag, the
remote system will not be able to make any changes to the
shared file system./cdrom -ro moe larry curlyThe following line exports /home to three
hosts by IP address. This is a useful setup if you have a
private network but do not have DNS running. The
flag allows all the directories below
the specified file system to be exported as well./home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4The following line exports /a to two
machines that have different domain names than the server. The
flag allows
the root user on the remote system to write to the shared
file system as root. Without the -maproot=0 flag even if
someone has root access on the remote system they won't
be able to modify files on the shared file system./a -maproot=0 host.domain.com box.example.comIn order for a client to share an exported file system it must
have permission to do so. Make sure your client is listed in your
/etc/exports file.It's important to remember that you must restart mountd
whenever you modify /etc/exports so that
your changes take effect. This can be accomplished by sending
the hangup signal to the mountd process :&prompt.root; kill -HUP `cat /var/run/mountd.pid`Now that you have made all these changes you can just reboot
and let FreeBSD start everything for you at boot time or you can
run the following commands as root:On the NFS server:&prompt.root; portmap
&prompt.root; nfsd -u -t -n 4
&prompt.root; mountd -rOn the NFS client:&prompt.root; nfsiod -n 4Now you should be ready to actually mount a remote file
system. This can be done one of two ways. In these examples the
server's name will be server and the client's
name will be client. If you just want to
temporarily mount a remote file system or just want to test out
your config you can run a command like this as root on the
client:NFSmounting filesystems&prompt.root; mount server:/home /mntThis will mount /home on the server on
/mnt on the client. If everything is setup
correctly you should be able to go into /mnt on the client and see
all the files that are on the server.If you want to permanently (each time you reboot) mount a
remote file system you need to add it to your
/etc/fstab file. Here is an example
line:server:/home /mnt nfs rw 0 0Read the &man.fstab.5; man page for more options.Practical UsesThere are many very cool uses for NFS. Some of the more common
ones are listed below.NFSusesHave several machines on a network and share a CDROM or
floppy drive among them. This is cheaper and often more
convenient.With so many machines on a network, it gets old having your
personal files strewn all over the place. You can have a
central NFS server that houses all user home directories and
shares them with the rest of the machines on the LAN, so no
matter where you log in you will have the same home
directory.When you get to reinstalling FreeBSD on one of your
machines, NFS is the way to go! Just pop your distribution
CDROM into your file server and away you go!Have a common /usr/ports/distfiles
directory that all your machines share. That way, when you go
to install a port that you've already installed on a different
machine, you do not have to download the source all over
again!Problems integrating with other systemsContributed by &a.jlind;.Certain Ethernet adapters for ISA PC systems have limitations
which can lead to serious network problems, particularly with NFS.
This difficulty is not specific to FreeBSD, but FreeBSD systems
are affected by it.The problem nearly always occurs when (FreeBSD) PC systems are
networked with high-performance workstations, such as those made
by Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS
mount will work fine, and some operations may succeed, but
suddenly the server will seem to become unresponsive to the
client, even though requests to and from other systems continue to
be processed. This happens to the client system, whether the
client is the FreeBSD system or the workstation. On many systems,
there is no way to shut down the client gracefully once this
problem has manifested itself. The only solution is often to
reset the client, because the NFS situation cannot be
resolved.Though the correct solution is to get a higher
performance and capacity Ethernet adapter for the FreeBSD system,
there is a simple workaround that will allow satisfactory
operation. If the FreeBSD system is the
server, include the option
on the mount from the client. If the
FreeBSD system is the client, then mount the
NFS file system with the option . These
options may be specified using the fourth field of the
fstab entry on the client for automatic
mounts, or by using the parameter of the mount
command for manual mounts.It should be noted that there is a different problem,
sometimes mistaken for this one, when the NFS servers and clients
are on different networks. If that is the case, make
certain that your routers are routing the
necessary UDP information, or you will not get anywhere, no matter
what else you are doing.In the following examples, fastws is the host
(interface) name of a high-performance workstation, and
freebox is the host (interface) name of a FreeBSD
system with a lower-performance Ethernet adapter. Also,
/sharedfs will be the exported NFS
filesystem (see man exports), and
/project will be the mount point on the
client for the exported file system. In all cases, note that
additional options, such as or
and may be desirable in
your application.Examples for the FreeBSD system (freebox) as
the client: in /etc/fstab on freebox:fastws:/sharedfs /project nfs rw,-r=1024 0 0As a manual mount command on freebox:&prompt.root; mount -t nfs -o -r=1024 fastws:/sharedfs /projectExamples for the FreeBSD system as the server: in
/etc/fstab on fastws:freebox:/sharedfs /project nfs rw,-w=1024 0 0As a manual mount command on fastws:&prompt.root; mount -t nfs -o -w=1024 freebox:/sharedfs /projectNearly any 16-bit Ethernet adapter will allow operation
without the above restrictions on the read or write size.For anyone who cares, here is what happens when the failure
occurs, which also explains why it is unrecoverable. NFS
typically works with a block size of 8k (though it
may do fragments of smaller sizes). Since the maximum Ethernet
packet is around 1500 bytes, the NFS block gets
split into multiple Ethernet packets, even though it is still a
single unit to the upper-level code, and must be received,
assembled, and acknowledged as a unit. The
high-performance workstations can pump out the packets which
comprise the NFS unit one right after the other, just as close
together as the standard allows. On the smaller, lower capacity
cards, the later packets overrun the earlier packets of the same
unit before they can be transferred to the host and the unit as a
whole cannot be reconstructed or acknowledged. As a result, the
workstation will time out and try again, but it will try again
with the entire 8K unit, and the process will be repeated, ad
infinitum.By keeping the unit size below the Ethernet packet size
limitation, we ensure that any complete Ethernet packet received
can be acknowledged individually, avoiding the deadlock
situation.Overruns may still occur when a high-performance workstations
is slamming data out to a PC system, but with the better cards,
such overruns are not guaranteed on NFS units. When
an overrun occurs, the units affected will be retransmitted, and
there will be a fair chance that they will be received, assembled,
and acknowledged.Diskless OperationContributed by &a.martin;.diskless workstationnetboot.com/netboot.rom
allow you to boot your FreeBSD machine over the network and run FreeBSD
without having a disk on your client. Under 2.0 it is now possible to
have local swap. Swapping over NFS is also still supported.Supported Ethernet cards include: Western Digital/SMC 8003, 8013,
8216 and compatibles; NE1000/NE2000 and compatibles (requires
recompile)Setup InstructionsFind a machine that will be your server. This machine will
require enough disk space to hold the FreeBSD 2.0 binaries and
have bootp, tftp and NFS services available. Tested
machines:HP-UXHP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't
work)SolarisSun/Solaris 2.3. (you may need to get bootp)Set up a bootp server to provide the client with IP address, gateway,
netmask.diskless:\
:ht=ether:\
:ha=0000c01f848a:\
:sm=255.255.255.0:\
:hn:\
:ds=192.1.2.3:\
:ip=192.1.2.4:\
:gw=192.1.2.5:\
:vm=rfc1048:TFTPbootpSet up a TFTP server (on same machine as bootp server) to
provide booting information to client. The name of this file is
cfg.X.X.X.X (or
/tftpboot/cfg.X.X.X.X,
it will try both) where X.X.X.X is the
IP address of the client. The contents of this file can be any
valid netboot commands. Under 2.0, netboot has the following
commands:helpprint help listip
print/set client's IP addressserver
print/set bootp/tftp server addressnetmask
print/set netmaskhostname nameprint/set hostnamekernel
print/set kernel namerootfs
print/set root filesystemswapfs
print/set swap filesystemswapsize
set diskless swapsize in KBytesdiskbootboot from diskautobootcontinue boot processtrans
|turn transceiver on|offflags
set boot flagsA typical completely diskless config file might contain:rootfs 192.1.2.3:/rootfs/myclient
swapfs 192.1.2.3:/swapfs
swapsize 20000
hostname myclient.mydomainA config file for a machine with local swap might contain:rootfs 192.1.2.3:/rootfs/myclient
hostname myclient.mydomainEnsure that your NFS server has exported the root (and swap if
applicable) filesystems to your client, and that the client has
root access to these filesystems A typical
/etc/exports file on FreeBSD might look
like:/rootfs/myclient -maproot=0:0 myclient.mydomain
/swapfs -maproot=0:0 myclient.mydomainAnd on HP-UX:/rootfs/myclient -root=myclient.mydomain
/swapfs -root=myclient.mydomainNFSswapping overIf you are swapping over NFS (completely diskless
configuration) create a swap file for your client using
dd. If your swapfs
command has the arguments /swapfs and
the size 20000 as in the example above, the swapfile for
myclient will be called
/swapfs/swap.X.X.X.X
where X.X.X.X is the client's IP
address, e.g.:&prompt.root; dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000Also, the client's swap space might contain sensitive
information once swapping starts, so make sure to restrict read
and write access to this file to prevent unauthorized
access:&prompt.root; chmod 0600 /swapfs/swap.192.1.2.4Unpack the root filesystem in the directory the client will
use for its root filesystem (/rootfs/myclient
in the example above).On HP-UX systems: The server should be running HP-UX 9.04
or later for HP9000/800 series machines. Prior versions do not
allow the creation of device files over NFS.When extracting /dev in
/rootfs/myclient, beware that some
systems (HPUX) will not create device files that FreeBSD is
happy with. You may have to go to single user mode on the
first bootup (press control-c during the bootup phase), cd
/dev and do a sh ./MAKEDEV
all from the client to fix this.Run netboot.com on the client or make an
EPROM from the netboot.rom fileUsing Shared / and /usr
filesystemsAlthough this is not an officially sanctioned or supported way
of doing this, some people report that it works quite well. If
anyone has any suggestions on how to do this cleanly, please tell
&a.doc;.Compiling netboot for specific setupsNetboot can be compiled to support NE1000/2000 cards by changing
the configuration in
/sys/i386/boot/netboot/Makefile. See the
comments at the top of this file.ISDNA good resource for information on ISDN technology and hardware is
Dan Kegel's ISDN
Page.A quick simple road map to ISDN follows:If you live in Europe you might want to investigate the ISDN card
section.If you are planning to use ISDN primarily to connect to the
Internet with an Internet Provider on a dial-up non-dedicated basis,
you might look into Terminal Adapters. This will give you the
most flexibility, with the fewest problems, if you change
providers.If you are connecting two LANs together, or connecting to the
Internet with a dedicated ISDN connection, you might consider
the stand alone router/bridge option.Cost is a significant factor in determining what solution you will
choose. The following options are listed from least expensive to most
expensive.ISDN CardsContributed by &a.hm;.ISDNcardsThis section is really only relevant to ISDN users in countries
where the DSS1/Q.931 ISDN standard is supported.Some growing number of PC ISDN cards are supported under FreeBSD
2.2.X and up by the isdn4bsd driver package. It is still under
development but the reports show that it is successfully used all over
Europe.isdn4bsdThe latest isdn4bsd version is available from ftp://isdn4bsd@ftp.consol.de/pub/,
the main isdn4bsd FTP site (you have to log in as user
isdn4bsd , give your mail address as the password
and change to the pub directory. Anonymous FTP
as user ftp or anonymous
will not give the desired result).Isdn4bsd allows you to connect to other ISDN routers using either
IP over raw HDLC or by using synchronous PPP. A telephone answering
machine application is also available.Many ISDN PC cards are supported, mostly the ones with a Siemens
ISDN chipset (ISAC/HSCX), support for other chipsets (from Motorola,
Cologne Chip Designs) is currently under development. For an
up-to-date list of supported cards, please have a look at the README
file.In case you are interested in adding support for a different ISDN
protocol, a currently unsupported ISDN PC card or otherwise enhancing
isdn4bsd, please get in touch with hm@kts.org.A majordomo maintained mailing list is available. To join the
list, send mail to &a.majordomo; and
specify:subscribe freebsd-isdnin the body of your message.ISDN Terminal AdaptersTerminal adapters(TA), are to ISDN what modems are to regular
phone lines.modemMost TA's use the standard hayes modem AT command set, and can be
used as a drop in replacement for a modem.A TA will operate basically the same as a modem except connection
and throughput speeds will be much faster than your old modem. You
will need to configure PPP exactly the same
as for a modem setup. Make sure you set your serial speed as high as
possible.PPPThe main advantage of using a TA to connect to an Internet
Provider is that you can do Dynamic PPP. As IP address space becomes
more and more scarce, most providers are not willing to provide you
with a static IP anymore. Most stand-alone routers are not able to
accommodate dynamic IP allocation.TA's completely rely on the PPP daemon that you are running for
their features and stability of connection. This allows you to
upgrade easily from using a modem to ISDN on a FreeBSD machine, if you
already have PPP setup. However, at the same time any problems you
experienced with the PPP program and are going to persist.If you want maximum stability, use the kernel PPP option, not the user-land iijPPP.The following TA's are know to work with FreeBSD.Motorola BitSurfer and Bitsurfer ProAdtranMost other TA's will probably work as well, TA vendors try to make
sure their product can accept most of the standard modem AT command
set.The real problem with external TA's is like modems you need a good
serial card in your computer.You should read the FreeBSD Serial
Hardware tutorial for a detailed understanding of
serial devices, and the differences between asynchronous and
synchronous serial ports.A TA running off a standard PC serial port (asynchronous) limits
you to 115.2Kbs, even though you have a 128Kbs connection. To fully
utilize the 128Kbs that ISDN is capable of, you must move the TA to a
synchronous serial card.Do not be fooled into buying an internal TA and thinking you have
avoided the synchronous/asynchronous issue. Internal TA's simply have
a standard PC serial port chip built into them. All this will do, is
save you having to buy another serial cable, and find another empty
electrical socket.A synchronous card with a TA is at least as fast as a stand-alone
router, and with a simple 386 FreeBSD box driving it, probably more
flexible.The choice of sync/TA v.s. stand-alone router is largely a
religious issue. There has been some discussion of this in
the mailing lists. I suggest you search the archives for
the complete discussion.Stand-alone ISDN Bridges/RoutersISDNstand-alone bridges/routersISDN bridges or routers are not at all specific to FreeBSD
or any other operating system. For a more complete
description of routing and bridging technology, please refer
to a Networking reference book.In the context of this page, the terms router and bridge will
be used interchangeably.As the cost of low end ISDN routers/bridges comes down, it
will likely become a more and more popular choice. An ISDN
router is a small box that plugs directly into your local
Ethernet network(or card), and manages its own connection to
the other bridge/router. It has all the software to do PPP
and other protocols built in.A router will allow you much faster throughput that a
standard TA, since it will be using a full synchronous ISDN
connection.The main problem with ISDN routers and bridges is that
interoperability between manufacturers can still be a problem.
If you are planning to connect to an Internet provider, you
should discuss your needs with them.If you are planning to connect two LAN segments together,
ie: home LAN to the office LAN, this is the simplest lowest
maintenance solution. Since you are buying the equipment for
both sides of the connection you can be assured that the link
will work.For example to connect a home computer or branch office
network to a head office network the following setup could be
used.Branch office or Home network10 base 2Network uses a bus based topology with 10 base 2
Ethernet ("thinnet"). Connect router to network cable with
AUI/10BT transceiver, if necessary.---Sun workstation
|
---FreeBSD box
|
---Windows 95 (Do not admit to owning it)
|
Stand-alone router
|
ISDN BRI line10 Base 2 EthernetIf your home/branch office is only one computer you can use a
twisted pair crossover cable to connect to the stand-alone router
directly.Head office or other LAN10 base TNetwork uses a star topology with 10 base T Ethernet
("Twisted Pair"). -------Novell Server
| H |
| ---Sun
| |
| U ---FreeBSD
| |
| ---Windows 95
| B |
|___---Stand-alone router
|
ISDN BRI lineISDN Network DiagramOne large advantage of most routers/bridges is that they allow you
to have 2 separate independent PPP connections to
2 separate sites at the same time. This is not
supported on most TA's, except for specific(expensive) models that
have two serial ports. Do not confuse this with channel bonding, MPP
etc.This can be very useful feature, for example if you have an
dedicated ISDN connection at your office and would like to
tap into it, but don't want to get another ISDN line at work. A router
at the office location can manage a dedicated B channel connection
(64Kbs) to the Internet, as well as a use the other B channel for a
separate data connection. The second B channel can be used for
dial-in, dial-out or dynamically bond(MPP etc.) with the first B channel
for more bandwidth.IPX/SPXAn Ethernet bridge will also allow you to transmit more than just
IP traffic, you can also send IPX/SPX or whatever other protocols you
use.NIS/YPWritten by &a.unfurl;, 21 January 2000, enhanced
with parts and comments from Eric Ogren
eogren@earthlink.net and Udo Erdelhoff
ue@nathan.ruhr.de in June 2000.What is it?NISSolarisHP-UXAIXLinuxNetBSDOpenBSDNIS, which stands for Network Information Services, was
developed by Sun Microsystems to centralize administration of Unix
(originally SunOS) systems. It has now essentially become an
industry standard; all major Unix systems (Solaris, HP-UX, AIX, Linux,
NetBSD, OpenBSD, FreeBSD, etc) support NIS.
- yellow pages (see NIS)
+ yellow pagesNISNIS was formerly known as Yellow Pages (or yp), but due to
copyright violations, Sun was forced to change the name.NISdomainsIt is a RPC-based client/server system that allows a group
of machines within an NIS domain to share a common set of
configuration files. This permits a system administrator to set
up NIS client systems with only minimal configuration data and
add, remove or modify configuration data from a single
location.Windows NTIt is similar to Windows NT's domain system; although the
internal implementation of the two aren't at all similar,
the basic functionality can be compared.Terms/processes you should knowThere are several terms and several important user processes
that you will come across when
attempting to implement NIS on FreeBSD, whether you are trying to
create an NIS server or act an NIS client:The NIS domainname. An NIS master
server and all of its clients (including its slave servers) have
a NIS domainname. Similar to an NT domain name, the NIS
domainname does not have anything to do with DNS.portmapportmap. portmap
must be running in order to enable RPC (Remote Procedure Call, a
network protocol used by NIS). If portmap is
not running, it will be impossible to run an NIS server, or to
act as an NIS client.ypbind. ypbind
“binds” an NIS client to its NIS server.
It will take the NIS domainname from the system, and
using RPC, connect to the server. ypbind is
the core of client-server communication in an NIS environment; if
ypbind dies on a client machine, it will not
be able to access the NIS server.ypserv. ypserv,
which should only be running on NIS servers, is the NIS server
process itself. If &man.ypserv.8; dies, then the server will no longer be
able to respond to NIS requests (hopefully, there is a slave
server to take over for it).There are some implementations of NIS (but not the
FreeBSD one), that don't try to reconnect to another server
if the server it used before dies. Often, the only thing
that helps in this case is to restart the server process (or
even the whole server) or the ypbind process
on the client.rpc.yppasswdd.
rpc.yppasswdd, another process that should
only be running on NIS master servers, is a daemon that will
allow NIS clients to change their NIS passwords.
If this daemon is not running, users will have to login to the
NIS master server and change their passwords there.How does it work?There are three types of hosts in an NIS environment; master
servers, slave servers, and clients. Servers act as a central
repository for host configuration information. Master servers
hold the authoritative copy of this information, while slave
servers mirror this information for redundancy. Clients rely on
the servers to provide this information to them.Information in many files can be shared in this manner. The
master.passwd, group,
and hosts files are commonly shared via NIS.
Whenever a process on a client needs information that would
normally be found in these files locally, it makes a query to the
server it is bound to, to get this information.Machine typesNISmaster serverA NIS master server.
This server, analogous to a Windows
NT primary domain controller, maintains the files used by all
of the NIS clients. The passwd,
group, and other various files used by the
NIS clients live on the master server.It is possible for one machine to be an NIS
master server for more than one NIS domain. However, this will
not be covered in this introduction, which assumes a relatively
small-scale NIS environment.NISslave serverNIS slave servers.
Similar to NT's backup domain
controllers, NIS slave servers maintain copies of the NIS
master's data files. NIS slave servers provide the redundancy,
which is needed in important environments. They also help
to balance the load of the master server: NIS Clients always
attach to the NIS server whose response they get first, and
this includes slave-server-replies.NISclientNIS clients. NIS clients, like most
NT workstations, authenticate against the NIS server (or the NT
domain controller in the NT Workstation case) to log on.Using NIS/YPThis section will deal with setting up a sample NIS
environment.This section assumes that you are running FreeBSD 3.3
or later. The instructions given here will
probably work for any version of FreeBSD greater
than 3.0, but there are no guarantees that this is
true.PlanningLet's assume that you are the administrator of a small
university lab. This lab, which consists of 15 FreeBSD machines,
currently has no centralized point of administration; each machine
has its own /etc/passwd and
/etc/master.passwd. These files are kept in
sync with each other only through manual intervention;
currently, when you add a user to the lab, you must run
adduser on all 15 machines.
Clearly, this has to change, so you have decided to convert the
lab to use NIS, using two of the machines as servers.Therefore, the configuration of the lab now looks something
like:Machine nameIP addressMachine roleellington10.0.0.2NIS mastercoltrane10.0.0.3NIS slavebasie10.0.0.4Faculty workstationbird10.0.0.5Client machinecli[1-11]10.0.0.[6-17]Other client machinesIf you are setting up a NIS scheme for the first time, it
is a good idea to think through how you want to go about it. No
matter what the size of your network, there are a few decisions
that need to be made.Choosing a NIS Domain NameNISdomainnameThis might not be the domainname that you
are used to. It is more accurately called the
NIS domainname. When a client broadcasts its
requests for info, it includes the name of the NIS domain
that it is part of. This is how multiple servers on one
network can tell which server should answer which request.
Think of the NIS domainname as the name for a group of hosts
that are related in some way.Some organizations choose to use their Internet domainname
for their NIS domainname. This is not recommended as it can
cause confusion when trying to debug network problems. The
NIS domainname should be unique within your network and it is
helpful if it describes the group of machines it represents.
For example, the Art department at Acme Inc. might be in the
"acme-art" NIS domain. For this example, assume you have
chosen the name test-domain.SunOSHowever, some operating systems (notably SunOS) use their
NIS domain name as their Internet domain name.
If one or more machines on your network have this restriction,
you must use the Internet domain name as
your NIS domain name.Physical Server RequirementsThere are several things to keep in mind when choosing a
machine to use as a NIS server. One of the unfortunate things
about NIS is the level of dependency the clients have on the
server. If a client cannot contact the server for its NIS
domain, very often the machine becomes unusable. The lack of
user and group information causes most systems to temporarily
freeze up. With this in mind you should make sure to choose a
machine that won't be prone to being rebooted regularly, or
one that might be used for development. The NIS server should
ideally be a stand alone machine whose sole purpose in life is
to be an NIS server. If you have a network that is not very
heavily used, it is acceptable to put the NIS server on a
machine running other services, just keep in mind that if the
NIS server becomes unavailable, it will affect
all of your NIS clients adversely.NIS Servers The canonical copies of all NIS information are stored on
a single machine called the NIS master server. The databases
used to store the information are called NIS maps. In FreeBSD,
these maps are stored in
/var/yp/[domainname] where
[domainname] is the name of the NIS domain
being served. A single NIS server can support several domains
at once, therefore it is possible to have several such
directories, one for each supported domain. Each domain will
have its own independent set of maps.NIS master and slave servers handle all NIS requests with
the ypserv daemon. Ypserv
is responsible for receiving incoming requests from NIS clients,
translating the requested domain and map name to a path to the
corresponding database file and transmitting data from the
database back to the client.Setting up a NIS master serverNISserver configurationSetting up a master NIS server can be relatively straight
forward, depending on your needs. FreeBSD comes with support
for NIS out-of-the-box. All you need is to add the following
lines to /etc/rc.conf, and FreeBSD will
do the rest for you.nisdomainname="test-domain"
This line will set the NIS domainname to
test-domain
upon network setup (e.g. after reboot).nis_server_enable="YES"
This will tell FreeBSD to start up the NIS server processes
when the networking is next brought up.nis_yppasswdd_enable="YES"
This will enable the rpc.yppasswdd
daemon, which, as mentioned above, will allow users to
change their NIS password from a client machine.Now, all you have to do is to run the command
/etc/netstart as superuser. It will
setup everything for you, using the values you defined in
/etc/rc.conf.Initializing the NIS mapsNIS mapsThe NIS maps are database files,
that are kept in the /var/yp directory.
They are generated from configuration files in the
/etc directory of the NIS master, with one
exception: the /etc/master.passwd file.
This is for a good reason; you don't want to propagate
passwords to your root and other administrative accounts to
all the servers in the NIS domain. Therefore, before we
initialize the NIS maps, you should:&prompt.root; cp /etc/master.passwd /var/yp/master.passwd
&prompt.root; cd /var/yp
&prompt.root; vi master.passwdYou should remove all entries regarding system accounts
(bin, tty, kmem, games, etc), as well as any accounts that you
don't want to be propagated to the NIS clients (for example
root and any other UID 0 (superuser) accounts).Make sure the
/var/yp/master.passwd is neither group
nor world readable (mode 600)! Use the
chmod command, if appropriate.Tru64 UnixWhen you have finished, it's time to initialize the NIS
maps! FreeBSD includes a script named
ypinit to do this for you
(see its man page for more information). Note that this
script is available on most Unix OSs, but not on all.
On Digital Unix/Compaq Tru64 Unix it is called
ypsetup.
Because we are generating maps for an NIS master, we are
going to pass the option to
ypinit.
To generate the NIS maps, assuming you already performed
the steps above, run:ellington&prompt.root; ypinit -m test-domain
Server Type: MASTER Domain: test-domain
Creating an YP server will require that you answer a few questions.
Questions will all be asked at the beginning of the procedure.
Do you want this procedure to quit on non-fatal errors? [y/n: n] n
Ok, please remember to go back and redo manually whatever fails.
If you don't, something might not work.
At this point, we have to construct a list of this domains YP servers.
rod.darktech.org is already known as master server.
Please continue to add any slave servers, one per line. When you are
done with the list, type a <control D>.
master server : ellington
next host to add: coltrane
next host to add: ^D
The current list of NIS servers looks like this:
ellington
coltrane
Is this correct? [y/n: y] y
[..output from map generation..]
NIS Map update completed.
ellington has been setup as an YP master server without any errors.ypinit should have created
/var/yp/Makefile from
/var/yp/Makefile.dist.
When created, this file assumes that you are operating
in a single server NIS environment with only FreeBSD
machines. Since test-domain has
a slave server as well, you must edit
/var/yp/Makefile:ellington&prompt.root; vi /var/yp/MakefileYou should comment out the line that says `NOPUSH =
"True"' (if it is not commented out already).Setting up a NIS slave serverNISconfiguring a slave serverSetting up an NIS slave server is even more simple than
setting up the master. Log on to the slave server and edit the
file /etc/rc.conf as you did before.
The only difference is that we now must use the
option when running ypinit.
The option requires the name of the NIS
master be passed to it as well, so our command line looks
like:coltrane&prompt.root; ypinit -s ellington test-domain
Server Type: SLAVE Domain: test-domain Master: ellington
Creating an YP server will require that you answer a few questions.
Questions will all be asked at the beginning of the procedure.
Do you want this procedure to quit on non-fatal errors? [y/n: n] n
Ok, please remember to go back and redo manually whatever fails.
If you don't, something might not work.
There will be no further questions. The remainder of the procedure
should take a few minutes, to copy the databases from ellington.
Transferring netgroup...
ypxfr: Exiting: Map successfully transferred
Transferring netgroup.byuser...
ypxfr: Exiting: Map successfully transferred
Transferring netgroup.byhost...
ypxfr: Exiting: Map successfully transferred
Transferring master.passwd.byuid...
ypxfr: Exiting: Map successfully transferred
Transferring passwd.byuid...
ypxfr: Exiting: Map successfully transferred
Transferring passwd.byname...
ypxfr: Exiting: Map successfully transferred
Transferring group.bygid...
ypxfr: Exiting: Map successfully transferred
Transferring group.byname...
ypxfr: Exiting: Map successfully transferred
Transferring services.byname...
ypxfr: Exiting: Map successfully transferred
Transferring rpc.bynumber...
ypxfr: Exiting: Map successfully transferred
Transferring rpc.byname...
ypxfr: Exiting: Map successfully transferred
Transferring protocols.byname...
ypxfr: Exiting: Map successfully transferred
Transferring master.passwd.byname...
ypxfr: Exiting: Map successfully transferred
Transferring networks.byname...
ypxfr: Exiting: Map successfully transferred
Transferring networks.byaddr...
ypxfr: Exiting: Map successfully transferred
Transferring netid.byname...
ypxfr: Exiting: Map successfully transferred
Transferring hosts.byaddr...
ypxfr: Exiting: Map successfully transferred
Transferring protocols.bynumber...
ypxfr: Exiting: Map successfully transferred
Transferring ypservers...
ypxfr: Exiting: Map successfully transferred
Transferring hosts.byname...
ypxfr: Exiting: Map successfully transferred
coltrane has been setup as an YP slave server without any errors.
Don't forget to update map ypservers on ellington.You should now have a directory called
/var/yp/test-domain. Copies of the NIS
master server's maps should be in this directory. You will
need to make sure that these stay updated. The following
/etc/crontab entries on your slave
servers should do the job:20 * * * * root /usr/libexec/ypxfr passwd.byname
21 * * * * root /usr/libexec/ypxfr passwd.byuidThese two lines force the slave to sync its maps with
the maps on the master server. Although this is
not mandatory, because the master server
tries to make sure any changes to its NIS maps are
communicated to its slaves, the password
information is so vital to systems that depend on the server,
that it is a good idea to force the updates. This is more
important on busy networks where map updates might not always
complete.Now, run the command /etc/netstart on the
slave server as well, which again starts the NIS server.NIS Clients An NIS client establishes what is called a binding to a
particular NIS server using the
ypbind daemon.
ypbind checks the system's default
domain (as set by the domainname command),
and begins broadcasting RPC requests on the local network.
These requests specify the name of the domain for which
ypbind is attempting to establish a binding.
If a server that has been configured to serve the requested
domain receives one of the broadcasts, it will respond to
ypbind, which will record the server's
address. If there are several servers available (a master and
several slaves, for example), ypbind will
use the address of the first one to respond. From that point
on, the client system will direct all of its NIS requests to
that server. Ypbind will
occasionally ping the server to make sure it is
still up and running. If it fails to receive a reply to one of
its pings within a reasonable amount of time,
ypbind will mark the domain as unbound and
begin broadcasting again in the hopes of locating another
server.Setting up an NIS clientNISclient configurationSetting up a FreeBSD machine to be a NIS client is fairly
straightforward.Edit the file /etc/rc.conf and
add the following lines in order to set the NIS domainname
and start ypbind upon network
startup:nisdomainname="test-domain"
nis_client_enable="YES"To import all possible password entries from the NIS
server, add this line to your
/etc/master.passwd file, using
vipw:+:::::::::This line will afford anyone with a valid account in
the NIS server's password maps an account. There are
many ways to configure your NIS client by changing this
line. See the netgroups
part below for more information.
For more detailed reading see O'Reilly's book on
Managing NFS and NIS.To import all possible group entries from the NIS
server, add this line to your
/etc/group file:+:*::After completing these steps, you should be able to run
ypcat passwd and see the NIS server's
passwd map.NIS SecurityIn general, any remote user can issue an RPC to &man.ypserv.8; and
retrieve the contents of your NIS maps, provided the remote user
knows your domainname. To prevent such unauthorized transactions,
&man.ypserv.8; supports a feature called securenets which can be used to
restrict access to a given set of hosts. At startup, &man.ypserv.8; will
attempt to load the securenets information from a file called
/var/yp/securenets.This path varies depending on the path specified with the
option. This file contains entries that
consist of a network specification and a network mask separated
by white space. Lines starting with # are
considered to be comments. A sample securenets file might look
like this:# allow connections from local host -- mandatory
127.0.0.1 255.255.255.255
# allow connections from any host
# on the 192.168.128.0 network
192.168.128.0 255.255.255.0
# allow connections from any host
# between 10.0.0.0 to 10.0.15.255
# this includes the machines in the testlab
10.0.0.0 255.255.240.0If &man.ypserv.8; receives a request from an address that matches one
of these rules, it will process the request normally. If the
address fails to match a rule, the request will be ignored and a
warning message will be logged. If the
/var/yp/securenets file does not exist,
ypserv will allow connections from any host.The ypserv program also has support for Wietse Venema's
tcpwrapper package. This allows the
administrator to use the tcpwrapper configuration
files for access control instead of
/var/yp/securenets.While both of these access control mechanisms provide some
security, they, like the privileged port test, are
vulnerable to IP spoofing attacks. All
NIS-related traffic should be blocked at your firewall.Servers using /var/yp/securenets
may fail to serve legitimate NIS clients with archaic TCP/IP
implementations. Some of these implementations set all
host bits to zero when doing broadcasts and/or fail to
observe the subnet mask when calculating the broadcast
address. While some of these problems can be fixed by
changing the client configuration, other problems may force
the retirement of the client systems in question or the
abandonment of /var/yp/securenets.Using /var/yp/securenets on a
server with such an archaic implementation of TCP/IP is a
really bad idea and will lead to loss of NIS functionality
for large parts of your network.tcpwrapperThe use of the tcpwrapper
package increases the latency of your NIS server. The
additional delay may be long enough to cause timeouts in
client programs, especially in busy networks or with slow
NIS servers. If one or more of your client systems
suffers from these symptoms, you should convert the client
systems in question into NIS slave servers and force them
to bind to themselves.Barring some users from logging onIn our lab, there is a machine basie that is
supposed to be a faculty only workstation. We don't want to take this
machine out of the NIS domain, yet the passwd
file on the master NIS server contains accounts for both faculty and
students. What can we do?There is a way to bar specific users from logging on to a
machine, even if they are present in the NIS database. To do this,
all you must do is add
-username to the end of
the /etc/master.passwd file on the client
machine, where username is the username of
the user you wish to bar from logging in. This should preferably be
done using vipw, since vipw
will sanity check your changes to
/etc/master.passwd, as well as
automatically rebuild the password database when you
finish editing. For example, if we wanted to bar user
bill from logging on to basie
we would:basie&prompt.root; vipw[add -bill to the end, exit]
vipw: rebuilding the database...
vipw: done
basie&prompt.root; cat /etc/master.passwd
root:[password]:0:0::0:0:The super-user:/root:/bin/csh
toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
operator:*:2:5::0:0:System &:/:/sbin/nologin
bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
+:::::::::
-bill
basie&prompt.root;Using netgroupsnetgroupsThe netgroups part was contributed by
Udo Erdelhoff ue@nathan.ruhr.de in July
2000.The method shown in the previous chapter works reasonably
well if you need special rules for a very small number of
users and/or machines. On larger networks, you
will forget to bar some users from logging
onto sensitive machines, or you may even have to modify each
machine separately, thus losing the main benefit of NIS,
centralized administration.The NIS developers' solution for this problem is called
netgroups. Their purpose and semantics
can be compared to the normal groups used by Unix file
systems. The main differences are the lack of a numeric id
and the ability to define a netgroup by including both user
accounts and other netgroups.Netgroups were developed to handle large, complex networks
with hundreds of users and machines. On one hand, this is
a Good Thing if you are forced to deal with such a situation.
On the other hand, this complexity makes it almost impossible to
explain netgroups with really simple examples. The example
used in the remainder of this chapter demonstrates this
problem.Let us assume that your successful introduction of NIS in
your laboratory caught your superiors' interest. Your next
job is to extend your NIS domain to cover some of the other
machines on campus. The two tables contain the names of the
new users and new machines as well as brief descriptions of
them.User Name(s)Descriptionalpha, betaNormal employees of the IT departmentcharlie, deltaThe new apprentices of the IT departmentecho, foxtrott, golf, ...Ordinary employeesable, baker, ...The current internsMachine Name(s)Descriptionwar, death, famine, pollutionYour most important servers. Only the IT
employees are allowed to log onto these
machines.pride, greed, envy, wrath, lust, slothLess important servers. All members of the IT
department are allowed to login onto these machines.one, two, three, four, ...Ordinary workstations. Only the
real employees are allowed to use
these machines.trashcanA very old machine without any critical data.
Even the intern is allowed to use this box.If you tried to implement these restrictions by separately
blocking each user, you would have to add one
-user line to each system's
passwd
for each user who is not allowed to login onto that system.
If you forget just one entry, you could be in trouble. It may
be feasible to do this correctly during the initial setup,
however you will eventually forget to add
the lines for new users during day-to-day operations. After
all, Murphy was an optimist.Handling this situation with netgroups offers several
advantages. Each user need not be handled separately;
you assign a user to one or more netgroups and allow or forbid
logins for all members of the netgroup. If you add a new
machine, you will only have to define login restrictions for
netgroups. If a new user is added, you will only have to add
the user to one or more netgroups. Those changes are
independent of each other; no more for each combination
of user and machine do... If your NIS setup is planned
carefully, you will only have to modify exactly one central
configuration file to grant or deny access to machines.The first step is the initialization of the NIS map
netgroup. FreeBSD's &man.ypinit.8; does not create this map by
default, but its NIS implementation will support it once it has
been created. To create an empty map, simply typeellington&prompt.root; vi /var/yp/netgroupand start adding content. For our example, we need at
least four netgroups: IT employees, IT apprentices, normal
employees and interns.IT_EMP (,alpha,test-domain) (,beta,test-domain)
IT_APP (,charlie,test-domain) (,delta,test-domain)
USERS (,echo,test-domain) (,foxtrott,test-domain) \
(,golf,test-domain)
INTERNS (,able,test-domain) (,baker,test-domain)IT_EMP, IT_APP etc.
are the names of the netgroups. Each bracketed group adds
one or more user accounts to it. The three fields inside a
group are:The name of the host(s) where the following items are
valid. If you do not specify a hostname, the entry is
valid on all hosts. If you do specify a hostname, you
will enter a realm of darkness, horror and utter confusion.The name of the account that belongs to this
netgroup.The NIS domain for the account. You can import
accounts from other NIS domains into your netgroup if you
are one of unlucky fellows with more than one NIS
domain.Each of these fields can contain wildcards. See
&man.netgroup.5; for details.netgroupsNetgroup names longer than 8 characters should not be
used, especially if you have machines running other
operating systems within your NIS domain. The names are
case sensitive; using capital letters for your netgroup
names is an easy way to distinguish between user, machine
and netgroup names.Some NIS clients (other than FreeBSD) cannot handle
netgroups with a large number of entries. For example, some
older versions of SunOS start to cause trouble if a netgroup
contains more than 15 entries. You can
circumvent this limit by creating several sub-netgroups with
15 users or less and a real netgroup that consists of the
sub-netgroups:BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...]
BIGGRP2 (,joe16,domain) (,joe17,domain) [...]
BIGGRP3 (,joe31,domain) (,joe32,domain)
BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3You can repeat this process if you need more than 225
users within a single netgroup.Activating and distributing your new NIS map is
easy:ellington&prompt.root; cd /var/yp
ellington&prompt.root; makeThis will generate the three NIS maps
netgroup,
netgroup.byhost and
netgroup.byuser. Use &man.ypcat.1; to
check if your new NIS maps are available:ellington&prompt.user; ypcat -k netgroup
ellington&prompt.user; ypcat -k netgroup.byhost
ellington&prompt.user; ypcat -k netgroup.byuserThe output of the first command should resemble the
contents of /var/yp/netgroup. The second
command will not produce output if you have not specified
host-specific netgroups. The third command can be used to
get the list of netgroups for a user.The client setup is quite simple. To configure the server
war, you only have to start
&man.vipw.8; and replace the line+:::::::::with+@IT_EMP:::::::::Now, only the data for the users defined in the netgroup
IT_EMP is imported into
war's password database and only
these users are allowed to login.Unfortunately, this limitation also applies to the ~
function of the shell and all routines converting between user
names and numerical user ids. In other words,
cd ~user will not work,
ls -l will show the numerical id instead of
the username and find . -user joe -print will
fail with No such user. To fix this, you will
have to import all user entries without allowing them
to login onto your servers.This can be achieved by adding another line to
/etc/master.passwd. This line should
contain +:::::::::/sbin/nologin, meaning
Import all entries but replace the shell with
/sbin/nologin in the imported
entries. You can replace any field
in the passwd entry by placing a default value in your
/etc/master.passwd.Make sure that the line
+:::::::::/sbin/nologin is placed after
+@IT_EMP:::::::::. Otherwise, all user
accounts imported from NIS will have /sbin/nologin as their
login shell.After this change, you will only have to change one NIS
map if a new employee joins the IT department. You could use
a similar approach for the less important servers by replacing
the old +::::::::: in their local version
of /etc/master.passwd with something like
this:+@IT_EMP:::::::::
+@IT_APP:::::::::
+:::::::::/sbin/nologinThe corresponding lines for the normal workstations
could be:+@IT_EMP:::::::::
+@USERS:::::::::
+:::::::::/sbin/nologinAnd everything would be fine until there is a policy
change a few weeks later: The IT department starts hiring
interns. The IT interns are allowed to use the normal
workstations and the less important servers; and the IT
apprentices are allowed to login onto the main servers. You
add a new netgroup IT_INTERN, add the new IT interns to this
netgroup and start to change the config on each and every
machine... As the old saying goes: Errors in
centralized planning lead to global mess.NIS' ability to create netgroups from other netgroups can
be used to prevent situations like these. One possibility
is the creation of role-based netgroups. For example, you
could create a netgroup called
BIGSRV to define the login
restrictions for the important servers, another netgroup
called SMALLSRV for the less
important servers and a third netgroup called
USERBOX for the normal
workstations. Each of these netgroups contains the netgroups
that are allowed to login onto these machines. The new
entries for your NIS map netgroup should look like this:BIGSRV IT_EMP IT_APP
SMALLSRV IT_EMP IT_APP ITINTERN
USERBOX IT_EMP ITINTERN USERSThis method of defining login restrictions works
reasonably well if you can define groups of machines with
identical restrictions. Unfortunately, this is the exception
and not the rule. Most of the time, you will need the ability
to define login restrictions on a per-machine basis.Machine-specific netgroup definitions are the other
possibility to deal with the policy change outlined above. In
this scenario, the /etc/master.passwd of
each box contains two lines starting with ``+''. The first of
them adds a netgroup with the accounts allowed to login onto
this machine, the second one adds all other accounts with
/sbin/nologin as shell. It is a good
idea to use the ALL-CAPS version of the machine name as the
name of the netgroup. In other words, the lines should look
like this:+@BOXNAME:::::::::
+:::::::::/sbin/nologinOnce you have completed this task for all your machines,
you will not have to modify the local versions of
/etc/master.passwd ever again. All
further changes can be handled by modifying the NIS map. Here
is an example of a possible netgroup map for this
scenario with some additional goodies.# Define groups of users first
IT_EMP (,alpha,test-domain) (,beta,test-domain)
IT_APP (,charlie,test-domain) (,delta,test-domain)
DEPT1 (,echo,test-domain) (,foxtrott,test-domain)
DEPT2 (,golf,test-domain) (,hotel,test-domain)
DEPT3 (,india,test-domain) (,juliet,test-domain)
ITINTERN (,kilo,test-domain) (,lima,test-domain)
D_INTERNS (,able,test-domain) (,baker,test-domain)
#
# Now, define some groups based on roles
USERS DEPT1 DEPT2 DEPT3
BIGSRV IT_EMP IT_APP
SMALLSRV IT_EMP IT_APP ITINTERN
USERBOX IT_EMP ITINTERN USERS
#
# And a groups for a special tasks
# Allow echo and golf to access our anti-virus-machine
SECURITY IT_EMP (,echo,test-domain) (,golf,test-domain)
#
# machine-based netgroups
# Our main servers
WAR BIGSRV
FAMINE BIGSRV
# User india needs access to this server
POLLUTION BIGSRV (,india,test-domain)
#
# This one is really important and needs more access restrictions
DEATH IT_EMP
#
# The anti-virus-machine mentioned above
ONE SECURITY
#
# Restrict a machine to a single user
TWO (,hotel,test-domain)
# [...more groups to follow]If you are using some kind of database to manage your user
accounts, you should be able to create the first part of the
map with your database's report tools. This way, new users
will automatically have access to the boxes.One last word of caution: It may not always be advisable
to use machine-based netgroups. If you are deploying a couple
dozen or even hundreds of identical machines for student labs,
you should use role-based netgroups instead of machine-based
netgroups to keep the size of the NIS map within reasonable
limits.Important things to rememberThere are still a couple of things that you will need to do
differently now that you are in an NIS environment.Every time you wish to add a user to the lab, you
must add it to the master NIS server only,
and you must remember to rebuild the NIS
maps. If you forget to do this, the new user will
not be able to login anywhere except on the NIS master.
For example, if we needed to add a new user
“jsmith” to the lab, we would:&prompt.root; pw useradd jsmith
&prompt.root; cd /var/yp
&prompt.root; make test-domainYou could also run adduser jsmith instead
of pw useradd jsmith.Keep the administration accounts out of the NIS
maps. You don't want to be propagating administrative
accounts and passwords to machines that will have users that
shouldn't have access to those accounts.Keep the NIS master and slave
secure, and minimize their downtime.
If somebody either hacks or simply turns off
these machines, they have effectively rendered many people without
the ability to login to the lab.This is the chief weakness of any centralized administration
system, and it is probably the most important weakness. If you do
not protect your NIS servers, you will have a lot of angry
users!NIS v1 compatibility FreeBSD's ypserv has some support
for serving NIS v1 clients. FreeBSD's NIS implementation only
uses the NIS v2 protocol, however other implementations include
support for the v1 protocol for backwards compatibility with older
systems. The ypbind daemons supplied
with these systems will try to establish a binding to an NIS v1
server even though they may never actually need it (and they may
persist in broadcasting in search of one even after they receive a
response from a v2 server). Note that while support for normal
client calls is provided, this version of ypserv does not handle
v1 map transfer requests; consequently, it cannot be used as a
master or slave in conjunction with older NIS servers that only
support the v1 protocol. Fortunately, there probably are not any
such servers still in use today.NIS servers that are also NIS clients Care must be taken when running ypserv in a multi-server
domain where the server machines are also NIS clients. It is
generally a good idea to force the servers to bind to themselves
rather than allowing them to broadcast bind requests and possibly
become bound to each other. Strange failure modes can result if
one server goes down and others are dependent upon on it.
Eventually all the clients will time out and attempt to bind to
other servers, but the delay involved can be considerable and the
failure mode is still present since the servers might bind to each
other all over again.You can force a host to bind to a particular server by running
ypbind with the
flag.libscrypt v.s. libdescryptNIScrypto libraryOne of the most common issues that people run into when trying
to implement NIS is crypt library compatibility. If your NIS
server is using the DES crypt libraries, it will only support
clients that are using DES as well. To check which one your server
and clients are using look at the symlinks in
/usr/lib. If the machine is configured to
use the DES libraries, it will look something like this:&prompt.user; ls -l /usr/lib/*crypt*
lrwxrwxrwx 1 root wheel 13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libdescrypt.a
lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libdescrypt.so
lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libdescrypt.so.2
lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libdescrypt_p.a
-r--r--r-- 1 root wheel 13018 Nov 8 14:27 /usr/lib/libdescrypt.a
lrwxr-xr-x 1 root wheel 16 Nov 8 14:27 /usr/lib/libdescrypt.so@ -> libdescrypt.so.2
-r--r--r-- 1 root wheel 12965 Nov 8 14:27 /usr/lib/libdescrypt.so.2
-r--r--r-- 1 root wheel 14750 Nov 8 14:27 /usr/lib/libdescrypt_p.aIf the machine is configured to use the standard FreeBSD MD5
crypt libraries they will look something like this:&prompt.user; ls -l /usr/lib/*crypt*
lrwxrwxrwx 1 root wheel 13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libscrypt.a
lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libscrypt.so
lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libscrypt.so.2
lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libscrypt_p.a
-r--r--r-- 1 root wheel 6194 Nov 8 14:27 /usr/lib/libscrypt.a
lrwxr-xr-x 1 root wheel 14 Nov 8 14:27 /usr/lib/libscrypt.so@ -> libscrypt.so.2
-r--r--r-- 1 root wheel 7579 Nov 8 14:27 /usr/lib/libscrypt.so.2
-r--r--r-- 1 root wheel 6684 Nov 8 14:27 /usr/lib/libscrypt_p.aIf you have trouble authenticating on an NIS client, this
is a pretty good place to start looking for possible problems.
If you want to deploy an NIS server for a heterogenous
network, you will probably have to use DES on all systems
because it is the lowest common standard.DHCPWritten by &a.gsutter;, March 2000.What is DHCP?Dynamic Host Configuration Protocol (DHCP)Internet Software Consortium (ISC)DHCP, the Dynamic Host Configuration Protocol, describes
the means by which a system can connect to a network and obtain the
necessary information for communication upon that network. FreeBSD
uses the ISC (Internet Software Consortium) DHCP implementation, so
all implementation-specific information here is for use with the ISC
distribution.What This Section CoversThis handbook section attempts to describe only the parts
of the DHCP system that are integrated with FreeBSD;
consequently, the server portions are not described. The DHCP
manual pages, in addition to the references below, are useful
resources.How it WorksUDPWhen dhclient, the DHCP client, is executed on the client
machine, it begins broadcasting requests for configuration
information. By default, these requests are on UDP port 68. The
server replies on UDP 67, giving the client an IP address and
other relevant network information such as netmask, router, and
DNS servers. All of this information comes in the form of a DHCP
"lease" and is only valid for a certain time (configured by the
DHCP server maintainer). In this manner, stale IP addresses for
clients no longer connected to the network can be automatically
reclaimed.DHCP clients can obtain a great deal of information from
the server. An exhaustive list may be found in
&man.dhcp-options.5;.FreeBSD IntegrationFreeBSD fully integrates the ISC DHCP client,
dhclient. DHCP client support is provided
within both the installer and the base system, obviating the need
for detailed knowledge of network configurations on any network
that runs a DHCP server. dhclient has been
included in all FreeBSD distributions since 3.2.sysinstallDHCP is supported by sysinstall.
When configuring a network interface within sysinstall,
the first question asked is, "Do you want to try dhcp
configuration of this interface?" Answering affirmatively will
execute dhclient, and if successful, will fill in the network
configuration information automatically.There are two things you must do to have your system use
DHCP upon startup:DHCPrequirementsMake sure that the bpf
device is compiled into your kernel. To do this, add
pseudo-device bpf to your kernel
configuration file, and rebuild the kernel. For more
information about building kernels, see .The bpf device is already
part of the GENERIC kernel that is
supplied with FreeBSD, so if you don't have a custom
kernel, you shouldn't need to create one in order to get
DHCP working.For those who are particularly security conscious,
you should be warned that bpf
is also the device that allows packet sniffers to work
correctly (although they still have to be run as
root). bpfis required to use DHCP, but if
you are very sensitive about security, you probably
shouldn't add bpf to your
kernel in the expectation that at some point in the
future you will be using DHCP.Edit your /etc/rc.conf to
include the following:ifconfig_fxp0="DHCP"Be sure to replace fxp0 with the
designation for the interface that you wish to dynamically
configure.If you are using a different location for
dhclient, or if you wish to pass additional
flags to dhclient, also include the
following (editing as necessary):dhcp_program="/sbin/dhclient"
dhcp_flags=""DHCPserverThe DHCP server, dhcpd, is included
as part of the isc-dhcp2 port in the ports
collection. This port contains the full ISC DHCP distribution,
consisting of client, server, relay agent and documentation.
FilesDHCPconfiguration files/etc/dhclient.confdhclient requires a configuration file,
/etc/dhclient.conf. Typically the file
contains only comments, the defaults being reasonably sane. This
configuration file is described by the &man.dhclient.conf.5;
man page./sbin/dhclientdhclient is statically linked and
resides in /sbin. The &man.dhclient.8;
manual page gives more information about
dhclient./sbin/dhclient-scriptdhclient-script is the FreeBSD-specific
DHCP client configuration script. It is described in
&man.dhclient-script.8;, but should not need any user
modification to function properly./var/db/dhclient.leasesThe DHCP client keeps a database of valid leases in this
file, which is written as a log. &man.dhclient.leases.5;
gives a slightly longer description.Further ReadingThe DHCP protocol is fully described in
RFC 2131.
An informational resource has also been set up at
dhcp.org.DNSContributed by &a.chern;, April 12, 2001.
OverviewBINDFreeBSD utilizes, by default, a version of BIND (Berkeley
Internet Name Domain), which is the most common implementation of the
DNS protocol. DNS is the protocol through which names are mapped to
IP addresses, and vice versa. For example, a query for www.freebsd.org
will send back a reply for the IP address of The FreeBSD Project's
webpage, whereas, a query for ftp.freebsd.org will return the IP
address of the corresponding FTP machine. Likewise, the opposite can
happen. A query for an IP address can resolve its hostname.
DNSDNS is coordinated across the Internet through a somewhat
complex system of authoritative root name servers, and other
smaller-scale nameservers who host and relay individual domain
information.
This document refers to BIND 8.x, as it is the most current,
stable version used in FreeBSD.
RFC1034 and RFC1035 dictates the DNS protocol.
Currently, BIND is maintained by the
Internet Software Consortium (www.isc.org)Terminologyzoneszone - Each individual domain, subdomain,
or 'area' dictated by DNS is considered a zone.
Examples of zones:
. is the root zoneorg. is a zone under the root zonefoobardomain.org is a zone under the org. zonefoo.foobardomain.org. is a subdomain, a zone under the
foobardomain.org. zone
1.2.3.in-addr.arpa is a zone referencing all IP addresses
which fall under the 3.2.1.* IP space.
named, bind, name server - these are all
common names for the BIND name server package within FreeBSD.
resolverresolver - a network process by which a
system queries a nameserver for answers
root zoneroot zone - literally, a '.', refers to
the root, or beginning zone. All zones fall under this, as do all
files in fall under the root directory. It is the beginning of the
Internet zone hierarchy
origin - refers to the point of start for
the particular zone
forward dns - mapping of hostnames to IP
addresses
reverse DNSreverse dns - the opposite, mapping of IP
addresses to hostnames
Reasons to run a name server
You need your machine to host DNS information to the world
An authoritative nameserver replies exclusively
to requests.
For example, you register foobardomain.org
and wish to assign hostnames to the proper IP addresses.
A slave nameserver, which replies to queries for a
domain when the primary is down or inaccessible.
The above two can also be done with in-addr.arpa, IP
to hostname entries
You wish your machine to act as a local relay of DNS
information
DNS traffic has been measured to be about 5% or more
of the total Internet traffic.
A local DNS server may have some added benefit by
providing a local cache of DNS information.
For example, when one queries for www.freebsd.org,
their resolver goes out to (usually) your ISP's name
server, and retrieves the query.
With a local, caching DNS server, the query only has to
be made once to the outside world. Every additional
query will not have to go outside of the local network,
since the information is cached.
How it works
A DNS server in FreeBSD relies on the BIND daemon. This daemon is
called 'named' for obvious reasons.
named - the bind daemonndc - name daemon control program/etc/namedb - directory where all the bind
information resides
/etc/namedb/named.conf - daemon configuration
file
zone files are usually contained within the
/etc/namedb
directory, and contain the information (query answers from
your site) served by your name server.
Starting BINDBINDstarting
Since bind is installed by default, configuring it all is
relatively simple.
To ensure the named daemon is started at boot, put the following
modifications in your /etc/rc.confnamed_enable="YES"To start the daemon manually (after configuring it)&prompt.root; ndc startConfiguration filesBINDconfiguration filesmake-localhostBe sure to
&prompt.root; cd /etc/namedb
&prompt.root; sh make-localhostto properly create your local reverse dns zone file in
/etc/namedb/localhost.rev.
/etc/namedb/named.conf
- // $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.60 2001/07/17 23:33:25 chern Exp $
+ // $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.61 2001/07/19 18:38:43 chern Exp $
//
// Refer to the named(8) man page for details. If you are ever going
// to setup a primary server, make sure you've understood the hairy
// details of how DNS is working. Even with simple mistakes, you can
// break connectivity for affected parties, or cause huge amount of
// useless Internet traffic.
options {
directory "/etc/namedb";
// In addition to the "forwarders" clause, you can force your name
// server to never initiate queries of its own, but always ask its
// forwarders only, by enabling the following line:
//
// forward only;
// If you've got a DNS server around at your upstream provider, enter
// its IP address here, and enable the line below. This will make you
// benefit from its cache, thus reduce overall DNS traffic in the
Internet.
/*
forwarders {
127.0.0.1;
};
*/
Just as the comment says, if you want to benefit from your
uplink's cache, you can enable this section of the config file.
Normally, your nameserver will recursively query different
nameservers until it finds the answer it is looking for. Having
this enabled will have it automatically see if your
uplink's (or whatever provided) ns has the requested query.
If your uplink has a heavily trafficked, fast nameserver,
enabling this properly could work to your advantage.
127.0.0.1 will *NOT* work here; change this to the IP of a
nameserver at your uplink.
/*
* If there is a firewall between you and nameservers you want
* to talk to, you might need to uncomment the query-source
* directive below. Previous versions of BIND always asked
* questions using port 53, but BIND 8.1 uses an unprivileged
* port by default.
*/
// query-source address * port 53;
/*
* If running in a sandbox, you may have to specify a different
* location for the dumpfile.
*/
// dump-file "s/named_dump.db";
};
// Note: the following will be supported in a future release.
/*
host { any; } {
topology {
127.0.0.0/8;
};
};
*/
// Setting up secondaries is way easier and the rough picture for this
// is explained below.
//
// If you enable a local name server, don't forget to enter 127.0.0.1
// into your /etc/resolv.conf so this server will be queried first.
// Also, make sure to enable it in /etc/rc.conf.
zone "." {
type hint;
file "named.root";
};
zone "0.0.127.IN-ADDR.ARPA" {
type master;
file "localhost.rev";
};
zone
"0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.INT" {
type master;
file "localhost.rev";
};
// NB: Do not use the IP addresses below, they are faked, and only
// serve demonstration/documentation purposes!
//
// Example secondary config entries. It can be convenient to become
// a secondary at least for the zone where your own domain is in. Ask
// your network administrator for the IP address of the responsible
// primary.
//
// Never forget to include the reverse lookup (IN-ADDR.ARPA) zone!
// (This is the first bytes of the respective IP address, in reverse
// order, with ".IN-ADDR.ARPA" appended.)
//
// Before starting to setup a primary zone, better make sure you fully
// understand how DNS and BIND works, however. There are sometimes
// unobvious pitfalls. Setting up a secondary is comparably simpler.
//
// NB: Don't blindly enable the examples below. :-) Use actual names
// and addresses instead.
//
// NOTE!!! FreeBSD runs bind in a sandbox (see named_flags in rc.conf).
// The directory containing the secondary zones must be write accessible
// to bind. The following sequence is suggested:
//
// mkdir /etc/namedb/s
// chown bind:bind /etc/namedb/s
// chmod 750 /etc/namedb/s
/*
zone "domain.com" {
type slave;
file "s/domain.com.bak";
masters {
192.168.1.1;
};
};
zone "0.168.192.in-addr.arpa" {
type slave;
file "s/0.168.192.in-addr.arpa.bak";
masters {
192.168.1.1;
};
};
*/
These are example slave entries, read below to see more.
For each new domain added to your nameserver, you must add one
of these entries to your named.conf
The simplest zone entry, can look like
zone "foobardomain.org" {
type master;
file "foorbardomain.org";
};For a master entry with the zone information within
foobardomain.org, or
zone "foobardomain.org" {
type slave;
file "foobardomain.org";
};
for a slave. Note that slave zones automatically query the
listed master (authoritative) name servers for the zone file.
Zone files
An example master 'foobardomain.org' (existing within
/etc/namedb/foobardomain.org) is as follows:
$TTL 3600
foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
86400 ) ; Minimum TTL
; DNS Servers
@ IN NS ns1.foobardomain.org.
@ IN NS ns2.foobardomain.org.
; Machine Names
localhost IN A 127.0.0.1
ns1 IN A 3.2.1.2
ns2 IN A 3.2.1.3
mail IN A 3.2.1.10
@ IN A 3.2.1.30
; Aliases
www IN CNAME @
; MX Record
@ IN MX 10 mail.foobardomain.org.
Note that every hostname ending in a '.' is an exact
hostname, whereas everything without a trailing '.' is
referenced to the origin. For example, www is translated
into www + origin. In our fictitious zone file, our origin
is foobardomain.org, so www would be www.foobardomain.org.
The format of this file follows:
recordname IN recordtype valueDNSrecords
The most commonly used DNS records:
SOA - start of zone authorityNS - an authoritative nameserverA - A host addressCNAME - the canonical name for an
aliasMX - mail exchangePTR - a domain name pointer (used in
reverse dns)
foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh after 3 hours
3600 ; Retry after 1 hour
604800 ; Expire after 1 week
86400 ) ; Minimum TTL of 1 day
foobardomain.org. - the domain name, also
the origin for this zone file.
ns1.foobardomain.org. - the
primary/authoritative nameserver for this zone
admin.foobardomain.org. - the
responsible person for this zone, e-mail address with @
replaced. (admin@foobardomain.org becomes
admin.foobardomain.org)
5 - the serial number of the file. this
must
be incremented each time the zone file is modified. Nowadays,
many admins prefer a yyyymmddrr format for the serial
number.
2001041002 would mean last modified 04/10/2001, the latter 02 being
the second time the zone file has been modified this day. The
serial number is important as it alerts slave nameservers for a zone
when it is updated.
@ IN NS ns1.foobardomain.org.
This is an NS entry. Every nameserver that is going to reply
authoritatively for the zone must have one of these entries.
The @ as seen here could have been foobardomain.org.
The @ translates to the origin.
localhost IN A 127.0.0.1
ns1 IN A 3.2.1.2
ns2 IN A 3.2.1.3
mail IN A 3.2.1.10
@ IN A 3.2.1.30
The A record indicates machine names. As seen above,
ns1.foobardomain.org would resolve to 3.2.1.2. Again, the
origin symbol, @, is used here, thus meaning foobardomain.org would
resolve to 3.2.1.30.
www IN CNAME @
The canonical name record is usually used for giving aliases
to a machine. In the example, www is aliased to the machine
addressed to the origin, or foobardomain.org (3.2.1.30).
CNAMEs can be used to provide alias hostnames, or round
robin one hostname among multiple machines.
@ IN MX 10 mail.foobardomain.org.
The MX record indicates which mail servers are responsible
for handling incoming mail for the zone.
mail.foobardomain.org is the hostname of the mail server,
and 10 being the priority of that mailserver.
One can have several mailservers, with priorities of 3, 2,
1. A mail server attempting to deliver to foobardomain.org
would first try the highest priority MX, then the second
highest, etc, until the mail can be properly delivered.
For in-addr.arpa zone files (reverse dns), the same format is
used, except with PTR entries instead of
A or CNAME.
$TTL 3600
1.2.3.in-addr.arpa. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
3600 ) ; Minimum
@ IN NS ns1.foobardomain.org.
@ IN NS ns2.foobardomain.org.
2 IN PTR ns1.foobardomain.org.
3 IN PTR ns2.foobardomain.org.
10 IN PTR mail.foobardomain.org.
30 IN PTR foobardomain.org.
This file gives the proper IP address to hostname mappings of our above
fictitious domain.
Caching Name ServerBINDcaching name server
A caching nameserver is simply a nameserver that is not
authoritative for any zones. It simply asks queries of its own,
and remembers them for later use. To set one up, just configure
the name server as usual, omitting any inclusions of zones.
Running named in a SandboxBINDrunning in a sandboxContributed by Mike Makonnen
mike_makonnen@yahoo.com, May 1, 2001chrootFor added security you may want to run &man.named.8; in a
sandbox. This will reduce the potential damage should it be
compromised. If you include a sandbox directory in its command
line, named will &man.chroot.8;
into that directory immediately upon finishing processing its
command line. It is also a good idea to have named run as a
non-privileged user in the sandbox. The default FreeBSD install
contains a user bind with group bind. If we wanted the sandbox in
the /etc/namedb/sandbox directory the command
line for named would look like this:
&prompt.root; /usr/sbin/named -u bind -g bind -t /etc/namedb/sandbox <path_to_named.conf> The following steps should be taken in order to
successfully run named in a sandbox. Throughout the following
discussion we will assume the path to your sandbox is
/etc/namedb/sandboxCreate the sandbox directory:
/etc/namedb/sandboxCreate other necessary directories off of the sandbox
directory: etc and
var/runcopy /etc/localtime to
sandbox/etcmake bind:bind the owner of all files and directories in
the sandbox:
&prompt.root; chown -R bind:bind /etc/namedb/sandbox&prompt.root; chmod -R 750 /etc/namedb/sandboxThere are some issues you need to be aware of when running
named in a sandbox.Your &man.named.conf.5; file and all your zone files must
be in the sandbox
sandbox/etc/localtime is needed
in order to have the correct time for your time zone in
log messages. &man.named.8; will write its process id to a file in
sandbox/var/runThe Unix socket used for communication by the &man.ndc.8;
utility will be created in
sandbox/var/runWhen using the &man.ndc.8; utility you need to specify the
location of the Unix socket created in the sandbox, by
&man.named.8;, by using the -c switch:
&prompt.root; ndc -c /etc/namedb/sandbox/var/run/ndcIf you enable logging to file, the log files must be
in the sandbox&man.named.8; can be started in a sandbox properly, if the
following is in /etc/rc.confnamed_flags="-u bind -g bind -t /etc/namedb/sandbox"How to use the nameserverIf setup properly, the nameserver should be accessible through
the network and locally. /etc/resolv.conf must
contain a nameserver entry with the local IP address so it will query the
local name server first.
To access it over the network, the machine must have the
nameserver's IP address set properly in its own nameserver
configuration options.
SecurityAlthough BIND is the most common implementation of DNS,
there is always the issue of security. Possible and
exploitable security holes are sometimes found.
It is a good idea to subscribe to CERT and
freebsd-announce
to stay up to date with the current Internet and FreeBSD security
issues.
If a problem arises, keeping your sources up to date and having a
fresh build of named can't hurt.
Further Reading
&man.ndc.8; &man.named.8; &man.named.conf.5;
Official ISC BIND Page
http://www.isc.org/products/BIND/
BIND FAQ
http://www.nominum.com/resources/faqs/bind-faqs.htmlO'Reilly DNS and BIND 4th EditionRFC1034 - Domain Names -
Concepts and FacilitiesRFC1035 - Domain Names -
Implementation and SpecificationNetwork Address Translation daemon (natd)Contributed by &a.chern;, June 2001.
OverviewnatdFreeBSD's Network Address Translation daemon, commonly known as
&man.natd.8; is a daemon that accepts incoming raw IP packets,
changes the source to the local machine and re-injects these packets
back into the outgoing IP packet stream. natd does this by changing
the source IP address and port such that when data is received back, it is
able to determine the original location of the data and forward it
back to its original requester.Internet connection sharingIP masqueradingThe most common use of NAT is to perform what is commonly known as
Internet Connection Sharing.SetupDue to the diminishing IP space in ipv4, and the increased number
of users on high-speed consumer lines such as cable or DSL, people are
in more and more need of an Internet Connection Sharing solution. The
ability to connect several computers online through one connection and
IP address makes &man.natd.8; a reasonable choice.Most commonly, a user has a machine connected to a cable or DSL
line with one IP address and wishes to use this one connected computer to
provide Internet access to several more over a LAN.To do this, the FreeBSD machine on the Internet must act as a
gateway. This gateway machine must have two NICs--one for connecting
to the Internet router, the other connecting to a LAN. All the
machines on the LAN are connected through a hub or switch. _______ __________ ________
| | | | | |
| Hub |-----| Client B |-----| Router |----- Internet
|_______| |__________| |________|
|
____|_____
| |
| Client A |
|__________|Network LayoutWith this setup, the machine without Internet access can use
the machine with access as a gateway to access the outside
world.kernelconfigurationConfigurationThe following options must be in the kernel configuration
file:options IPFIREWALL
options IPDIVERTAdditionally, at choice, the following may also be suitable:options IPFIREWALL_DEFAULT_TO_ACCEPT
options IPFIREWALL_VERBOSEThe following must be in /etc/rc.conf:gateway_enable="YES"
firewall_enable="YES"
firewall_type="OPEN"
natd_enable="YES"
natd_interface="fxp0"
natd_flags=""gateway_enable="YES"Sets up the machine to act as a gateway. Running
sysctl -w net.inet.ip.forwarding=1
would have the same effect.firewall_enable="YES"Enables the firewall rules in
/etc/rc.firewall at boot.firewall_type="OPEN"This specifies a predefined firewall ruleset that
allows anything in. See
/etc/rc.firewall for additional
types.natd_interface="fxp0"Indicates which interface to forward packets through.
(the interface connected to the Internet)natd_flags=""Any additional configuration options passed to
&man.natd.8; on boot.Having the previous options defined in
/etc/rc.conf would run
natd -interface fxp0 at boot. This can also
be run manually.Each machine and interface behind the LAN should be assigned IP address
numbers in the private network space as defined by
RFC 1918
and have a default gateway of the natd machine's internal IP address.For example, client a and b behind the LAN have IP addresses of 192.168.0.2
and 192.168.0.3, while the natd machine's LAN interface has an IP address of
192.168.0.1. Client a and b's default gateway must be set to that of
the natd machine, 192.168.0.1. The natd machine's external, or
Internet interface does not require any special modification for natd
to work.Port RedirectionThe drawback with natd is that the LAN clients are not accessible
from the Internet. Clients on the LAN can make outgoing connections to
the world but cannot receive incoming ones. This presents a problem
if trying to run Internet services on one of the LAN client machines.
A simple way around this is to redirect selected Internet ports on the
natd machine to a LAN client.
For example, an IRC server runs on Client A, and a web server runs
on Client B. For this to work properly, connections received on ports
6667 (irc) and 80 (web) must be redirected to the respective machines.
The -redirect_port must be passed to
&man.natd.8; with the proper options. The syntax is as follows: -redirect_port proto targetIP:targetPORT[-targetPORT]
[aliasIP:]aliasPORT[-aliasPORT]
[remoteIP[:remotePORT[-remotePORT]]]In the above example, the argument should be:
-redirect_port tcp 192.168.0.2:6667 6667
-redirect_port tcp 192.168.0.3:80 80
This will redirect the proper tcp ports to the
LAN client machines.
The -redirect_port argument can be used to indicate port
ranges over individual ports. For example, tcp
192.168.0.2:2000-3000 2000-3000 would redirect
all connections received on ports 2000 to 3000 to ports 2000
to 3000 on Client A.These options can be used when directly running
&man.natd.8; or placed within the
natd_flags="" option in
/etc/rc.conf.For further configuration options, consult &man.natd.8;Address Redirectionaddress redirectionAddress redirection is useful if several IP addresses are available, yet
they must be on one machine. With this, &man.natd.8; can assign each
LAN client its own external IP address. &man.natd.8; then rewrites outgoing
packets from the LAN clients with the proper external IP address and redirects
all traffic incoming on that particular IP address back to the specific LAN
client. This is also known as static NAT. For example, the IP addresses
128.1.1.1, 128.1.1.2, and 128.1.1.3 belong to the natd gateway
machine. 128.1.1.1 can be used as the natd gateway machine's external
IP address, while 128.1.1.2 and 128.1.1.3 are forwarded back to LAN
clients A and B.The -redirect_address syntax is as follows:localIPThe internal IP address of the LAN client.publicIPThe external IP address corresponding to the LAN client.In the example, this argument would read:Like -redirect_port, these arguments are also placed within
natd_flags of /etc/rc.conf. With address
redirection, there is no need for port redirection since all data
received on a particular IP address is redirected.The external IP addresses on the natd machine must be active and aliased
to the external interface. Look at &man.rc.conf.5; to do so.
diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
index 97212a3f5e..153dcb6aa6 100644
--- a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
@@ -1,2862 +1,2901 @@
PPP and SLIPRestructured, reorganized, and updated by &a.jim;,
1 March 2000.Synopsis
- PPP
- SLIP
+
+ PPP
+
+
+ SLIP
+ If you are connecting to the Internet via modem, or wish to
provide dial-up connections to the Internet for others using FreeBSD,
you have the option of using PPP or SLIP.
- PPPuser PPP
- PPPkernel PPP
- PPPover Ethernet
+
+ PPP
+ user PPP
+
+
+ PPP
+ kernel PPP
+
+
+ PPP
+ over Ethernet
+ This chapter covers three varieties of PPP;
user, kernel, and
PPPoE (PPP over Ethernet). It also covers
setting up a SLIP client and server.The first variety of PPP that will be covered is User PPP. User
PPP was introduced into FreeBSD in 2.0.5-RELEASE as an addition to
the already existing kernel implementation of PPP.You may be wondering what the main difference is between User
PPP and kernel PPP. The answer is simple; user PPP does not run as
a daemon, and can run as and when desired. No PPP interface needs
to be compiled into their kernel; it runs as a user process, and uses
the tunnel device driver (tun) to get data
into and out of the kernel.From here on out in this chapter, user ppp will simply be
referred to as ppp unless a distinction needs to be made between it
and any other PPP software such as pppd.
Unless otherwise stated, all of the commands explained in this
section should be executed as root.Using User PPPOriginally contributed by &a.brian;, with input
from &a.nik;, &a.dirkvangulik;, and &a.pjc;.User PPPAssumptionsThis document assumes you have the following:
- ISP
- PPP
+
+ ISP
+
+
+ PPP
+ An account with an Internet Service Provider (ISP) which
you connect to using PPP. Further, you have a modem or
other device connected to your system and configured
correctly, which allows you to connect to your ISP.The dial-up number(s) of your ISP.
- PAP
- CHAP
- Unix
- login name
- password
+
+ PAP
+
+
+ CHAP
+
+
+ Unix
+
+
+ login name
+
+
+ password
+ Your login name and password. This can be either a
regular Unix-style login and password pair, or a PAP or CHAP
login and password pair.
- name server
+
+ name server
+ The IP address(es) of one or more name servers.
Normally, you will be given two IP addresses by your ISP to
use for this. If they have not given you at least one, then
you can use the enable dns command in
your ppp.conf file to tell
ppp to set the name servers for
you.The following information may be supplied by your ISP, but
is not completely necessary:The IP address of your ISP's gateway. The gateway is
the machine to which you will connect and will be set up as
your default route. If you do not have
this information, we can make one up and your ISP's PPP
server will tell us the correct value when we connect.This IP number is referred to as
HISADDR by
ppp.The netmask you should use. If your ISP has not
provided you with one, you can safely use 255.255.255.0.
- static IP address
+
+ static IP address
+ If your ISP provides you with a static IP address and
hostname, you can enter it. Otherwise, we simply let the
peer assign whatever IP address it sees fit.If you do not have any of the required information, contact
your ISP and make sure they provide it to you.Preparing the KernelAs previously mentioned, ppp
uses the tun device, and whichever kernel
you are using must have tun configured.
The tun device is preconfigured
for the default GENERIC kernel that ships
with FreeBSD. However, if you have installed a custom kernel,
you must make sure your kernel is configured for ppp.
- kernelcompilation
+
+ kernel
+ compilation
+ To check, go to your kernel compile directory
(/sys/i386/conf or
/sys/pc98/conf) and examine your
configuration file. It should have the following line somewhere
in it:pseudo-device tun 1If this line is not present, you will need to add it to the
configuration file and recompile your kernel. The stock
GENERIC kernel has this included, so if you
have not installed a custom kernel or do not have a
/sys directory, you do not have to change
anything. If you do need to recompile your kernel, please refer
to the kernel configuration
section for more information.You can check how many tunnel devices your current kernel
has by typing the following:&prompt.root; ifconfig -a
tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
inet 200.10.100.1 --> 203.10.100.24 netmask 0xffffffff
tun1: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 576
tun2: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
inet 203.10.100.1 --> 203.10.100.20 netmask 0xffffffff
tun3: flags=8010<POINTOPOINT,MULTICAST> mtu 1500In FreeBSD 4.0 and later releases, you will only see any
tun devices which have already been
used. This means you might not see anytun devices. If this is the case, do
not worry; the device should be created dynamically when
ppp attempts to use it.This case shows four tunnel devices, two of which are
currently configured and being used. It should be noted that
the RUNNING flag above indicates that the
interface has been used at some point—it is not an error
if your interface does not show up as
RUNNING.If for some reason you have a kernel that does not have the
tun device in it and cannot recompile
the kernel, all is not lost. You should be able to dynamically
load the code. Please refer to the appropriate
&man.modload.8; and &man.lkm.4; man pages for further
details.Check the tun deviceUnder normal circumstances, most users will only require one
tun device
(/dev/tun0). If you have specified more
than one on the pseudo-device line for
tun in your kernel configuration file,
then alter all references to tun0 below
to reflect whichever device number you are using (e.g.,
tun2).The easiest way to make sure that the
tun0 device is configured correctly,
is to remake the device. This process is quite easy. To remake
the device, do the following:&prompt.root; cd /dev
&prompt.root; ./MAKEDEV tun0If you need 16 tunnel devices in your kernel, you will need
to create them. This can be done by executing the following
commands:&prompt.root; cd /dev
&prompt.root; ./MAKEDEV tun15To confirm that the kernel is configured correctly, issue
the follow command and compare the results:&prompt.root; ifconfig tun0
tun0: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mut 1500The RUNNING flag may not yet be set, in
which case you will see:&prompt.root; ifconfig tun0
tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500Remember from earlier that you might not see the device if it
has not been used yet, as tun devices are
created on demand in FreeBSD 4.0 and later releases.Name Resolution Configuration
- resolver
-
- hostname
-
-
- hosts
-
+
+ resolver
+
+
+ hostname
+
+
+ hosts
+ The resolver is the part of the system that turns IP
addresses into hostnames and vice versa. It can be configured
to look for maps that describe IP to hostname mappings in one of
two places. The first is a file called
/etc/hosts. Read &man.hosts.5; for more
information. The second is the Internet Domain Name Service
(DNS), a distributed data base, the discussion of which is
beyond the scope of this document.The resolver is a set of system calls that do the name
mappings, but you have to tell them where to find their
information. You do this by first editing the file
/etc/host.conf. Do not
call this file /etc/hosts.conf (note the
extra s) as the results can be
confusing.Edit /etc/host.confThis file should contain the following two lines (in this
order):hosts
bindThese instruct the resolver to first look in the file
/etc/hosts, and then to consult the DNS
if the name was not found.Edit /etc/hostsThis file should contain the IP addresses and names of
machines on your network. At a bare minimum it should contain
entries for the machine which will be running ppp. Assuming
that your machine is called foo.bar.com with the IP address 10.0.0.1,
/etc/hosts should contain:127.0.0.1 localhost.bar.com localhost
127.0.0.1 localhost.bar.com.
10.0.0.1 foo.bar.com foo
10.0.0.1 foo.bar.com.The first two lines define the alias
localhost as a synonym for the current
machine. Regardless of your own IP address, the IP address
for this line should always be 127.0.0.1. The second two lines map
the name foo.bar.com (and the
shorthand foo) to the IP address 10.0.0.1.If your provider allocates you a static IP address and
name, use them in place of the 10.0.0.1 entry.Edit /etc/resolv.confThe /etc/resolv.conf file tells the
resolver how to behave. If you are running your own DNS, you
may leave this file empty. Normally, you will need to enter
the following line(s):domain bar.com
nameserver x.x.x.x
nameserver y.y.y.yThe x.x.x.x and
y.y.y.y
addresses are those given to you by your ISP. Add as many
nameserver lines as your ISP provides. The
domain line defaults to your hostname's
domain, and is probably unnecessary. Refer to the
&man.resolv.conf.5; manual page for details of other possible
entries in this file.PPPISPIf you are running PPP version 2 or greater, the
enable dns command will tell PPP to request
that your ISP confirms the nameserver values. If your ISP
supplies different addresses (or if there are no nameserver
lines in /etc/resolv.conf), PPP will
rewrite the file with the ISP-supplied values.PPP ConfigurationPPPconfigurationBoth ppp and pppd
(the kernel level implementation of PPP) use the configuration
files located in the /usr/share/examples/ppp directory.
The sample configuration files provided are a good reference,
so do not delete them.Configuring ppp requires that you edit a
number of files, depending on your requirements. What you put
in them depends to some extent on whether your ISP allocates IP
addresses statically (i.e., you get given one IP address, and
always use that one) or dynamically (i.e., your IP address
changes each time you connect to your ISP).PPP and Static IP AddressesPPPwith static IP addressesYou will need to create a configuration file called
/etc/ppp/ppp.conf. It should look
similar to the example below.Lines that end in a : start in the
first column, all other lines should be indented as shown
using spaces or tabs.1 default:
2 set device /dev/cuaa0
3 set speed 115200
4 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0 OK-AT-OK \\dATDT\\TTIMEOUT 40 CONNECT"
5 provider:
6 set phone "(123) 456 7890"
7 set login "TIMEOUT 10 \"\" \"\" gin:--gin: foo word: bar col: ppp"
8 set timeout 300
9 set ifaddr x.x.x.xy.y.y.y 255.255.255.0 0.0.0.0
10 add default HISADDR
11 enable dnsDo not include the line numbers, they are just for
reference in this discussion.Line 1:Identifies the default entry. Commands in this
entry are executed automatically when ppp is run.Line 2:Identifies the device to which the modem is
connected. COM1 is
/dev/cuaa0 and
COM2 is
/dev/cuaa1.Line 3:Sets the speed you want to connect at. If 115200
does not work (it should with any reasonably new modem),
try 38400 instead.Line 4:PPPuser PPPThe dial string. User PPP uses an expect-send
syntax similar to the &man.chat.8; program. Refer to
the manual page for information on the features of this
language.Line 5:Identifies an entry for a provider called
provider.Line 6:Sets the phone number for this provider. Multiple
phone numbers may be specified using the colon
(:) or pipe character
(|)as a separator. The difference
between the two separators is described in &man.ppp.8;.
To summarize, if you want to rotate through the numbers,
use a colon. If you want to always attempt to dial the
first number first and only use the other numbers if the
first number fails, use the pipe character. Always
quote the entire set of phone numbers as shown.Line 7:The login string is of the same chat-like syntax as
the dial string. In this example, the string works for
a service whose login session looks like this:J. Random Provider
login: foo
password: bar
protocol: pppYou will need to alter this script to suit your own
needs. When you write this script for the first time,
you should enable chat logging to ensure
that the conversation is going as expected.PAPCHAPIf you are using PAP or CHAP, there will be no login
at this point, so your login string can be left blank.
See PAP and CHAP
authentication for further details.Line 8:timeoutSets the default timeout (in seconds) for the
connection. Here, the connection will be closed
automatically after 300 seconds of inactivity. If you
never want to timeout, set this value to zero.Line 9:ISPSets the interface addresses. The string
x.x.x.x should be replaced by
the IP address that your provider has allocated to you.
The string y.y.y.y should be
replaced by the IP address that your ISP indicated for
their gateway (the machine to which you connect). If
your ISP hasn't given you a gateway address, use 10.0.0.2/0. If you need to use
a guessed address, make sure that you
create an entry in
/etc/ppp/ppp.linkup as per the
instructions for PPP
and Dynamic IP addresses. If this line is
omitted, ppp cannot run in
or
mode.Line 10:Adds a default route to your ISP's gateway. The
special word HISADDR is replaced with
the gateway address specified on line 9. It is
important that this line appears after line 9,
otherwise HISADDR will not yet be
initialized.Line 11:nameserverThis line tells PPP to ask your ISP to confirm that
your nameserver addresses are correct. If your ISP
supports this facility, PPP can then update
/etc/resolv.conf with the correct
nameserver entries.It is not necessary to add an entry to
ppp.linkup when you have a static IP
address as your routing table entries are already correct
before you connect. You may however wish to create an entry
to invoke programs after connection. This is explained later
with the sendmail example.Example configuration files can be found in the
/usr/share/examples/ppp directory.PPP and Dynamic IP AddressesPPPwith dynamic IP addressesIPCPIf your service provider does not assign static IP
addresses, ppp can be configured to
negotiate the local and remote addresses. This is done by
guessing an IP address and allowing
ppp to set it up correctly using the IP
Configuration Protocol (IPCP) after connecting. The
ppp.conf configuration is the same as
PPP and Static IP
Addresses, with the following change:9 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0Again, do not include the line numbers, they are just for
reference. Indentation of at least one space is
required.Line 9:The number after the / character
is the number of bits of the address that ppp will
insist on. You may wish to use IP numbers more
appropriate to your circumstances, but the above example
will always work.The last argument (0.0.0.0) tells
PPP to negotiate using address 0.0.0.0 rather than 10.0.0.1. Do not use
0.0.0.0 as the first argument to
set ifaddr as it prevents PPP from
setting up an initial route in
mode.If you are running version 1.x of PPP, you will also need
to create an entry in /etc/ppp/ppp.linkup.
ppp.linkup is used after a connection has
been established. At this point, ppp will
know what IP addresses should really be
used. The following entry will delete the existing bogus
routes, and create correct ones:1 provider:
2 delete ALL
3 add 0 0 HISADDRLine 1:On establishing a connection, ppp
will look for an entry in ppp.linkup
according to the following rules: First, try to match
the same label as we used in
ppp.conf. If that fails, look for
an entry for the IP address of our gateway. This entry
is a four-octet IP style label. If we still have not
found an entry, look for the MYADDR
entry.Line 2:This line tells ppp to delete all
of the existing routes for the acquired
tun interface (except the
direct route entry).Line 3:This line tells ppp to add a
default route that points to HISADDR.
HISADDR will be replaced with the IP
number of the gateway as negotiated in the IPCP.See the pmdemand entry in the files
/usr/share/examples/ppp/ppp.conf.sample and
/usr/share/examples/ppp/ppp.linkup.sample for a
detailed example.Version 2 of PPP introduces sticky routes.
Any add or delete lines
that contain MYADDR or
HISADDR will be remembered, and any time
the actual values of MYADDR or
HISADDR change, the routes will be
reapplied. This removes the necessity of repeating these
lines in ppp.linkup.Receiving Incoming CallsPPPreceiving
incoming callsWhen you configure ppp to
receive incoming calls on a machine connected to a LAN, you
must decide if you wish to forward packets to the LAN. If you
do, you should allocate the peer an IP number from your LAN's
subnet, and use the command enable proxy in
your /etc/ppp/ppp.conf file. You should
also confirm that the /etc/rc.conf file
contains the following:gateway="YES"Which getty?Configuring FreeBSD for Dial-up
Services provides a good description on enabling
dial-up services using &man.getty.8;.An alternative to getty is mgetty,
a smarter version of getty designed with
dial-up lines in mind.The advantages of using mgetty is
that it actively talks to modems,
meaning if port is turned off in
/etc/ttys then your modem will not answer
the phone.Later versions of mgetty (from
0.99beta onwards) also support the automatic detection of
PPP streams, allowing your clients script-less access to
your server.Refer to Mgetty and
AutoPPP for more information on
mgetty.PPP PermissionsThe ppp command must normally be run
as user id 0. If however, you wish to allow
ppp to run in server mode as a normal
user by executing ppp as described below,
that user must be given permission to run
ppp by adding them to the
network group in
/etc/group.You will also need to give them access to one or more
sections of the configuration file using the
allow command:allow users fred maryIf this command is used in the default
section, it gives the specified users access to
everything.PPP Shells for Dynamic-IP UsersPPP shellsCreate a file called
/etc/ppp/ppp-shell containing the
following:#!/bin/sh
IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'`
CALLEDAS="$IDENT"
TTY=`tty`
if [ x$IDENT = xdialup ]; then
IDENT=`basename $TTY`
fi
echo "PPP for $CALLEDAS on $TTY"
echo "Starting PPP for $IDENT"
exec /usr/sbin/ppp -direct $IDENTThis script should be executable. Now make a symbolic
link called ppp-dialup to this script
using the following commands:&prompt.root; ln -s ppp-shell /etc/ppp/ppp-dialupYou should use this script as the
shell for all of your dialup users.
This is an example from /etc/password
for a dialup PPP user with username
pchilds (remember don't directly edit
the password file, use vipw).pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialupCreate a /home/ppp directory that
is world readable containing the following 0 byte
files:-r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin
-r--r--r-- 1 root wheel 0 May 27 02:22 .rhostswhich prevents /etc/motd from being
displayed.PPP shells for Static-IP UsersPPP shellsCreate the ppp-shell file as above
and for each account with statically assigned IPs create a
symbolic link to ppp-shell.For example, if you have three dialup customers
fred, sam, and
mary, that you route class C networks
for, you would type the following:&prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred
&prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam
&prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-maryEach of these users dialup accounts should have their
shell set to the symbolic link created above (i.e.,
mary's shell should be
/etc/ppp/ppp-mary).Setting up ppp.conf for dynamic-IP usersThe /etc/ppp/ppp.conf file should
contain something along the lines of:default:
set debug phase lcp chat
set timeout 0
ttyd0:
set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
enable proxy
ttyd1:
set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255
enable proxyThe indenting is important.The default: section is loaded for
each session. For each dialup line enabled in
/etc/ttys create an entry similar to
the one for ttyd0: above. Each line
should get a unique IP address from your pool of IP
addresses for dynamic users.Setting up ppp.conf for static-IP
usersAlong with the contents of the sample
/usr/share/examples/ppp/ppp.conf above you should add
a section for each of the statically assigned dialup users.
We will continue with our fred,
sam, and mary
example.fred:
set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255
sam:
set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255
mary:
set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255The file /etc/ppp/ppp.linkup should
also contain routing information for each static IP user if
required. The line below would add a route for the 203.14.101.0 class C via the
client's ppp link.fred:
add 203.14.101.0 netmask 255.255.255.0 HISADDR
sam:
add 203.14.102.0 netmask 255.255.255.0 HISADDR
mary:
add 203.14.103.0 netmask 255.255.255.0 HISADDRMore on mgetty, AutoPPP, and MS
extensionsmgetty and AutoPPPmgettyAutoPPPLCPConfiguring and compiling mgetty with
the AUTO_PPP option enabled allows
mgetty to detect the LCP phase of PPP
connections and automatically spawn off a ppp shell.
However, since the default login/password sequence does not
occur it is necessary to authenticate users using either PAP
or CHAP.This section assumes the user has successfully
configured, compiled, and installed a version of
mgetty with the
AUTO_PPP option (v0.99beta or
later).Make sure your
/usr/local/etc/mgetty+sendfax/login.config
file has the following in it:/AutoPPP/ - - /etc/ppp/ppp-pap-dialupThis will tell mgetty to run the
ppp-pap-dialup script for detected PPP
connections.Create a file called
/etc/ppp/ppp-pap-dialup containing the
following (the file should be executable):#!/bin/sh
exec /usr/sbin/ppp -direct pap$IDENTFor each dialup line enabled in
/etc/ttys, create a corresponding entry
in /etc/ppp/ppp.conf. This will
happily co-exist with the definitions we created
above.pap:
enable pap
set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40
enable proxyEach user logging in with this method will need to have
a username/password in
/etc/ppp/ppp.secret file, or
alternatively add the following option to authenticate users
via PAP from /etc/password file.enable passwdauthIf you wish to assign some users a static IP number, you
can specify the number as the third argument in
/etc/ppp/ppp.secret. See
/usr/share/examples/ppp/ppp.secret.sample for
examples.MS extensionsDNSNetBIOSPPPMicrosoft extensionsIt is possible to configure PPP to supply DNS and
NetBIOS nameserver addresses on demand.To enable these extensions with PPP version 1.x, the
following lines might be added to the relevant section of
/etc/ppp/ppp.conf.enable msext
set ns 203.14.100.1 203.14.100.2
set nbns 203.14.100.5And for PPP version 2 and above:accept dns
set dns 203.14.100.1 203.14.100.2
set nbns 203.14.100.5This will tell the clients the primary and secondary
name server addresses, and a netbios nameserver host.In version 2 and above, if the
set dns line is omitted, PPP will use the
values found in /etc/resolv.conf.PAP and CHAP authenticationPAPCHAPSome ISPs set their system up so that the authentication
part of your connection is done using either of the PAP or
CHAP authentication mechanisms. If this is the case, your ISP
will not give a login: prompt when you
connect, but will start talking PPP immediately.PAP is less secure than CHAP, but security is not normally
an issue here as passwords, although being sent as plain text
with PAP, are being transmitted down a serial line only.
There's not much room for crackers to
eavesdrop.Referring back to the PPP
and Static IP addresses or PPP and Dynamic IP addresses
sections, the following alterations must be made:7 set login
…
12 set authname MyUserName
13 set authkey MyPasswordAs always, do not include the line numbers, they are just
for reference in this discussion. Indentation of at least one
space is required.Line 7:Your ISP will not normally require that you log into
the server if you're using PAP or CHAP. You must
therefore disable your set login
string.Line 12:This line specifies your PAP/CHAP user name. You
will need to insert the correct value for
MyUserName.Line 13:passwordThis line specifies your PAP/CHAP password. You
will need to insert the correct value for
MyPassword. You may want to
add an additional line, such as:15 accept PAPor15 accept CHAPto make it obvious that this is the intention, but
PAP and CHAP are both accepted by default.Changing your ppp configuration on the
flyIt is possible to talk to the ppp
program while it is running in the background, but only if a
suitable diagnostic port has been set up. To do this, add the
following line to your configuration:set server /var/run/ppp-tun%d DiagnosticPassword 0177This will tell PPP to listen to the specified unix-domain
socket, asking clients for the specified password before
allowing access. The %d in the name is
replaced with the tun device number
that is in use.Once a socket has been set up, the &man.pppctl.8; program
may be used in scripts that wish to manipulate the running
program.Final system configurationPPPconfigurationYou now have ppp configured, but there
are a few more things to do before it is ready to work. They
all involve editing the /etc/rc.conf
file.Working from the top down in this file, make sure the
hostname= line is set, e.g.:hostname="foo.bar.com"If your ISP has supplied you with a static IP address and
name, it's probably best that you use this name as your host
name.Look for the network_interfaces variable.
If you want to configure your system to dial your ISP on demand,
make sure the tun0 device is added to
the list, otherwise remove it.network_interfaces="lo0 tun0" ifconfig_tun0=The ifconfig_tun0 variable should be
empty, and a file called
/etc/start_if.tun0 should be created.
This file should contain the line:ppp -auto mysystemThis script is executed at network configuration time,
starting your ppp daemon in automatic mode. If you have a LAN
for which this machine is a gateway, you may also wish to use
the switch. Refer to the manual page
for further details.Set the router program to NO with
following line in your
/etc/rc.conf:router_enable="NO"routedIt is important that the routed daemon is
not started (it is started by default), as it
routed tends to delete the default routing
table entries created by ppp.It is probably worth your while ensuring that the
sendmail_flags line does not include the
option, otherwise
sendmail will attempt to do a network lookup
every now and then, possibly causing your machine to dial out.
You may try:sendmail_flags="-bd"sendmailThe downside of this is that you must force
sendmail to re-examine the mail queue
whenever the ppp link is up by typing:&prompt.root; /usr/sbin/sendmail -qYou may wish to use the !bg command in
ppp.linkup to do this automatically:1 provider:
2 delete ALL
3 add 0 0 HISADDR
4 !bg sendmail -bd -q30mSMTPIf you don't like this, it is possible to set up a
dfilter to block SMTP traffic. Refer to the
sample files for further details.Now the only thing left to do is reboot the machine.All that is left is to reboot the machine. After rebooting,
you can now either type:&prompt.root; pppand then dial provider to start the PPP
session, or, if you want ppp to establish
sessions automatically when there is outbound traffic (and
you have not created the start_if.tun0
script), type:&prompt.root; ppp -auto providerSummaryTo recap, the following steps are necessary when setting up
ppp for the first time:Client side:Ensure that the tun device is
built into your kernel.Ensure that the
tunX device
file is available in the /dev
directory.Create an entry in
/etc/ppp/ppp.conf. The
pmdemand example should suffice for
most ISPs.If you have a dynamic IP address, create an entry in
/etc/ppp/ppp.linkup.Update your /etc/rc.conf
file.Create a start_if.tun0 script if
you require demand dialing.Server side:Ensure that the tun device is
built into your kernel.Ensure that the
tunX device
file is available in the /dev
directory.Create an entry in /etc/passwd
(using the &man.vipw.8; program).Create a profile in this users home directory that runs
ppp -direct direct-server or
similar.Create an entry in
/etc/ppp/ppp.conf. The
direct-server example should
suffice.Create an entry in
/etc/ppp/ppp.linkup.Update your /etc/rc.conf
file.Using Kernel PPPParts originally contributed by &a.gena; and
&a.rhuff;.Setting up Kernel PPPPPPkernel PPPBefore you start setting up PPP on your machine make sure
that pppd is located in
/usr/sbin and the directory
/etc/ppp exists.pppd can work in two modes:As a client, i.e., you want to connect your
machine to the outside world via a PPP serial connection or
modem line.PPPserveras a server, i.e. your machine is located on
the network and used to connect other computers using
PPP.In both cases you will need to set up an options file
(/etc/ppp/options or
~/.ppprc if you have more than one user on
your machine that uses PPP).You also will need some modem/serial software (preferably
kermit) so you can dial and establish a connection with the
remote host.Using pppd as a clientPPPclientCiscoThe following /etc/ppp/options might be
used to connect to a CISCO terminal server PPP line.crtscts # enable hardware flow control
modem # modem control line
noipdefault # remote PPP server must supply your IP address.
# if the remote host doesn't send your IP during IPCP
# negotiation , remove this option
passive # wait for LCP packets
domain ppp.foo.com # put your domain name here
:<remote_ip> # put the IP of remote PPP host here
# it will be used to route packets via PPP link
# if you didn't specified the noipdefault option
# change this line to <local_ip>:<remote_ip>
defaultroute # put this if you want that PPP server will be your
# default routerTo connect:kermitmodemDial to the remote host using kermit (or some other modem
program), and enter your user name and password (or whatever
is needed to enable PPP on the remote host).Exit kermit (without hanging up the line).Enter the following:&prompt.root; /usr/src/usr.sbin/pppd.new/pppd /dev/tty0119200Be sure to use the appropriate speed and device name.Now your computer is connected with PPP. If the connection
fails, you can add the option to the
/etc/ppp/options file and check messages on
the console to track the problem.Following /etc/ppp/pppup script will make
all 3 stages automatically:#!/bin/sh
ps ax |grep pppd |grep -v grep
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing kermit, PID=' ${pid}
kill -9 ${pid}
fi
ifconfig ppp0 down
ifconfig ppp0 delete
kermit -y /etc/ppp/kermit.dial
pppd /dev/tty01 19200kermit/etc/ppp/kermit.dial is a kermit script
that dials and makes all necessary authorization on the remote
host (an example of such a script is attached to the end of this
document).Use the following /etc/ppp/pppdown script
to disconnect the PPP line:#!/bin/sh
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ X${pid} != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill -TERM ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing kermit, PID=' ${pid}
kill -9 ${pid}
fi
/sbin/ifconfig ppp0 down
/sbin/ifconfig ppp0 delete
kermit -y /etc/ppp/kermit.hup
/etc/ppp/ppptestCheck to see if PPP is still running by executing
/usr/etc/ppp/ppptest, which should look like
this:#!/bin/sh
pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'`
if [ X${pid} != "X" ] ; then
echo 'pppd running: PID=' ${pid-NONE}
else
echo 'No pppd running.'
fi
set -x
netstat -n -I ppp0
ifconfig ppp0To hang up the modem, execute
/etc/ppp/kermit.hup, which should
contain:set line /dev/tty01 ; put your modem device here
set speed 19200
set file type binary
set file names literal
set win 8
set rec pack 1024
set send pack 1024
set block 3
set term bytesize 8
set command bytesize 8
set flow none
pau 1
out +++
inp 5 OK
out ATH0\13
echo \13
exitHere is an alternate method using chat
instead of kermit.The following two files are sufficient to accomplish a
pppd connection./etc/ppp/options:/dev/cuaa1 115200
crtscts # enable hardware flow control
modem # modem control line
connect "/usr/bin/chat -f /etc/ppp/login.chat.script"
noipdefault # remote PPP serve must supply your IP address.
# if the remote host doesn't send your IP during
# IPCP negotiation, remove this option
passive # wait for LCP packets
domain <your.domain> # put your domain name here
: # put the IP of remote PPP host here
# it will be used to route packets via PPP link
# if you didn't specified the noipdefault option
# change this line to <local_ip>:<remote_ip>
defaultroute # put this if you want that PPP server will be
# your default router/etc/ppp/login.chat.script:The following should go on a single line.ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<phone.number>
CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <login-id>
TIMEOUT 5 sword: <password>Once these are installed and modified correctly, all you need
to do is run pppd, like so:&prompt.root; pppdThis sample is based primarily on information provided by:
Trev Roydhouse <Trev.Roydhouse@f401.n711.z3.fidonet.org>
and used with permission.Using pppd as a server/etc/ppp/options should contain something
similar to the following:crtscts # Hardware flow control
netmask 255.255.255.0 # netmask ( not required )
192.114.208.20:192.114.208.165 # ip's of local and remote hosts
# local ip must be different from one
# you assigned to the ethernet ( or other )
# interface on your machine.
# remote IP is ip address that will be
# assigned to the remote machine
domain ppp.foo.com # your domain
passive # wait for LCP
modem # modem lineThe following /etc/ppp/pppserv script
will enable tell pppd to behave as a
server:#!/bin/sh
ps ax |grep pppd |grep -v grep
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing kermit, PID=' ${pid}
kill -9 ${pid}
fi
# reset ppp interface
ifconfig ppp0 down
ifconfig ppp0 delete
# enable autoanswer mode
kermit -y /etc/ppp/kermit.ans
# run ppp
pppd /dev/tty01 19200Use this /etc/ppp/pppservdown script to
stop the server:#!/bin/sh
ps ax |grep pppd |grep -v grep
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing kermit, PID=' ${pid}
kill -9 ${pid}
fi
ifconfig ppp0 down
ifconfig ppp0 delete
kermit -y /etc/ppp/kermit.noansThe following kermit script
(/etc/ppp/kermit.ans) will enable/disable
autoanswer mode on your modem. It should look like this:set line /dev/tty01
set speed 19200
set file type binary
set file names literal
set win 8
set rec pack 1024
set send pack 1024
set block 3
set term bytesize 8
set command bytesize 8
set flow none
pau 1
out +++
inp 5 OK
out ATH0\13
inp 5 OK
echo \13
out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable
; autoanswer mod
inp 5 OK
echo \13
exitA script named /etc/ppp/kermit.dial is
used for dialing and authenticating on the remote host. You will
need to customize it for your needs. Put your login and password
in this script; you will also need to change the input statement
depending on responses from your modem and remote host.;
; put the com line attached to the modem here:
;
set line /dev/tty01
;
; put the modem speed here:
;
set speed 19200
set file type binary ; full 8 bit file xfer
set file names literal
set win 8
set rec pack 1024
set send pack 1024
set block 3
set term bytesize 8
set command bytesize 8
set flow none
set modem hayes
set dial hangup off
set carrier auto ; Then SET CARRIER if necessary,
set dial display on ; Then SET DIAL if necessary,
set input echo on
set input timeout proceed
set input case ignore
def \%x 0 ; login prompt counter
goto slhup
:slcmd ; put the modem in command mode
echo Put the modem in command mode.
clear ; Clear unread characters from input buffer
pause 1
output +++ ; hayes escape sequence
input 1 OK\13\10 ; wait for OK
if success goto slhup
output \13
pause 1
output at\13
input 1 OK\13\10
if fail goto slcmd ; if modem doesn't answer OK, try again
:slhup ; hang up the phone
clear ; Clear unread characters from input buffer
pause 1
echo Hanging up the phone.
output ath0\13 ; hayes command for on hook
input 2 OK\13\10
if fail goto slcmd ; if no OK answer, put modem in command mode
:sldial ; dial the number
pause 1
echo Dialing.
output atdt9,550311\13\10 ; put phone number here
assign \%x 0 ; zero the time counter
:look
clear ; Clear unread characters from input buffer
increment \%x ; Count the seconds
input 1 {CONNECT }
if success goto sllogin
reinput 1 {NO CARRIER\13\10}
if success goto sldial
reinput 1 {NO DIALTONE\13\10}
if success goto slnodial
reinput 1 {\255}
if success goto slhup
reinput 1 {\127}
if success goto slhup
if < \%x 60 goto look
else goto slhup
:sllogin ; login
assign \%x 0 ; zero the time counter
pause 1
echo Looking for login prompt.
:slloop
increment \%x ; Count the seconds
clear ; Clear unread characters from input buffer
output \13
;
; put your expected login prompt here:
;
input 1 {Username: }
if success goto sluid
reinput 1 {\255}
if success goto slhup
reinput 1 {\127}
if success goto slhup
if < \%x 10 goto slloop ; try 10 times to get a login prompt
else goto slhup ; hang up and start again if 10 failures
:sluid
;
; put your userid here:
;
output ppp-login\13
input 1 {Password: }
;
; put your password here:
;
output ppp-password\13
input 1 {Entering SLIP mode.}
echo
quit
:slnodial
echo \7No dialtone. Check the telephone line!\7
exit 1
; local variables:
; mode: csh
; comment-start: "; "
; comment-start-skip: "; "
; end:Using PPP over Ethernet (PPPoE)PPPover Ethernet
- PPPoE (see PPP, over Ethernet)
+
+ PPPoE
+ PPP, over Ethernet
+ Contributed by &a.jim; (from node.to) 10 Jan 2000.The following describes how to set up PPP over Ethernet, a.k.a,
PPPoE.PrerequisitesThere are a few requirements that your system will need to meet
in order for PPPoE to function properly. They are:Kernel source for FreeBSD 3.4 or laterppp from FreeBSD 3.4 or laterKernel ConfigurationkernelconfigurationYou will need to set the following options in your kernel
configuration file and then compile a new
kernel.Optionally, you can add
although if this functionality is not available at runtime,
ppp will load the relevant modules
on demand
Setting up ppp.confHere is an example of a working
ppp.conf:default: # or name_of_service_provider
set device PPPoE:xl1 # replace xl1 with your ethernet device
set mru 1492
set mtu 1492
set authname YOURLOGINNAME
set authkey YOURPASSWORD
set log Phase tun command # you can add more detailed logging if you wish
set dial
set login
set ifaddr 10.0.0.1/0 10.0.0.2/0
add default HISADDR
nat enable yes # if you want to enable nat for your local net
papchap:
set authname YOURLOGINNAME
set authkey YOURPASSWORD
Care should be taken when running PPPoE with the
option.
Running PPPAs root, you can run:&prompt.root; ppp -ddial name_of_service_providerStarting PPP at BootAdd the following to your /etc/rc.conf
file:ppp_enable="YES"
ppp_mode="ddial"
ppp_nat="YES"
ppp_profile="default" # or your providerPPPoE with a 3Com HomeConnect ADSL Modem Dual LinkContributed by &a.lioux;, 07 Apr
2001.In short, it does not work. It should, but unfortunately,
that is not the case. For whatever reason, this modem does not
follow RFC
2516 (A Method for transmitting PPP over
Ethernet (PPPoE), written by L. Mamakos, K. Lidl,
J. Evarts, D. Carrel, D. Simone, and R. Wheeler).Since it does not follow the specification, FreeBSD's PPPoE
implementation will not talk to it. It is very likely that it will
not work under other Unix systems for that same reason.
Complain to 3Com if you think it should
comply with the PPPoE specification.ADSLIf you absolutely want to use your ADSL connection with
FreeBSD and are stuck with this modem, you can either:DSLTry replacing the modem with a different brand or model
if your DSL provider permits you to do so. If you are not
sure which brand(s) will work, the &a.questions; is a good
place to ask.Try to get it working. Keep in mind that there is no
guarantee it will work, your mileage may vary.If you want to try to make it work, you can do the
following, but please keep in mind that you do this at
your own risk! Just because it worked for me does
not mean it will work for you.There are three steps to the process. They are:Make sure you already have ppp.conf
set up. See the beginning of this chapter for more details
on doing so.Since the modem does not speak the correct protocol, we
need to learn how to speak its variant of the protocol.
This information was obtained from a DSLreports
forum message.The modem speaks 0x3c12 for
DISCOVERY, and 0x3c13
for PAYLOAD identifiers instead of
0x8863 and 0x8864
respectively, as mandated by the PPPoE specification.CodeRFC's CodeDual Link Modem's CodePAYLOAD0x88630x3c12PAYLOAD0x88640x3c13So, now what? You need to recompile the
NETGRAPH_PPPOE code with the modem's
codes. For this, you should have installed the full kernel
sources.Find the
/usr/src/sys/netgraph/ng_pppoe.h file.
Be careful while editing this file. You have to modify both
the little and the big endian entries.For big endian, find the line with
0x8863 in it, and replace the number
with 0x3c12. Do the same with
0x8864, replacing it with
0x3c13.For little endian, find the line with
0x6388in it, and replace the number
with 0x123c. Do the same with
0x6488, replacing it with
0x133c.Here is a diff of how the new file
should look:&prompt.user; diff -u ng_pppoe.h.orig ng_pppoe.h
--- ng_pppoe.h.orig Thu Apr 12 13:42:46 2001
+++ ng_pppoe.h Thu Apr 12 13:44:47 2001
@@ -148,8 +148,8 @@
#define PTT_SYS_ERR (0x0202)
#define PTT_GEN_ERR (0x0203)
-#define ETHERTYPE_PPPOE_DISC 0x8863 /* pppoe discovery packets */
-#define ETHERTYPE_PPPOE_SESS 0x8864 /* pppoe session packets */
+#define ETHERTYPE_PPPOE_DISC 0x3c12 /* pppoe discovery packets */
+#define ETHERTYPE_PPPOE_SESS 0x3c13 /* pppoe session packets */
#else
#define PTT_EOL (0x0000)
#define PTT_SRV_NAME (0x0101)
@@ -162,8 +162,8 @@
#define PTT_SYS_ERR (0x0202)
#define PTT_GEN_ERR (0x0302)
-#define ETHERTYPE_PPPOE_DISC 0x6388 /* pppoe discovery packets */
-#define ETHERTYPE_PPPOE_SESS 0x6488 /* pppoe session packets */
+#define ETHERTYPE_PPPOE_DISC 0x123c /* pppoe discovery packets */
+#define ETHERTYPE_PPPOE_SESS 0x133c /* pppoe session packets */
#endif
struct pppoe_tag {Then do the following as
root:&prompt.root; cd /usr/src/sys/modules/netgraph/pppoe
&prompt.root; make clean depend all install
&prompt.root; make cleanNow you can speak the modem's variant of the PPPoE
specification.The third step is to figure out the name of the profile
your ISP assigned to the modem. The information for this
step was obtained from the Roaring Penguin
PPPoE program which can be found in the ports collection. If you still are
not able to find it, ask your ISP's tech support.If they do not know it either, and you are feeling bold
(this may de-program your modem and render it useless, so
think twice about doing it).Install the program shipped with the modem by your
provider. Then, access the System menu
from the program. The name of your profile should be
listed there. It is usually ISP.The profile name will be used in the PPPoE configuration
inside ppp.conf as the provider
parameter. See the &man.ppp.8; manual page for more
information.The PPPoE line in your ppp.conf
should look like this:set device PPPoE:xl1:ISPDo not forget to change xl1
to the proper device for your Ethernet card.Do not forget to change ISP
to the profile you have just found above.For additional information, you can try:Cheaper
Broadband with FreeBSD on DSL by Renaud
Waldura in Daemon
News.Another PPPoE tutorial by Sympatico
Users Group.Using SLIPSLIPOriginally contributed by &a.asami; and
&a.ghelmer;, with input from &a.wilko; and
&a.piero;.Setting up a SLIP ClientSLIPclientThe following is one way to set up a FreeBSD machine for SLIP
on a static host network. For dynamic hostname assignments (i.e.,
your address changes each time you dial up), you probably need to
do something much fancier.First, determine which serial port your modem is connected to.
I have a symbolic link to /dev/modem from
/dev/cuaa1, and only use the modem name in
my configuration files. It can become quite cumbersome when you
need to fix a bunch of files in /etc and
.kermrc's all over the system!/dev/cuaa0 is
COM1, cuaa1 is
COM2, etc.Make sure you have the following in your kernel configuration
file:pseudo-device sl 1It is included in the GENERIC kernel, so
this should not be a problem unless you have deleted it.Things you have to do only onceAdd your home machine, the gateway and nameservers to
your /etc/hosts file. Mine looks like
this:127.0.0.1 localhost loghost
136.152.64.181 silvia.HIP.Berkeley.EDU silvia.HIP silvia
136.152.64.1 inr-3.Berkeley.EDU inr-3 slip-gateway
128.32.136.9 ns1.Berkeley.edu ns1
128.32.136.12 ns2.Berkeley.edu ns2Make sure you have before
in your
/etc/host.conf. Otherwise, funny
things may happen.Edit the /etc/rc.conf file.Set your hostname by editing the line that
says:hostname=myname.my.domainYou should give it your full Internet
hostname.Add sl0 to the list of network interfaces by
changing the line that says:network_interfaces="lo0"to:network_interfaces=lo0 sl0Set the startup flags of sl0 by adding a
line:ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up"default routerDesignate the default router by changing the
line:defaultrouter=NOto:defaultrouter=slip-gatewayMake a file /etc/resolv.conf which
contains:domain HIP.Berkeley.EDU
nameserver 128.32.136.9
nameserver 128.32.136.12name serverdomain nameAs you can see, these set up the nameserver hosts. Of
course, the actual domain names and addresses depend on your
environment.Set the password for root and
toor (and any other
accounts that do not have a password). Use passwd or
&man.vipw.8;, do not edit the
/etc/passwd or
/etc/master.passwd files!Reboot your machine and make sure it comes up with the
correct hostname.Making a SLIP connectionSLIPconnecting withDial up, type slip at the prompt,
enter your machine name and password. The things you need
to enter depends on your environment. If you use kermit, you
can try a script like this:# kermit setup
set modem hayes
set line /dev/modem
set speed 115200
set parity none
set flow rts/cts
set terminal bytesize 8
set file type binary
# The next macro will dial up and login
define slip dial 643-9600, input 10 =>, if failure stop, -
output slip\x0d, input 10 Username:, if failure stop, -
output silvia\x0d, input 10 Password:, if failure stop, -
output ***\x0d, echo \x0aCONNECTED\x0aOf course, you have to change the hostname and password
to fit yours. After doing so, you can just type
slip from the kermit prompt to get
connected.Leaving your password in plain text anywhere in the
filesystem is generally a BAD idea. Do it at your own
risk.Leave the kermit there (you can suspend it by
z) and as root, type:&prompt.root; slattach -h -c -s 115200 /dev/modemIf you are able to ping hosts on the
other side of the router, you are connected! If it does not
work, you might want to try instead of
as an argument to
slattach.How to shutdown the connectionDo the following:&prompt.root; kill -INT `cat /var/run/slattach.modem.pid`to kill slattach. Keep in mind you must be
root to do the above. Then go back to
kermit (fg if you suspended it) and exit from
it (q).The slattach man page says you have
to use ifconfig sl0 down
to mark the interface down, but this does not
seem to make any difference for me.
(ifconfig sl0 reports the same thing.)Some times, your modem might refuse to drop the carrier
(mine often does). In that case, simply start kermit and quit
it again. It usually goes out on the second try.TroubleshootingIf it does not work, feel free to ask me. The things that
people tripped over so far:Not using or in
slattach (I have no idea why this
can be fatal, but adding
this flag solved the problem for at least one
person).Using instead of
(might be hard to see the difference on
some fonts).Try ifconfig sl0 to see your
interface status. For example, you might get:&prompt.root; ifconfig sl0
sl0: flags=10<POINTOPOINT>
inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00Also, netstat -r will give the
routing table, in case you get the no route to
host messages from ping. Mine looks like:&prompt.root; netstat -r
Routing tables
Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks:
(root node)
(root node)
Route Tree for Protocol Family inet:
(root node) =>
default inr-3.Berkeley.EDU UG 8 224515 sl0 - -
localhost.Berkel localhost.Berkeley UH 5 42127 lo0 - 0.438
inr-3.Berkeley.E silvia.HIP.Berkele UH 1 0 sl0 - -
silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438
(root node)This is after transferring a bunch of files, your
numbers should be smaller).Setting up a SLIP ServerSLIPserverThis document provides suggestions for setting up SLIP Server
services on a FreeBSD system, which typically means configuring
your system to automatically startup connections upon login for
remote SLIP clients. The author has written this document based
on his experience; however, as your system and needs may be
different, this document may not answer all of your questions, and
the author cannot be responsible if you damage your system or lose
data due to attempting to follow the suggestions here.PrerequisitesTCP/IPThis document is very technical in nature, so background
knowledge is required. It is assumed that you are familiar with
the TCP/IP network protocol, and in particular, network and node
addressing, network address masks, subnetting, routing, and
routing protocols, such as RIP. Configuring SLIP services on a
dial-up server requires a knowledge of these concepts, and if
you are not familiar with them, please read a copy of either
Craig Hunt's TCP/IP Network Administration
published by O'Reilly & Associates, Inc. (ISBN Number
0-937175-82-X), or Douglas Comer's books on the TCP/IP
protocol.modemIt is further assumed that you have already setup your
modem(s) and configured the appropriate system files to allow
logins through your modems. If you have not prepared your
system for this yet, please see the tutorial for configuring
dialup services; if you have a World-Wide Web browser available,
browse the list of tutorials at http://www.FreeBSD.org/.
You may also want to check the manual pages for &man.sio.4; for
information on the serial port device driver and &man.ttys.5;,
&man.gettytab.5;, &man.getty.8;, & &man.init.8; for
information relevant to configuring the system to accept logins
on modems, and perhaps &man.stty.1; for information on setting
serial port parameters (such as clocal for
directly-connected serial interfaces).Quick OverviewIn its typical configuration, using FreeBSD as a SLIP server
works as follows: a SLIP user dials up your FreeBSD SLIP Server
system and logs in with a special SLIP login ID that uses
/usr/sbin/sliplogin as the special user's
shell. The sliplogin program browses the
file /etc/sliphome/slip.hosts to find a
matching line for the special user, and if it finds a match,
connects the serial line to an available SLIP interface and then
runs the shell script
/etc/sliphome/slip.login to configure the
SLIP interface.An Example of a SLIP Server LoginFor example, if a SLIP user ID were
Shelmerg, Shelmerg's
entry in /etc/master.passwd would look
something like this (except it would be all on one
line):Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliploginWhen Shelmerg logs in,
sliplogin will search
/etc/sliphome/slip.hosts for a line that
had a matching user ID; for example, there may be a line in
/etc/sliphome/slip.hosts that
reads:Shelmerg dc-slip sl-helmer 0xfffffc00 autocompsliplogin will find that matching line,
hook the serial line into the next available SLIP interface,
and then execute /etc/sliphome/slip.login
like this:/etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocompIf all goes well,
/etc/sliphome/slip.login will issue an
ifconfig for the SLIP interface to which
sliplogin attached itself (slip interface
0,in the above example, which was the first parameter in the
list given to slip.login) to set the
local IP address (dc-slip), remote IP address
(sl-helmer), network mask for the SLIP
interface (0xfffffc00), and
any additional flags (autocomp). If
something goes wrong, sliplogin usually
logs good informational messages via the
daemon syslog facility, which usually goes
into /var/log/messages (see the manual
pages for &man.syslogd.8; and &man.syslog.conf.5; and perhaps
check /etc/syslog.conf to see to which
files syslogd is logging).OK, enough of the examples — let us dive into
setting up the system.Kernel ConfigurationkernelconfigurationFreeBSD's default kernels usually come with two SLIP
interfaces defined (sl0 and
sl1); you can use netstat
-i to see whether these interfaces are defined in your
kernel.Sample output from netstat -i:Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll
ed0 1500 <Link>0.0.c0.2c.5f.4a 291311 0 174209 0 133
ed0 1500 138.247.224 ivory 291311 0 174209 0 133
lo0 65535 <Link> 79 0 79 0 0
lo0 65535 loop localhost 79 0 79 0 0
sl0* 296 <Link> 0 0 0 0 0
sl1* 296 <Link> 0 0 0 0 0The sl0 and
sl1 interfaces shown in
netstat -i's output indicate that there are
two SLIP interfaces built into the kernel. (The asterisks after
the sl0 and sl1 indicate
that the interfaces are down.)However, FreeBSD's default kernels do not come configured
to forward packets (ie, your FreeBSD machine will not act as a
router) due to Internet RFC requirements for Internet hosts (see
RFCs 1009 [Requirements for Internet Gateways], 1122
[Requirements for Internet Hosts — Communication Layers],
and perhaps 1127 [A Perspective on the Host Requirements RFCs]),
so if you want your FreeBSD SLIP Server to act as a router, you
will have to edit the /etc/rc.conf file and
change the setting of the gateway_enable variable to
.You will then need to reboot for the new settings to take
effect.You will notice that near the end of the default kernel
configuration file (/sys/i386/conf/GENERIC)
is a line that reads:pseudo-device sl 2SLIPThis is the line that defines the number of SLIP devices
available in the kernel; the number at the end of the line is
the maximum number of SLIP connections that may be operating
simultaneously.Please refer to Configuring the
FreeBSD Kernel for help in reconfiguring your
kernel.Sliplogin ConfigurationAs mentioned earlier, there are three files in the
/etc/sliphome directory that are part of
the configuration for /usr/sbin/sliplogin
(see &man.sliplogin.8; for the actual manual page for
sliplogin): slip.hosts,
which defines the SLIP users & their associated IP
addresses; slip.login, which usually just
configures the SLIP interface; and (optionally)
slip.logout, which undoes
slip.login's effects when the serial
connection is terminated.slip.hosts Configuration/etc/sliphome/slip.hosts contains
lines which have at least four items, separated by
whitespace:SLIP user's login IDLocal address (local to the SLIP server) of the SLIP
linkRemote address of the SLIP linkNetwork maskThe local and remote addresses may be host names (resolved
to IP addresses by /etc/hosts or by the
domain name service, depending on your specifications in
/etc/host.conf), and the
network mask may be a name that can be resolved by a lookup
into /etc/networks. On a sample system,
/etc/sliphome/slip.hosts looks like
this:#
# login local-addr remote-addr mask opt1 opt2
# (normal,compress,noicmp)
#
Shelmerg dc-slip sl-helmerg 0xfffffc00 autocompAt the end of the line is one or more of the
options. — no header
compression — compress
headers — compress headers if
the remote end allows it — disable ICMP packets
(so any ping packets will be dropped instead
of using up your bandwidth)Note that sliplogin under early releases
of FreeBSD 2 ignored the options that FreeBSD 1.x recognized,
so the options ,
, , and
had no effect until support was added
in FreeBSD 2.2 (unless your slip.login
script included code to make use of the flags).SLIPTCP/IPYour choice of local and remote addresses for your SLIP
links depends on whether you are going to dedicate a TCP/IP
subnet or if you are going to use proxy ARP on
your SLIP server (it is not true proxy ARP, but
that is the terminology used in this document to describe it).
If you are not sure which method to select or how to assign IP
addresses, please refer to the TCP/IP books referenced in the
slips-prereqs section
and/or consult your IP network manager.gatedIf you are going to use a separate subnet for your SLIP
clients, you will need to allocate the subnet number out of
your assigned IP network number and assign each of your SLIP
client's IP numbers out of that subnet. Then, you will
probably either need to configure a static route to the SLIP
subnet via your SLIP server on your nearest IP router, or
install gated on your FreeBSD SLIP server
and configure it to talk the appropriate routing protocols to
your other routers to inform them about your SLIP server's
route to the SLIP subnet.EthernetOtherwise, if you will use the proxy ARP
method, you will need to assign your SLIP client's IP
addresses out of your SLIP server's Ethernet subnet, and you
will also need to adjust your
/etc/sliphome/slip.login and
/etc/sliphome/slip.logout scripts to use
&man.arp.8; to manage the proxy-ARP entries in the SLIP
server's ARP table.slip.login ConfigurationThe typical /etc/sliphome/slip.login
file looks like this:#!/bin/sh -
#
# @(#)slip.login 5.1 (Berkeley) 7/1/90
#
# generic login file for a slip line. sliplogin invokes this with
# the parameters:
# 1 2 3 4 5 6 7-n
# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 inet $4 $5 netmask $6This slip.login file merely
ifconfig's the appropriate SLIP interface
with the local and remote addresses and network mask of the
SLIP interface.If you have decided to use the proxy ARP
method (instead of using a separate subnet for your SLIP
clients), your /etc/sliphome/slip.login
file will need to look something like this:#!/bin/sh -
#
# @(#)slip.login 5.1 (Berkeley) 7/1/90
#
# generic login file for a slip line. sliplogin invokes this with
# the parameters:
# 1 2 3 4 5 6 7-n
# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 inet $4 $5 netmask $6
# Answer ARP requests for the SLIP client with our Ethernet addr
/usr/sbin/arp -s $5 00:11:22:33:44:55 pubThe additional line in this
slip.login, arp -s
$5 00:11:22:33:44:55 pub, creates an ARP entry
in the SLIP server's ARP table. This ARP entry causes the
SLIP server to respond with the SLIP server's Ethernet MAC
address whenever a another IP node on the Ethernet asks to
speak to the SLIP client's IP address.EthernetMAC addressWhen using the example above, be sure to replace the
Ethernet MAC address (00:11:22:33:44:55) with the MAC address of
your system's Ethernet card, or your proxy ARP
will definitely not work! You can discover your SLIP server's
Ethernet MAC address by looking at the results of running
netstat -i; the second line of the output
should look something like:ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116This indicates that this particular system's Ethernet MAC
address is 00:02:c1:28:5f:4a
— the periods in the Ethernet MAC address given by
netstat -i must be changed to colons and
leading zeros should be added to each single-digit hexadecimal
number to convert the address into the form that &man.arp.8;
desires; see the manual page on &man.arp.8; for complete
information on usage.When you create
/etc/sliphome/slip.login and
/etc/sliphome/slip.logout, the
execute bit (ie, chmod 755
/etc/sliphome/slip.login /etc/sliphome/slip.logout)
must be set, or sliplogin will be unable
to execute it.slip.logout Configuration/etc/sliphome/slip.logout is not
strictly needed (unless you are implementing proxy
ARP), but if you decide to create it, this is an
example of a basic
slip.logout script:#!/bin/sh -
#
# slip.logout
#
# logout file for a slip line. sliplogin invokes this with
# the parameters:
# 1 2 3 4 5 6 7-n
# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 downIf you are using proxy ARP, you will want to
have /etc/sliphome/slip.logout remove the
ARP entry for the SLIP client:#!/bin/sh -
#
# @(#)slip.logout
#
# logout file for a slip line. sliplogin invokes this with
# the parameters:
# 1 2 3 4 5 6 7-n
# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 down
# Quit answering ARP requests for the SLIP client
/usr/sbin/arp -d $5The arp -d $5 removes the ARP entry
that the proxy ARPslip.login added when the SLIP client
logged in.It bears repeating: make sure
/etc/sliphome/slip.logout has the execute
bit set for after you create it (ie, chmod 755
/etc/sliphome/slip.logout).Routing ConsiderationsSLIProutingIf you are not using the proxy ARP method for
routing packets between your SLIP clients and the rest of your
network (and perhaps the Internet), you will probably either
have to add static routes to your closest default router(s) to
route your SLIP client subnet via your SLIP server, or you will
probably need to install and configure gated
on your FreeBSD SLIP server so that it will tell your routers
via appropriate routing protocols about your SLIP subnet.Static Routesstatic routesAdding static routes to your nearest default routers can
be troublesome (or impossible, if you do not have authority to
do so...). If you have a multiple-router network in your
organization, some routers, such as Cisco and Proteon, may
not only need to be configured with the static route to the
SLIP subnet, but also need to be told which static routes to
tell other routers about, so some expertise and
troubleshooting/tweaking may be necessary to get
static-route-based routing to work.Running gatedgatedAn alternative to the headaches of static routes is to
install gated on your FreeBSD SLIP server
and configure it to use the appropriate routing protocols
(RIP/OSPF/BGP/EGP) to tell other routers about your SLIP
subnet. You can use gated from the ports collection or retrieve and build
it yourself from the
GateD anonymous FTP site; the current version
as of this writing is
gated-R3_5Alpha_8.tar.Z, which includes
support for FreeBSD out-of-the-box. Complete
information and documentation on gated is
available on the Web starting at the Merit GateD
Consortium. Compile and install it, and then write a
/etc/gated.conf file to configure your
gated; here is a sample, similar to what the author used on a
FreeBSD SLIP server:#
# gated configuration file for dc.dsu.edu; for gated version 3.5alpha5
# Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface
#
#
# tracing options
#
traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ;
rip yes {
interface sl noripout noripin ;
interface ed ripin ripout version 1 ;
traceoptions route ;
} ;
#
# Turn on a bunch of tracing info for the interface to the kernel:
kernel {
traceoptions remnants request routes info interface ;
} ;
#
# Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP
#
export proto rip interface ed {
proto direct {
xxx.xxx.yy mask 255.255.252.0 metric 1; # SLIP connections
} ;
} ;
#
# Accept routes from RIP via ed Ethernet interfaces
import proto rip interface ed {
all ;
} ;RIPThe above sample gated.conf file
broadcasts routing information regarding the SLIP subnet
xxx.xxx.yy via RIP onto the
Ethernet; if you are using a different Ethernet driver than
the ed driver, you will need to
change the references to the ed
interface appropriately. This sample file also sets up
tracing to /var/tmp/gated.output for
debugging gated's activity; you can
certainly turn off the tracing options if
gated works OK for you. You will need to
change the xxx.xxx.yy's into the
network address of your own SLIP subnet (be sure to change the
net mask in the proto direct clause as
well).When you get gated built and installed
and create a configuration file for it, you will need to run
gated in place of routed
on your FreeBSD system; change the
routed/gated startup parameters in
/etc/netstart as appropriate for your
system. Please see the manual page for
gated for information on
gated's command-line parameters.
diff --git a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
index 84cb0f31e6..1c5828206a 100644
--- a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
@@ -1,4683 +1,4689 @@
PrintingContributed by &a.kelly;, 30 September 1995.
Restructured and updated by &a.jim;, March 2000.SynopsisLPD spooling systemprintingIn order to use printers with FreeBSD, you will need to set them
up to work with the Berkeley line printer spooling system, also
known as the LPD spooling system. It is the standard printer
control system in FreeBSD. This chapter introduces the LPD spooling
system, often simply called LPD, and will guide you through its
configuration.If you are already familiar with LPD or another printer spooling
system, you may wish to skip to section Setting up the spooling
system.IntroductionLPD controls everything about a host's printers. It is
responsible for a number of things:It controls access to attached printers and printers
attached to other hosts on the network.print jobsIt enables users to submit files to be printed; these
submissions are known as jobs.It prevents multiple users from accessing a printer at the
same time by maintaining a queue for each
printer.It can print header pages (also known
as banner or burst
pages) so users can easily find jobs they have printed in a
stack of printouts.It takes care of communications parameters for printers
connected on serial ports.It can send jobs over the network to a 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
(/etc/printcap), 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 SpoolerIf you are the sole user of your system, you may be wondering
why you should bother with the spooler when you do not need access
control, header pages, or printer accounting. While it is
possible to enable direct access to a printer, you should use the
spooler anyway since:LPD prints jobs in the background; you do not have to wait
for data to be copied to the printer.TeXLPD can conveniently run a job to be printed through
filters to add date/time headers or convert a special file
format (such as a TeX DVI file) into a format the printer will
understand. You will not have to do these steps
manually.Many free and commercial programs that provide a print
feature usually expect to talk to the spooler on your system.
By setting up the spooling system, you will more easily
support other software you may later add or already
have.Basic SetupTo use printers with the LPD spooling system, you will need to
set up both your printer hardware and the LPD software. This
document describes two levels of setup:See section Simple Printer
Setup to learn how to connect a printer, tell LPD how to
communicate with it, and print plain text files to the
printer.See section Advanced
Printer Setup 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 SetupThis section tells how to configure printer hardware and the
LPD software to use the printer. It teaches the basics:Section Hardware
Setup gives some hints on connecting the printer to a
port on your computer.Section Software
Setup shows how to setup the LPD spooler configuration
file (/etc/printcap).If you are setting up a printer that uses a network protocol
to accept data to print instead of a serial or parallel interface,
see Printers With
Networked Data Stream Interfaces.Although this section is called Simple Printer
Setup, it is actually fairly complex. Getting the printer
to work with your computer and the LPD spooler is the hardest
part. The advanced options like header pages and accounting are
fairly easy once you get the printer working.Hardware SetupThis 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 have already connected your printer and have
successfully printed with it under another operating system, you
can probably skip to section Software Setup.Ports and CablesNearly all printers you can get for a PC today support one
or both of the following interfaces:printerserialSerial interfaces use a serial
port on your computer to send data to the printer. Serial
interfaces are common in the computer industry and cables
are readily available and also easy to construct. Serial
interfaces sometimes need special cables and might require
you to configure somewhat complex communications
options.printerparallelParallel interfaces use a
parallel port on your computer to send data to the
printer. Parallel interfaces are common in the PC market.
Cables are readily available but more difficult to
construct by hand. There are usually no communications
options with parallel interfaces, making their
configuration exceedingly simple.
- centronics (see parallel printers)
+
+ centronics
+ parallel printers
+ 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 and printers
can communicate in both directions under FreeBSD when a
IEEE1284 compliant cable is used.PostScriptUsually, 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 need not 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 has 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.Parallel PortsTo 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 PortsTo 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 are unsure what the proper serial
cable is, you may wish to try one of the following
alternatives:A modem cable connects each pin
of the connector on one end of the cable straight through
to its corresponding pin of the connector on the other
end. This type of cable is also known as a
DTE-to-DCE cable.null-modem cableA null-modem cable connects some
pins straight through, swaps others (send data to receive
data, for example), and shorts some internally in each
connector hood. This type of cable is also known as a
DTE-to-DTE cable.A serial printer cable, required
for some unusual printers, is like the null-modem cable,
but sends some signals to their counterparts instead of
being internally shorted.baud rateparityflow control protocolYou 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
baud rate) rate that both your computer
and the printer can support. Choose 7 or 8 data bits; none,
even, or odd parity; and 1 or 2 stop bits. Also choose a flow
control protocol: either none, or XON/XOFF (also known as
in-band or software) flow control.
Remember these settings for the software configuration that
follows.Software SetupThis section describes the software setup necessary to print
with the LPD spooling system in FreeBSD.Here is an outline of the steps involved:Configure your kernel, if necessary, for the port you
are using for the printer; section Kernel Configuration tells
you what you need to do.Set the communications mode for the parallel port, if
you are using a parallel port; section Setting the
Communication Mode for the Parallel Port gives
details.Test if the operating system can send data to the printer.
Section Checking Printer
Communications gives some suggestions on how to do
this.Set up LPD for the printer by modifying the file
/etc/printcap. You will find out how
to do this later in this chapter.Kernel ConfigurationThe 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 is not already configured for one.To find out if the kernel you are currently using supports
a serial interface, type:&prompt.root; dmesg | grep sioNWhere N is the number of the
serial port, starting from zero. If you see output similar to
the following:sio2 at 0x3e8-0x3ef irq 5 on isa
sio2: type 16550Athen the kernel supports the port.To find out if the kernel supports a parallel interface,
type:&prompt.root; dmesg | grep lptNWhere N is the number of the
parallel port, starting from zero. If you see output similar
to the following 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 are 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 and the section that
follows.Adding /dev Entries for the
PortsEven though the kernel may support communication along a
serial or parallel port, you will still need a software
interface through which programs running on the system can
send and receive data. That is what entries in the
/dev directory are for.To add a /dev entry for a
port:Become root with the &man.su.1; command. Enter the
root password when prompted.Change to the /dev
directory:&prompt.root; cd /devType:&prompt.root; ./MAKEDEV portWhere port is the device
entry for the port you want to make. Use
lpt0 for the first parallel port,
lpt1 for the second, and so on; use
ttyd0 for the first serial port,
ttyd1 for the second, and so on.Type:&prompt.root; ls -l portto make sure the device entry got created.Setting the Communication Mode for the Parallel
PortWhen you are using the parallel interface, you can choose
whether FreeBSD should use interrupt-driven or polled
communication with the printer.The interrupt-driven method is
the default with the GENERIC kernel. With this method,
the operating system uses an IRQ line to determine when
the printer is ready for data.The polled method directs the
operating system to repeatedly ask the printer if it is
ready for more data. When it responds ready, the kernel
sends more data.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 &man.lptcontrol.8;
program.To set the communications mode by configuring
the kernel:Edit your kernel configuration file. Look for or add
an lpt0 entry. If you are setting up
the second parallel port, use lpt1
instead. Use lpt2 for the third port,
and so on.If you want interrupt-driven mode, add the
irq specifier:device lpt0 at isa? port? tty irq N vector lptintrWhere N is the IRQ
number for your computer's parallel port.If you want polled mode, do not add the
irq specifier:device lpt0 at isa? port? tty vector lptintrSave the file. Then configure, build, and install the
kernel, then reboot. See kernel configuration for
more details.To set the communications mode with
&man.lptcontrol.8;:Type:&prompt.root; lptcontrol -i -u Nto set interrupt-driven mode for
lptN.Type:&prompt.root; lptcontrol -p -u Nto set polled-mode for
lptN.You could put these commands in your
/etc/rc.local file to set the mode each
time your system boots. See &man.lptcontrol.8; for more
information.Checking Printer CommunicationsBefore proceeding to configure the spooling system, you
should make sure the operating system can successfully send
data to your printer. It is a lot easier to debug printer
communication and the spooling system separately.To test the printer, we will send some text to it. For
printers that can immediately print characters sent to them,
the program &man.lptest.1; is perfect: it generates all 96
printable ASCII characters in 96 lines.PostScriptFor a PostScript (or other language-based) printer, we
will need a more sophisticated test. A small PostScript
program, such as the following, will suffice:%!PS
100 100 moveto 300 300 lineto stroke
310 310 moveto /Helvetica findfont 12 scalefont setfont
(Is this thing working?) show
showpageThe above PostScript code can be placed into a file and
used as shown in the examples appearing in the following
sections.PCLWhen this document refers to a printer language, it is
assuming a language like PostScript, and not Hewlett
Packard's PCL. Although PCL has great functionality, you
can intermingle plain text with its escape sequences.
PostScript cannot directly print plain text, and that is the
kind of printer language for which we must make special
accommodations.Checking a Parallel PrinterprinterparallelThis 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 &man.su.1;.Send data to the printer.If the printer can print plain text, then use
&man.lptest.1;. Type:&prompt.root; lptest > /dev/lptNWhere N is the number
of the parallel port, starting from zero.If the printer understands PostScript or other
printer language, then send a small program to the
printer. Type:&prompt.root; cat > /dev/lptNThen, line by line, type the program
carefully as you cannot edit a
line once you have pressed RETURN
or ENTER. When you have finished
entering the program, press
CONTROL+D, or whatever your end
of file key is.Alternatively, you can put the program in a file
and type:&prompt.root; cat file > /dev/lptNWhere file is the
name of the file containing the program you want to
send to the printer.You should see something print. Do not worry if the
text does not look right; we will fix such things
later.Checking a Serial PrinterprinterserialThis 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 &man.su.1;.Edit the file /etc/remote. Add
the following entry:printer:dv=/dev/port:br#bps-rate:pa=paritybits-per-secondserial portparityWhere port is the device
entry for the serial port (ttyd0,
ttyd1, etc.),
bps-rate is the
bits-per-second rate at which the printer communicates,
and parity is the parity
required by the printer (either even,
odd, none, or
zero).Here is 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=noneConnect to the printer with &man.tip.1;.
Type:&prompt.root; tip printerIf this step does not work, edit the file
/etc/remote again and try using
/dev/cuaaN
instead of
/dev/ttydN.Send data to the printer.If the printer can print plain text, then use
&man.lptest.1;. Type:~$lptestIf the printer understands PostScript or other
printer language, then send a small program to the
printer. Type the program, line by line,
very carefully as backspacing
or other editing keys may be significant to the
printer. You may also need to type a special
end-of-file key for the printer so it knows it
received the whole program. For PostScript
printers, press CONTROL+D.Alternatively, you can put the program in a file
and type:~>fileWhere file is the
name of the file containing the program. After
&man.tip.1; sends the file, press any required
end-of-file key.You should see something print. Do not worry if the
text does not look right; we will fix that later.Enabling the Spooler: The /etc/printcap
FileAt this point, your printer should be hooked up, your kernel
configured to communicate with it (if necessary), and you have
been able to send some simple data to the printer. Now, we are
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.printercapabilitiesThe format of the &man.printcap.5; file is straightforward.
Use your favorite text editor to make changes to
/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 &man.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 the
Naming the Printer
section for more information on naming.header pagesTurn off header pages (which are on by default) by
inserting the sh capability; see the
Suppressing Header
Pages section for more information.Make a spooling directory, and specify its location with
the sd capability; see the Making the Spooling
Directory section for more information.Set the /dev entry to use for the
printer, and note it in /etc/printcap
with the lp capability; see the Identifying the Printer
Device for more information. Also, if the printer is
on a serial port, set up the communication parameters with
the fs, fc,
xs, and xc
capabilities; which is discussed in the Configuring Spooler
Communications Parameters section.Install a plain text input filter; see the Installing the Text
Filter section for details.Test the setup by printing something with the
&man.lpr.1; command. More details are available in the
Trying It Out and
Troubleshooting
sections.Language-based printers, such as PostScript printers,
cannot directly print plain text. The simple setup outlined
above and described in the following sections assumes that if
you are installing such a printer you will print only files
that the printer can understand.Users often expect that they can print plain text to any of
the printers installed on your system. Programs that interface
to LPD to do their printing usually make the same assumption.
If you are installing such a printer and want to be able to
print jobs in the printer language and
print plain text jobs, you are strongly urged to add an
additional step to the simple setup outlined above: install an
automatic plain-text-to-PostScript (or other printer language)
conversion program. The section entitled Accommodating Plain
Text Jobs on PostScript Printers tells how to do
this.Naming the PrinterThe first (easy) step is to pick a name for your printer
It really does not matter whether you choose functional or
whimsical names since you can also provide a number of aliases
for the printer.At least one of the printers specified in the
/etc/printcap should have the alias
lp. This is the default printer's name.
If users do not have the PRINTER environment
variable nor specify a printer name on the command line of any
of the LPD commands, then lp will be the
default printer they get to use.Also, it is common practice to make the last alias for a
printer be a full description of the printer, including make
and model.Once you have picked a name and some common aliases, put
them in the /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
rattan and has as aliases
line, diablo,
lp, and Diablo 630 Line
Printer. Since it has the alias
lp, it is also the default printer. The
second is named bamboo, and has as aliases
ps, PS,
S, panasonic, and
Panasonic KX-P4455 PostScript v51.4.Suppressing Header Pagesprintingheader pagesThe LPD spooling system will by default print a
header page for each job. The header
page contains the user name who requested the job, the host
from which the job came, and the name of the job, in nice
large letters. Unfortunately, all this extra text gets in the
way of debugging the simple printer setup, so we will suppress
header pages.To suppress header pages, add the sh
capability to the entry for the printer in
/etc/printcap. Here is an example
/etc/printcap with sh
added:#
# /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 Directoryprinter spoolprint jobsThe next step in the simple spooler setup is to make a
spooling directory, a directory where
print jobs reside until they are printed, and where a number
of other spooler support files live.Because of the variable nature of spooling directories, it
is customary to put these directories under
/var/spool. It is not necessary to
backup the contents of spooling directories, either.
Recreating them is as simple as running &man.mkdir.1;.It is also customary to make the directory with a name
that is identical to the name of the printer, as shown
below:&prompt.root; mkdir /var/spool/printer-nameHowever, 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
will do this for our two example printers
rattan and
bamboo:&prompt.root; mkdir /var/spool/lpd
&prompt.root; mkdir /var/spool/lpd/rattan
&prompt.root; mkdir /var/spool/lpd/bambooIf you are concerned about the privacy of jobs that
users print, you might want to protect the spooling
directory so it is not publicly accessible. Spooling
directories should be owned and be readable, writable, and
searchable by user daemon and group daemon, and no one else.
We will do this for our example printers:&prompt.root; chown daemon:daemon /var/spool/lpd/rattan
&prompt.root; chown daemon:daemon /var/spool/lpd/bamboo
&prompt.root; chmod 770 /var/spool/lpd/rattan
&prompt.root; chmod 770 /var/spool/lpd/bambooFinally, you need to tell LPD about these directories
using the /etc/printcap file. You
specify the pathname of the spooling directory with the
sd capability:#
# /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 do not specify a spooling directory with
sd, the spooling system will use
/var/spool/lpd as a default.Identifying the Printer DeviceIn the Adding
/dev Entries for the Ports
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
lp capability.In our running example, let us assume that
rattan is on the first parallel port, and
bamboo is on a sixth serial port; here are
the additions to /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 do not specify the lp capability
for a printer in your /etc/printcap file,
LPD uses /dev/lp as a default.
/dev/lp currently does not exist in
FreeBSD.If the printer you are installing is connected to a
parallel port, skip to the section entitled, Installing the Text
Filter. Otherwise, be sure to follow the instructions
in the next section.Configuring Spooler Communication ParametersprinterserialFor 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 do not 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 lp capability:br#bps-rateSets the communications speed of the device to
bps-rate, where
bps-rate can be 50, 75, 110,
134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600,
19200, or 38400 bits-per-second.fc#clear-bitsClears the flag bits
clear-bits in the
sgttyb structure after
opening the device.fs#set-bitsSets the flag bits
set-bits in the
sgttyb structure.xc#clear-bitsClears local mode bits
clear-bits after opening the
device.xs#set-bitsSets local mode bits
set-bits.For more information on the bits for the
fc, fs,
xc, and xs capabilities,
see the file
/usr/include/sys/ioctl_compat.h.When LPD opens the device specified by the
lp capability, it reads the flag bits in
the sgttyb structure; it clears any bits in
the fc capability, then sets bits in the
fs capability, then applies the resultant
setting. It does the same for the local mode bits as
well.Let us add to our example printer on the sixth serial
port. We will set the bps rate to 38400. For the flag bits,
we will set the TANDEM,
ANYP, LITOUT,
FLUSHO, and PASS8 flags.
For the local mode bits, we will set the
LITOUT and PASS8
flags: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 Filterprint filtersWe are now ready to tell LPD what text filter to use to
send jobs to the printer. A text filter,
also known as an input filter, is a
program that LPD runs when it has a job to print. When LPD
runs the text filter for a printer, it sets the filter's
standard input to the job to print, and its standard output to
the printer device specified with the lp
capability. The filter is expected to read the job from
standard input, perform any necessary translation for the
printer, and write the results to standard output, which will
get printed. For more information on the text filter, see
the Filters
section.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
lpf that handles backspacing and
underlining for printers that might not deal with such
character streams well. And, of course, you can use any other
filter program you want. The filter lpf is
described in detail in section entitled lpf: a Text
Filter.First, let us 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 && exit 0
exit 2Make the file executable:&prompt.root; chmod 555 /usr/local/libexec/if-simpleAnd then tell LPD to use it by specifying it with the
if capability in
/etc/printcap. We will 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:Turn on LPD&man.lpd.8; is run from /etc/rc,
controlled by the lpd_enable variable. This
variable defaults to NO. If you have not done
so already, add the line:lpd_enable="YES"to /etc/rc.conf, and then either restart
your machine, or just run &man.lpd.8;.&prompt.root; lpdTrying It OutYou have reached the end of the simple LPD setup.
Unfortunately, congratulations are not quite yet in order,
since we still have 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 &man.lpr.1;,
which submits a job for printing.You can combine &man.lpr.1; with the &man.lptest.1;
program, introduced in section Checking Printer
Communications to generate some test text.To test the simple LPD setup:Type:&prompt.root; lptest 20 5 | lpr -Pprinter-nameWhere printer-name is a the
name of a printer (or an alias) specified in
/etc/printcap. To test the default
printer, type &man.lpr.1; without any
argument. Again, if you are testing a printer that expects
PostScript, send a PostScript program in that language instead
of using &man.lptest.1;. You can do so by putting the program
in a file and typing lpr
file.For a PostScript printer, you should get the results of
the program. If you are using &man.lptest.1;, then your
results should look like the following:!"#$%&'()*+,-./01234
"#$%&'()*+,-./012345
#$%&'()*+,-./0123456
$%&'()*+,-./01234567
%&'()*+,-./012345678To further test the printer, try downloading larger
programs (for language-based printers) or running
&man.lptest.1; with different arguments. For example,
lptest 80 60 will produce 60 lines of 80
characters each.If the printer did not work, see the Troubleshooting
section.Advanced Printer SetupThis section describes filters for printing specially formatted
files, header pages, printing across networks, and restricting and
accounting for printer usage.Filtersprint filtersAlthough LPD handles network protocols, queuing, access control,
and other aspects of printing, most of the real
work happens in the filters. Filters are
programs that communicate with the printer and handle its device
dependencies and special requirements. In the simple printer setup,
we installed a plain text filter—an extremely simple one that
should work with most printers (section Installing the Text
Filter).However, in order to take advantage of format conversion, printer
accounting, specific printer quirks, and so on, you should understand
how filters work. It will ultimately be the filter's responsibility
to handle these aspects. And the bad news is that most of the time
you have to provide filters yourself. The good
news is that many are generally available; when they are not, they are
usually easy to write.Also, FreeBSD comes with one,
/usr/libexec/lpr/lpf, that works with many
printers that can print plain text. (It handles backspacing and tabs
in the file, and does accounting, but that is about all it does.)
There are also several filters and filter components in the FreeBSD
ports collection.Here is what you will find in this section:Section How Filters
Work, tries to give an overview of a filter's role in the
printing process. You should read this section to get an
understanding of what is happening under the hood
when LPD uses filters. This knowledge could help you anticipate
and debug problems you might encounter as you install more and
more filters on each of your printers.LPD expects every printer to be able to print plain text by
default. This presents a problem for PostScript (or other
language-based printers) which cannot directly print plain text.
Section Accommodating
Plain Text Jobs on PostScript Printers tells you what you
should do to overcome this problem. You should read this
section if you have a PostScript printer.PostScript is a popular output format for many programs. Even
some people (myself included) write PostScript code directly. But
PostScript printers are expensive. Section Simulating PostScript on
Non-PostScript Printers tells how you can further modify
a printer's text filter to accept and print PostScript data on a
non-PostScript printer. You should read
this section if you do not have a PostScript printer.Section Conversion
Filters tells about a way you can automate the conversion
of specific file formats, such as graphic or typesetting data,
into formats your printer can understand. After reading this
section, you should be able to set up your printers such that
users can type lpr -t to print troff data, or
lpr -d to print TeX DVI data, or lpr
-v to print raster image data, and so forth. I
recommend reading this section.Section Output
Filters tells all about a not often used feature of LPD:
output filters. Unless you are printing header pages (see Header Pages),
you can probably skip that section altogether.Section lpf: a Text
Filter describes lpf, a fairly
complete if simple text filter for line printers (and laser
printers that act like line printers) that comes with FreeBSD. If
you need a quick way to get printer accounting working for plain
text, or if you have a printer which emits smoke when it sees
backspace characters, you should definitely consider
lpf.How Filters WorkAs 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 lf
capability in /etc/printcap, or
/dev/console by default).troffWhich filter LPD starts and the filter's arguments depend on
what is listed in the /etc/printcap file and
what arguments the user specified for the job on the
&man.lpr.1; command line. For example, if the user typed
lpr -t, LPD would start the troff filter, listed
in the tf capability for the destination printer.
If the user wanted to print plain text, it would start the
if filter (this is mostly true: see Output Filters for
details).There are three kinds of filters you can specify in
/etc/printcap:The text filter, confusingly called the
input filter in LPD documentation, handles
regular text printing. Think of it as the default filter. LPD
expects every printer to be able to print plain text by default,
and it is the text filter's job to make sure backspaces, tabs,
or other special characters do not confuse the printer. If you
are in an environment where you have to account for printer
usage, the text filter must also account for pages printed,
usually by counting the number of lines printed and comparing
that to the number of lines per page the printer supports. The
text filter is started with the following argument list:
filter-name-c-wwidth-llength-iindent-n login-h hostacct-file
where
appears if the job's submitted with lpr
-lwidthis the value from the pw (page
width) capability specified in
/etc/printcap, default 132lengthis the value from the pl (page
length) capability, default 66indentis the amount of the indentation from lpr
-i, default 0loginis the account name of the user printing the
filehostis the host name from which the job was
submittedacct-fileis the name of the accounting file from the
af capability.printerfiltersA conversion filter converts a specific
file format into one the printer can render onto paper. For
example, ditroff typesetting data cannot be directly printed,
but you can install a conversion filter for ditroff files to
convert the ditroff data into a form the printer can digest and
print. Section Conversion
Filters tells all about them. Conversion filters also
need to do accounting, if you need printer accounting.
Conversion filters are started with the following arguments:
filter-name-xpixel-width-ypixel-height-n login-h hostacct-file
where pixel-width is the value
from the px capability (default 0) and
pixel-height is the value from the
py capability (default 0).The output filter is used only if there
is no text filter, or if header pages are enabled. In my
experience, output filters are rarely used. Section Output Filters describe
them. There are only two arguments to an output filter:
filter-name-wwidth-llength
which are identical to the text filters and
arguments.Filters should also exit with the
following exit status:exit 0If the filter printed the file successfully.exit 1If the filter failed to print the file but wants LPD to
try to print the file again. LPD will restart a filter if it
exits with this status.exit 2If the filter failed to print the file and does not want
LPD to try again. LPD will throw out the file.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 are shopping for filters, see if they are 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 Printersprint jobsIf you are 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 do not
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 are 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
%! (for other printer languages, see your printer
documentation). If those are the first two characters in the job,
we have PostScript, and can pass the rest of the job directly. If
those are not the first two characters in the file, then the filter
will convert the text into PostScript and print the result.How do we do this?printerserialIf you have got a serial printer, a great way to do it is to
install lprps. lprps is a
PostScript printer filter which performs two-way communication with
the printer. It updates the printer's status file with verbose
information from the printer, so users and administrators can see
exactly what the state of the printer is (such as toner
low or paper jam). But more
importantly, it includes a program called psif
which detects whether the incoming job is plain text and calls
textps (another program that comes with
lprps) to convert it to PostScript. It then uses
lprps to send the job to the printer.lprps is part of the FreeBSD ports collection
(see The Ports Collection). You can
fetch, build and install it yourself, of course. After installing
lprps, just specify the pathname to the
psif program that is part of
lprps. If you installed lprps
from the ports collection, use the following in the serial
PostScript printer's entry in
/etc/printcap::if=/usr/local/libexec/psif:You should also specify the rw capability;
that tells LPD to open the printer in read-write mode.If you have a parallel PostScript printer (and therefore cannot
use two-way communication with the printer, which
lprps needs), you can use the following shell
script as the text filter:#!/bin/sh
#
# psif - Print PostScript or plain text on a PostScript printer
# Script version; NOT the version that comes with lprps
# Installed in /usr/local/libexec/psif
#
read first_line
first_two_chars=`expr "$first_line" : '\(..\)'`
if [ "$first_two_chars" = "%!" ]; then
#
# PostScript job, print it.
#
echo "$first_line" && cat && printf "\004" && exit 0
exit 2
else
#
# Plain text, convert it, then print it.
#
( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0
exit 2
fiIn the above script, textps is a program we
installed separately to convert plain text to PostScript. You can
use any text-to-PostScript program you wish. The FreeBSD ports
collection (see The Ports Collection)
includes a full featured text-to-PostScript program called
a2ps that you might want to investigate.Simulating PostScript on Non-PostScript PrintersPostScriptemulatingGhostscriptPostScript is the de facto standard for
high quality typesetting and printing. PostScript is, however, an
expensive standard. Thankfully, Alladin
Enterprises has a free PostScript work-alike called
Ghostscript that runs with FreeBSD.
Ghostscript can read most PostScript files and can render their
pages onto a variety of devices, including many brands of
non-PostScript printers. By installing Ghostscript and using a
special text filter for your printer, you can make your
non-PostScript printer act like a real PostScript printer.Ghostscript is in the FreeBSD ports collection, if you
would like to install it from there. You can fetch, build, and
install it quite easily yourself, as well.To simulate PostScript, we have the text filter detect if it is
printing a PostScript file. If it is not, then the filter will pass
the file directly to the printer; otherwise, it will use Ghostscript
to first convert the file into a format the printer will
understand.Here is an example: the following script is a text filter
for Hewlett Packard DeskJet 500 printers. For other printers,
substitute the argument to the
gs (Ghostscript) command. (Type gs
-h to get a list of devices the current installation of
Ghostscript supports.)#!/bin/sh
#
# ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500
# Installed in /usr/local/libexec/hpif
#
# Treat LF as CR+LF:
#
printf "\033&k2G" || exit 2
#
# Read first two characters of the file
#
read first_line
first_two_chars=`expr "$first_line" : '\(..\)'`
if [ "$first_two_chars" = "%!" ]; then
#
# It is PostScript; use Ghostscript to scan-convert and print it.
#
# Note that PostScript files are actually interpreted programs,
# and those programs are allowed to write to stdout, which will
# mess up the printed output. So, we redirect stdout to stderr
# and then make descriptor 3 go to stdout, and have Ghostscript
# write its output there. Exercise for the clever reader:
# capture the stderr output from Ghostscript and mail it back to
# the user originating the print job.
#
exec 3>&1 1>&2
/usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \
-sOutputFile=/dev/fd/3 - && exit 0
#
/usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 -sOutputFile=- - \
&& exit 0
else
#
# Plain text or HP/PCL, so just print it directly; print a form
# at the end to eject the last page.
#
echo $first_line && cat && printf "\033&l0H" &&
exit 0
fi
exit 2Finally, you need to notify LPD of the filter via the
if capability::if=/usr/local/libexec/hpif:That is it. You can type lpr plain.text and
lpr whatever.ps and both should print
successfully.Conversion FiltersAfter completing the simple setup described in Simple Printer Setup, the first
thing you will probably want to do is install conversion filters for
your favorite file formats (besides plain ASCII text).Why Install Conversion Filters?TeXprinting dvi filesConversion 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 cannot print it directly until
we convert the DVI file into PostScript. The command sequence
goes like this:&prompt.user; dvips seaweed-analysis.dvi
&prompt.user; lpr seaweed-analysis.psBy 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 are just one step away from
printing it:&prompt.user; lpr -d seaweed-analysis.dviWe got LPD to do the DVI file conversion for us by specifying
the option. Section Formatting and Conversion
Options lists the conversion options.For each of the conversion options you want a printer to
support, install a conversion filter and
specify its pathname in /etc/printcap. A
conversion filter is like the text filter for the simple printer
setup (see section Installing
the Text Filter) 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 have 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 lpr command:File type/etc/printcap capabilitylpr optioncifplotcfDVIdfplotgfditroffnfFORTRAN textrftroffrfrastervfplain textifnone, , or
In our example, using lpr -d means the
printer needs a df capability in its entry in
/etc/printcap.fortranDespite 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 would 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
gf capability and then educate your users that
lpr -g mean print Printerleaf
files.Installing Conversion FiltersSince 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 are specialized programs that only LPD will run;
regular users should not 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 will add the DVI conversion filter to the
entry for the printer named bamboo. Here is
the example /etc/printcap file again, with
the new df capability for the printer
bamboo.#
# /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 is that
script:#!bin/sh
#
# psdf - DVI to PostScript printer filter
# Installed in /usr/local/libexec/psdf
#
# Invoked by lpd when user runs lpr -d
#
exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@"This script runs dvips in filter mode (the
argument) on standard input, which is the job
to print. It then starts the PostScript printer filter
lprps (see section Accommodating Plain
Text Jobs on PostScript Printers) with the arguments LPD
passed to this script. lprps will use those
arguments to account for the pages printed.More Conversion Filter ExamplesSince there is 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 2It 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 is 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
bamboo:#!/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 lprps again
to handle the communication with the printer. If the printer were
on a parallel port, we would use this script instead:#!/bin/sh
#
# pstf - Convert groff's troff data into PS, then print.
# Installed in /usr/local/libexec/pstf
#
exec gropsThat is it. Here is the entry we need to add to
/etc/printcap to enable the filter::tf=/usr/local/libexec/pstf:Here is an example that might make old hands at FORTRAN blush.
It is a FORTRAN-text filter for any printer that can directly
print plain text. We will install it for the printer
teak:#!/bin/sh
#
# hprf - FORTRAN text filter for LaserJet 3si:
# Installed in /usr/local/libexec/hprf
#
printf "\033&k2G" && fpr && printf "\033&l0H" &&
exit 0
exit 2And we will add this line to the
/etc/printcap for the printer
teak to enable this filter::rf=/usr/local/libexec/hprf:Here is one final, somewhat complex example. We will add a
DVI filter to the LaserJet printer teak
introduced earlier. First, the easy part: updating
/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 The Ports Collection)
has one: dvi2xx is the name of the package.
Installing this package gives us the program we need,
dvilj2p, which converts DVI into LaserJet IIp,
LaserJet III, and LaserJet 2000 compatible codes.dvilj2p makes the filter
hpdf quite complex since
dvilj2p cannot read from standard input. It
wants to work with a filename. What is worse, the filename has to
end in .dvi so using
/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 .dvi)
to /dev/fd/0, thereby forcing
dvilj2p to read from standard input.The only other fly in the ointment is the fact that we cannot
use /tmp for the temporary link. Symbolic
links are owned by user and group bin. The
filter runs as user daemon. And the
/tmp directory has the sticky bit set. The
filter can create the link, but it will not 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 sd capability in
/etc/printcap). This is a perfect place for
filters to do their work, especially since there is (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 do not try to reprint the
# job.
#
fatal() {
echo "$@" 1>&2
cleanup
exit 2
}
#
# If user removes the job, LPD will send SIGINT, so trap SIGINT
# (and a few other signals) to clean up after ourselves.
#
trap cleanup 1 2 15
#
# Make sure we are not colliding with any existing files.
#
cleanup
#
# Link the DVI input file to standard input (the file to print).
#
ln -s /dev/fd/0 hpdf$$.dvi || fatal "Cannot symlink /dev/fd/0"
#
# Make LF = CR+LF
#
printf "\033&k2G" || fatal "Cannot initialize printer"
#
# Convert and print. Return value from dvilj2p does not seem to be
# reliable, so we ignore it.
#
dvilj2p -M1 -q -e- dfhp$$.dvi
#
# Clean up and exit
#
cleanup
exit 0Automated Conversion: An Alternative To Conversion
FiltersAll these conversion filters accomplish a lot for your
printing environment, but at the cost forcing the user to specify
(on the &man.lpr.1; command line) which one to use.
If your users are not particularly computer literate, having to
specify a filter option will become annoying. What is worse,
though, is that an incorrectly specified filter option may run a
filter on the wrong type of file and cause your printer to spew
out hundreds of sheets of paper.Rather than install conversion filters at all, you might want
to try having the text filter (since it is the default filter)
detect the type of file it has been asked to print and then
automatically run the right conversion filter. Tools such as
file can be of help here. Of course, it will
be hard to determine the differences between
some file types—and, of course, you can
still provide conversion filters just for them.apsfilterprinterfiltersapsfilterThe FreeBSD ports collection has a text filter that performs
automatic conversion called apsfilter. It can
detect plain text, PostScript, and DVI files, run the proper
conversions, and print.Output FiltersThe LPD spooling system supports one other type of filter that
we have 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 are 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 does not make any provision to identify the start or the
end of files within the job for the output filter.LPD does not pass the user's login or host to the filter, so
it is not intended to do accounting. In fact, it gets only two
arguments:filter-name-wwidth-llengthWhere width is from the
pw capability and
length is from the
pl capability for the printer in
question.Do not be seduced by an output filter's simplicity. If you
would like each file in a job to start on a different page an output
filter will not work. Use a text filter (also
known as an input filter); see section Installing the Text Filter.
Furthermore, an output filter is actually more
complex in that it has to examine the byte stream being
sent to it for special flag characters and must send signals to
itself on behalf of LPD.However, an output filter is necessary if
you want header pages and need to send escape sequences or other
initialization strings to be able to print the header page. (But it
is also futile if you want to charge header
pages to the requesting user's account, since LPD does not give any
user or host information to the output filter.)On a single printer, LPD allows both an output filter and text
or other filters. In such cases, LPD will start the output filter
to print the header page (see section Header Pages)
only. LPD then expects the output filter to stop
itself by sending two bytes to the filter: ASCII 031
followed by ASCII 001. When an output filter sees these two bytes
(031, 001), it should stop by sending SIGSTOP to itself. When LPD's
done running other filters, it will restart the output filter by
sending SIGCONT to it.If there is an output filter but no text
filter and LPD is working on a plain text job, LPD uses the output
filter to do the job. As stated before, the output filter will
print each file of the job in sequence with no intervening form
feeds or other paper advancement, and this is probably
not what you want. In almost all cases, you
need a text filter.The program lpf, which we introduced earlier
as a text filter, can also run as an output filter. If you need a
quick-and-dirty output filter but do not want to write the byte
detection and signal sending code, try lpf. You
can also wrap lpf in a shell script to handle any
initialization codes the printer might require.lpf: a Text FilterThe program /usr/libexec/lpr/lpf that comes
with FreeBSD binary distribution is a text filter (input filter)
that can indent output (job submitted with lpr
-i), allow literal characters to pass (job submitted
with lpr -l), adjust the printing position for
backspaces and tabs in the job, and account for pages printed. It
can also act like an output filter.lpf is suitable for many printing
environments. And although it has no capability to send
initialization sequences to a printer, it is easy to write a shell
script to do the needed initialization and then execute
lpf.page accountingaccountingprinterIn order for lpf to do page accounting
correctly, it needs correct values filled in for the
pw and pl capabilities in the
/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 Accounting for Printer
Usage.Header PagesIf you have lots of users, all of them using
various printers, then you probably want to consider header
pages as a necessary evil.
- banner pages (see header pages)
+
+ banner pages
+ header pages
+ header pagesHeader pages, also known as banner or
burst pages identify to whom jobs belong after
they are printed. They are usually printed in large, bold letters,
perhaps with decorative borders, so that in a stack of printouts they
stand out from the real documents that comprise users' jobs. They
enable users to locate their jobs quickly. The obvious drawback to a
header page is that it is yet one more sheet that has to be printed
for every job, their ephemeral usefulness lasting not more than a few
minutes, ultimately finding themselves in a recycling bin or rubbish
heap. (Note that header pages go with each job, not each file in a
job, so the paper waste might not be that bad.)The LPD system can provide header pages automatically for your
printouts if your printer can directly print
plain text. If you have a PostScript printer, you will need an
external program to generate the header page; see Header Pages on
PostScript Printers.Enabling Header PagesIn the Simple Printer
Setup, we turned off header pages by specifying
sh (meaning suppress header) in the
/etc/printcap file. To enable header pages for
a printer, just remove the sh capability.Sounds too easy, right?You are right. You might have to provide
an output filter to send initialization strings to the printer.
Here is an example output filter for Hewlett Packard PCL-compatible
printers:#!/bin/sh
#
# hpof - Output filter for Hewlett Packard PCL-compatible printers
# Installed in /usr/local/libexec/hpof
printf "\033&k2G" || exit 2
exec /usr/libexec/lpr/lpfSpecify the path to the output filter in the
of capability. See Output Filters for more
information.Here is an example /etc/printcap file for
the printer teak that we introduced earlier; we
enabled header pages and added the above output filter:#
# /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 teak, they get
a header page with each job. If users want to spend time searching
for their printouts, they can suppress header pages by submitting
the job with lpr -h; see Header Page Options for
more &man.lpr.1; options.LPD prints a form feed character after the header page. If
your printer uses a different character or sequence of characters
to eject a page, specify them with the ff
capability in /etc/printcap.Controlling Header PagesBy enabling header pages, LPD will produce a long
header, a full page of large letters identifying the
user, host, and job. Here is an example (kelly printed the job
named outline from host rose): 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 1995LPD appends a form feed after this text so the job starts on a
new page (unless you have sf (suppress form
feeds) in the destination printer's entry in
/etc/printcap).If you prefer, LPD can make a short header;
specify sb (short banner) in the
/etc/printcap file. The header page will look
like this:rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995Also by default, LPD prints the header page first, then the job.
To reverse that, specify hl (header last) in
/etc/printcap.Accounting for Header PagesUsing LPD's built-in header pages enforces a particular paradigm
when it comes to printer accounting: header pages must be
free of charge.Why?Because the output filter is the only external program that will
have control when the header page is printed that could do
accounting, and it is not provided with any user or
host information or an accounting file, so it has no
idea whom to charge for printer use. It is also not enough to just
add one page to the text filter or any of the
conversion filters (which do have user and host information) since
users can suppress header pages with lpr -h.
They could still be charged for header pages they did not print.
Basically, lpr -h will be the preferred option of
environmentally-minded users, but you cannot offer any incentive to
use it.It is still not enough to have each of the
filters generate their own header pages (thereby being able to
charge for them). If users wanted the option of suppressing the
header pages with lpr -h, they will still get
them and be charged for them since LPD does not pass any knowledge
of the option to any of the filters.So, what are your options?You can:Accept LPD's paradigm and make header pages free.Install an alternative to LPD, such as LPRng. Section
Alternatives to the
Standard Spooler tells more about other spooling
software you can substitute for LPD.Write a smart output filter. Normally,
an output filter is not meant to do anything more than
initialize a printer or do some simple character conversion. It
is suited for header pages and plain text jobs (when there is no
text (input) filter). But, if there is a text filter for the
plain text jobs, then LPD will start the output filter only for
the header pages. And the output filter can parse the header
page text that LPD generates to determine what user and host to
charge for the header page. The only other problem with this
method is that the output filter still does not know what
accounting file to use (it is not passed the name of the file
from the af capability), but if you have a
well-known accounting file, you can hard-code that into the
output filter. To facilitate the parsing step, use the
sh (short header) capability in
/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 PrintersAs described above, LPD can generate a plain text header page
suitable for many printers. Of course, PostScript cannot 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 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 lpr
-h.Let us explore this method. The following script takes three
arguments (user login name, host name, and job name) and makes a
simple PostScript header page:#!/bin/sh
#
# make-ps-header - make a PostScript header page on stdout
# Installed in /usr/local/libexec/make-ps-header
#
#
# These are PostScript units (72 to the inch). Modify for A4 or
# whatever size paper you are using:
#
page_width=612
page_height=792
border=72
#
# Check arguments
#
if [ $# -ne 3 ]; then
echo "Usage: `basename $0` <user> <host> <job>" 1>&2
exit 1
fi
#
# Save these, mostly for readability in the PostScript, below.
#
user=$1
host=$2
job=$3
date=`date`
#
# Send the PostScript code to stdout.
#
exec cat <<EOF
%!PS
%
% Make sure we do not interfere with user's job that will follow
%
save
%
% Make a thick, unpleasant border around the edge of the paper.
%
$border $border moveto
$page_width $border 2 mul sub 0 rlineto
0 $page_height $border 2 mul sub rlineto
currentscreen 3 -1 roll pop 100 3 1 roll setscreen
$border 2 mul $page_width sub 0 rlineto closepath
0.8 setgray 10 setlinewidth stroke 0 setgray
%
% Display user's login name, nice and large and prominent
%
/Helvetica-Bold findfont 64 scalefont setfont
$page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto
($user) show
%
% Now show the boring particulars
%
/Helvetica findfont 14 scalefont setfont
/y 200 def
[ (Job:) (Host:) (Date:) ] {
200 y moveto show /y y 18 sub def }
forall
/Helvetica-Bold findfont 14 scalefont setfont
/y 200 def
[ ($job) ($host) ($date) ] {
270 y moveto show /y y 18 sub def
} forall
%
% That is it
%
restore
showpage
EOFNow, 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 is the DVI conversion filter from earlier in this
document, modified to make a header page:#!/bin/sh
#
# psdf - DVI to PostScript printer filter
# Installed in /usr/local/libexec/psdf
#
# Invoked by lpd when user runs lpr -d
#
orig_args="$@"
fail() {
echo "$@" 1>&2
exit 2
}
while getopts "x:y:n:h:" option; do
case $option in
x|y) ;; # Ignore
n) login=$OPTARG ;;
h) host=$OPTARG ;;
*) echo "LPD started `basename $0` wrong." 1>&2
exit 2
;;
esac
done
[ "$login" ] || fail "No login name"
[ "$host" ] || fail "No host name"
( /usr/local/libexec/make-ps-header $login $host "DVI File"
/usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_argsNotice 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 How Filters
Work).As we have mentioned before, the above scheme, though fairly
simple, disables the suppress header page option (the
option) to lpr. If users
wanted to save a tree (or a few pennies, if you charge for header
pages), they would not be able to do so, since every filter's going
to print a header page with every job.To allow users to shut off header pages on a per-job basis, you
will need to use the trick introduced in section Accounting for
Header Pages: write an output filter that parses the
LPD-generated header page and produces a PostScript version. If the
user submits the job with lpr -h, then LPD will
not generate a header page, and neither will your output filter.
Otherwise, your output filter will read the text from LPD and send
the appropriate header page PostScript code to the printer.If you have a PostScript printer on a serial line, you can make
use of lprps, which comes with an output filter,
psof, which does the above. Note that
psof does not charge for header pages.Networked Printingprinternetworknetwork printingFreeBSD supports networked printing: sending jobs to remote
printers. Networked printing generally refers to two different
things:Accessing a printer attached to a remote host. You install a
printer that has a conventional serial or parallel interface on
one host. Then, you set up LPD to enable access to the printer
from other hosts on the network. Section Printers Installed on
Remote Hosts tells how to do this.Accessing a printer attached directly to a network. The
printer has a network interface in addition (or in place of) a
more conventional serial or parallel interface. Such a printer
might work as follows:It might understand the LPD protocol and can even queue
jobs from remote hosts. In this case, it acts just like a
regular host running LPD. Follow the same procedure in
section Printers
Installed on Remote Hosts to set up such a
printer.It might support a data stream network connection. In this
case, you attach the printer to one host on the
network by making that host responsible for spooling jobs and
sending them to the printer. Section Printers with
Networked Data Stream Interfaces gives some
suggestions on installing such printers.Printers Installed on Remote HostsThe 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 printer host, using the simple
printer setup described in Simple
Printer Setup. Do any advanced setup in Advanced Printer Setup that you
need. Make sure to test the printer and see if it works with the
features of LPD you have enabled. Also ensure that the
local host has authorization to use the LPD
service in the remote host (see Restricting Jobs
from Remote Printers).printernetworknetwork printingIf you are using a printer with a network interface that is
compatible with LPD, then the printer host in
the discussion below is the printer itself, and the
printer name is the name you configured for the
printer. See the documentation that accompanied your printer and/or
printer-network interface.If you are using a Hewlett Packard Laserjet then the printer
name text will automatically perform the LF to
CRLF conversion for you, so you will not require the
hpif script.Then, on the other hosts you want to have access to the printer,
make an entry in their /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 lp capability blank, explicitly
(:lp=:).Make a spooling directory and specify its location in the
sd capability. LPD will store jobs here
before they get sent to the printer host.Place the name of the printer host in the
rm capability.Place the printer name on the printer
host in the rp
capability.That is it. You do not need to list conversion filters, page
dimensions, or anything else in the
/etc/printcap file.Here is an example. The host rose has two
printers, bamboo and rattan.
We will enable users on the host orchid to print to those printers.
Here is the /etc/printcap file for
orchid (back from section Enabling Header
Pages). It already had the entry for the printer
teak; we have added entries for the two printers
on the host rose:#
# /etc/printcap for host orchid - added (remote) printers on rose
#
#
# teak is local; it is connected directly to orchid:
#
teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
:lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
:if=/usr/local/libexec/ifhp:\
:vf=/usr/local/libexec/vfhp:\
:of=/usr/local/libexec/ofhp:
#
# rattan is connected to rose; send jobs for rattan to rose:
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
#
# bamboo is connected to rose as well:
#
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:Then, we just need to make spooling directories on
orchid:&prompt.root; mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo
&prompt.root; chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo
&prompt.root; chown daemon:daemon /var/spool/lpd/rattan /var/spool/lpd/bambooNow, users on orchid can print to
rattan and bamboo. If, for
example, a user on orchid typed
&prompt.user; 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
bamboo spooling directory, the two LPDs would
transfer the file to rose. The file would wait in rose's queue
until it was finally printed. It would be converted from DVI to
PostScript (since bamboo is a PostScript printer) on rose.Printers with Networked Data Stream InterfacesOften, 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 one, see the previous section Printers Installed on
Remote Hosts.The format of the /etc/printcap file lets
you specify what serial or parallel interface to use, and (if you
are using a serial interface), what baud rate, whether to use flow
control, delays for tabs, conversion of newlines, and more. But
there is no way to specify a connection to a printer that is
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 is one such example: the script
netprint takes all data on standard input and
sends it to a network-attached printer. We specify the hostname of
the printer as the first argument and the port number to which to
connect as the second argument to netprint. Note
that this supports one-way communication only (FreeBSD to printer);
many network printers support two-way communication, and you might
want to take advantage of that (to get printer status, perform
accounting, etc.).#!/usr/bin/perl
#
# netprint - Text filter for printer attached to network
# Installed in /usr/local/libexec/netprint
#
$#ARGV eq 1 || die "Usage: $0 <printer-hostname> <port-number>";
$printer_host = $ARGV[0];
$printer_port = $ARGV[1];
require 'sys/socket.ph';
($ignore, $ignore, $protocol) = getprotobyname('tcp');
($ignore, $ignore, $ignore, $ignore, $address)
= gethostbyname($printer_host);
$sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address);
socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol)
|| die "Can't create TCP/IP stream socket: $!";
connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!";
while (<STDIN>) { print PRINTER; }
exit 0;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 is 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 5100Restricting Printer Usageprinterrestricting access toThis 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 CopiesThe LPD system makes it easy for users to print multiple copies
of a file. Users can print jobs with lpr -#5
(for example) and get five copies of each file in the job. Whether
this is a good thing is up to you.If you feel multiple copies cause unnecessary wear and tear on
your printers, you can disable the option to
&man.lpr.1; by adding the sc capability to the
/etc/printcap file. When users submit jobs
with the option, they will see:lpr: multiple copies are not allowedNote that if you have set up access to a printer remotely (see
section Printers
Installed on Remote Hosts), you need the
sc capability on the remote
/etc/printcap files as well, or else users will
still be able to submit multiple-copy jobs by using another
host.Here is an example. This is the
/etc/printcap file for the host
rose. The printer rattan is
quite hearty, so we will allow multiple copies, but the laser
printer bamboo's a bit more delicate, so we will
disable multiple copies by adding the sc
capability:#
# /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 sc capability on
the host orchid's
/etc/printcap (and while we are at it, let us
disable multiple copies for the printer
teak):#
# /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 sc capability, we prevent the
use of lpr -#, but that still does not prevent
users from running &man.lpr.1;
multiple times, or from submitting the same file multiple times in
one job like this:&prompt.user; lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.signThere are many ways to prevent this abuse (including ignoring
it) which you are free to explore.Restricting Access To PrintersYou can control who can print to what printers by using the Unix
group mechanism and the rg capability in
/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 rg capability.Users outside the group (including root) will be greeted with
lpr: Not a member of the restricted group
if they try to print to the controlled printer.As with the sc (suppress multiple copies)
capability, you need to specify rg on remote
hosts that also have access to your printers, if you feel it is
appropriate (see section Printers Installed on
Remote Hosts).For example, we will let anyone access the printer
rattan, but only those in group
artists can use bamboo. Here
is the familiar /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 us leave the other example
/etc/printcap file (for the host
orchid) alone. Of course, anyone on
orchid can print to bamboo. It
might be the case that we only allow certain logins on
orchid anyway, and want them to have access to the
printer. Or not.There can be only one restricted group per printer.Controlling Sizes of Jobs Submittedprint jobsIf 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 is only so much free space on the
filesystem that houses the spooling directories, and you also need
to make sure there is room for the jobs of other users.print jobscontrollingLPD enables you to limit the maximum byte size a file in a job
can be with the mx capability. The units are in
BUFSIZ blocks, which are 1024 bytes. If you put a zero for this
capability, there will be no limit on file size; however, if no
mx capability is specified, then a default limit
of 1000 blocks will be used.The limit applies to files in a job, and
not the total job size.LPD will not refuse a file that is larger than the limit you
place on a printer. Instead, it will queue as much of the file up
to the limit, which will then get printed. The rest will be
discarded. Whether this is correct behavior is up for
debate.Let us add limits to our example printers
rattan and bamboo. Since
those artists' PostScript files tend to be large, we will limit them
to five megabytes. We will put no limit on the plain text line
printer:#
# /etc/printcap for host rose
#
#
# No limit on job size:
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:sh:mx#0:sd=/var/spool/lpd/rattan:\
:lp=/dev/lpt0:\
:if=/usr/local/libexec/if-simple:
#
# Limit of five megabytes:
#
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\
:lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
:if=/usr/local/libexec/psif:\
:df=/usr/local/libexec/psdf:Again, the limits apply to the local users only. If you have
set up access to your printers remotely, remote users will not get
those limits. You will need to specify the mx
capability in the remote /etc/printcap files as
well. See section Printers Installed on
Remote Hosts for more information on remote
printing.There is another specialized way to limit job sizes from remote
printers; see section Restricting Jobs
from Remote Printers.Restricting Jobs from Remote PrintersThe LPD spooling system provides several ways to restrict print
jobs submitted from remote hosts:Host restrictionsYou can control from which remote hosts a local LPD
accepts requests with the files
/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
&man.ruserok.3; protocol, and affects programs like
&man.rsh.1; and &man.rcp.1;, so be careful.For example, here is the
/etc/hosts.lpd file on the host
rose:orchid
violet
madrigal.fishbaum.deThis means rose will accept requests from
the hosts orchid, violet,
and madrigal.fishbaum.de. If any
other host tries to access rose's
LPD, the job will be refused.Size restrictionsYou can control how much free space there needs to remain
on the filesystem where a spooling directory resides. Make a
file called minfree in the spooling
directory for the local printer. Insert in that file a number
representing how many disk blocks (512 bytes) of free space
there has to be for a remote job to be accepted.This lets you insure that remote users will not fill your
filesystem. You can also use it to give a certain priority to
local users: they will be able to queue jobs long after the
free disk space has fallen below the amount specified in the
minfree file.For example, let us add a minfree
file for the printer bamboo. We examine
/etc/printcap to find the spooling
directory for this printer; here is bamboo's
entry: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
sd capability. We will make three
megabytes (which is 6144 disk blocks) the amount of free disk
space that must exist on the filesystem for LPD to accept
remote jobs:&prompt.root; echo 6144 > /var/spool/lpd/bam
boo/minfreeUser restrictionsYou can control which remote users can print to local
printers by specifying the rs capability in
/etc/printcap. When
rs appears in the entry for a
locally-attached printer, LPD will accept jobs from remote
hosts if the user submitting the job also
has an account of the same login name on the local host.
Otherwise, LPD refuses the job.This capability is particularly useful in an environment
where there are (for example) different departments sharing a
network, and some users transcend departmental boundaries. By
giving them accounts on your systems, they can use your
printers from their own departmental systems. If you would
rather allow them to use only your
printers and not your compute resources, you can give them
token accounts, with no home directory and a
useless shell like /usr/bin/false.Accounting for Printer UsageaccountingprinterSo, you need to charge for printouts. And why not? Paper and ink
cost money. And then there are maintenance costs—printers are
loaded with moving parts and tend to break down. You have examined
your printers, usage patterns, and maintenance fees and have come up
with a per-page (or per-foot, per-meter, or per-whatever) cost. Now,
how do you actually start accounting for printouts?Well, the bad news is the LPD spooling system does not provide
much help in this department. Accounting is highly dependent on the
kind of printer in use, the formats being printed, and
your requirements in charging for printer
usage.To implement accounting, you have to modify a printer's text
filter (to charge for plain text jobs) and the conversion filters (to
charge for other file formats), to count pages or query the printer
for pages printed. You cannot get away with using the simple output
filter, since it cannot do accounting. See section Filters.Generally, there are two ways to do accounting:Periodic accounting is the more common
way, possibly because it is easier. Whenever someone prints a
job, the filter logs the user, host, and number of pages to an
accounting file. Every month, semester, year, or whatever time
period you prefer, you collect the accounting files for the
various printers, tally up the pages printed by users, and charge
for usage. Then you truncate all the logging files, starting with
a clean slate for the next period.Timely accounting is less common,
probably because it is more difficult. This method has the
filters charge users for printouts as soon as they use the
printers. Like disk quotas, the accounting is immediate. You can
prevent users from printing when their account goes in the red,
and might provide a way for users to check and adjust their
print quotas. But this method requires some database
code to track users and their quotas.The LPD spooling system supports both methods easily: since you
have to provide the filters (well, most of the time), you also have to
provide the accounting code. But there is a bright side: you have
enormous flexibility in your accounting methods. For example, you
choose whether to use periodic or timely accounting. You choose what
information to log: user names, host names, job types, pages printed,
square footage of paper used, how long the job took to print, and so
forth. And you do so by modifying the filters to save this
information.Quick and Dirty Printer AccountingFreeBSD comes with two programs that can get you set up with
simple periodic accounting right away. They are the text filter
lpf, described in section lpf: a Text Filter, and
&man.pac.8;, a program to gather and total
entries from printer accounting files.As mentioned in the section on filters (Filters), LPD starts
the text and the conversion filters with the name of the accounting
file to use on the filter command line. The filters can use this
argument to know where to write an accounting file entry. The name
of this file comes from the af capability in
/etc/printcap, and if not specified as an
absolute path, is relative to the spooling directory.LPD starts lpf with page width and length
arguments (from the pw and pl
capabilities). lpf uses these arguments to
determine how much paper will be used. After sending the file to
the printer, it then writes an accounting entry in the accounting
file. The entries look like this:2.00 rose:andy
3.00 rose:kelly
3.00 orchid:mary
5.00 orchid:mary
2.00 orchid:zhangYou should use a separate accounting file for each printer, as
lpf has no file locking logic built into it, and
two lpfs might corrupt each other's entries if
they were to write to the same file at the same time. A easy way to
insure a separate accounting file for each printer is to use
af=acct in /etc/printcap.
Then, each accounting file will be in the spooling directory for a
printer, in a file named acct.When you are ready to charge users for printouts, run the
&man.pac.8; program. Just change to the spooling directory for
the printer you want to collect on and type pac.
You will get a dollar-centric summary like the following: 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.74These are the arguments &man.pac.8; expects:Which printer to summarize.
This option works only if there is an absolute path in the
af capability in
/etc/printcap.Sort the output by cost instead of alphabetically by user
name.Ignore host name in the accounting files. With this
option, user smith on host
alpha is the same user
smith on host gamma.
Without, they are different users.Compute charges with price
dollars per page or per foot instead of the price from the
pc capability in
/etc/printcap, or two cents (the
default). You can specify price as
a floating point number.Reverse the sort order.Make an accounting summary file and truncate the
accounting file.name…Print accounting information for the given user
names only.In the default summary that &man.pac.8; produces, you see the
number of pages printed by each user from various hosts. If, at
your site, host does not matter (because users can use any host),
run pac -m, to produce the following
summary: 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.74To compute the dollar amount due,
&man.pac.8; uses the pc capability in the
/etc/printcap file (default of 200, or 2 cents
per page). Specify, in hundredths 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 &man.pac.8; with the
option. The units for the
option are in dollars, though, not hundredths of cents. For
example,
&prompt.root; 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 pac -s will save the summary
information in a summary accounting file, which is named the same as
the printer's accounting file, but with _sum
appended to the name. It then truncates the accounting file. When
you run &man.pac.8; again, it rereads the
summary file to get starting totals, then adds information from the
regular accounting file.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 is 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. Do not 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 lpf (introduced in lpf: a Text Filter) takes
into account these things when it does accounting. If you are
writing a text filter which needs to do accounting, you might want
to examine lpf's source code.How do you handle other file formats, though?Well, for DVI-to-LaserJet or DVI-to-PostScript conversion, you
can have your filter parse the diagnostic output of
dvilj or dvips and look to see
how many pages were converted. You might be able to do similar
things with other file formats and conversion programs.But these methods suffer from the fact that the printer may not
actually print all those pages. For example, it could jam, run out
of toner, or explode—and the user would still get
charged.So, what can you do?There is only one sure way to do
accurate accounting. Get a printer that can
tell you how much paper it uses, and attach it via a serial line or
a network connection. Nearly all PostScript printers support this
notion. Other makes and models do as well (networked Imagen laser
printers, for example). Modify the filters for these printers to
get the page usage after they print each job and have them log
accounting information based on that value
only. There is no line counting nor
error-prone file examination required.Of course, you can always be generous and make all printouts
free.Using PrintersprinterusageThis section tells you how to use printers you have setup with
FreeBSD. Here is an overview of the user-level commands:&man.lpr.1;Print jobs&man.lpq.1;Check printer queues&man.lprm.1;Remove jobs from a printer's queueThere is also an administrative command, &man.lpc.8;, described in
the section Administrating the LPD
Spooler, used to control printers and their queues.All three of the commands &man.lpr.1;, &man.lprm.1;, and &man.lpq.1;
accept an option to specify on which
printer/queue to operate, as listed in the
/etc/printcap file. This enables you to submit,
remove, and check on jobs for various printers. If you do not use the
option, then these commands use the printer
specified in the PRINTER environment variable. Finally,
if you do not have a PRINTER environment variable, these
commands default to the printer named lp.Hereafter, the terminology default printer
means the printer named in the PRINTER environment
variable, or the printer named lp when there is no
PRINTER environment variable.Printing JobsTo print files, type:&prompt.user; lpr filename...printingThis prints each of the listed files to the default printer. If
you list no files, &man.lpr.1; reads data to
print from standard input. For example, this command prints some
important system files:&prompt.user; lpr /etc/host.conf /etc/hosts.equivTo select a specific printer, type:&prompt.user; lpr -P printer-namefilename...This example prints a long listing of the current directory to the
printer named rattan:&prompt.user; ls -l | lpr -P rattanBecause no files were listed for the
&man.lpr.1; command, lpr read the data to print
from standard input, which was the output of the ls
-l command.The &man.lpr.1; command can also accept a wide variety of options
to control formatting, apply file conversions, generate multiple
copies, and so forth. For more information, see the section Printing Options.Checking Jobsprint jobsWhen you print with &man.lpr.1;, the data you wish to print is put
together in a package called a print job, which is sent
to the LPD spooling system. Each printer has a queue of jobs, and
your job waits in that queue along with other jobs from yourself and
from other users. The printer prints those jobs in a first-come,
first-served order.To display the queue for the default printer, type &man.lpq.1;.
For a specific printer, use the option. For
example, the command
&prompt.user; lpq -P bamboo
shows the queue for the printer named bamboo. Here
is an example of the output of the lpq
command: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 bytesThis shows three jobs in the queue for bamboo.
The first job, submitted by user kelly, got assigned job
number 9. Every job for a printer gets a unique job number.
Most of the time you can ignore the job number, but you will need it
if you want to cancel the job; see section Removing Jobs for details.Job number nine consists of two files; multiple files given on the
&man.lpr.1; command line are treated as part of a single job. It
is the currently active job (note the word active
under the Rank column), which means the printer should
be currently printing that job. The second job consists of data
passed as the standard input to the &man.lpr.1; command. The third
job came from user mary; it is a much larger
job. The pathname of the files she's trying to print is too long to
fit, so the &man.lpq.1; command just shows three dots.The very first line of the output from &man.lpq.1; is also useful:
it tells what the printer is currently doing (or at least what LPD
thinks the printer is doing).The &man.lpq.1; command also support a option
to generate a detailed long listing. Here is an example of
lpq -l:waiting for bamboo to become ready (offline ?)
kelly: 1st [job 009rose]
/etc/host.conf 73 bytes
/etc/hosts.equiv 15 bytes
kelly: 2nd [job 010rose]
(standard input) 1635 bytes
mary: 3rd [job 011rose]
/home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytesRemoving JobsIf you change your mind about printing a job, you can remove the
job from the queue with the &man.lprm.1; command. Often, you can
even use &man.lprm.1; to remove an active job, but some or all of the
job might still get printed.To remove a job from the default printer, first use
&man.lpq.1; to find the job number. Then type:&prompt.user; lprm job-numberTo remove the job from a specific printer, add the
option. The following command removes job number
10 from the queue for the printer bamboo:&prompt.user; lprm -P bamboo 10The &man.lprm.1; command has a few shortcuts:lprm -Removes all jobs (for the default printer) belonging to
you.lprm userRemoves all jobs (for the default printer) belonging to
user. The superuser can remove other
users' jobs; you can remove only your own jobs.lprmWith no job number, user name, or
appearing on the command line,
&man.lprm.1; removes the currently active job on the
default printer, if it belongs to you. The superuser can remove
any active job.Just use the option with the above shortcuts
to operate on a specific printer instead of the default. For example,
the following command removes all jobs for the current user in the
queue for the printer named rattan:&prompt.user; lprm -P rattan -If you are working in a networked environment, &man.lprm.1; will
let you remove jobs only from the
host from which the jobs were submitted, even if the same printer is
available from other hosts. The following command sequence
demonstrates this:&prompt.user; lpr -P rattan myfile
&prompt.user; rlogin orchid
&prompt.user; lpq -P rattan
Rank Owner Job Files Total Size
active seeyan 12 ... 49123 bytes
2nd kelly 13 myfile 12 bytes
&prompt.user; lprm -P rattan 13
rose: Permission denied
&prompt.user; logout
&prompt.user; lprm -P rattan 13
dfA013rose dequeued
cfA013rose dequeued
Beyond Plain Text: Printing OptionsThe &man.lpr.1; command supports a number of options that control
formatting text, converting graphic and other file formats, producing
multiple copies, handling of the job, and more. This section
describes the options.Formatting and Conversion OptionsThe following &man.lpr.1; options control formatting of the
files in the job. Use these options if the job does not contain
plain text or if you want plain text formatted through the
&man.pr.1; utility.TeXFor example, the following command prints a DVI file (from the
TeX typesetting system) named fish-report.dvi
to the printer named bamboo:&prompt.user; lpr -P bamboo -d fish-report.dviThese options apply to every file in the job, so you cannot 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.All of these options except and
require conversion filters installed for the
destination printer. For example, the option
requires the DVI conversion filter. Section Conversion
Filters gives details.Print cifplot files.Print DVI files.Print FORTRAN text files.Print plot data.Indent the output by number
columns; if you omit number, indent
by 8 columns. This option works only with certain conversion
filters.Do not put any space between the and
the number.Print literal text data, including control
characters.Print ditroff (device independent troff) data.-pFormat plain text with &man.pr.1; before printing. See
&man.pr.1; for more information.Use title on the
&man.pr.1; header instead of the file name. This option has
effect only when used with the
option.Print troff data.Print raster data.Here is an example: this command prints a nicely formatted
version of the &man.ls.1; manual page on the default printer:&prompt.user; zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -tThe &man.zcat.1; command uncompresses the source of the
&man.ls.1; manual page and passes it to the &man.troff.1;
command, which formats that source and makes GNU troff
output and passes it to &man.lpr.1;, which submits the job
to the LPD spooler. Because we used the
option to &man.lpr.1;, the spooler will convert the GNU
troff output into a format the default printer can
understand when it prints the job.Job Handling OptionsThe following options to &man.lpr.1; tell LPD to handle the job
specially:-# copiesProduce a number of copies of
each file in the job instead of just one copy. An
administrator may disable this option to reduce printer
wear-and-tear and encourage photocopier usage. See section
Restricting
Multiple Copies.This example prints three copies of
parser.c followed by three copies of
parser.h to the default printer:&prompt.user; lpr -#3 parser.c parser.h-mSend mail after completing the print job. With this
option, the LPD system will send mail to your account when it
finishes handling your job. In its message, it will tell you
if the job completed successfully or if there was an error,
and (often) what the error was.-sDo not copy the files to the spooling directory, but make
symbolic links to them instead.If you are printing a large job, you probably want to use
this option. It saves space in the spooling directory (your
job might overflow the free space on the filesystem where the
spooling directory resides). It saves time as well since LPD
will not have to copy each and every byte of your job to the
spooling directory.There is a drawback, though: since LPD will refer to the
original files directly, you cannot modify or remove them
until they have been printed.If you are printing to a remote printer, LPD will
eventually have to copy files from the local host to the
remote host, so the option will save
space only on the local spooling directory, not the remote.
It is still useful, though.-rRemove the files in the job after copying them to the
spooling directory, or after printing them with the
option. Be careful with this
option!Header Page OptionsThese options to &man.lpr.1; adjust the text that normally
appears on a job's header page. If header pages are suppressed for
the destination printer, these options have no effect. See section
Header Pages
for information about setting up header pages.-C textReplace the hostname on the header page with
text. The hostname is normally the
name of the host from which the job was submitted.-J textReplace the job name on the header page with
text. The job name is normally the
name of the first file of the job, or
stdin if you are printing standard
input.-hDo not print any header page.At some sites, this option may have no effect due to the
way header pages are generated. See Header
Pages for details.Administrating PrintersAs an administrator for your printers, you have had to install,
set up, and test them. Using the &man.lpc.8; command, you
can interact with your printers in yet more ways. With &man.lpc.8;,
you canStart and stop the printersEnable and disable their queuesRearrange the order of the jobs in each queue.First, a note about terminology: if a printer is
stopped, it will not print anything in its queue.
Users can still submit jobs, which will wait in the queue until the
printer is started or the queue is
cleared.If a queue is disabled, no user (except root)
can submit jobs for the printer. An enabled
queue allows jobs to be submitted. A printer can be
started for a disabled queue, in which case it
will continue to print jobs in the queue until the queue is
empty.In general, you have to have root privileges to use the
&man.lpc.8; command. Ordinary users can use the &man.lpc.8; command
to get printer status and to restart a hung printer only.Here is a summary of the &man.lpc.8; commands. Most of the
commands takes a printer-name argument to
tell on which printer to operate. You can use all
for the printer-name to mean all printers
listed in /etc/printcap.abort
printer-nameCancel the current job and stop the printer. Users can
still submit jobs if the queue's enabled.clean
printer-nameRemove old files from the printer's spooling directory.
Occasionally, the files that make up a job are not properly
removed by LPD, particularly if there have been errors during
printing or a lot of administrative activity. This command
finds files that do not belong in the spooling directory and
removes them.disable
printer-nameDisable queuing of new jobs. If the printer's started, it
will continue to print any jobs remaining in the queue. The
superuser (root) can always submit jobs, even to a disabled
queue.This command is useful while you are testing a new printer
or filter installation: disable the queue and submit jobs as
root. Other users will not be able to submit jobs until you
complete your testing and re-enable the queue with the
enable command.down printer-namemessageTake a printer down. Equivalent to
disable followed by stop.
The message appears as the printer's
status whenever a user checks the printer's queue with
&man.lpq.1; or status with lpc
status.enable
printer-nameEnable the queue for a printer. Users can submit jobs but
the printer will not print anything until it is started.help
command-namePrint help on the command
command-name. With no
command-name, print a summary of the
commands available.restart
printer-nameStart the printer. Ordinary users can use this command if
some extraordinary circumstance hangs LPD, but they cannot start
a printer stopped with either the stop or
down commands. The
restart command is equivalent to
abort followed by
start.start
printer-nameStart the printer. The printer will print jobs in its
queue.stop
printer-nameStop the printer. The printer will finish the current job
and will not print anything else in its queue. Even though the
printer is stopped, users can still submit jobs to an enabled
queue.topq printer-namejob-or-usernameRearrange the queue for
printer-name by placing the jobs with
the listed job numbers or the jobs
belonging to username at the top of
the queue. For this command, you cannot use
all as the
printer-name.up
printer-nameBring a printer up; the opposite of the
down command. Equivalent to
start followed by
enable.&man.lpc.8; accepts the above commands on the command line. If
you do not enter any commands, &man.lpc.8; enters an interactive mode,
where you can enter commands until you type exit,
quit, or end-of-file.Alternatives to the Standard SpoolerIf you have been reading straight through this manual, by now you
have 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)?LPRngLPRngLPRng, which purportedly means LPR: the Next
Generation is a complete rewrite of PLP. Patrick Powell
and Justin Mason (the principal maintainer of PLP) collaborated to
make LPRng. The main site for LPRng is http://www.astart.com/lprng/LPRng.html.TroubleshootingAfter performing the simple test with &man.lptest.1;, you might
have gotten one of the following results instead of the correct
printout:It worked, after awhile; or, it did not eject a full
sheet.The printer printed the above, but it sat for awhile and
did nothing. In fact, you might have needed to press a
PRINT REMAINING or FORM FEED button on the printer to get any
results to appear.If this is the case, the printer was probably waiting to
see if there was any more data for your job before it printed
anything. To fix this problem, you can have the text filter
send a FORM FEED character (or whatever is necessary) to the
printer. This is usually sufficient to have the printer
immediately print any text remaining in its internal buffer.
It is also useful to make sure each print job ends on a full
sheet, so the next job does not start somewhere on the middle
of the last page of the previous job.The following replacement for the shell script
/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 && printf "\f" && exit 0
exit 2It produced the staircase effect.You got the following on paper:!"#$%&'()*+,-./01234
"#$%&'()*+,-./012345
#$%&'()*+,-./0123456MS-DOSOS/2ASCIIYou have become another victim of the staircase
effect, caused by conflicting interpretations of
what characters should indicate a new line. Unix-style
operating systems use a single character: ASCII code 10, the
line feed (LF). MS-DOS, OS/2, and others uses a pair of
characters, ASCII code 10 and ASCII code
13 (the carriage return or CR). Many printers use the MS-DOS
convention for representing new-lines.When you print with FreeBSD, your text used just the line
feed character. The printer, upon seeing a line feed
character, advanced the paper one line, but maintained the
same horizontal position on the page for the next character
to print. That is what the carriage return is for: to move
the location of the next character to print to the left edge
of the paper.Here is what FreeBSD wants your printer to do:Printer received CRPrinter prints CRPrinter received LFPrinter prints CR + LFHere 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.If you boot your system into other operating systems
besides FreeBSD, you may have to
reconfigure the printer to use a an
interpretation for CR and LF characters that those other
operating systems use. You might prefer one of the other
solutions, below.Have FreeBSD's serial line driver automatically
convert LF to CR+LF. Of course, this works with printers
on serial ports only. To enable this
feature, set the CRMOD bit in fs
capability in the /etc/printcap file
for the printer.Send an escape code to the
printer to have it temporarily treat LF characters
differently. Consult your printer's manual for escape
codes that your printer might support. When you find the
proper escape code, modify the text filter to send the
code first, then send the print job.PCLHere is 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. Ejects the page when done.
printf "\033&k2G" && cat && printf "\033&l0H" && exit 0
exit 2Here is 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 teak. It is using the
above script as its text 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:It overprinted each line.The printer never advanced a line. All of the lines of
text were printed on top of each other on one line.This problem is the opposite of the
staircase effect, described above, and is much rarer.
Somewhere, the LF characters that FreeBSD uses to end a line
are being treated as CR characters to return the print
location to the left edge of the paper, but not also down a
line.Use the printer's configuration switches or control panel
to enforce the following interpretation of LF and CR
characters:Printer receivesPrinter printsCRCRLFCR + LFThe printer lost characters.While printing, the printer did not print a few characters
in each line. The problem might have gotten worse as the
printer ran, losing more and more characters.The problem is that the printer cannot keep up with the
speed at which the computer sends data over a serial line
(this problem should not occur with printers on parallel
ports). There are two ways to overcome the problem:If the printer supports XON/XOFF flow control, have
FreeBSD use it by specifying the TANDEM bit in the
fs capability.If the printer supports carrier flow control, specify
the MDMBUF bit in the fs capability.
Make sure the cable connecting the printer to the computer
is correctly wired for carrier flow control.If the printer does not support any flow control, use
some combination of the NLDELAY, TBDELAY, CRDELAY, VTDELAY,
and BSDELAY bits in the fs capability
to add appropriate delays to the stream of data sent to
the printer.It printed garbage.The printer printed what appeared to be random garbage,
but not the desired text.This is usually another symptom of incorrect
communications parameters with a serial printer. Double-check
the bps rate in the br capability, and the
parity bits in the fs and
fc capabilities; make sure the printer is
using the same settings as specified in the
/etc/printcap file.Nothing happened.If nothing happened, the problem is probably within
FreeBSD and not the hardware. Add the log file
(lf) capability to the entry for the
printer you are debugging in the
/etc/printcap file. For example, here is
the entry for rattan, with the
lf capability: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.logThen, 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 do not specify a lf capability,
LPD uses /dev/console as a
default.