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 d2020bf052..54f0b71931 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,6183 +1,6183 @@
Advanced NetworkingSynopsisThis chapter will cover some of the more frequently used network
services on Unix systems. We will cover how to define, setup, test and
maintain all of the network services that FreeBSD utilizes. In addition,
there have been example configuration files included throughout this
chapter for you to benefit from.After reading this chapter, you will know:The basics of gateways and routes.How to make FreeBSD act as a bridge.How to setup a network filesystem.How to setup network booting on a diskless machine.How to setup a network information server for sharing user
accounts.How to setup automatic network settings using DHCP.How to setup a domain name server.How to synchronize the time and date, and setup a
time server, with the NTP protocol.How to setup network address translation.How to manage the inetd daemon.How to connect two computers via PLIP.How to setup IPv6 on a FreeBSD machine.Before reading this chapter, you should:Understand the basics of the /etc/rc scripts.Be familiar with basic network terminology.CoranthGryphonContributed by Gateways and RoutesroutinggatewaysubnetFor one machine to be able to find another over a network, 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, communicate 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 (MAC addresses).
An ExampleTo illustrate different aspects of routing, we will use the
following example from netstat:&prompt.user; netstat -r
Routing tables
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
example.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.example.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 this routing table 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.EthernetMAC addressThe next thing that stands out are the addresses beginning
with 0:e0:. These are Ethernet
hardware addresses, which are also known as MAC 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. When this happens, the route to this host 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 example.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 (i.e. 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 on 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 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 routes.The final line (destination subnet 224) deals
with multicasting, which will be covered in another section.Finally, various attributes of each route can be seen in the
Flags 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 a 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,
DSL, cable modem, T1, or another network interface).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.
Local1 is connected to an ISP via a dial up
PPP connection. This PPP server computer is connected through
a local area network to another gateway computer through an
external interface to the ISPs 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 X.X.X.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:HostDefault RouteLocal2 (10.20.3.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 has 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 router
between the two subnets, is often used when we need to implement
packet filtering or firewall security in either or both
directions.If you want this machine to actually forward packets
between the two interfaces, you need to tell FreeBSD to enable
this ability.Building a RouterrouterA network router is simply a system that forwards packets
from one interface to another. Internet standards and good
engineering practice prevent the FreeBSD Project from enabling
this by default in FreeBSD. You can enable this feature by
changing the following variable to YES in
&man.rc.conf.5;:gateway_enable=YES # Set to YES if this host will be a gatewayThis option will set the &man.sysctl.8; variable
net.inet.ip.forwarding to
1. If you should need to stop routing
temporarily, you can reset this to 0 temporarily.Your new router will need routes to know where to send the
traffic. If your network is simple enough you can use static
routes. FreeBSD also comes with the standard BSD routing
daemon &man.routed.8;, which speaks RIP (both version 1 and
version 2) and IRDP. For more complex situations you may want
to try net/gated.Even when FreeBSD is configured in this way, it does not
completely comply with the Internet standard requirements for
routers. It comes close enough for ordinary use,
however.Routing Propagationrouting propagationWe 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 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;.StevePetersonWritten by BridgingIntroductionIP subnetbridgeIt is sometimes useful to divide one physical network (such as 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. A FreeBSD system with two network
interface cards can act as a bridge.The bridge works by learning the MAC layer addresses
(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 do not want for whatever reason to
subnet the network and interconnect the subnets with a
router.Let us 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 globally-accessible IP addresses
from 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
+ 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 the:options 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 line:net.link.ether.bridge=1to /etc/sysctl.conf to enable the bridge at
runtime, and the line:net.link.ether.bridge_cfg=if1,if2to enable bridging on the specified interfaces (replace if1 and
if2 with the names of your two network interfaces). If you want the
bridged packets to be filtered by &man.ipfw.8;, you should add:net.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
+ 3C905B. The protected side of the network runs at 10 mbps half duplex
and the connection between the bridge and my router (a Cisco 675) runs
- at 100mbps full duplex. With no filtering enabled, I have found that
- the bridge adds about 0.4 milliseconds of latency to pings from the
- protected 10mbps network to the Cisco 675.
+ at 100 mbps full duplex. With no filtering enabled, I have found that
+ the bridge adds about 0.4 milliseconds of latency to pings from the
+ protected 10 mbps 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.TomRhodesReorganized and enhanced by BillSwingleWritten by NFSNFSAmong the many different filesystems that FreeBSD supports is
the Network File System, also known as NFS.
NFS allows a system to share directories and files
with others over a network. By using NFS, users and
programs can access files on remote systems almost as if they were local
files.Some of the most notable benefits that NFS can provide are:Local workstations use less disk space because
commonly used data can be stored on a single machine and still
remain accessible to others over the network.There is no need for users to have separate home directories
on every network machine. Home directories could be setup on the
NFS server and made available throughout the network.Storage devices such as floppy disks, CDROM drives, and ZIP drives
can be used by other machines on the network. This may reduce the number
of removable media drives throughout the network.How NFS WorksNFS consists of at least two main parts: a server
and one or more clients. The client remotely accesses the data that is stored
on the server machine. In order for this to function properly a few
processes have to be configured and running:The server has to be running the following daemons:NFSserverportmapmountdnfsdDaemonDescriptionnfsdThe NFS daemon which services requests from
the NFS clients.mountdThe NFS mount daemon which carries out
the requests that &man.nfsd.8; passes on to it.portmap The portmapper daemon
allows NFS clients to discover which port the NFS server
is using.The client can also run a daemon, known as
nfsiod. The nfsiod
daemon services the requests from the NFS server. This
is optional, and improves performance, but is not required for normal
and correct operation. See the &man.nfsiod.8; manual page for more information.
Configuring NFSNFSconfigurationNFS configuration is a relatively straightforward
process. The processes that need to be running can all start at boot time with
a few modifications to your /etc/rc.conf
file.On the NFS server, make sure that the following options
are configured in the /etc/rc.conf file:portmap_enable="YES"
nfs_server_enable="YES"
mountd_flags="-r"mountd runs automatically whenever the
NFS server is enabled.On the client, make sure this option is present in
/etc/rc.conf:nfs_client_enable="YES"
The /etc/exports
file specifies which filesystems NFS should export (sometimes
referred to as share).
Each line in /etc/exports specifies a filesystem to be exported and
which machines have access to that filesystem. Along with what machines have access
to that filesystem, access options may also be specified. There are many such options
that can be used in this file but only a few will be mentioned here. You can easily discover
other options by reading over the &man.exports.5; manual page.Here are a few example /etc/exports
entries:NFSExamples of exporting filesystemsThe following examples give an idea of how to export filesystems,
although the settings may be different depending on
your environment and network configuration.
For instance, to export the /cdrom directory to
three example 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 exported filesystem read-only. With this flag, the
remote system will not be able to write any changes to the
exported filesystem./cdrom -ro host1 host2 host3The following line exports /home to three
hosts by IP address. This is a useful setup if you have a
private network without a DNS server configured.
Optionally the /etc/hosts file could be configured
for internal hostnames; please review &man.hosts.5; for more
information. The flag allows the subdirectories
to be mount points. In other words, it will not mount the subdirectories
but permit the client to mount only the directories that are required or
needed./home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4The following line exports /a so that two
clients from different domains may access the filesystem. The
flag allows the root
user on the remote system to write data on the exported filesystem as
root. If the -maproot=root flag is not specified, then even if
a user has root access on the remote system, they will not
be able to modify files on the exported filesystem./a -maproot=root host.example.com box.example.orgIn order for a client to access an exported filesystem, the client must
have permission to do so. Make sure the client is listed in your
/etc/exports file.In /etc/exports, each line represents
the export information for one filesystem to one host. A
remote host can only be specified once per filesystem, and may only
have one default entry. For example, assume that /usr
is a single filesystem. The following /etc/exports
would be invalid:/usr/src client
/usr/ports clientOne filesystem, /usr, has two lines
specifying exports to the same host, client.
The correct format for this situation is:/usr/src /usr/ports clientThe properties of one filesystem exported to a given host
must all occur on one line. Lines without a client specified
are treated as a single host. This limits how you can export
filesystems, but for most people this is not an issue.The following is an example of a valid export list, where
/usr and /exports
are local filesystems:# Export src and ports to client01 and client02, but only
# client01 has root privileges on it
/usr/src /usr/ports -maproot=root client01
/usr/src /usr/ports client02
# The client machines have root and can mount anywhere
# on /exports. Anyone in the world can mount /exports/obj read-only
/exports -alldirs -maproot=root client01 client02
/exports/obj -roYou must restart
mountd whenever you modify
/etc/exports so the changes can take effect.
This can be accomplished by sending the HUP signal
to the mountd process:&prompt.root; kill -HUP `cat /var/run/mountd.pid`Alternatively, a reboot will make FreeBSD set everything
up properly. A reboot is not necessary though.
Executing the following commands as root
should start everything up.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 everything should be ready to actually mount a remote file
system. In these examples the
server's name will be server and the client's
name will be client. If you only want to
temporarily mount a remote filesystem or would rather test the
configuration, just execute a command like this as root on the
client:NFSmounting filesystems&prompt.root; mount server:/home /mntThis will mount the /home directory
on the server at /mnt on the client. If
everything is set up correctly you should be able to enter
/mnt on the client and see all the files
that are on the server.If you want to automatically mount a remote filesystem
each time the computer boots, add the filesystem to the
/etc/fstab file. Here is an example:server:/home /mnt nfs rw 0 0The &man.fstab.5; manual page lists all the available options.Practical UsesNFS has many practical uses. Some of the more common
ones are listed below:NFSusesSet several machines to share a CDROM or
other media among them. This is cheaper and often
a more convenient method to install software on multiple machines.On large networks, it might be more convenient to configure a
central NFS server in which to store all the user
home directories. These home directories can then be exported to
the network so that users would always have the same home directory,
regardless of which workstation they log in to.Several machines could have a common
/usr/ports/distfiles directory.
That way, when you need to install a port on several machines, you can
quickly access the source without downloading it on each machine.WylieStilwellContributed by ChernLeeRewritten by amdamdautomatic mounter daemon&man.amd.8; (the automatic mounter daemon)
automatically mounts a
remote filesystem whenever a file or directory within that
filesystem is accessed. Filesystems that are inactive for a
period of time will also be automatically unmounted by
amd. Using
amd provides a simple alternative
to permanent mounts, as permanent mounts are usually listed in
/etc/fstab.amd operates by attaching
itself as an NFS server to the /host and
/net directories. When a file is accessed
within one of these directories, amd
looks up the corresponding remote mount and automatically mounts
it. /net is used to mount an exported
filesystem from an IP address, while /host
is used to mount an export from a remote hostname.An access to a file within
/host/foobar/usr would tell
amd to attempt to mount the
/usr export on the host
foobar.Mounting an Export with amdYou can view the available mounts of a remote host with
the showmount command. For example, to
view the mounts of a host named foobar, you
can use:&prompt.user; showmount -e foobar
Exports list on foobar:
/usr 10.10.10.0
/a 10.10.10.0
&prompt.user; cd /host/foobar/usrAs seen in the example, the showmount shows
/usr as an export. When changing directories to
/host/foobar/usr, amd
attempts to resolve the hostname foobar and
automatically mount the desired export.amd can be started by the
startup scripts by placing the following lines in
/etc/rc.conf:amd_enable="YES"Additionally, custom flags can be passed to
amd from the
amd_flags option. By default,
amd_flags is set to:amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"The /etc/amd.map file defines the
default options that exports are mounted with. The
/etc/amd.conf file defines some of the more
advanced features of amd.Consult the &man.amd.8; and &man.amd.conf.5; manual pages for more
information.JohnLindContributed by Problems Integrating with Other SystemsCertain 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 filesystem 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.5;), and
/project will be the mount point on the
client for the exported filesystem. 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
+ typically works with a block size of 8 k (though it
may do fragments of smaller sizes). Since the maximum Ethernet
- packet is around 1500 bytes, the NFS block gets
+ 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
+ with the entire 8 K 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.Jean-FrançoisDockèsUpdated by Diskless Operationdiskless workstationdiskless operationA FreeBSD machine can boot over the network and operate without a
local disk, using filesystems mounted from an NFS server. No system
modification is necessary, beyond standard configuration files.
Such a system is easy to set up because all the necessary elements
are readily available:There are at least two possible methods to load the kernel over
the network:PXE: Intel's Preboot Execution
Environment system is a form of smart boot ROM built into some
networking cards or motherboards. See &man.pxeboot.8; for more
details.The etherboot
port (net/etherboot)
produces ROM-able code to boot kernels over the network. The code
can be either burnt into a boot PROM on a network card, or loaded
from a local floppy (or hard) disk drive, or from a running
MS-DOS system. Many network cards are supported.A sample script
(/usr/share/examples/diskless/clone_root) eases
the creation and maintenance of the workstation's root filesystem
on the server. The script will probably require a little
customization but it will get you started very quickly.Standard system startup files exist in /etc
to detect and support a diskless system startup.Swapping, if needed, can be done either to an NFS file or to
a local disk.There are many ways to set up diskless workstations. Many
elements are involved, and most can be customized to suit local
taste. The following will describe the setup of a complete system,
emphasizing simplicity and compatibility with the
standard FreeBSD startup scripts. The system described has the
following characteristics:The diskless workstations use a shared
read-only root filesystem, and a shared
read-only /usr.The root filesystem is a copy of a
standard FreeBSD root (typically the server's), with some
configuration files overridden by ones specific to diskless
operation or, possibly, to the workstation they belong to.The parts of the root which have to be
writable are overlaid with &man.mfs.8; filesystems. Any changes
will be lost when the system reboots.The kernel is loaded by etherboot
, using DHCP (or BOOTP) and TFTP.As described, this system is insecure. It should
live in a protected area of a network, and be untrusted by
other hosts.Setup InstructionsConfiguring DHCP/BOOTPThere are two protocols that are commonly used to boot a
workstation that retrieves its configuration over the network: BOOTP
and DHCP. They are used at several points in the workstation
bootstrap:etherboot uses
DHCP (by default) or BOOTP (needs a configuration option) to
find the kernel. (PXE uses DHCP).The kernel uses BOOTP to locate the NFS
root.It is possible to configure a system to use only BOOTP.
The &man.bootpd.8; server program is included in the
base FreeBSD system.However, DHCP has a number of advantages over BOOTP (nicer
configuration files, possibility of using PXE, plus many others
not directly related to diskless operation), and we shall describe
both a pure BOOTP, and a BOOTP+DHCP configuration, with an
emphasis on the latter, which will use the ISC DHCP software
package.Configuration Using ISC DHCPThe isc-dhcp server can answer
both BOOTP and DHCP requests.As of release 4.4, isc-dhcp
3.0 is not part of the base
system. You will first need to install the
net/isc-dhcp3 port or the
corresponding package. Please refer to
for general information about ports and packages.Once isc-dhcp is installed, it
needs a configuration file to run, (normally named
/usr/local/etc/dhcpd.conf). Here follows
a commented example:
default-lease-time 600;
max-lease-time 7200;
authoritative;
option domain-name "example.com";
option domain-name-servers 192.168.4.1;
option routers 192.168.4.1;
subnet 192.168.4.0 netmask 255.255.255.0 {
use-host-decl-names on;
option subnet-mask 255.255.255.0;
option broadcast-address 192.168.4.255;
host margaux {
hardware ethernet 01:23:45:67:89:ab;
fixed-address margaux.example.com;
next-server 192.168.4.4;
filename "/tftpboot/kernel.diskless";
option root-path "192.168.4.4:/data/misc/diskless";
}
}
This option tells
dhcpd to send the value in the
host declarations as the hostname for the
diskless host. An alternate way would be to add an
option host-name
margaux inside the
host declarations.The
next-server directive designates
the TFTP server (the default is to use the same host as the
DHCP server).The
filename directive defines the file that
etherboot will load as a
kernel.
PXE appears to prefer a relative file
name, and it loads pxeboot, not the
kernel (option filename
"pxeboot").The
root-path option defines the path to
the root filesystem, in usual NFS notation.Configuration Using BOOTPHere follows an equivalent bootpd
configuration. This would be found in
/etc/bootptab.Please note that etherboot must
be compiled with the non-default option
NO_DHCP_SUPPORT in order to use BOOTP, and that PXE
needs DHCP. The only obvious advantage of
bootpd is that it exists in the base system.
.def100:\
:hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
:sm=255.255.255.0:\
:ds=192.168.4.1:\
:gw=192.168.4.1:\
:hd="/tftpboot":\
:bf="/kernel.diskless":\
:rp="192.168.4.4:/data/misc/diskless":
margaux:ha=0123456789ab:tc=.def100
Preparing a Boot Program with
EtherbootEtherboot's Web
site contains
extensive documentation mainly intended for Linux
systems, but nonetheless containing useful information. The following
will just outline how you would use
etherboot on a FreeBSD system.You must first install the
net/etherboot package or port. The
etherboot port can normally be found in
/usr/ports/net/etherboot. If the ports tree is
installed on your system, just typing make in
this directory should take care of everything. Else refer to
for information about ports and
packages.For our setup, we shall use a boot floppy. For other methods
(PROM, or dos program), please refer to the
etherboot documentation.To make a boot floppy, insert a floppy in the drive on the
machine where you installed etherboot,
then change your current directory to the src
directory in the etherboot tree and
type:
&prompt.root; gmake bin32/devicetype.fd0devicetype depends on the type of
the Ethernet card in the diskless workstation. Refer to the
NIC file in the same directory to determine the
right devicetype.Configuring the TFTP and NFS ServersYou need to enable tftpd on the TFTP
server:Create a directory from which tftpd
will serve the files, i.e.: /tftpbootAdd this line to your
/etc/inetd.conf:tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /tftpbootIt appears that at least some PXE versions want
the TCP version of TFTP. In this case, add a second line,
replacing dgram udp with stream
tcp.Tell inetd to reread its configuration
file:&prompt.root; kill -HUP `cat /var/run/inetd.pid`You can place the tftpboot
directory anywhere on the server. Make sure that the
location is set in both inetd.conf and
dhcpd.conf.You also need to enable NFS and export the
appropriate filesystem on the NFS server.Add this to /etc/rc.conf:nfs_server_enable="YES"Export the filesystem where the diskless root directory
is located by adding the following to
/etc/exports (adjust the volume mount
point and replace margaux with the name of the diskless workstation):/data/misc -alldirs -ro margauxTell mountd to reread its configuration
file. If you actually needed to enable NFS in /etc/rc.conf
at the first step, you probably want to reboot instead.&prompt.root; kill -HUP `cat /var/run/mountd.pid`Building a Diskless KernelCreate a kernel configuration file for the diskless client
with the following options (in addition to the usual
ones):
options BOOTP # Use BOOTP to obtain IP address/hostname
options BOOTP_NFSROOT # NFS mount root filesystem using BOOTP info
options BOOTP_COMPAT # Workaround for broken bootp daemons.
You may also want to use BOOTP_NFSV3 and
BOOTP_WIRED_TO (refer to LINT).Build the kernel (See ),
and copy it to the tftp directory, under the name listed
in dhcpd.conf.Preparing the root FilesystemYou need to create a root filesystem for the diskless
workstations, in the location listed as
root-path in
dhcpd.conf.The easiest way to do this is to use the
/usr/share/examples/diskless/clone_root
shell script. This script needs customization, at least to adjust the
place where the filesystem will be created (the
DEST variable).
Refer to the comments at the top of the script for
instructions. They explain how the base filesystem is built,
and how files may be selectively overridden by versions specific
to diskless operation, to a subnetwork, or to an individual
workstation. They also give examples for the diskless
/etc/fstab and
/etc/rc.conf files.The README files in
/usr/share/examples/diskless contain a lot
of interesting background information, but, together with the
other examples in the diskless directory,
they actually document a configuration method which is distinct
from the one used by clone_root and
/etc/rc.diskless[12], which is a little
confusing. Use them for reference only, except if you prefer
the method that they describe, in which case you will need
customized rc scripts.Configuring SwapIf needed, a swap file located on the server can be
accessed via NFS. The exact bootptab
or dhcpd.conf options are not clearly
documented at this time. The following configuration
suggestions have been reported to work in some installations
using isc-dhcp 3.0rc11.Add the following lines to
dhcpd.conf:
# Global section
option swap-path code 128 = string;
option swap-size code 129 = integer 32;
host margaux {
... # Standard lines, see above
option swap-path "192.168.4.4:/netswapvolume/netswap";
option swap-size 64000;
}
The idea is that, at least for a FreeBSD client,
DHCP/BOOTP option code 128 is the path to the NFS swap file,
and option code 129 is the swap size in kilobytes. Older
versions of dhcpd allowed a syntax of
option option-128 "..., which does not
seem to work any more./etc/bootptab would use the
following syntax instead:T128="192.168.4.4:/netswapvolume/netswap":T129=64000
On the NFS swap file server, create the swap
file(s)
&prompt.root; mkdir /netswapvolume/netswap
&prompt.root; cd /netswapvolume/netswap
&prompt.root; dd if=/dev/zero bs=1024 count=64000 of=swap.192.168.4.6
&prompt.root; chmod 0600 swap.192.168.4.6192.168.4.6 is the IP address
for the diskless client.On the NFS swap file server, add the following line to
/etc/exports:/netswapvolume -maproot=0:10 -alldirs margauxThen tell mountd to reread the
exports file, as above.Miscellaneous IssuesRunning with a read-only /usrIf the diskless workstation is configured to run X, you
will have to adjust the xdm configuration file, which puts
the error log on /usr by default.
Using a non-FreeBSD ServerWhen the server for the root filesystem is not running FreeBSD,
you will have to create the root filesystem on a
FreeBSD machine, then copy it to its destination, using
tar or cpio.In this situation, there are sometimes
problems with the special files in /dev,
due to differing major/minor integer sizes. A solution to this
problem is to export a directory from the non-FreeBSD server,
mount this directory onto a FreeBSD machine, and run
MAKEDEV on the FreeBSD machine
to create the correct device entries.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.HellmuthMichaelisContributed by ISDN CardsISDNcardsFreeBSD's ISDN implementation supports only the DSS1/Q.931
(or Euro-ISDN) standard using passive cards. Starting with
- FreeBSD 4.4, some active cards are supported where the firmware
+ FreeBSD 4.4, some active cards are supported where the firmware
also supports other signaling protocols; this also includes the
first supported Primary Rate (PRI) ISDN card.Isdn4bsd allows you to connect
to other ISDN routers using either IP over raw HDLC or by using
synchronous PPP: either by using kernel PPP with isppp, a
modified sppp driver, or by using userland &man.ppp.8;. By using
userland &man.ppp.8;, channel bonding of two or more ISDN
B-channels is possible. A telephone answering machine
application is also available as well as many utilities such as
a software 300 Baud modem.Some growing number of PC ISDN cards are supported under
FreeBSD and the reports show that it is successfully used all
over Europe and in many other parts of the world.The passive ISDN cards supported are mostly the ones with
the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets,
but also ISDN cards with chips from Cologne Chip (ISA bus only),
PCI cards with Winbond W6692 chips, some cards with the
Tiger300/320/ISAC chipset combinations and some vendor specific
chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the
AVM Fritz!Card PnP.Currently the active supported ISDN cards are the AVM B1
(ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.For documentation on isdn4bsd,
have a look at /usr/share/examples/isdn/
directory on your FreeBSD system or at the homepage of
isdn4bsd which also has pointers to hints, erratas and
much more documentation such as the isdn4bsd
handbook.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 &a.hm;.For questions regarding the installation, configuration
and troubleshooting isdn4bsd, a
majordomo maintained mailing list is available. To join, 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 known 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 that, 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
+ you to 115.2 Kbs, even though you have a 128 Kbs connection. To fully
+ utilize the 128 Kbs 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, and manages its own connection to the other
bridge/router. It has built in software to communicate via
PPP and other popular protocols.A router will allow you much faster throughput than 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,
such as your 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 (usually expensive) models
that
have two serial ports. Do not confuse this with channel bonding, MPP,
etc.This can be a very useful feature if, for example, you have an
dedicated ISDN connection at your office and would like to
tap into it, but do not want to get another ISDN line at work. A router
at the office location can manage a dedicated B channel connection
- (64Kbps) to the Internet and use the other B channel for a
+ (64 Kbps) to the Internet and use the other B channel for a
separate data connection. The second B channel can be used for
dial-in, dial-out or dynamically bonding (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.BillSwingleWritten by EricOgrenEnhanced by UdoErdelhoffNIS/YPWhat 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 pagesNISNIS was formerly known as Yellow Pages, but because of
trademark issues, Sun changed the name. The old term (and yp) is
still often seen and used.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 are not 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 as an NIS client:portmapTermDescriptionNIS domainnameAn 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.portmapMust 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.ypbindbinds 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.ypservShould 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 do not 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.yppasswddAnother 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
NIS server that it is bound to instead.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
+ 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 us 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 will not 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.Depending on your NIS setup, you may need to add
further entries. See the section about NIS servers
that are also NIS clients, below, for
details.Now, all you have to do is to run the command
/etc/netstart as superuser. It will
set up everything for you, using the values you defined in
/etc/rc.conf.Initializing the NIS MapsNISmapsThe 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 do not 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 do not 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 is time to initialize the NIS
maps! FreeBSD includes a script named
ypinit to do this for you
(see its manual page for more information). Note that this
script is available on most Unix Operating Systems, 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 these entries are
not mandatory, since the master server attempts to ensure
any changes to its NIS maps are communicated to its slaves
and because password information is vital to systems
depending on the server, 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, remove all user accounts from your
/etc/master.passwd file and use
vipw to add the following line to
the end of the file:+:::::::::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
section below for more information.
For more detailed reading see O'Reilly's book on
Managing NFS and NIS.You should keep at least one local account (i.e.
not imported via NIS) in your
/etc/master.passwd and this
account should also be a member of the group
wheel. If there is something
wrong with NIS, this account can be used to log in
remotely, become root, and fix things.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 do not 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;UdoErdelhoffContributed by Using NetgroupsnetgroupsThe method shown in the previous section 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 section 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 the 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 of
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 do not want to be propagating administrative
accounts and passwords to machines that will have users that
should not 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 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. If you do not want to do this manually each time you
reboot your NIS server, you can add the following lines to
your /etc/rc.conf:nis_client_enable="YES" # run client stuff as well
nis_client_flags="-S NIS domain,server"See &man.ypbind.8; for further information.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 libcrypt.a@ -> libdescrypt.a
lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 libcrypt.so@ -> libdescrypt.so
lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 libcrypt.so.2@ -> libdescrypt.so.2
lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 libcrypt_p.a@ -> libdescrypt_p.a
-r--r--r-- 1 root wheel 13018 Nov 8 14:27 libdescrypt.a
lrwxr-xr-x 1 root wheel 16 Nov 8 14:27 libdescrypt.so@ -> libdescrypt.so.2
-r--r--r-- 1 root wheel 12965 Nov 8 14:27 libdescrypt.so.2
-r--r--r-- 1 root wheel 14750 Nov 8 14:27 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 libcrypt.a@ -> libscrypt.a
lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 libcrypt.so@ -> libscrypt.so
lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 libcrypt.so.2@ -> libscrypt.so.2
lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 libcrypt_p.a@ -> libscrypt_p.a
-r--r--r-- 1 root wheel 6194 Nov 8 14:27 libscrypt.a
lrwxr-xr-x 1 root wheel 14 Nov 8 14:27 libscrypt.so@ -> libscrypt.so.2
-r--r--r-- 1 root wheel 7579 Nov 8 14:27 libscrypt.so.2
-r--r--r-- 1 root wheel 6684 Nov 8 14:27 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.GregSutterWritten by DHCPWhat Is DHCP?Dynamic Host Configuration ProtocolDHCPInternet 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 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 do not have a custom
kernel, you should not 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
should not 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 net/isc-dhcp3 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;
manual 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.CeriDaviesWritten by ceri@FreeBSD.orgInstalling And Configuring A DHCP ServerWhat this Section CoversThis section provides information on how to configure
a FreeBSD system to act as a DHCP server using the ISC
(Internet Software Consortium) implementation of the DHCP
suite.The server portion of the suite is not provided as part of
FreeBSD, and so you will need to install the
net/isc-dhcp3
port to provide this service. See for
more information on using the ports collection.DHCP Server InstallationDHCPinstallationIn order to configure your FreeBSD system as a DHCP server,
you will need to ensure that the &man.bpf.4;
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 you do not need to create a custom
kernel in order to get DHCP working.Those who are particularly security conscious
should note that bpf
is also the device that allows packet sniffers to work
correctly (although such programs still need privileged
access). bpfis required to use DHCP, but if
you are very sensitive about security, you probably
should not include bpf in your
kernel purely because you expect to use DHCP at some
point in the future.The next thing that you will need to do is edit the sample
dhcpd.conf which was installed by the
net/isc-dhcp3 port.
By default, this will be
/usr/local/etc/dhcpd.conf.sample, and you
should copy this to
/usr/local/etc/dhcpd.conf before proceeding
to make changes.Configuring the DHCP ServerDHCP configurationdhcpd.confdhcpd.conf is
comprised of declarations regarding subnets and hosts, and is
perhaps most easily explained using an example :option domain-name "example.com";
option domain-name-servers 192.168.4.100;
option subnet-mask 255.255.255.0;
default-lease-time 3600;
max-lease-time 86400;
ddns-update-style none;
subnet 192.168.4.0 netmask 255.255.255.0 {
range 192.168.4.129 192.168.4.254;
option routers 192.168.4.1;
}
host mailhost {
hardware ethernet 02:03:04:05:06:07;
fixed-address mailhost.example.com;
}This option specifies the domain that will be provided
to clients as the default search domain. See
&man.resolv.conf.5; for more information on what this
means.This option specifies a comma separated list of DNS
servers that the client should use.The netmask that will be provided to clients.A client may request a specific length of time that a
lease will be valid. Otherwise the server will assign
a lease with this expiry value (in seconds).This is the maximum length of time that the server will
lease for. Should a client request a longer lease, a lease
will be issued, although it will only be valid for
max-lease-time seconds.This option specifies whether the DHCP server should
attempt to update DNS when a lease is accepted or released.
In the ISC implementation, this option is
required.This denotes which IP addresses should be used in the
pool reserved for allocating to clients. IP addresses between,
and including, the ones stated are handed out to clients.Declares the default gateway that will be provided to
clients.The hardware MAC address of a host (so that the DHCP server
can recognise a host when it makes a request).Specifies that the host should always be given the same
IP address. Note that a hostname is OK here, since the DHCP
server will resolve the hostname itself before returning the
lease information.Once you have finished writing your
dhcpd.conf, you can proceed to start the
server by issuing the following command:&prompt.root; /usr/local/etc/rc.d/isc-dhcpd.sh startShould you need to make changes to the configuration of your
server in the future, it is important to note that sending a
SIGHUP signal to
dhcpd does not
result in the configuration being reloaded, as it does with most
daemons. You will need to send a SIGTERM
signal to stop the process, and then restart it using the command
above.FilesDHCPconfiguration files/usr/local/sbin/dhcpddhcpd is statically linked and
resides in /usr/local/sbin. The
dhcpd(8) manual page installed with the
port gives more information about
dhcpd./usr/local/etc/dhcpd.confdhcpd requires a configuration
file, /usr/local/etc/dhcpd.conf before it
will start providing service to clients. This file needs to
contain all the information that should be provided to clients
that are being serviced, along with information regarding the
operation of the server. This configuration file is described
by the dhcpd.conf(5) manual page installed
by the port./var/db/dhcpd.leasesThe DHCP server keeps a database of leases it has issued
in this file, which is written as a log. The manual page
dhcpd.leases(5), installed by the port
gives a slightly longer description./usr/local/sbin/dhcrelaydhcrelay is used in advanced
environments where one DHCP server forwards a request from a
client to another DHCP server on a separate network. The
dhcrelay(8) manual page provided with the
port contains more detail.ChernLeeContributed by DNSOverviewBINDFreeBSD 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 receive a reply with the IP address of The FreeBSD Project's
web server, 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. It is
not necessary to run a name server to perform DNS lookups on a system.
DNSDNS is coordinated across the Internet through a somewhat
complex system of authoritative root name servers, and other
smaller-scale name servers who host and cache individual domain
information.
This document refers to BIND 8.x, as it is the stable version
used in FreeBSD. BIND 9.x in FreeBSD can be installed through
the net/bind9 port.
RFC1034 and RFC1035 dictates the DNS protocol.
Currently, BIND is maintained by the
Internet Software Consortium (www.isc.org)TerminologyTo understand this document, some terms related to DNS must be
understood.TermDefinitionforward DNSmapping of hostnames to IP addressesoriginrefers to the domain covered for the particular zone
filenamed, bind, name servercommon names for the BIND name server package within
FreeBSDresolverresolvera system process through which a
machine queries a name server for zone informationreverse DNSreverse DNSthe opposite of forward DNS, mapping of IP addresses to
hostnamesroot zoneroot zoneliterally, 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.zoneEach individual domain, subdomain, or area dictated by
DNSzonesexamplesExamples of zones:
. is the root zoneorg. is a zone under the root zoneexample.org is a zone under the org. zonefoo.example.org. is a subdomain, a zone under the
example.org. zone
1.2.3.in-addr.arpa is a zone referencing all IP addresses
which fall under the 3.2.1.* IP space.
As one can see, the more specific part of a hostname appears to
its left. For example, example.org. is more
specific than org., as org. is
more specific than the root zone. The layout of each part of
a hostname is much like a filesystem: the /dev
directory falls within the root, and so on.Reasons to Run a Name ServerName servers usually come in two forms: an authoritative
name server, and a caching name server.An authoritative name server is needed when:one wants to serve DNS information to the
world, replying authoritatively to queries.a domain, such as example.org, is
registered and IP addresses need to be assigned to hostnames
under it.an IP address block requires reverse DNS entries (IP to
hostname).a backup name server, called a slave, must reply to queries
when the primary is down or inaccessible.A caching name server is needed when:a local DNS server may cache and respond more quickly
then querying an outside name server.a reduction in overall network traffic is desired (DNS
traffic has been measured to account for 5% or more of total
Internet traffic).When one queries for www.FreeBSD.org, the
resolver usually queries the uplink ISP's name server, and retrieves
the reply. With a local, caching DNS server, the query only has to
be made once to the outside world by the caching DNS server. Every
additional query will not have to look to the outside of the local
network, since the information is cached locally.How It WorksIn FreeBSD, the BIND daemon is called
named for obvious reasons.FileDescriptionnamedthe BIND daemonndcname daemon control program/etc/namedbdirectory where BIND zone information resides/etc/namedb/named.confdaemon configuration file
Zone files are usually contained within the
/etc/namedb
directory, and contain the DNS zone information
served by the 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 /etc/rc.conf:
named_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 the local reverse DNS zone file in
/etc/namedb/localhost.rev.
/etc/namedb/named.conf// $FreeBSD$
//
// Refer to the named(8) manual 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, to benefit from an uplink's cache,
forwarders can be enabled here. Under normal
circumstances, a name server will recursively query the Internet
looking at certain name servers until it finds the answer it is
looking for. Having this enabled will have it query the uplink's
name server (or name server provided) first, taking advantage of
its cache. If the uplink name server in question is a heavily
trafficked, fast name server, enabling this may be worthwhile.
127.0.0.1 will not work here.
Change this IP address to a name server at your uplink. /*
* If there is a firewall between you and name servers 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/sFor more information on running BIND in a sandbox, see
Running named in a sandbox.
/*
zone "example.com" {
type slave;
file "s/example.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;
};
};
*/In named.conf, these are examples of slave
entries for a forward and reverse zone.For each new zone served, a new zone entry must be added to
named.confFor example, the simplest zone entry for example.org can
look like:zone "example.org" {
type master;
file "example.org";
};The zone is a master, as indicated by the
statement, holding its zone information in
/etc/namedb/example.org indicated by
the statement.zone "example.org" {
type slave;
file "example.org";
};In the slave case, the zone information is transferred from
the master name server for the particular zone, and saved in the
file specified. If and when the master server dies or is
unreachable, the slave name server will have the transferred
zone information and will be able to serve it.Zone Files
An example master zone file for example.org
(existing within /etc/namedb/example.org)
is as follows:
$TTL 3600
example.org. IN SOA ns1.example.org. admin.example.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
86400 ) ; Minimum TTL
; DNS Servers
@ IN NS ns1.example.org.
@ IN NS ns2.example.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.example.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 example.org., so
www would translate to
www.example.org.
The format of a zone file follows:
recordname IN recordtype valueDNSrecords
The most commonly used DNS records:
SOAstart of zone authorityNSan authoritative name serverAA host addressCNAMEthe canonical name for an aliasMXmail exchangerPTRa domain name pointer (used in reverse DNS)
example.org. IN SOA ns1.example.org. admin.example.org. (
5 ; Serial
10800 ; Refresh after 3 hours
3600 ; Retry after 1 hour
604800 ; Expire after 1 week
86400 ) ; Minimum TTL of 1 dayexample.org.the domain name, also the origin for this
zone file.ns1.example.org.the primary/authoritative name server for this
zoneadmin.example.org.the responsible person for this zone,
email address with @
replaced. (admin@example.org becomes
admin.example.org)5the 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 name servers for a zone when it is
updated.
@ IN NS ns1.example.org.
This is an NS entry. Every name server that is going to reply
authoritatively for the zone must have one of these entries.
The @ as seen here could have been
example.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.example.org would resolve to
3.2.1.2. Again, the origin symbol, @, is
used here, thus meaning example.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
example.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.example.org.
The MX record indicates which mail servers are responsible
for handling incoming mail for the zone.
mail.example.org is the hostname of the mail server,
and 10 being the priority of that mail server.
One can have several mail servers, with priorities of 3, 2,
1. A mail server attempting to deliver to example.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.example.org. admin.example.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
3600 ) ; Minimum
@ IN NS ns1.example.org.
@ IN NS ns2.example.org.
2 IN PTR ns1.example.org.
3 IN PTR ns2.example.org.
10 IN PTR mail.example.org.
30 IN PTR example.org.
This file gives the proper IP address to hostname mappings of our above
fictitious domain.
Caching Name ServerBINDcaching name server
A caching name server is a name server 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.
CeriDaviesContributed by Running named in a SandboxBINDrunning in a sandboxchrootFor added security you may want to run &man.named.8; as an
unprivileged user, and configure it to &man.chroot.8; into a
sandbox directory. This makes everything outside of the sandbox
inaccessible to the named daemon. Should
named be compromised, this will help to
reduce the damage that can be caused. By default, FreeBSD has a user
and a group called bind, intended for this
use.Various people would recommend that instead of configuring
named to chroot, you
should run named inside a &man.jail.8;. This
section does not attempt to cover this situation.Since named will not be able to
access anything outside of the sandbox (such as shared
libraries, log sockets, and so on), there are a number of steps
that need to be followed in order to allow
named to function correctly. In the
following checklist, it is assumed that the path to the sandbox
is /etc/namedb and that you have made no
prior modifications to the contents of this directory. Perform
the following steps as root.Create all directories that named
expects to see:&prompt.root; cd /etc/namedb
&prompt.root; mkdir -p bin dev etc var/tmp var/run master slave
&prompt.root; chown bind:bind slave var/*named only needs write access to
these directories, so that is all we give it.Rearrange and create basic zone and configuration files:&prompt.root; cp /etc/localtime etc
&prompt.root; mv named.conf etc && ln -sf etc/named.conf
&prompt.root; mv named.root master
&prompt.root; sh make-localhost && mv localhost.rev localhost-v6.rev master
&prompt.root; cat > master/named.localhost
$ORIGIN localhost.
$TTL 6h
@ IN SOA localhost. postmaster.localhost. (
1 ; serial
3600 ; refresh
1800 ; retry
604800 ; expiration
3600 ) ; minimum
IN NS localhost.
IN A 127.0.0.1
^DThis allows named to log the
correct time to &man.syslogd.8;Build a statically linked copy of
named-xfer, and copy it into the sandbox:&prompt.root; cd /usr/src/lib/libisc && make clean all
&prompt.root; cd /usr/src/lib/libbind && make clean all
&prompt.root; cd /usr/src/libexec/named-xfer && make NOSHARED=yes all
&prompt.root; cp named-xfer /etc/namedb/bin && chmod 555 /etc/namedb/bin/named-xferThis step has been reported to fail occasionally. If this
happens to you, then issue the command:&prompt.root; cd /usr/src && make cleandir && make cleandirThis will clean out any cruft from your
source tree, and retrying the steps above should then work.Make a dev/null that
named can see and write to:&prompt.root; cd /etc/namedb/dev && mknod null c 2 2
&prompt.root; chmod 666 nullSymlink /var/run/ndc to
/etc/namedb/var/run/ndc:&prompt.root; ln -sf /etc/namedb/var/run/ndc /var/run/ndcThis simply avoids having to specify the
option to &man.ndc.8; every time you
run it. Since the contents of /var/run are deleted on boot,
if this is something that you find useful you
may wish to add this command to root's crontab, making use
of the option. See
&man.crontab.5; for more information regarding
this.Configure &man.syslogd.8; to create an extra
log socket that
named can write to. To do this,
add -l /etc/namedb/dev/log to the
syslogd_flags variable in
/etc/rc.conf.Arrange to have named start
and chroot itself to the sandbox by
adding the following to
/etc/rc.conf:named_enable="YES"
named_flags="-u bind -g bind -t /etc/namedb /etc/named.conf"Note that the configuration file
/etc/named.conf is denoted by a full
pathname relative to the sandbox, i.e. in
the line above, the file referred to is actually
/etc/namedb/etc/named.conf.The next step is to edit
/etc/namedb/etc/named.conf so that
named knows which zones to load and
where to find them on the disk. There follows a commented
example (anything not specifically commented here is no
different from the setup for a DNS server not running in a
sandbox):options {
directory "/";
named-xfer "/bin/named-xfer";
version ""; // Don't reveal BIND version
query-source address * port 53;
};
// ndc control socket
controls {
unix "/var/run/ndc" perm 0600 owner 0 group 0;
};
// Zones follow:
zone "localhost" IN {
type master;
file "master/named.localhost";
allow-transfer { localhost; };
notify no;
};
zone "0.0.127.in-addr.arpa" IN {
type master;
file "master/localhost.rev";
allow-transfer { localhost; };
notify no;
};
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 "master/localhost-v6.rev";
allow-transfer { localhost; };
notify no;
};
zone "." IN {
type hint;
file "master/named.root";
};
zone "private.example.net" in {
type master;
file "master/private.example.net.db";
allow-transfer { 192.168.10.0/24; };
};
zone "10.168.192.in-addr.arpa" in {
type slave;
masters { 192.168.10.2; };
file "slave/192.168.10.db";
};The
directory statement is specified as
/, since all files that
named needs are within this
directory (recall that this is equivalent to a
normal user's
/etc/namedb.Specifies the full path
to the named-xfer binary (from
named's frame of reference). This
is necessary since named is
compiled to look for named-xfer in
/usr/libexec by default.Specifies the filename (relative
to the directory statement above) where
named can find the zonefile for this
zone.Specifies the filename
(relative to the directory statement above)
where named should write a copy of
the zonefile for this zone after successfully transferring it
from the master server. This is why we needed to change the
ownership of the directory slave to
bind in the setup stages above.After completing the steps above, either reboot your
server or restart &man.syslogd.8; and start &man.named.8;, making
sure to use the new options specified in
syslogd_flags and
named_flags. You should now be running a
sandboxed copy of named!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-security-notifications
to stay up to date with the current Internet and FreeBSD security
issues.
If a problem arises, keeping sources up to date and having a
fresh build of named would not hurt.Further Reading
BIND/named manual pages: &man.ndc.8; &man.named.8; &man.named.conf.5;
Official ISC Bind
Page
BIND FAQO'Reilly
DNS and BIND 4th EditionRFC1034
- Domain Names - Concepts and FacilitiesRFC1035
- Domain Names - Implementation and SpecificationTomHukinsContributed by NTPNTPOverviewOver time, a computer's clock is prone to drift. As time
passes, the computer's clock becomes less accurate. NTP
(Network Time Protocol) is one way to ensure your clock is
right.Many Internet services rely on, or greatly benefit from,
computers' clocks being accurate. For example, a Web server
may receive requests to send a file if it has modified since a
certain time. Services such as &man.cron.8; run commands at a
given time. If the clock is inaccurate, these commands may
not run when expected.NTPntpdFreeBSD ships with the &man.ntpd.8; NTP server which can
be used to query other NTP servers to set the clock on your
machine or provide time services to others.Choosing Appropriate NTP ServersNTPchoosing serversIn order to synchronize your clock, you will need to find
one or more NTP servers to use. Your network administrator or
ISP may have setup an NTP server for this purpose—check
their documentation to see if this is the case. There is a
list of
publicly accessible NTP servers which you can use to
find an NTP server near to you. Make sure you are aware of
the policy for any servers you choose, and ask for permission
if required.Choosing several unconnected NTP servers is a good idea in
case one of the servers you are using becomes unreachable or
its clock is unreliable. &man.ntpd.8; uses the responses it
receives from other servers intelligently—it will favor
unreliable servers less than reliable ones.Configuring Your MachineNTPconfigurationBasic ConfigurationntpdateIf you only wish to synchronize your clock when the
machine boots up, you can use &man.ntpdate.8;. This may be
appropriate for some desktop machines which are frequently
rebooted and only require infrequent synchronization, but
most machines should run &man.ntpd.8;.Using &man.ntpdate.8; at boot time is also a good idea
for machines that run &man.ntpd.8;. &man.ntpd.8; changes the
clock gradually, whereas &man.ntpdate.8; sets the clock, no
matter how great the difference between a machine's current
clock setting and the correct time.To enable &man.ntpdate.8; at boot time, add
ntpdate_enable="YES" to
/etc/rc.conf. You will also need to
specify all servers you wish to synchronize with and any
flags to be passed to &man.ntpdate.8; in
ntpdate_flags.NTPntp.confGeneral ConfigurationNTP is configured by the
/etc/ntp.conf file in the format
described in &man.ntp.conf.5;. Here is a simple
example:server ntplocal.example.com prefer
server timeserver.example.org
server ntp2a.example.net
driftfile /var/db/ntp.driftThe server option specifies which
servers are to be used, with one server listed on each line.
If a server is specified with the prefer
argument, as with ntplocal.example.com, that server is
preferred over other servers. A response from a preferred
server will be discarded if it differs significantly from
other servers' responses, otherwise it will be used without
any consideration to other responses. The
prefer argument is normally used for NTP
servers that are known to be highly accurate, such as those
with special time monitoring hardware.The driftfile option specifies which
file is used to store the system clock's frequency offset.
&man.ntpd.8; uses this to automatically compensate for the
clock's natural drift, allowing it to maintain a reasonably
correct setting even if it is cut off from all external time
sources for a period of time.The driftfile option specifies which
file is used to store information about previous responses
from the NTP servers you are using. This file contains
internal information for NTP. It should not be modified by
any other process.Controlling Access to Your ServerBy default, your NTP server will be accessible to all
hosts on the Internet. The restrict
option in &man.ntp.conf.5; allows you to control which
machines can access your server.If you want to deny all machines from accessing your NTP
server, add the line restrict default ignore
to /etc/ntp.conf. If you only want to
allow machines within your own network to synchronize their
clocks with your server, but ensure they are not allowed to
configure the server or used as peers to synchronize
against, add restrict 192.168.1.0 mask 255.255.255.0 notrust nomodify notrap
instead, where 192.168.1.0 is
an IP address on your network and 255.255.255.0 is your network's
netmask./etc/ntp.conf can contain multiple
restrict options. For more details, see
the Access Control Support subsection of
&man.ntp.conf.5;.Running the NTP ServerTo ensure the NTP server is started at boot time, add the
line xntpd_enable="YES" to
/etc/rc.conf. If you wish to pass
additional flags to &man.ntpd.8; edit the
xntpd_flags parameter in
/etc/rc.conf.To start the server without rebooting your machine, run
ntpd being sure to specify any additional
parameters from xntpd_flags in
/etc/rc.conf. For example:&prompt.root; ntpd -p /var/run/ntpd.pidUsing &man.ntpd.8; with a temporary Internet
connectionntpd does not need a permanent
connection to the Internet to function properly. However, if
you have a temporary connection that is configured to dial out
on demand, it is a good idea to prevent NTP traffic from
triggering a dial out or keeping the connection alive. If you
are using user PPP, you can use filter
directives in /etc/ppp/ppp.conf. For
example: set filter dial 0 deny udp src eq 123
# Prevent NTP traffic from initiating dial out
set filter dial 1 permit 0 0
set filter alive 0 deny udp src eq 123
# Prevent incoming NTP traffic from keeping the connection open
set filter alive 1 deny udp dst eq 123
# Prevent outgoing NTP traffic from keeping the connection open
set filter alive 2 permit 0/0 0/0For more details see the PACKET
FILTERING section in &man.ppp.8; and the examples in
/usr/share/examples/ppp/.Some Internet access providers block low-numbered ports,
preventing NTP from functioning since replies never
reach your machine.Further InformationDocumentation for the NTP server can be found in
/usr/share/doc/ntp/ in HTML
format.ChernLeeContributed by Network Address TranslationOverviewnatdFreeBSD'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
increasingly in 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 LayoutA setup like this is commonly used to share an Internet
connection. One of the LAN machines is
connected to the Internet. The rest of the machines access
the Internet through that gateway
machine.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 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.ChernLeeContributed by inetd Super-ServerOverview&man.inetd.8; is referred to as the Internet
Super-Server because it manages connections for several
daemons. Programs that provide network service are commonly
known as daemons. inetd serves as a
managing server for other daemons. When a connection is
received by inetd, it determines
which daemon the connection is destined for, spawns the
particular daemon and delegates the socket to it. Running one
instance of inetd reduces the overall
system load as compared to running each daemon individually in
stand-alone mode.Primarily, inetd is used to
spawn other daemons, but several trivial protocols are handled
directly, such as chargen,
auth, and
daytime.This section will cover the basics in configuring
inetd through its command-line
options and its configuration file,
/etc/inetd.conf.Settingsinetd is initialized through
the /etc/rc.conf system. The
inetd_enable option is set to
NO by default, but is often times turned on by
sysinstall with the medium security
profile. Placing:
inetd_enable="YES" or
inetd_enable="NO" into
/etc/rc.conf can enable or disable
inetd starting at boot time.Additionally, different command-line options can be passed
to inetd via the
inetd_flags option.Command-Line Optionsinetd synopsis:-dTurn on debugging.-lTurn on logging of successful connections.-wTurn on TCP Wrapping for external services (on by
default).-WTurn on TCP Wrapping for internal services which are
built into inetd (on by
default).-c maximumSpecify the default maximum number of simultaneous
invocations of each service; the default is unlimited.
May be overridden on a per-service basis with the
parameter.-C rateSpecify the default maximum number of times a
service can be invoked from a single IP address in one
minute; the default is unlimited. May be overridden on a
per-service basis with the
parameter.-R rateSpecify the maximum number of times a service can be
invoked in one minute; the default is 256. A rate of 0
allows an unlimited number of invocations.-aSpecify one specific IP address to bind to.
Alternatively, a hostname can be specified, in which case
the IPv4 or IPv6 address which corresponds to that
hostname is used. Usually a hostname is specified when
inetd is run inside a
&man.jail.8;, in which case the hostname corresponds to
the &man.jail.8; environment.When hostname specification is used and both IPv4
and IPv6 bindings are desired, one entry with the
appropriate protocol type for each binding is required for
each service in /etc/inetd.conf. For
example, a TCP-based service would need two entries, one
using ``tcp4'' for the protocol and the other using
``tcp6''.-pSpecify an alternate file in which to store the
process ID.These options can be passed to
inetd using the
inetd_flags option in
/etc/rc.conf. By default,
inetd_flags is set to -wW,
which turns on TCP wrapping for
inetd's internal and external
services. For novice users, these parameters usually do not need
to be modified or even entered in
/etc/rc.conf.An external service is a daemon outside of
inetd, which is invoked when a
connection is received for it. On the other hand, an internal
service is one that inetd has the
facility of offering within itself.inetd.confConfiguration of inetd is
controlled through the /etc/inetd.conf
file.When a modification is made to
/etc/inetd.conf,
inetd can be forced to re-read its
configuration file by sending a HangUP signal to the
inetd process as shown:Sending inetd a HangUP Signal&prompt.root; kill -HUP `cat /var/run/inetd.pid`Each line of the configuration file specifies an
individual daemon. Comments in the file are preceded by a
#. The format of
/etc/inetd.conf is as follows:service-name
socket-type
protocol
{wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]
user[:group][/login-class]
server-program
server-program-argumentsAn example entry for the ftpd daemon
using IPv4:ftp stream tcp nowait root /usr/libexec/ftpd ftpd -lservice-nameThis is the service name of the particular daemon.
It must correspond to a service listed in
/etc/services. This determines which
port inetd must listen to. If
a new service is being created, it must be placed in
/etc/services
first.socket-typeEither stream,
dgram, raw, or
seqpacket. stream
must be used for connection-based, TCP daemons, while
dgram is used for daemons utilizing the
UDP transport protocol.protocolOne of the following:ProtocolExplanationtcp, tcp4TCP IPv4udp, udp4UDP IPv4tcp6TCP IPv6udp6UDP IPv6tcp46Both TCP IPv4 and v6udp46Both UDP IPv4 and v6{wait|nowait}[/max-child[/max-connections-per-ip-per-minute]] indicates whether the
daemon invoked from inetd is
able to handle its own socket or not.
socket types must use the wait
option, while stream socket daemons, which are usually
multi-threaded, should use .
usually hands off multiple sockets
to a single daemon, while spawns a
child daemon for each new socket.The maximum number of child daemons
inetd may spawn can be set using
the option. If a limit of ten
instances of a particular daemon is needed, a
/10 would be placed after
.In addition to , another
option limiting the maximum connections from a single
place to a particular daemon can be enabled.
does
just this. A value of ten here would limit any particular
IP address connecting to a particular service to ten
attempts per minute. This is useful to prevent
intentional or unintentional resource consumption and
Denial of Service (DoS) attacks to a machine.In this field, or
is mandatory.
and
are
optional.A stream-type multi-threaded daemon without any
or
limits
would simply be: nowaitThe same daemon with a maximum limit of ten daemons
would read: nowait/10Additionally, the same setup with a limit of twenty
connections per IP address per minute and a maximum
total limit of ten child daemons would read:
nowait/10/20These options are all utilized by the default
settings of the fingerd daemon,
as seen here:finger stream tcp nowait/3/10 nobody /usr/libexec/fingerd fingerd -suserThe user is the username that the particular daemon
should run as. Most commonly, daemons run as the
root user. For security purposes, it is
common to find some servers running as the
daemon user, or the least privileged
nobody user.server-programThe full path of the daemon to be executed when a
connection is received. If the daemon is a service
provided by inetd internally,
then should be
used.server-program-argumentsThis works in conjunction with
by specifying the
arguments, starting with argv[0], passed to the daemon on
invocation. If mydaemon -d is
the command line, mydaemon -d would be
the value of .
Again, if the daemon is an internal service, use
here.SecurityDepending on the security profile chosen at install, many
of inetd's daemons may be enabled by
default. If there is no apparent need for a particular daemon,
disable it! Place a # in front of the daemon in
question, and send a hangup signal
to inetd.
Some daemons, such as fingerd, may
not be desired at all because they provide an attacker with too
much information.Some daemons are not security-conscious and have long, or
non-existent timeouts for connection attempts. This allows an
attacker to slowly send connections to a particular daemon, thus
saturating available resources. It may be a good idea to place
and
limitations on certain daemons.By default, TCP wrapping is turned on. Consult the
&man.hosts.access.5; manual page for more information on placing
TCP restrictions on various inetd
invoked daemons.Miscellaneousdaytime,
time,
echo,
discard,
chargen, and
auth are all internally provided
services of inetd.The auth service provides identity
(ident, identd) network services, and is configurable to a certain
degree.Consult the &man.inetd.8; manual page for more in-depth
information.Parallel Line IP (PLIP)PLIPParallel Line IPPLIP lets us run TCP/IP between parallel ports. It is
useful on machines without network cards, or to install on
laptops. In this section, we will discuss:Creating a parallel (laplink) cable.connecting two computers with PLIP.Creating a Parallel CableYou can purchase a parallel cable at most computer supply
stores. If you can't do that, or you just want to know how
it's done, here's how you make one out of a normal parallel
printer cable.
Setting up PLIPGet a laplink cable.Confirm that both computers have a kernel with lpt driver
support.&prompt.root; dmesg | grep lp
lpt0 at 0x378-0x37f irq 7 on isa
lpt0: Interrupt-driven
lp0: TCP/IP capable interfacePlug in the laplink cable into the parallel interface on
both computers.Configure the network interface parameters for lp0 on both
sites as root. For example, if you want connect
the host host1 with host2 host1 <-----> host2
IP Address 10.0.0.1 10.0.0.2Configure the interface on host1 by doing:&prompt.root; ifconfig lp0 10.0.0.1 10.0.0.2Configure the interface on host2 by doing:&prompt.root; ifconfig lp0 10.0.0.2 10.0.0.1You now should have a working connection. Please read the
manual pages &man.lp.4; and &man.lpt.4; for more details.You should also add both hosts to
/etc/hosts.127.0.0.1 localhost.my.domain localhost
10.0.0.1 host1.my.domain host1
10.0.0.2 host2.my.domainTo confirm the connection works, go to each host and ping
the other. For example, on host1:&prompt.root; ifconfig lp0
lp0: flags=8851<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500
inet 10.0.0.1 --> 10.0.0.2 netmask 0xff000000
&prompt.root; netstat -r
Routing tables
Internet:
Destination Gateway Flags Refs Use Netif Expire
host2 host1 UH 4 127592 lp0
&prompt.root; ping -c 4 host2
PING host2 (10.0.0.2): 56 data bytes
64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
--- host2 ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 msAaronKaplanOriginally Written by TomRhodesRestructured and Added by IPv6IPv6 (also know as IPng IP next generation) is
the new version of the well known IP protocol (also know as
IPv4). Like the other current *BSD systems,
FreeBSD includes the KAME IPv6 reference implementation.
So your FreeBSD system comes with all you will need to experiment with IPv6.
This section focuses on getting IPv6 configured and running.In the early 1990s, people became aware of the rapidly
diminishing address space of IPv4. Given the expansion rate of the
Internet there were two major concerns:Running out of addresses. Today this is not so much of a concern
anymore since private address spaces (10.0.0.0/8, 192.168.0.0/24,
etc.) and natd address translation are being employed.Router table entries were getting to large. This is still a concern
today.IPv6 deals with these and many other issues:128 bit address space. In other words theoretically there are
340,282,366,920,938,463,463,374,607,431,768,211,456 addresses
available. This means there are approximately. 6.67 * 10^27 IPv6 addresses
per square meter on our planet.Routers will only store network aggregation addresses in their routing
tables thus reducing the average space of a routing table to 8192
entries.There are also lots of other useful features of IPv6 such as:Address autoconfiguration (RFC2462)Anycast addresses (one-out-of many)Mandatory multicast addressesIPSec (IP Security)Simplified header structureMobile IPIPv4-to-IPv6 transition mechanismsFor more information see:IPv6 overview at Sun.comIPv6.orgKAME.net6bone.netBackground on IPv6 AddressesThere are different types of IPv6 addresses: Unicast, Anycast and
Multicast.Unicast addresses are the well known addresses. A packet sent
to a unicast address arrives exactly at the interface belonging to
the address.Anycast addresses are syntactically indistinguishable from unicast
addresses but they address a group of interfaces. The packet destined for
an anycast address will arrive at the nearest (in router metric)
interface. Anycast addresses may only be used by routers.Multicast addresses identify a group of interfaces. A packet destined
for a multicast address will arrive at all interfaces belonging to the
multicast group.The IPv4 broadcast address (usually xxx.xxx.xxx.255) is expressed
by multicast addresses in IPv6.Reserved IPv6 addresses:ipv6-address prefixlength(Bits) description Notes
:: 128 Bits unspecified cf. 0.0.0.0 in IPv4 address
::1 128 Bits loopback address cf. 127.0.0.1 in IPv4
::00:xx:xx:xx:xx 96 Bits embedded IPv4 The lower 32 bits are the
address IPv4 address. Also called
IPv4 compatible IPv6
address
::ff:xx:xx:xx:xx 96 Bits IPv4 mapped The lower 32 bits are the
IPv6 address IPv4 address. For hosts
which do not support IPv6
fe80:: - feb:: 10 Bits link-local cf. loopback address in
IPv4
fec0:: - fef:: 10 Bits site-local
ff:: 8 Bits multicast
001 (base 2) 3 Bits global unicast All global unicast
addresses are assigned from
this pool. The first 3 Bits
are 001.Reading IPv6 AddressesThe canonical form is represented as: x:x:x:x:x:x:x:x, each
x being a 16 Bit hex value. For example
FEBC:A574:382B:23C1:AA49:4592:4EFE:9982Often an address will have long substrings of all zeros therefore each
such substring can be abbreviated by ::. For example fe80::1
corresponds to the canonical form fe80:0000:0000:0000:0000:0000:0000:0001A third form is to write the last 32 Bit part in the well known (decimal)
IPv4 style with dots . as separators. For example 2002::10.0.0.1
corresponds to the (hexadecimal) canonical representation
2002:0000:0000:0000:0000:0000:000a:0001 which in turn is equivalent to
writing 2002::a:1By now the reader should be able to understand the following:&prompt.root; ifconfigrl0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500
inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255
inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1
ether 00:00:21:03:08:e1
media: Ethernet autoselect (100baseTX )
status: activefe80::200:21ff:fe03:8e1%rl0 is an auto configured link-local address. It
includes the enscrambled Ethernet MAC as part of the auto configuration.For further information on the structure of IPv6 addresses see RFC2373Getting ConnectedCurrently there are four ways to connect to other IPv6 hosts and networks:Join the experimental 6boneGetting an IPv6 network from your upstream provider. Talk to your
Internet provider for instructions.Tunnel via 6-to-4Use the freenet6 port if you are on a dial-up connection.Here we will talk on how to connect to the 6bone since it currently seems
to be the most popular way.First take a look at the 6bone site and find a 6bone connection nearest to
you. Write to the responsible person and with a little bit of luck you
will be given instructions on how to set up your connection. Usually this
involves setting up a GRE (gif) tunnel.Here is a typical example on setting up a &man.gif.4; tunnel:&prompt.root; ifconfig create gif0&prompt.root; ifconfig gif0gif0: flags=8010<POINTOPOINT,MULTICAST> mtu 1280&prompt.root; ifconfig tunnel MY_IPv4_ADDR HIS_IPv4_ADDR&prompt.root; ifconfig gif0 inet6 alias MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDRReplace the capitalized words by the information you received from the
upstream 6bone nodeThis establishes the tunnel. Check if the tunnel is working by &man.ping6.8;
'ing ff02::1%gif0. You should receive two ping replies.In case you are intrigued by the address ff02:1%gif0, this is a
multicast address. %gif0 states that the multicast address at network
interface gif0 is to be used. Since we ping a multicast address the
other endpoint of the tunnel should reply as well).By now setting up a route to your 6bone uplink should be rather
straightforward:&prompt.root; route add -inet6 default -interface gif0&prompt.root; ping6 -n MY_UPLINK&prompt.root; traceroute6 www.jp.freebsd.org(3ffe:505:2008:1:2a0:24ff:fe57:e561) from 3ffe:8060:100::40:2, 30 hops max, 12 byte packets
1 atnet-meta6 14.147 ms 15.499 ms 24.319 ms
2 6bone-gw2-ATNET-NT.ipv6.tilab.com 103.408 ms 95.072 ms *
3 3ffe:1831:0:ffff::4 138.645 ms 134.437 ms 144.257 ms
4 3ffe:1810:0:6:290:27ff:fe79:7677 282.975 ms 278.666 ms 292.811 ms
5 3ffe:1800:0:ff00::4 400.131 ms 396.324 ms 394.769 ms
6 3ffe:1800:0:3:290:27ff:fe14:cdee 394.712 ms 397.19 ms 394.102 msThis output will differ from machine to machine. By now you should be
able to reach the IPv6 site www.kame.net
and see the dancing tortoise - that is if you have a IPv6 enabled browser such as
mozilla+ipv6.DNS in the IPv6 WorldThere are two new types of DNS records for IPv6:AAAA records,A6recordsUsing AAAA records is straightforward. Assign your hostname to the new
IPv6 address you just got by adding:MYHOSTNAME AAAA MYIPv6ADDRTo your primary zone DNS file. In case you don't serve your own
DNS zones ask your DNS provider.
Current versions of bind (version 8.3 and 9)
support AAAA records.
diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
index bd7a9fc329..8bf94b4038 100644
--- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
@@ -1,3108 +1,3108 @@
JimMockRestructured and parts updated by Brian N.HandyOriginally contributed by RichMurpheyLinux Binary CompatibilitySynopsisLinux binary compatibilitybinary compatibilityLinuxFreeBSD provides binary compatibility with several other
Unix-like operating systems, including Linux. At this point,
you may be asking yourself why exactly, does
FreeBSD need to be able to run Linux binaries? The answer to that
question is quite simple. Many companies and developers develop
only for Linux, since it is the latest hot thing in
the computing world. That leaves the rest of us FreeBSD users
bugging these same companies and developers to put out native
FreeBSD versions of their applications. The problem is, that most
of these companies do not really realize how many people would use
their product if there were FreeBSD versions too, and most continue
to only develop for Linux. So what is a FreeBSD user to do? This
is where the Linux binary compatibility of FreeBSD comes into
play.In a nutshell, the compatibility allows FreeBSD users to run
about 90% of all Linux applications without modification. This
includes applications such as Star Office,
the Linux version of Netscape,
Adobe Acrobat,
RealPlayer
5 and 7, VMWare,
Oracle,
WordPerfect, Doom,
Quake, and more. It is also reported
that in some situations, Linux binaries perform better on FreeBSD
than they do under Linux.Linux/proc filesystemThere are, however, some Linux-specific operating system
features that are not supported under FreeBSD. Linux binaries will
not work on FreeBSD if they overly use the Linux
/proc filesystem (which is different from
FreeBSD's /proc filesystem), or i386-specific
calls, such as enabling virtual 8086 mode.After reading this chapter, you will know:How to enable Linux binary compatibility on your system.How to install additional Linux shared
libraries.How to install Linux applications on your FreeBSD system.The implementation details of Linux compatibility in FreeBSD.Before reading this chapter, you should:Know how to install additional third-party
software ().InstallationKLD (kernel loadable object)Linux binary compatibility is not turned on by default. The
easiest way to enable this functionality is to load the
linux KLD object (Kernel LoaDable
object). You can load this module by simply typing
linux at the command prompt.If you would like Linux compatibility to always be enabled,
then you should add the following line to
/etc/rc.conf:linux_enable="YES"This, in turn, triggers the following action in
/etc/rc.i386:# Start the Linux binary compatibility if requested.
#
case ${linux_enable} in
[Yy][Ee][Ss])
echo -n ' linux'; linux > /dev/null 2>&1
;;
esacThe &man.kldstat.8; command can be used to verify that the
KLD is loaded:&prompt.user; kldstat
Id Refs Address Size Name
1 2 0xc0100000 16bdb8 kernel
7 1 0xc24db000 d000 linux.kokernel optionsLINUXIf for some reason you do not want to or cannot load the KLD,
then you may statically link Linux binary compatibility into the kernel
by adding options LINUX to your kernel
configuration file. Then install your new kernel as described in
.Installing Linux Runtime LibrariesLinuxinstalling Linux librariesThis can be done one of two ways, either by using the
linux_base port, or
by installing them manually.Installing Using the linux_base Portports collectionThis is by far the easiest method to use when installing the
runtime libraries. It is just like installing any other port
from the ports collection.
Simply do the following:&prompt.root; cd /usr/ports/emulators/linux_base
&prompt.root; make install distcleanYou should now have working Linux binary compatibility.
Some programs may complain about incorrect minor versions of the
system libraries. In general, however, this does not seem to be
a problem.Installing Libraries ManuallyIf you do not have the ports collection
installed, you can install the libraries by hand instead. You
will need the Linux shared libraries that the program depends on
and the runtime linker. Also, you will need to create a
shadow root directory,
/compat/linux, for Linux libraries on your
FreeBSD system. Any shared libraries opened by Linux programs
run under FreeBSD will look in this tree first. So, if a Linux
program loads, for example, /lib/libc.so,
FreeBSD will first try to open
/compat/linux/lib/libc.so, and if that does
not exist, it will then try /lib/libc.so.
Shared libraries should be installed in the shadow tree
/compat/linux/lib rather than the paths
that the Linux ld.so reports.Generally, you will need to look for the shared libraries
that Linux binaries depend on only the first few times that you
install a Linux program on your FreeBSD system. After a while,
you will have a sufficient set of Linux shared libraries on your
system to be able to run newly imported Linux binaries without
any extra work.How to Install Additional Shared Librariesshared librariesWhat if you install the linux_base port
and your application still complains about missing shared
libraries? How do you know which shared libraries Linux
binaries need, and where to get them? Basically, there are 2
possibilities (when following these instructions you will need
to be root on your FreeBSD system).If you have access to a Linux system, see what shared
libraries the application needs, and copy them to your FreeBSD
system. Look at the following example:Let us assume you used FTP to get the Linux binary of
Doom, and put it on a Linux system you have access to. You
then can check which shared libraries it needs by running
ldd linuxdoom, like so:&prompt.user; ldd linuxdoom
libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0
libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0
libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29symbolic linksYou would need to get all the files from the last column,
and put them under /compat/linux, with
the names in the first column as symbolic links pointing to
them. This means you eventually have these files on your
FreeBSD system:/compat/linux/usr/X11/lib/libXt.so.3.1.0
/compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0
/compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
Note that if you already have a Linux shared library
with a matching major revision number to the first column
of the ldd output, you will not need to
copy the file named in the last column to your system, the
one you already have should work. It is advisable to copy
the shared library anyway if it is a newer version,
though. You can remove the old one, as long as you make
the symbolic link point to the new one. So, if you have
these libraries on your system:/compat/linux/lib/libc.so.4.6.27
/compat/linux/lib/libc.so.4 -> libc.so.4.6.27and you find a new binary that claims to require a
later version according to the output of
ldd:libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29If it is only one or two versions out of date in the
in the trailing digit then do not worry about copying
/lib/libc.so.4.6.29 too, because the
program should work fine with the slightly older version.
However, if you like, you can decide to replace the
libc.so anyway, and that should leave
you with:/compat/linux/lib/libc.so.4.6.29
/compat/linux/lib/libc.so.4 -> libc.so.4.6.29
The symbolic link mechanism is
only needed for Linux binaries. The
FreeBSD runtime linker takes care of looking for matching
major revision numbers itself and you do not need to worry
about it.
Installing Linux ELF BinariesLinuxELF binariesELF binaries sometimes require an extra step of
branding. If you attempt to run an unbranded ELF
binary, you will get an error message like the following:&prompt.user; ./my-linux-elf-binary
ELF binary type not known
AbortTo help the FreeBSD kernel distinguish between a FreeBSD ELF
binary from a Linux binary, use the &man.brandelf.1;
utility.&prompt.user; brandelf -t Linux my-linux-elf-binaryGNU toolchainThe GNU toolchain now places the appropriate branding
information into ELF binaries automatically, so you this step
should become increasingly more rare in the future.Configuring the Hostname ResolverIf DNS does not work or you get this message:resolv+: "bind" is an invalid keyword resolv+:
"hosts" is an invalid keywordYou will need to configure a
/compat/linux/etc/host.conf file
containing:order hosts, bind
multi onThe order here specifies that /etc/hosts
is searched first and DNS is searched second. When
/compat/linux/etc/host.conf is not
installed, Linux applications find FreeBSD's
/etc/host.conf and complain about the
incompatible FreeBSD syntax. You should remove
bind if you have not configured a name server
using the /etc/resolv.conf file.MurrayStokelyUpdated for Mathematica 4.X by BojanBistrovicMerged with work by Installing MathematicaapplicationsMathematicaThis document describes the process of installing the Linux
version of Mathematica 4.X onto
a FreeBSD system.The Linux version of Mathematica
runs perfectly under FreeBSD
however the binaries shipped by Wolfram need to be branded so that
FreeBSD knows to use the Linux ABI to execute them.The Linux version of Mathematica
or Mathematica for Students can
be ordered directly from Wolfram at http://www.wolfram.com/.Branding the Linux BinariesThe Linux binaries are located in the Unix
directory of the Mathematica CDROM
distributed by Wolfram. You
need to copy this directory tree to your local hard drive so that
you can brand the Linux binaries with &man.brandelf.1; before
running the installer:&prompt.root; mount /cdrom
&prompt.root; cp -rp /cdrom/Unix/ /localdir/
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm
&prompt.root; cd /localdir/Installers/Linux/
&prompt.root; ./MathInstallerAlternatively, you can simply set the default ELF brand
to Linux for all unbranded binaries with the command:&prompt.root; sysctl kern.fallback_elf_brand=3This will make FreeBSD assume that unbranded ELF binaries
use the Linux ABI and so you should be able to run the
installer straight from the CDROM.Obtaining Your Mathematica PasswordBefore you can run Mathematica
you will have to obtain a
password from Wolfram that corresponds to your machine
ID.EthernetMAC addressOnce you have installed the Linux compatibility runtime
libraries and unpacked Mathematica
you can obtain the
machine ID by running the program
mathinfo in the Install directory. This
machine ID is based solely on the MAC address of your first
Ethernet card.&prompt.root; cd /localdir/Files/SystemFiles/Installation/Binaries/Linux
&prompt.root; mathinfo
disco.example.com 7115-70839-20412When you register with Wolfram, either by email, phone or fax,
you will give them the machine ID and they will
respond with a corresponding password consisting of groups of
numbers. You can then enter this information when you attempt to
run Mathematica for the first time
exactly as you would for any other
Mathematica platform.Running the Mathematica Frontend over a NetworkMathematica uses some special
fonts to display characters not
present in any of the standard font sets (integrals, sums, Greek
letters, etc.). The X protocol requires these fonts to be install
locally. This means you will have to copy
these fonts from the CDROM or from a host with
Mathematica
installed to your local machine. These fonts are normally stored
in /cdrom/Unix/Files/SystemFiles/Fonts on the
CDROM, or
/usr/local/mathematica/SystemFiles/Fonts on
your hard drive. The actual fonts are in the subdirectories
Type1 and X. There are
several ways to use them, as described below.The first way is to copy them into one of the existing font
directories in /usr/X11R6/lib/X11/fonts.
This will require editing the fonts.dir file,
adding the font names to it, and changing the number of fonts on
the first line. Alternatively, you should also just be able to
run mkfontdir in the directory you have copied
them to.The second way to do this is to copy the directories to
/usr/X11R6/lib/X11/fonts:&prompt.root; cd /usr/X11R6/lib/X11/fonts
&prompt.root; mkdir X
&prompt.root; mkdir MathType1
&prompt.root; cd /cdrom/Unix/Files/SystemFiles/Fonts
&prompt.root; cp X/* /usr/X11R6/lib/X11/fonts/X
&prompt.root; cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1
&prompt.root; cd /usr/X11R6/lib/X11/fonts/X
&prompt.root; mkfontdir
&prompt.root; cd ../MathType1
&prompt.root; mkfontdirNow add the new font directories to your font path:&prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/X
&prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/MathType1
&prompt.root; xset fp rehashIf you are using the XFree86 server, you can have these font
directories loaded automatically by adding them to your
XF86Config file.fontsIf you do not already have a directory
called /usr/X11R6/lib/X11/fonts/Type1, you
can change the name of the MathType1
directory in the example above to
Type1.AaronKaplanContributed by RobertGetschmannThanks to Installing MapleapplicationsMapleMaple is a commercial mathematics program similar to
Mathematica. You must purchase this software from and then register there
for a license file. To install this software on FreeBSD, please
follow these simple steps.Execute the INSTALL shell
script from the product distribution. Choose the
RedHat option when prompted by the
installation program. A typical installation directory
might be /usr/local/mapleIf you have not done so, order a license for Maple
from Maple Waterloo Software (http://register.maplesoft.com)
and copy it to
/usr/local/maple/license/license.datInstall the FLEXlm
license manager by running the
INSTALL_LIC install shell script that
comes with Maple. Specify the
primary hostname for your machine for the license
server.Patch the
usr/local/maple/bin/maple.system.type
file with the following: ----- snip ------------------
*** maple.system.type.orig Sun Jul 8 16:35:33 2001
--- maple.system.type Sun Jul 8 16:35:51 2001
***************
*** 72,77 ****
--- 72,78 ----
# the IBM RS/6000 AIX case
MAPLE_BIN="bin.IBM_RISC_UNIX"
;;
+ "FreeBSD"|\
"Linux")
# the Linux/x86 case
# We have two Linux implementations, one for Red Hat and
----- snip end of patch -----Please note that after the "FreeBSD"|\ no other
whitespace should be present.This patch instructs Maple to
recognize FreeBSD as a type of Linux system.
The bin/maple shell script calls the
bin/maple.system.type shell script
which in turn calls uname -a to find out the operating
system name. Depending on the OS name it will find out which
binaries to use.Start the license server.The following script, installed as
/usr/local/etc/rc.d/lmgrd.sh is a
convenient way to start up lmgrd: ----- snip ------------
#! /bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin
PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX
export PATH
LICENSE_FILE=/usr/local/maple/license/license.dat
LOG=/var/log/lmgrd.log
case "$1" in
start)
lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2
echo -n " lmgrd"
;;
stop)
lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2
;;
*)
echo "Usage: `basename $0` {start|stop}" 1>&2
exit 64
;;
esac
exit 0
----- snip ------------Test-start maple:&prompt.user; cd /usr/local/maple/bin
&prompt.user; ./xmapleYou should be up and running. Make sure to write
Maplesoft to let them know you would like a native FreeBSD
version!Common PitfallsThe FLEXlm license manager can be a difficult
tool to work with. Additional documentation on the subject
can be found at .lmgrd is known to be very picky
about the license file and to core dump if there are any
problems. A correct license file should look like this:# =======================================================
# License File for UNIX Installations ("Pointer File")
# =======================================================
SERVER chillig ANY
#USE_SERVER
VENDOR maplelmg
FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \
PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \
ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \
SN=XXXXXXXXXSerial number and key 'X''ed out. "chillig" is a
hostname.Editing the license file works as long as you do not
touch the "FEATURE" line (which is protected by the
license key).MarcelMoolenaarContributed by Installing OracleapplicationsOraclePrefaceThis document describes the process of installing Oracle 8.0.5 and
Oracle 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD
machineInstalling the Linux EnvironmentMake sure you have both linux_base and
linux_devtools from the ports collection
installed. These ports are added to the collection after the release
- of FreeBSD 3.2. If you are using FreeBSD 3.2 or an older version for
+ of FreeBSD 3.2. If you are using FreeBSD 3.2 or an older version for
that matter, update your ports collection. You may want to consider
updating your FreeBSD version too. If you run into difficulties with
linux_base-6.1 or
linux_devtools-6.1 you may have to use version
5.2 of these packages.If you want to run the intelligent agent, you will
also need to install the Red Hat Tcl package:
tcl-8.0.3-20.i386.rpm. The general command
for installing packages with the official RPM port is:&prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm packageInstallation of the package should not generate any errors.Creating the Oracle EnvironmentBefore you can install Oracle, you need to set up a proper
environment. This document only describes what to do
specially to run Oracle for Linux on FreeBSD, not
what has been described in the Oracle installation guide.Kernel Tuningkernel tuningAs described in the Oracle installation guide, you need to set
the maximum size of shared memory. Do not use
SHMMAX under FreeBSD. SHMMAX
is merely calculated out of SHMMAXPGS and
PGSIZE. Therefore define
SHMMAXPGS. All other options can be used as
described in the guide. For example:options SHMMAXPGS=10000
options SHMMNI=100
options SHMSEG=10
options SEMMNS=200
options SEMMNI=70
options SEMMSL=61Set these options to suit your intended use of Oracle.Also, make sure you have the following options in your kernel
config-file:options SYSVSHM #SysV shared memory
options SYSVSEM #SysV semaphores
options SYSVMSG #SysV interprocess communicationOracle AccountCreate an Oracle account just as you would create any other
account. The Oracle account is special only that you need to give
it a Linux shell. Add /compat/linux/bin/bash to
/etc/shells and set the shell for the Oracle
account to /compat/linux/bin/bash.EnvironmentBesides the normal Oracle variables, such as
ORACLE_HOME and ORACLE_SID you must
set the following environment variables:VariableValueLD_LIBRARY_PATH$ORACLE_HOME/libCLASSPATH$ORACLE_HOME/jdbc/lib/classes111.zipPATH/compat/linux/bin
/compat/linux/sbin
/compat/linux/usr/bin
/compat/linux/usr/sbin
/bin
/sbin
/usr/bin
/usr/sbin
/usr/local/bin
$ORACLE_HOME/binIt is advised to set all the environment variables in
.profile. A complete example is:ORACLE_BASE=/oracle; export ORACLE_BASE
ORACLE_HOME=/oracle; export ORACLE_HOME
LD_LIBRARY_PATH=$ORACLE_HOME/lib
export LD_LIBRARY_PATH
ORACLE_SID=ORCL; export ORACLE_SID
ORACLE_TERM=386x; export ORACLE_TERM
CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip
export CLASSPATH
PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin
PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin
PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin
export PATHInstalling OracleDue to a slight inconsistency in the Linux emulator, you need to
create a directory named .oracle in
/var/tmp before you start the installer. Either
make it world writable or let it be owner by the oracle user. You
should be able to install Oracle without any problems. If you have
problems, check your Oracle distribution and/or configuration first!
After you have installed Oracle, apply the patches described in the
next two subsections.A frequent problem is that the TCP protocol adapter is not
installed right. As a consequence, you cannot start any TCP listeners.
The following actions help solve this problem:&prompt.root; cd $ORACLE_HOME/network/lib
&prompt.root; make -f ins_network.mk ntcontab.o
&prompt.root; cd $ORACLE_HOME/lib
&prompt.root; ar r libnetwork.a ntcontab.o
&prompt.root; cd $ORACLE_HOME/network/lib
&prompt.root; make -f ins_network.mk installDo not forget to run root.sh again!Patching root.shWhen installing Oracle, some actions, which need to be performed
as root, are recorded in a shell script called
root.sh. root.sh is
written in the orainst directory. Apply the
following patch to root.sh, to have it use to proper location of
chown or alternatively run the script under a
Linux native shell.*** orainst/root.sh.orig Tue Oct 6 21:57:33 1998
--- orainst/root.sh Mon Dec 28 15:58:53 1998
***************
*** 31,37 ****
# This is the default value for CHOWN
# It will redefined later in this script for those ports
# which have it conditionally defined in ss_install.h
! CHOWN=/bin/chown
#
# Define variables to be used in this script
--- 31,37 ----
# This is the default value for CHOWN
# It will redefined later in this script for those ports
# which have it conditionally defined in ss_install.h
! CHOWN=/usr/sbin/chown
#
# Define variables to be used in this scriptWhen you do not install Oracle from CD, you can patch the source
for root.sh. It is called
rthd.sh and is located in the
orainst directory in the source tree.Patching genclntshThe script genclntsh is used to create
a single shared client
library. It is used when building the demos. Apply the following
patch to comment out the definition of PATH:*** bin/genclntsh.orig Wed Sep 30 07:37:19 1998
--- bin/genclntsh Tue Dec 22 15:36:49 1998
***************
*** 32,38 ****
#
# Explicit path to ensure that we're using the correct commands
#PATH=/usr/bin:/usr/ccs/bin export PATH
! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
#
# each product MUST provide a $PRODUCT/admin/shrept.lst
--- 32,38 ----
#
# Explicit path to ensure that we're using the correct commands
#PATH=/usr/bin:/usr/ccs/bin export PATH
! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
#
# each product MUST provide a $PRODUCT/admin/shrept.lstRunning OracleWhen you have followed the instructions, you should be able to run
Oracle as if it was run on Linux
itself.HolgerKippContributed by ValentinoVaschettoOriginal version converted to SGML by Installing SAP R/3applicationsSAP R/3Installations of SAP Systems using FreeBSD will not be
supported by the SAP support team — they only offer support
for certified platforms.PrefaceThis document describes a possible way of installing a
SAP R/3-System
with Oracle Database
for Linux onto a FreeBSD machine, including the installation
of FreeBSD and Oracle. Two different
configurations will be described:SAP R/3 4.6B (IDES) with
Oracle 8.0.5 on FreeBSD 4.3-STABLESAP R/3 4.6C with
Oracle 8.1.7 on FreeBSD 4.5-STABLEEven though this document tries to describe all important
steps in a greater detail, it is not intended as a replacement
for the Oracle and
SAP R/3 installation guides.Please see the documentation that comes with the
SAP R/3
Linux edition for SAP- and
Oracle-specific questions, as well
as resources from Oracle and
SAP OSS.SoftwareThe following CD-ROMs have been used for SAP-installations:SAP R/3 4.6B, Oracle 8.0.5NameNumberDescriptionKERNEL51009113SAP Kernel Oracle /
Installation / AIX, Linux, SolarisRDBMS51007558Oracle / RDBMS 8.0.5.X /
LinuxEXPORT151010208IDES / DB-Export /
Disc 1 of 6EXPORT251010209IDES / DB-Export /
Disc 2 of 6EXPORT351010210IDES / DB-Export /
Disc 3 of 6EXPORT451010211IDES / DB-Export /
Disc 4 of 6EXPORT551010212IDES / DB-Export /
Disc 5 of 6EXPORT651010213IDES / DB-Export /
Disc 6 of 6Additionally, I used the Oracle 8
Server (Pre-production version 8.0.5 for Linux,
Kernel Version 2.0.33) CD which is not really necessary, and
of course FreeBSD 4.3-STABLE (it was only a few days past 4.3
RELEASE).SAP R/3 4.6C SR2, Oracle 8.1.7NameNumberDescriptionKERNEL51014004SAP Kernel Oracle /
SAP Kernel Version 4.6D / DEC, LinuxRDBMS51012930Oracle 8.1.7/ RDBMS /
LinuxEXPORT151013953Release 4.6C SR2 / Export
/ Disc 1 of 4EXPORT151013953Release 4.6C SR2 / Export
/ Disc 2 of 4EXPORT151013953Release 4.6C SR2 / Export
/ Disc 3 of 4EXPORT151013953Release 4.6C SR2 / Export
/ Disc 4 of 4LANG151013954Release 4.6C SR2 /
Language / DE, EN, FR / Disc 1 of 3Depending on the languages you would like to install, additional
language CDs might be necessary. Here we're just using DE and EN, so
the first Language-CD is the only one needed. As a little note, the
numbers for all four export CDs are identical. All three language CDs
also have the same number (this is different from the 4.6B IDES
release CD numbering). At the time of writing this installation is
running on FreeBSD 4.5-STABLE (20.03.2002).SAP-NotesThe following notes should be read before installing
SAP R/3 or proved to be useful
during installation:SAP R/3 4.6B, Oracle 8.0.5NumberTitle0171356SAP Software on Linux: Essential
Comments0201147INST: 4.6C R/3 Inst. on UNIX -
Oracle0373203Update / Migration Oracle 8.0.5 -->
8.0.6/8.1.6 LINUX0072984Release of Digital UNIX 4.0B for
Oracle0130581R3SETUP step DIPGNTAB terminates0144978Your system has not been installed
correctly0162266Questions and tips for R3SETUP on Windows
NT / W2KSAP R/3 4.6C, Oracle 8.1.7NumberTitle0015023Initializing table TCPDB (RSXP0004)
(EBCDIC)0045619R/3 with several languages or
typefaces0171356SAP Software on Linux: Essential
Comments0195603RedHat 6.1 Enterprise version:
Known problems0212876The new archiving tool SAPCAR0300900Linux: Released DELL Hardware0377187RedHat 6.2: important remarks0387074INST: R/3 4.6C SR2 Installation on
UNIX0387077INST: R/3 4.6C SR2 Inst. on UNIX -
Oracle0387078SAP Software on UNIX: OS Dependencies
4.6C SR2Hardware-RequirementsThe following equipment is sufficient for the installation
of a SAP R/3 System. For production
use, a more exact sizing is of course needed:Component4.6B4.6CProcessor2 x 800MHz Pentium III2 x 800MHz Pentium IIIMemory1GB ECC2GB ECCHard Disk Space50-60GB (IDES)50-60GB (IDES)For use in production, Xeon-Processors with large cache,
high-speed disk access (SCSI, RAID hardware controller), USV
and ECC-RAM is recommended. The large amount of hard disk
space is due to the preconfigured IDES System, which creates
- 27 GB of database files during installation. This space is
+ 27 GB of database files during installation. This space is
also sufficient for initial production systems and application
data.SAP R/3 4.6B, Oracle 8.0.5The following off-the-shelf hardware was used: a dual processor
- board with 2 800MHz Pentium III processors, Adaptec 29160 Ultra160
- SCSI adapter (for accessing a 40/80 GB DLT tape drive and CDROM),
- Mylex AcceleRAID (2 channels, firmware 6.00-1-00 with 32MB RAM).
- To the Mylex Raid-controller are attached two 17GB hard disks
- (mirrored) and four 36GB hard disks (RAID level 5).
+ board with 2 800 MHz Pentium III processors, Adaptec 29160 Ultra160
+ SCSI adapter (for accessing a 40/80 GB DLT tape drive and CDROM),
+ Mylex AcceleRAID (2 channels, firmware 6.00-1-00 with 32 MB RAM).
+ To the Mylex Raid-controller are attached two 17 GB hard disks
+ (mirrored) and four 36 GB hard disks (RAID level 5).
SAP R/3 4.6C, Oracle 8.1.7For this installation a DELL PowerEdge 2500 was used: a
- dual processor board with two 1000MHz Pentium III processors
- (256kB Cache), 2GB PC133 ECC SDRAM, PERC/3 DC PCI Raid Controller
- with 128MB, and an EIDE DVD-ROM drive. To the RAID-controller are
- attached two 18GB hard disks (mirrored) and four 36GB hard disks
+ dual processor board with two 1000 MHz Pentium III processors
+ (256 kB Cache), 2 GB PC133 ECC SDRAM, PERC/3 DC PCI Raid Controller
+ with 128 MB, and an EIDE DVD-ROM drive. To the RAID-controller are
+ attached two 18 GB hard disks (mirrored) and four 36 GB hard disks
(RAID level 5).Installation of FreeBSDFirst you have to install FreeBSD. There are several ways to do
- this (FreeBSD 4.3 was installed via FTP, FreeBSD 4.5 directly from
+ this (FreeBSD 4.3 was installed via FTP, FreeBSD 4.5 directly from
release-CD).Disk LayoutTo keep it simple, the same disk layout both for the
SAP R/3 46B- and SAP R/3 46C
SR2-installation was used. Only the device names
changed, as the installations were on different hardware (/dev/da
and /dev/amr respectively, so if using an AMI MegaRAID, one will see
/dev/amr0s1a instead of /dev/da0s1a):FilesystemSize (1k-blocks)Size (GB)Mounted on/dev/da0s1a1.016.3031//dev/da0s1b6<swap>/dev/da0s1e2.032.6232/var/dev/da0s1f8.205.3398/usr/dev/da1s1e45.734.36145/compat/linux/oracle/dev/da1s1f2.032.6232/compat/linux/sapmnt/dev/da1s1g2.032.6232/compat/linux/usr/sapConfigure and initialize the two logical drives
with the Mylex- or PERC/3 RAID software beforehand.
The software can be started during the
bios boot phase. Please note that this disk layout differs slightly from
the SAP recommendations, as SAP suggests mounting the
oracle-subdirectories (and some others) separately - I
decided to just create them as real subdirectories for
simplicity.make world and a New KernelDownload the latest stable-sources. Rebuild world and your
custom kernel after configuring your kernel configuration file.
Here you should also include the
kernel parameters
which are required for both SAP R/3
and Oracle.Installing the Linux EnvironmentDuring the first installation with FreeBSD 4.3-STABLE I had some
trouble downloading the required RPM-files (for 4.3 stable, 2nd May
2001), but with FreeBSD 4.5-STABLE, everything went very smooth.
Should you encounter some problems, try to download those files by
hand. For a list of RPM-Mirrors and required files, see the
corresponding makefile.Installing Linux Base-systemFirst the linux_base
port needs to be installed (as root). This is
currently linux_base-6.&prompt.root; cd /usr/ports/emulators/linux_base
&prompt.root; make packageInstalling Linux DevelopmentThe Linux development is needed, if you want to install
Oracle on FreeBSD according to the
corresponding description in the handbook:&prompt.root; cd /usr/ports/devel/linux_devtools
&prompt.root; make packageLinux Development has only been installed for the SAP
R/3 46B IDES- installation. It is not needed, if
the Oracle DB is not relinked on the
FreeBSD system. This is the case if you are using the
Oracle tarball from a linux system.Installing Necessary RPMsRPMsTo start the R3SETUP-Program, pam support is needed.
During the first SAP-Installation on FreeBSD 4.3-STABLE I
tried to install pam with all the required packages and
finally forced the installation of the pam package, which
worked. For SAP R/3 4.6C SR2 I
directly forced the installation of pam rpm, which also
works, so it seems the dependend packages are not needed:&prompt.root; rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm \
pam-0.68-7.i386.rpmFor Oracle 8.0.5 to run the
intelligent agent, I also had to install the RedHat Tcl package
tcl-8.0.5-30.i386.rpm (otherwise the
relinking during Oracle install
will not work). There are some other issues regarding
relinking of Oracle, but that is
a Oracle-Linux issue, not FreeBSD specific.Some additional hintsIt might also be a good idea to add linprocfs
to /etc/fstab. See man linprocfs.
Another parameter to set is kern.fallback_elf_brand=3
which is done in file /etc/sysctl.conf.
Creating the SAP/R3 EnvironmentCreating the Necessary Filesystems and MountpointsFor a simple installation, it is sufficient to create the
following filesystems:mountpointsize in GB/compat/linux/oracle45 GB/compat/linux/sapmnt2 GB/compat/linux/usr/sap2 GBIt is also necessary to created some links. Otherwise
the SAP-Installer will complain, as it is checking the
created links:&prompt.root; ln -s /compat/linux/oracle /oracle
&prompt.root; ln -s /compat/linux/sapmnt /sapmnt
&prompt.root; ln -s /compat/linux/usr/sap /usr/sapPossible error message during installation (here with
System PRD and the
SAP R/3 4.6C SR2
installation):INFO 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:200
Checking existence of symbolic link /usr/sap/PRD/SYS/exe/dbg to
/sapmnt/PRD/exe. Creating if it does not exist...
WARNING 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:400
Link /usr/sap/PRD/SYS/exe/dbg exists but it points to file
/compat/linux/sapmnt/PRD/exe instead of /sapmnt/PRD/exe. The
program cannot go on as long as this link exists at this
location. Move the link to another location.
ERROR 2002-03-19 16:45:36 R3LINKS_IND_IND Ins_SetupLinks:0
can not setup link '/usr/sap/PRD/SYS/exe/dbg' with content
'/sapmnt/PRD/exe'Creating Users and DirectoriesSAP R/3 needs two users and
three groups. The usernames depend on the
SAP system id (SID) which consists
of three letters. Some of these SIDs are reserved
by SAP (for example
SAP and NIX. For a
complete list please see the SAP documentation). For the IDES
installation I used IDS, for the
4.6C SR2 installation PRD, as that system
is intended for production use. We have
therefore the following groups (group ids might differ, these
are just the values I used with my installation):group idgroup namedescription100dbaData Base Administrator101sapsysSAP System102operData Base OperatorFor a default Oracle-Installation, only group
dba is used. As
oper-group, one also uses group
dba (see Oracle- and
SAP-documentation for further information).We also need the following users:user idusernamegeneric namegroupadditional groupsdescription1000idsadm/prdadm<sid>admsapsysoperSAP Administrator1002oraids/oraprdora<sid>dbaoperDB AdministratorAdding the users with adduser
requires the following (please note shell and home
directory) entries for SAP-Administrator:Name: <sid>adm
Password: ******
Fullname: SAP Administrator <SID>
Uid: 1000
Gid: 101 (sapsys)
Class:
Groups: sapsys dba
HOME: /home/<sid>adm
Shell: bash (/compat/linux/bin/bash)and for Database-Administrator:Name: ora<sid>
Password: ******
Fullname: Oracle Administrator <SID>
Uid: 1002
Gid: 100 (dba)
Class:
Groups: dba
HOME: /oracle/<sid>
Shell: bash (/compat/linux/bin/bash)This should also include group
oper in case you are using both
groups dba and
oper.Creating DirectoriesThese directories are usually created as separate
filesystems. This depends entirely on your requirements. I
choose to create them as simple directories, as they are all
located on the same RAID 5 anyway:First we will set owners and rights of some directories (as
user root):&prompt.root; chmod 775 /oracle
&prompt.root; chmod 777 /sapmnt
&prompt.root; chown root:dba /oracle
&prompt.root; chown <sid>adm:sapsys /compat/linux/usr/sap
&prompt.root; chmod 775 /compat/linux/usr/sapSecond we will create directories as user
ora<sid>. These
will all be subdirectories of
/oracle/<SID>:&prompt.root; su - ora<sid>
&prompt.root; cd /oracle/<SID>
&prompt.root; mkdir mirrlogA mirrlogB origlogA origlogB
&prompt.root; mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6
&prompt.root; mkdir saparch sapreorg
&prompt.root; exitFor the Oracle 8.1.7-installation
some additional directories are needed:&prompt.root; su - ora<sid>
&prompt.root; cd /oracle
&prompt.root; mkdir 805_32
&prompt.root; mkdir client stage
&prompt.root; mkdir client/80x_32
&prompt.root; mkdir stage/817_32
&prompt.root; cd /oracle/<SID>
&prompt.root; mkdir 817_32The directory client/80x_32 is used
with exactly this name. Don't replace the x
with some number or anything.In the third step we create directories as user
<sid>adm:&prompt.root; su - <sid>adm
&prompt.root; cd /usr/sap
&prompt.root; mkdir <SID>
&prompt.root; mkdir trans
&prompt.root; exitEntries in /etc/servicesSAP R/3 requires some entries in file
/etc/services, which will not be set
correctly during installation under FreeBSD. Please add the
following entries (you need at least those entries
corresponding to the instance number - in this case,
00. It will do no harm adding all
entries from 00 to
99 for dp,
gw, sp and
ms). If you are going to use a saprouter
or need to access SAP OSS, you also need 99,
as port 3299 is usually used for the saprouter process on the
target system:
sapdp00 3200/tcp # SAP Dispatcher. 3200 + Instance-Number
sapgw00 3300/tcp # SAP Gateway. 3300 + Instance-Number
sapsp00 3400/tcp # 3400 + Instance-Number
sapms00 3500/tcp # 3500 + Instance-Number
sapms<SID> 3600/tcp # SAP Message Server. 3600 + Instance-Number
sapgw00s 4800/tcp # SAP Secure Gateway 4800 + Instance-NumberNecessary LocaleslocaleSAP requires at least two locales that are not part of
the default RedHat installation. SAP offers the required
RPMs as download from their FTP-server (which is only
accessible if you are a customer with OSS-access). See note
0171356 for a list of RPMs you need.It is also possible to just create appropriate links
(for example from de_DE and
en_US ), but I would not recommend this
for a production system (so far it worked with the IDES
system without any problems, though). The following locales
are needed:de_DE.ISO-8859-1
en_US.ISO-8859-1Create the links like this:&prompt.root; cd /compat/linux/usr/share/locale
&prompt.root; ln -s de_DE de_DE.ISO-8859-1
&prompt.root; ln -s en_US en_US.ISO-8859-1If they are not present, there will be some problems
during the installation. If these are then subsequently
ignored (by setting the status of the offending steps to
OK in file CENTRDB.R3S), it will be impossible to log onto
the SAP-system without some additional effort.Kernel Tuningkernel tuningSAP R/3 Systems need a lot of resources. I therefore
added the following parameters to my kernel config-file:# Set these for memory pigs (SAP and Oracle):
options MAXDSIZ="(1024*1024*1024)"
options DFLDSIZ="(1024*1024*1024)"
# System V options needed.
options SYSVSHM #SYSV-style shared memory
options SHMMAXPGS=262144 #max amount of shared mem. pages
#options SHMMAXPGS=393216 #use this for the 46C inst.parameters
options SHMMNI=256 #max number of shared memory ident if.
options SHMSEG=100 #max shared mem.segs per process
options SYSVMSG #SYSV-style message queues
options MSGSEG=32767 #max num. of mes.segments in system
options MSGSSZ=32 #size of msg-seg. MUST be power of 2
options MSGMNB=65535 #max char. per message queue
options MSGTQL=2046 #max amount of msgs in system
options SYSVSEM #SYSV-style semaphores
options SEMMNU=256 #number of semaphore UNDO structures
options SEMMNS=1024 #number of semaphores in system
options SEMMNI=520 #number of semaphore indentifiers
options SEMUME=100 #number of UNDO keysThe minimum values are specified in the documentation that
comes from SAP. As there is no description for Linux, see the
HP-UX-section (32-bit) for further information. As the system
for the 4.6C SR2 installation has more main memory, the shared
segments can be larger both for SAP
and Oracle, therefore choose a larger
number of shared memory pages.
- With the default installation of FreeBSD 4.5 on x386,
- leave MAXDSIZ and DFLDSIZ at 1GB maximum. Otherwise, strange
+ With the default installation of FreeBSD 4.5 on x386,
+ leave MAXDSIZ and DFLDSIZ at 1 GB maximum. Otherwise, strange
errors like ORA-27102: out of memory and
Linux Error: 12: Cannot allocate memory
might happen.Installing SAP R/3Preparing SAP CDROMsThere are many CDROMs to mount and unmount during the
installation. Assuming you have enough CDROM-drives, you
can just mount them all. I decided to copy the CDROM
contents to corresponding directories:/oracle/<SID>/sapreorg/<cd-name>where <cd-name> was one of KERNEL,
RDBMS, EXPORT1,
EXPORT2, EXPORT3,
EXPORT4, EXPORT5 and
EXPORT6 for the 4.6B/IDES-installation, and
KERNEL, RDBMS,
DISK1, DISK2,
DISK3, DISK4 and
LANG for the 4.6C SR2-installation. All the
filenames on the mounted CDs should be in capital letters,
otherwise use the -g option for mounting. So use the following
commands:&prompt.root; mount_cd9660 -g /dev/cd0a /mnt
&prompt.root; cp -R /mnt/* /oracle/<SID>/sapreorg/<cd-name>
&prompt.root; umount /mntRunning the install-scriptFirst you have to prepare an install-directory:&prompt.root; cd /oracle/<SID>/sapreorg
&prompt.root; mkdir install
&prompt.root; cd installThen the install-script is started, which will copy nearly
all the relevant files into the install-directory:&prompt.root; /oracle/<SID>/sapreorg/KERNEL/UNIX/INSTTOOL.SHThe IDES-Installation (4.6B) comes with a fully customized
SAP R/3 Demo-System, so there are six instead of just three
EXPORT-CDs. At this point the installation template
CENTRDB.R3S is for installing a standard
central instance (R/3 and Database), not the IDES central
instance, so one needs to copy the corresponding CENTRDB.R3S
from the EXPORT1 directory, otherwise R3SETUP will only ask
for three EXPORT-CDs.The newer SAP 4.6C SR2-release
comes with four EXPORT-CDs. The parameter-file that controls
the installation-steps is CENTRAL.R3S.
Contrary to earlier releases there are no separate installation
templates for a central instance with or without database.
SAP is using a separate template for DB-installation. To restart
the installation later it is however sufficient to restart with
the original file.During and after installation, SAP requires
hostname to return the computer name
only, not the fully qualified domain name. So either
set the hostname accordingly, or set an alias with
alias hostname='hostname -s' for
both ora<sid> and
<sid>adm (and for
root at least during installation
steps performed as root). It is also
possible to adjust the installed profile- and login-scripts of
both users that are installed during
SAP-installation.Start R3SETUP 4.6BMake sure LD_LIBRARY_PATH is set correctly:&prompt.root; export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/libStart R3SETUP as root from
installation directory:&prompt.root; cd /oracle/IDS/sapreorg/install
&prompt.root; ./R3SETUP -f CENTRDB.R3SThe script then asks some questions (defaults in brackets,
followed by actual input):QuestionDefaultInputEnter SAP System ID[C11]IDS<ret>Enter SAP Instance Number[00]<ret>Enter SAPMOUNT Directory[/sapmnt]<ret>Enter name of SAP central host[troubadix.domain.de]<ret>Enter name of SAP db host[troubadix]<ret>Select character set[1] (WE8DEC)<ret>Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.61<ret>Extract Oracle Client archive[1] (Yes, extract)<ret>Enter path to KERNEL CD[/sapcd]/oracle/IDS/sapreorg/KERNELEnter path to RDBMS CD[/sapcd]/oracle/IDS/sapreorg/RDBMSEnter path to EXPORT1 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT1Directory to copy EXPORT1 CD[/oracle/IDS/sapreorg/CD4_DIR]<ret>Enter path to EXPORT2 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT2Directory to copy EXPORT2 CD[/oracle/IDS/sapreorg/CD5_DIR]<ret>Enter path to EXPORT3 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT3Directory to copy EXPORT3 CD[/oracle/IDS/sapreorg/CD6_DIR]<ret>Enter path to EXPORT4 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT4Directory to copy EXPORT4 CD[/oracle/IDS/sapreorg/CD7_DIR]<ret>Enter path to EXPORT5 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT5Directory to copy EXPORT5 CD[/oracle/IDS/sapreorg/CD8_DIR]<ret>Enter path to EXPORT6 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT6Directory to copy EXPORT6 CD[/oracle/IDS/sapreorg/CD9_DIR]<ret>Enter amount of RAM for SAP + DB850<ret> (in Megabytes)Service Entry Message Server[3600]<ret>Enter Group-ID of sapsys[101]<ret>Enter Group-ID of oper[102]<ret>Enter Group-ID of dba[100]<ret>Enter User-ID of <sid>adm[1000]<ret>Enter User-ID of ora<sid>[1002]<ret>Number of parallel procs[2]<ret>If you had not copied the CDs to the different locations,
then the SAP-Installer cannot find the CD needed (identified
by the LABEL.ASC-File on CD) and would
then ask you to insert and mount the CD and confirm or enter
the mount path.The CENTRDB.R3S might not be
error-free. In my case, it requested EXPORT4 again (but
indicated the correct key (6_LOCATION, then 7_LOCATION
etc.), so one can just continue with entering the correct
values. Do not get irritated.Apart from some problems mentioned below, everything
should go straight through up to the point where the Oracle
database software needs to be installed.Start R3SETUP 4.6C SR2Make sure LD_LIBRARY_PATH is set correctly. This is a
different value from the 4.6B installation with
Oracle 8.0.5:&prompt.root; export LD_LIBRARY_PATH=/sapmnt/PRD/exe:/oracle/PRD/817_32/libStart R3SETUP as user root from installation directory:&prompt.root; cd /oracle/PRD/sapreorg/install
&prompt.root; ./R3SETUP -f CENTRAL.R3SThe script then asks some questions (defaults in brackets,
followed by actual input):QuestionDefaultInputEnter SAP System ID[C11]PRD<ret>Enter SAP Instance Number[00]<ret>Enter SAPMOUNT Directory[/sapmnt]<ret>Enter name of SAP central host[majestix]<ret>Enter Database System ID[PRD]PRD<ret>Enter name of SAP db host[majestix]<ret>Select character set[1] (WE8DEC)<ret>Enter Oracle server version (2) Oracle 8.1.72<ret>Extract Oracle Client archive[1] (Yes, extract)<ret>Enter path to KERNEL CD[/sapcd]/oracle/PRD/sapreorg/KERNELEnter amount of RAM for SAP + DB20441800<ret> (in Megabytes)Service Entry Message Server[3600]<ret>Enter Group-ID of sapsys[100]<ret>Enter Group-ID of oper[101]<ret>Enter Group-ID of dba[102]<ret>Enter User-ID of oraprd[1002]<ret>Enter User-ID of prdadm[1000]<ret>LDAP support3<ret> (no support)Installation step completed[1] (continue)<ret>Choose installation service[1] (DB inst,file)<ret>So far, creation of users gives an error during
installation in phases OSUSERDBSID_IND_ORA (for creating
user ora<sid>) and
OSUSERSIDADM_IND_ORA (creating user
<sid>adm).Apart from some problems mentioned below, everything
should go straight through up to the point where the Oracle
database software needs to be installed.Installing Oracle 8.0.5Please see the corresponding SAP-Notes and Oracle Readmes
regarding Linux and Oracle DB for possible problems. Most if
not all problems stem from incompatible librariesFor more information on installing Oracle, refer to the Installing Oracle
chapter.Installing the Oracle 8.0.5 with orainstIf Oracle 8.0.5 is to be
used, some additional libraries are needed for successfully
relinking, as Oracle 8.0.5 was linked with an old glibc
(RedHat 6.0), but RedHat 6.1 already uses a new glibc. So
you have to install the following additional packages to
ensure that linking will work:compat-libs-5.2-2.i386.rpmcompat-glibc-5.2-2.0.7.2.i386.rpmcompat-egcs-5.2-1.0.3a.1.i386.rpmcompat-egcs-c++-5.2-1.0.3a.1.i386.rpmcompat-binutils-5.2-2.9.1.0.23.1.i386.rpmSee the corresponding SAP-Notes or Oracle Readmes for
further information. If this is no option (at the time of
installation I did not have enough time to check this), one
could use the original binaries, or use the relinked
binaries from an original RedHat System.For compiling the intelligent agent, the RedHat Tcl
package must be installed. If you cannot get
tcl-8.0.3-20.i386.rpm, a newer one like
tcl-8.0.5-30.i386.rpm for RedHat 6.1
should also do.Apart from relinking, the installation is
straightforward:&prompt.root; su - oraids
&prompt.root; export TERM=xterm
&prompt.root; export ORACLE_TERM=xterm
&prompt.root; export ORACLE_HOME=/oracle/IDS
&prompt.root; cd /ORACLE_HOME/orainst_sap
&prompt.root; ./orainstConfirm all Screens with Enter until the software is
installed, except that one has to deselect the
Oracle On-Line Text Viewer, as this is
not currently available for Linux. Oracle then wants to
relink with i386-glibc20-linux-gcc
instead of the available gcc,
egcs or i386-redhat-linux-gcc
.Due to time constrains I decided to use the binaries
from an Oracle 8.0.5 PreProduction
release, after the first
attempt at getting the version from the RDBMS-CD working,
failed, and finding and accessing the correct RPMs was a
nightmare at that time.Installing the Oracle 8.0.5 Pre-Production release for
Linux (Kernel 2.0.33)This installation is quite easy. Mount the CD, start the
installer. It will then ask for the location of the Oracle
home directory, and copy all binaries there. I did not
delete the remains of my previous RDBMS-installation tries,
though.Afterwards, Oracle Database could be started with no
problems.Installing the Oracle 8.1.7 linux tarballTake the tarball oracle81732.tgz you
produced from the installation directory on a linux system
and untar it to /oracle/<SID>/817_32/Continue with SAP R/3 InstallationFirst check the environment settings of users
idsamd
(<sid>adm) and
oraids (ora<sid>). They should now
both have the files .profile,
.login and .cshrc
which are all using hostname. In case the
system's hostname is the fully qualified name, you need to
change hostname to hostname
-s within all three files.Database LoadAfterwards, R3SETUP can either be restarted or continued
(depending on whether exit was chosen or not). R3SETUP then
creates the tablespaces and loads the data (for 46B IDES, from
EXPORT1 to EXPORT6, for 46C from DISK1 to DISK4) with R3load
into the database.When the database load is finished (might take a few
hours), some passwords are requested. For test
installations, one can use the well known default passwords
(use different ones if security is an issue!):QuestionInputEnter Password for sapr3sap<ret>Confirum Password for sapr3sap<ret>Enter Password for syschange_on_install<ret>Confirm Password for syschange_on_install<ret>Enter Password for systemmanager<ret>Confirm Password for systemmanager<ret>At this point I had a few problems with
dipgntab during the 4.6B
installation.ListenerStart the Oracle-Listener as user
ora<sid> as follows:&prompt.user; umask 0; lsnrctl startOtherwise you might get ORA-12546 as the sockets will not
have the correct permissions. See SAP note 072984.Updating MNLS TablesIf you plan to import non-Latin-1 languages into the SAP-System,
you have to update the Multi National Language Support tables.
This is described in the SAP OSS-Notes 15023 and 45619. Otherwise,
you can skip this question during SAP installation.If you don't need MNLS, it is still necessary to check
table TCPDB and initializing it if this hasn't been done. See
SAP note 0015023 and 0045619 for further information.Post-installation StepsRequest SAP R/3 License KeyYou have to request your SAP R/3 License Key. This is needed,
as the temporary license that was installed during installation
is only valid for four weeks. First get the hardware key. Log
on as user idsadm and call
saplicense:&prompt.root; /sapmnt/IDS/exe/saplicense -getCalling saplicense without options gives
a list of options. Upon receiving the license key, it can be
installed using&prompt.root; /sapmnt/IDS/exe/saplicense -installYou are then required to enter the following values:SAP SYSTEM ID = <SID, 3 chars>
CUSTOMER KEY = <hardware key, 11 chars>
INSTALLATION NO = <installation, 10 digits>
EXPIRATION DATE = <yyyymmdd, usually "99991231">
LICENSE KEY = <license key, 24 chars>Creating UsersCreate a user within client 000 (for some tasks required
to be done within client 000, but with a user different from
users sap* and
ddic). As a username, I usually choose
wartung (or
service in English). Profiles
required are sap_new and
sap_all. For additional safety the
passwords of default users within all clients should be
changed (this includes users sap* and
ddic).Configure Transport System, Profile, Operation Modes, Etc.Within client 000, user different from ddic
and sap*, do at least the following:TaskTransactionConfigure Transport System, eg as Stand-Alone
Transport Domain EntitySTMSCreate / Edit Profile for SystemRZ10Maintain Operation Modes and InstancesRZ04These and all the other post-installation steps are
thoroughly described in SAP installation guides.Edit init<sid>.sap (initIDS.sap)The file /oracle/IDS/dbs/initIDS.sap
contains the SAP backup profile. Here the size of the tape to
be used, type of compression and so on need to be defined. To
get this running with sapdba /
brbackup, I changed the following values:compress = hardware
archive_function = copy_delete_save
cpio_flags = "-ov --format=newc --block-size=128 --quiet"
cpio_in_flags = "-iuv --block-size=128 --quiet"
tape_size = 38000M
tape_address = /dev/nsa0
tape_address_rew = /dev/sa0Explanations:compress The tape I use is a HP DLT1
which does hardware compression.archive_function This defines the
default behavior for saving Oracle archive logs: New logfiles
are saved to tape, already saved logfiles are saved again and
are then deleted. This prevents lots of trouble if you need to
recover the database, and one of the archive-tapes has gone
bad.cpio_flags Default is to use -B which
- sets blocksize to 5120 Bytes. For DLT-Tapes, HP recommends at
- least 32K blocksize, so I used --block-size=128 for
- 64K. --format=newc is needed I have inode numbers greater than
+ sets blocksize to 5120 Bytes. For DLT-Tapes, HP recommends at
+ least 32 K blocksize, so I used --block-size=128 for
+ 64 K. --format=newc is needed I have inode numbers greater than
65535. The last option --quiet is needed as otherwise
brbackup
complains as soon as cpio outputs the
numbers of blocks saved.cpio_in_flags Flags needed for
loading data back from tape. Format is recognized
automagically.tape_size This usually gives the raw
storage capability of the tape. For security reason (we use
hardware compression), the value is slightly lower than the
actual value.tape_address The non-rewindable
device to be used with cpio.tape_address_rew The rewindable device to be
used with cpio.Configuration Issues after InstallationThe following SAP-parameters should be tuned after
- installation (examples for IDES 46B, 1GB memory):
+ installation (examples for IDES 46B, 1 GB memory):
NameValueztta/roll_extension250000000abap/heap_area_dia300000000abap/heap_area_nondia400000000em/initial_size_MB256em/blocksize_kB1024ipc/shm_psize_4070000000SAP-Note 0013026:NameValueztta/dynpro_area2500000SAP-Note 0157246:NameValuerdisp/ROLL_MAXFS16000rdisp/PG_MAXFS30000
- With the above parameters, on a system with 1 gigabyte
+ With the above parameters, on a system with 1 gigabyte
of memory, one may find memory consumption similar to:
Mem: 547M Active, 305M Inact, 109M Wired, 40M Cache, 112M Buf, 3492K FreeProblems During InstallationRestart R3SETUP after fixing a problemR3SETUP stops if it encounters an error. If you have
looked at the corresponding logfiles and fixed the error,
you have to start R3SETUP again, usually selecting REPEAT
as option for the last step R3SETUP complained about.To restart R3SETUP, just start it with the corresponding
R3S-file:
&prompt.root; ./R3SETUP -f CENTRDB.R3S
for 4.6B, or with
&prompt.root; ./R3SETUP -f CENTRAL.R3S
for 4.6C, no matter whether the error occured
with CENTRAL.R3s or
DATABASE.R3S.At some stages, R3SETUP assumes that both database-
and SAP-processes are up and running (as those were steps it
already completed). Should errors occur and for example the
database could not be started, you have to start both database
and SAP by hand after you fixed the errors and before starting
R3SETUP again.Don't forget to also start the oracle listener again (as
ora<sid> with
umask 0; lsnrctl start) if it was also
stopped (for example due to a necessary reboot of the
system).OSUSERSIDADM_IND_ORA During R3SETUPIf R3SETUP complains at this stage, edit the
template file R3SETUP used at that time
(CENTRDB.R3S (4.6B) or either
CENTRAL.R3S or
DATABASE.R3S (4.6C)).
Locate [OSUSERSIDADM_IND_ORA] or search for the
only STATUS=ERROR-entry
and edit the following values:HOME=/home/<sid>adm (was empty)
STATUS=OK (had status ERROR)
Then you can restart R3SETUP again.OSUSERDBSID_IND_ORA During R3SETUPPossibly R3SETUP also complains at this stage. The error
here is similar to the one in phase OSUSERSIDADM_IND_ORA.
Just edit
the template file R3SETUP used at that time
(CENTRDB.R3S (4.6B) or either
CENTRAL.R3S or
DATABASE.R3S (4.6C)).
Locate [OSUSERDBSID_IND_ORA] or search for the
only STATUS=ERROR-entry
and edit the following value in that section:STATUS=OKThen restart R3SETUP.oraview.vrf FILE NOT FOUND During Oracle InstallationYou have not deselected Oracle On-Line Text Viewer
before starting the installation. This is marked for installation even
though this option is currently not available for Linux. Deselect this
product inside the Oracle installation menu and restart installation.TEXTENV_INVALID During R3SETUP, RFC or SAPGUI StartIf this error is encountered, the correct locale is
missing. SAP note 0171356 lists the necessary RPMs that need
be installed (eg saplocales-1.0-3,
saposcheck-1.0-1 for RedHat 6.1). In case
you ignored all the related errors and set the corresponding
status from ERROR to OK (in CENTRDB.R3S) every time R3SETUP
complained and just restarted R3SETUP, the SAP-System will not
be properly configured and you will then not be able to
connect to the system with a
sapgui, even though the system
can be started. Trying to connect with the old Linux
sapgui gave the following
messages:Sat May 5 14:23:14 2001
*** ERROR => no valid userarea given [trgmsgo. 0401]
Sat May 5 14:23:22 2001
*** ERROR => ERROR NR 24 occured [trgmsgi. 0410]
*** ERROR => Error when generating text environment. [trgmsgi. 0435]
*** ERROR => function failed [trgmsgi. 0447]
*** ERROR => no socket operation allowed [trxio.c 3363]
SpeicherzugriffsfehlerThis behavior is due to SAP R/3 being unable to correctly
assign a locale and also not being properly configured itself
(missing entries in some database tables). To be able to connect
to SAP, add the following entries to file
DEFAULT.PFL (see note 0043288):abap/set_etct_env_at_new_mode = 0
install/collate/active = 0
rscp/TCP0B = TCP0BRestart the SAP system. Now you can connect to the
system, even though country-specific language settings might
not work as expected. After correcting country-settings
(and providing the correct locales), these entries can be
removed from DEFAULT.PFL and the SAP
system can be restarted.ORA-00001This error only happened with
- Oracle 8.1.7 on FreeBSD 4.5.
+ Oracle 8.1.7 on FreeBSD 4.5.
The reason was that the Oracle database could not initialize itself
properly and crashed, leaving semaphores and shared memory on the
system. The next try to start the database then returned
ORA-00001.Find them with ipcs -a and remove them
with ipcrm.ORA-00445 (background process PMON did not start)This error happened with Oracle 8.1.7.
This error is reported if the Database is started with
the usual startsap-script (for example
startsap_majestix_00) as user
prdadm.A possible workaround is to start the database as user
oraprd instead
with svrmgrl:&prompt.user; svrmgrl
SVRMGR> connect internal;
SVRMGR> startup;
SVRMGR> exitORA-12546 (start Listener with Correct Permissions)Start the Oracle Listener as user
oraids with the following commands:&prompt.root; umask 0; lsnrctl startOtherwise you might get ORA-12546 as the sockets will not
have the correct permissions. See SAP note 0072984.ORA-27102 (out of memory)This error happend whilst trying to use values for
MAXDSIZ and DFLDSIZ
- greater than 1GB (1024x1024x1024). Additionally, I got
+ greater than 1 GB (1024x1024x1024). Additionally, I got
Linux Error 12: Cannot allocate memory.[DIPGNTAB_IND_IND] During R3SETUPIn general, see SAP note 0130581 (R3SETUP step
DIPGNTAB terminates). During the
IDES-specific installation, for some reasons the installation
process was not using the proper SAP system name "IDS", but
the empty string "" instead. This lead to some minor problems
with accessing directories, as the paths are generated
dynamically using <SID> (in this case IDS). So instead
of accessing:/usr/sap/IDS/SYS/...
/usr/sap/IDS/DVMGS00the following paths were used:/usr/sap//SYS/...
/usr/sap/D00To continue with the installation, I created a link and an
additional directory:&prompt.root; pwd
/compat/linux/usr/sap
&prompt.root; ls -l
total 4
drwxr-xr-x 3 idsadm sapsys 512 May 5 11:20 D00
drwxr-x--x 5 idsadm sapsys 512 May 5 11:35 IDS
lrwxr-xr-x 1 root sapsys 7 May 5 11:35 SYS -> IDS/SYS
drwxrwxr-x 2 idsadm sapsys 512 May 5 13:00 tmp
drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 transI also found SAP notes (0029227 and 0008401) describing
this behavior. I did not encounter any of these problems with
the SAP 4.6C-Installation.[RFCRSWBOINI_IND_IND] During R3SETUPDuring installation of SAP 4.6C,
this error was just the result of another error happening
earlier during installation. In this case, you have to look
through the corresponding logfiles and correct the real
problem.If after looking through the logfiles this error is
indeed the correct one (check the SAP-notes), you can set
STATUS of the offending step from ERROR to OK (file
CENTRDB.R3S) and restart R3SETUP. After
installation, you have to execute the report
RSWBOINS from transaction SE38. See SAP
note 0162266 for additional information about phase
RFCRSWBOINI and
RFCRADDBDIF.[RFCRADDBDIF_IND_IND] During R3SETUPHere the same restrictions apply: Make sure by looking
through the logfiles, that this error is not caused by some
previous problems.If you can confirm that SAP-Note 0162266 applies, just
set STATUS of the offending step from ERROR to OK (file
CENTRDB.R3S) and restart R3SETUP. After
installation, you have to execute the report
RADDBDIF from transaction SE38.sigaction sig31: File size limit exceededThis error occured during start of SAP-processes
disp+work. If starting SAP with the
startsap-script, subprocesses are then started which
detach and do the dirty work of starting all other SAP
processes. As a result, the script itself won't notice
if something goes wrong.To check whether the SAP processes did start properly,
have a look at the process status with
ps ax | grep <SID>, which will give
you a list of all Oracle- and SAP-processes. If it looks like
some processes are missing or if you can't connect to the SAP-System,
look at the corresponding logfiles which can be found
at /usr/sap/<SID>/DVEBMGS<nr>/work/.
The files to look at are dev_ms and
dev_disp.Signal 31 happens here if the amount of shared memory used by
Oracle and SAP exceed the one defined within the kernel configuration
file and could be resolved by using a larger value:# larger value for 46C production systems:
options SHMMAXPGS=393216
# smaller value sufficient for 46B:
#options SHMMAXPGS=262144Start of saposcol failedThere are some problems with Program saposcol (version 4.6D).
The SAP-System is using saposcol to collect data about the
system performance. This program is not needed to use the SAP-System,
so this problem can be considered a minor one. The older versions
(4.6B) does work, but doesn't collect all the data (many calls will
just return 0, for example for CPU useage).Advanced TopicsIf you are curious as to how the Linux binary compatibility
works, this is the section you want to read. Most of what follows
is based heavily on an email written to &a.chat; by Terry Lambert
tlambert@primenet.com (Message ID:
<199906020108.SAA07001@usr09.primenet.com>).How Does It Work?execution class loaderFreeBSD has an abstraction called an execution class
loader. This is a wedge into the &man.execve.2; system
call.What happens is that FreeBSD has a list of loaders, instead of
a single loader with a fallback to the #!
loader for running any shell interpreters or shell scripts.Historically, the only loader on the Unix platform examined
the magic number (generally the first 4 or 8 bytes of the file) to
see if it was a binary known to the system, and if so, invoked the
binary loader.If it was not the binary type for the system, the
&man.execve.2; call returned a failure, and the shell attempted to
start executing it as shell commands.The assumption was a default of whatever the current
shell is.Later, a hack was made for &man.sh.1; to examine the first two
characters, and if they were :\n, then it
invoked the &man.csh.1; shell instead (we believe SCO first made
this hack).What FreeBSD does now is go through a list of loaders, with a
generic #! loader that knows about interpreters
as the characters which follow to the next whitespace next to
last, followed by a fallback to
/bin/sh.ELFFor the Linux ABI support, FreeBSD sees the magic number as an
ELF binary (it makes no distinction between FreeBSD, Solaris,
Linux, or any other OS which has an ELF image type, at this
point).SolarisThe ELF loader looks for a specialized
brand, which is a comment section in the ELF
image, and which is not present on SVR4/Solaris ELF
binaries.For Linux binaries to function, they must be
branded as type Linux;
from &man.brandelf.1;:&prompt.root; brandelf -t Linux fileWhen this is done, the ELF loader will see the
Linux brand on the file.ELFbrandingWhen the ELF loader sees the Linux brand,
the loader replaces a pointer in the proc
structure. All system calls are indexed through this pointer (in
a traditional Unix system, this would be the
sysent[] structure array, containing the system
calls). In addition, the process flagged for special handling of
the trap vector for the signal trampoline code, and sever other
(minor) fix-ups that are handled by the Linux kernel
module.The Linux system call vector contains, among other things, a
list of sysent[] entries whose addresses reside
in the kernel module.When a system call is called by the Linux binary, the trap
code dereferences the system call function pointer off the
proc structure, and gets the Linux, not the
FreeBSD, system call entry points.In addition, the Linux mode dynamically
reroots lookups; this is, in effect, what the
union option to FS mounts
(not the unionfs!) does. First, an attempt
is made to lookup the file in the
/compat/linux/original-path
directory, then only if that fails, the
lookup is done in the
/original-path
directory. This makes sure that binaries that require other
binaries can run (e.g., the Linux toolchain can all run under
Linux ABI support). It also means that the Linux binaries can
load and exec FreeBSD binaries, if there are no corresponding
Linux binaries present, and that you could place a &man.uname.1;
command in the /compat/linux directory tree
to ensure that the Linux binaries could not tell they were not
running on Linux.In effect, there is a Linux kernel in the FreeBSD kernel; the
various underlying functions that implement all of the services
provided by the kernel are identical to both the FreeBSD system
call table entries, and the Linux system call table entries: file
system operations, virtual memory operations, signal delivery,
System V IPC, etc… The only difference is that FreeBSD
binaries get the FreeBSD glue functions, and
Linux binaries get the Linux glue functions
(most older OS's only had their own glue
functions: addresses of functions in a static global
sysent[] structure array, instead of addresses
of functions dereferenced off a dynamically initialized pointer in
the proc structure of the process making the
call).Which one is the native FreeBSD ABI? It does not matter.
Basically the only difference is that (currently; this could
easily be changed in a future release, and probably will be after
this) the FreeBSD glue functions are
statically linked into the kernel, and the Linux glue functions
can be statically linked, or they can be accessed via a kernel
module.Yeah, but is this really emulation? No. It is an ABI
implementation, not an emulation. There is no emulator (or
simulator, to cut off the next question) involved.So why is it sometimes called Linux emulation?
To make it hard to sell FreeBSD! Really, it
is because the historical implementation was done at a time when
there was really no word other than that to describe what was
going on; saying that FreeBSD ran Linux binaries was not true, if
you did not compile the code in or load a module, and there needed
to be a word to describe what was being loaded—hence
the Linux emulator.
diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
index b1865d772d..49fa7de695 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
@@ -1,1578 +1,1578 @@
Installing Applications: Packages and PortsSynopsisportspackagesFreeBSD is bundled with a rich collection of system tools as
part of the base system. However, there is only so much one can
do before needing to install an additional third-party
application to get real work done. FreeBSD provides two
complementary technologies for installing third party software
on your system: the FreeBSD Ports Collection, and binary
software packages. Either system may be used to install the
newest version of your favorite applications from local media or
straight off the network.After reading this chapter, you will know:How to install third-party binary software packages.How to build third-party software from the ports
collection.How to remove previously installed packages or ports.Overview of Software InstallationIf you have used a Unix system before you will know that the typical
procedure for installing third party software goes something like
this:Download the software, which might be distributed in source code
format, or as a binary.Unpack the software from its distribution format (typically a
tarball compressed with either &man.compress.1; or &man.gzip.1;).Locate the documentation (perhaps a README
file, or some files in a doc/ subdirectory) and
read up on how to install the software.If the software was distributed in source format, compile it.
This may involve editing a Makefile, or
running a configure script, and other work.Test and install the software.And that is only if everything goes well. If you are installing a
software package that was not deliberately ported to FreeBSD you may
even have to go in and edit the code to make it work properly.Should you want to, you can continue to install software the
traditional way with FreeBSD. However, FreeBSD
provides two technologies which can save you a lot of effort:
packages and ports. At the time of writing, over &os.numports;
third party applications have been made available in this
way.For any given application, the FreeBSD package for that application
is a single file which you must download. The package contains
pre-compiled copies of all the commands for the application, as well as
any configuration files or documentation. A downloaded package file can
be manipulated with FreeBSD package management commands, such as
&man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so on.Installing a new application can be carried out with a single
command.A FreeBSD port for an application is a collection of files designed
to automate the process of compiling an application from source
code.Remember that there are a number of steps you would normally carry
out if you compiled a program yourself (unpacking, patching, compiling,
installing). The files that make up a port contain all the necessary
information to allow the system to do this for you. You run a handful
of simple commands and the source code for the application is
automatically downloaded, extracted, patched, compiled, and installed
for you.In fact, the ports system can also be used to generate packages
which can later be manipulated with pkg_add
and the other package management commands that will be introduced
shortly.Both packages and ports understand
dependencies. Suppose you want to install an
application that depends on a specific library being installed. Both
the application and the library have been made available as FreeBSD
ports and packages. If you use the pkg_add command
or the ports system to add the application, both will notice that the
library has not been installed, and the commands will install the
library first.Given that the two technologies are quite similar, you might be
wondering why FreeBSD bothers with both. Packages and ports both have
their own strengths, and which one you use will depend on your own
preference.Package BenefitsA compressed package tarball is typically smaller than the
compressed tarball containing the source code for the application.Packages do not require any additional compilation. For large
applications, such as Mozilla,
KDE, or GNOME
this can be important, particularly if you are on a slow system.Packages do not require you to understand the process
involved in compiling software on FreeBSD.Ports BenefitsPackages are normally compiled with conservative options,
because they have to run on the maximum number of systems. By
installing from the port, you can tweak the compilation options to
(for example) generate code that is specific to a Pentium
III or Athlon processor.Some applications have compile time options relating to what they
can and cannot do. For example, Apache
can be configured with a wide variety of different built-in options.
By building from the port you do not have to accept the default
options, and can set them yourself.In some cases, multiple packages will exist for the same
application to specify certain settings. For example,
Ghostscript is available as a
ghostscript package and a
ghostscript-nox11 package, depending on whether
or not you have installed an X11 server. This sort of rough
tweaking is possible with packages, but rapidly becomes impossible
if an application has more than one or two different compile time
options.The licensing conditions of some software distributions forbid
binary distribution. They must be distributed as source
code.Some people do not trust binary distributions. At least with
source code, you can (in theory) read through it and look for
potential problems yourself.If you have local patches, you will need the source in order to
apply them.Some people like having code around, so they can read it if they
get bored, hack it, borrow from it (license permitting, of course),
and so on.To keep track of updated ports, subscribe to the
&a.ports;.The remainder of this chapter will explain how to use packages and
ports to install and manage third party software on FreeBSD.Finding Your ApplicationBefore you can install any applications you need to know what you
want, and what the application is called.FreeBSD's list of available applications is growing all the
time. Fortunately, there are a number of ways to
find what you want:The FreeBSD web site maintains an up-to-date searchable list of
all the available applications, at
http://www.FreeBSD.org/ports/.
The name space is divided into categories, and you may either
search for an application by name (if you know it), or you can list
all the applications available in a category.FreshPortsDan Langille maintains FreshPorts, at
http://www.FreshPorts.org/.
FreshPorts tracks changes to the applications in the ports tree as
they happen, and allows you to watch one or more
ports, and will send you an email when they are updated.FreshMeatIf you do not know the name of the application you want, try
using a site like FreshMeat
(http://www.freshmeat.net/)
to find an application, then check back at the FreeBSD site to see
if the application has been ported yet.ChernLeeContributed by Using the Packages SystemInstalling a Packagepackagesinstallingpkg_addYou can use the &man.pkg.add.1; utility to install a
FreeBSD software package from a local file or from a server on
the network.Downloading a Package and then Installing It Locally&prompt.root; ftp -a ftp2.FreeBSD.org
Connected to ftp2.FreeBSD.org.
220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready.
331 Guest login ok, send your email address as password.
230-
230- This machine is in Vienna, VA, USA, hosted by Verio.
230- Questions? E-mail freebsd@vienna.verio.net.
230-
230-
230 Guest login ok, access restrictions apply.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp>cd /pub/FreeBSD/ports/packages/sysutils/
250 CWD command successful.
ftp>get lsof-4.56.4.tgz
local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
200 PORT command successful.
150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
100% |**************************************************| 92375 00:00 ETA
226 Transfer complete.
92375 bytes received in 5.60 seconds (16.11 KB/s)
ftp>exit
&prompt.root; pkg_add lsof-4.56.4.tgzIf you do not have a source of local packages (such as a
FreeBSD CDROM set) then it will probably be easier to use the
option to &man.pkg.add.1;. This will cause the utility to
automatically determine the correct object format and release
and then to fetch and install the package from an FTP site.
pkg_add&prompt.root; pkg_add -r lsofThe example above would download the correct package and add
it without any further user intervention. &man.pkg.add.1; uses
&man.fetch.3; to download the files, which honours various
environment variables, including FTP_PASSIVE_MODE,
FTP_PROXY, and FTP_PASSWORD. You
may need to set one or more of these if you are behind a firewall,
or need to use an FTP/HTTP proxy. See &man.fetch.3; for the
complete list. You can also note that in the example above
lsof is used instead of
lsof-4.56.4. When the remote fetching
feature is used, the version number of the package must be
removed. &man.pkg.add.1; will automatically fetch the latest
version of the application.Package files are distributed in .tgz format. You can
find them at
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/,
or on the FreeBSD CDROM distribution. Every CD on the
FreeBSD 4-CD set (and PowerPak, etc) contains packages in
the /packages directory. The layout of
the packages is similar to that of the
/usr/ports tree. Each category has its
own directory, and every package can be found within the
All directory.
The directory structure of the package system is identical
to that of the ports; they work with each other to form the entire
package/port system.
Deleting a Packagepkg_deletepackagesdeletingTo remove a previously installed software package, use the
&man.pkg.delete.1; utility.
&prompt.root; pkg_delete xchat-1.7.1Managing Packagespackagesmanaging&man.pkg.info.1; is a utility that lists and describes
the various packages installed.
pkg_info&prompt.root; pkg_info
cvsup-16.1 A general network file distribution system optimized for CV
docbook-1.2 Meta-port for the different versions of the DocBook DTD
...&man.pkg.version.1; is a utility that summarizes the
versions of all installed packages. It compares the package
version to the current version found in the ports tree.
pkg_version&prompt.root; pkg_version
cvsup =
docbook =
...The symbols in the second column indicate the relative age
of the installed version and the version available in the local
ports tree.SymbolMeaning=The version of the
installed package matches that of the one found in the
local ports tree.<The installed version is older than the one available
in the ports tree.>The installed version is newer
than the one found in the local ports tree. (local ports
tree is probably out of date)?The installed package cannot be
found in the ports index.*There are multiple versions of the
package.MiscellaneousAll package information is stored within the
/var/db/pkg directory. The installed
file list and descriptions of each package can be found within
files in this directory.
Using the Ports CollectionThe following sections provide basic instructions on using the
ports collection to install or remove programs from your
system.Obtaining the Ports CollectionBefore you can install ports, you must first obtain the
ports collection—which is essentially a set of Makefiles,
patches, and description files placed in
/usr/ports.
When installing your FreeBSD system,
Sysinstall asked if you would like to
install the ports collection. If you chose no, you can follow
these instructions to obtain the ports collection:Sysinstall MethodThis method involves using
sysinstall again to manually
install the ports collection.As root, run /stand/sysinstall as
shown below:&prompt.root; /stand/sysinstallScroll down and select Configure,
press Enter.Scroll down and select
Distributions, press Enter.Scroll down to ports, press
Space.Scroll up to Exit, press
Enter.Select your desired installation media, such as CDROM,
FTP, and so on.Follow the menus to exit sysinstall.The alternative method to obtain and keep your ports
collection up to date is by using
CVSup. Look at the ports
CVSup file,
/usr/share/examples/cvsup/ports-supfile.
See Using CVSup () for more information on using
CVSup and the mentioned file.CVSup MethodThis is a quick method to getting the ports collection
using CVSup. If you want to keep
your ports tree up to date, or learn more about
CVSup, read the previously
mentioned sections.Install the net/cvsup port. See CVSup Installation () for more details.As root, copy
/usr/share/examples/cvsup/ports-supfile
to a new location, such as /root or your
home directory.Edit ports-supfile.Change CHANGE_THIS.FreeBSD.org to a
CVSup server near you. See CVSup Mirrors () for a complete listing of mirror
sites.Run cvsup:&prompt.root; cvsup -g -L 2 /root/ports-supfileRunning this consequent times at later dates will
download all the recent changes to your ports
collection.Installing PortsportsinstallingThe first thing that should be explained
when it comes to the ports collection is what is actually meant
by a skeleton. In a nutshell, a port skeleton is a
minimal set of files that tell your FreeBSD system how to
cleanly compile and install a program. Each port skeleton includes:A Makefile. The
Makefile contains various statements that
specify how the application should be compiled and where it
should be installed on your system.A distinfo file. This file contains
information about the files that must be downloaded to build the
port, and checksums, to ensure that those files have not been
corrupted during the download.A files directory. This directory
contains patches to make the program compile and install on
your FreeBSD system. Patches are basically small files that
specify changes to particular files. They are in plain text
format, and basically say Remove line 10 or
Change line 26 to this .... Patches are also
known as diffs because they are generated by the
&man.diff.1; program.This directory may also contain other files used in building
the port.A pkg-comment file. This is a one-line
description of the program.A pkg-descr file. This is a more
detailed, often multiple-line, description of the program.A pkg-plist file. This is a list of all
the files that will be installed by the port. It also tells the
ports system what files to remove upon deinstallation.Some ports have other files, such as
pkg-message. The ports system uses these
files to handle special situations. If you want more details
on these files, and on ports in general, check out the FreeBSD Porter's
Handbook.Now that you have enough background information to know what
the ports collection is used for, you are ready to install your
first port. There are two ways this can be done, and each is
explained below.Before we get into that however, you will need to choose a
port to install. There are a few ways to do this, with the
easiest method being the ports listing on the FreeBSD
web site. You can browse through the ports listed there
or use the search function on the site. Each port also includes
a description so you can read a bit about each port before
deciding to install it.Another method is to use the &man.whereis.1;
command. Simply type whereis file,
where file is the program you want to
install. If it is found on
your system, you will be told where it is, like so:&prompt.root; whereis lsof
lsof: /usr/ports/sysutils/lsofThis tells us that lsof (a system utility)
can be found in the
/usr/ports/sysutils/lsof directory.Yet another way of finding a particular port is by using the
ports collection's built-in search mechanism. To use the search
feature, you will need to be in the
/usr/ports directory. Once in that
directory, run make search name=program-name
where program-name is the name of the program you
want to find. For example, if you were looking for
lsof:&prompt.root; cd /usr/ports
&prompt.root; make search name=lsof
Port: lsof-4.56.4
Path: /usr/ports/sysutils/lsof
Info: Lists information about open files (similar to fstat(1))
Maint: obrien@FreeBSD.org
Index: sysutils
B-deps:
R-deps: The part of the output you want to pay particular attention
to is the Path: line, since that tells you where to
find it. The other information provided is not needed in order
to install the port directly, so it will not be covered
here.For more in-depth searching you can also use
make search key=string where
string is some text to search for. This searches
port names, comments, descriptions and dependencies and can be used
to find ports which relate to a particular subject if you don't
know the name of the program you are looking for.In both of these cases, the search string is case-insensitive.
Searching for LSOF will yield the same results as
searching for lsof.You must be the root user to install
ports.Now that you have found a port you would like to install,
you are ready to do the actual installation. The port
includes instructions on how to build source code, but no
actual source code. You can get the source code from a CDROM
or from the Internet. Source code is distributed in whatever
manner the software author desires. Frequently this is a
tarred and gzipped file, but it might be compressed with some
other tool or even uncompressed. The program source code,
whatever form it comes in, is called a
distfile. You can get the distfile from a
CDROM or from the Internet.Installing Ports from a CDROMportsinstalling from CDROMThe FreeBSD Project's official CDROM images no longer
include distfiles. They take up a lot of room that is
better used by precompiled packages. CDROM products such as
the FreeBSD PowerPak do include distfiles, and you can
order these sets from a vendor such as the FreeBSD Mall.
This section assumes you have such a FreeBSD CDROM
set.Place your FreeBSD CDROM in the drive. Mount it on
/cdrom. (If you use a different mount
point, the install will not work.) To begin, change to the
directory for the port you want to install:&prompt.root; cd /usr/ports/sysutils/lsofOnce inside the lsof directory,
you will see the port
skeleton. The next step is to compile (also called build) the
port. This is done by simply typing make at
the prompt. Once you have done so, you should see something
like this:&prompt.root; make
>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
>> Attempting to fetch from file:/cdrom/ports/distfiles/.
===> Extracting for lsof-4.57
...
[extraction output snipped]
...
>> Checksum OK for lsof_4.57D.freebsd.tar.gz.
===> Patching for lsof-4.57
===> Applying FreeBSD patches for lsof-4.57
===> Configuring for lsof-4.57
...
[configure output snipped]
...
===> Building for lsof-4.57
...
[compilation output snipped]
...
&prompt.root;Take notice that once the compile is complete you are
returned to your prompt. The next step is to install the
port. In order to install it, you simply need to tack one word
onto the make command, and that word is
install:&prompt.root; make install
===> Installing for lsof-4.57
...
[installation output snipped]
...
===> Generating temporary packing list
===> Compressing manual pages for lsof-4.57
===> Registering installation for lsof-4.57
===> SECURITY NOTE:
This port has installed the following binaries which execute with
increased privileges.
&prompt.root;Once you are returned to your prompt, you should be able to
run the application you just installed. Since
lsof is a
program that runs with increased privileges, a security
warning is shown. During the building and installation of
ports, you should take heed of any other warnings that
may appear.You can save an extra step by just running make
install instead of make and
make install as two separate steps.Some shells keep a cache of the commands that are available in
the directories listed in the PATH environment
variable, to speed up lookup operations for the executable file of
these commands. If you are using one of these shells, you might
have to use the rehash command after installing
a port, before the newly installed commands can be used. This is
true for both shells that are part of the base-system (such as
tcsh) and shells that are available as ports
(for instance,
shells/zsh).Please be aware that the licenses of a few ports do not
allow for inclusion on the CDROM. This could be because a
registration form needs
to be filled out before downloading, redistribution is not
allowed, and so on. If you wish to install a port not
included on the CDROM, you will need to be online in order to
do so (see the next
section).Installing Ports from the InternetAs with the last section, this section makes an assumption
that you have a working Internet connection. If you do not,
you will need to perform the CDROM
installation.Installing a port from the Internet is done exactly the same
way as it would be if you were installing from a CDROM. The
only difference between the two is that the port distfile
is downloaded from the Internet instead of pulled from the
CDROM.The steps involved are identical:&prompt.root; make install
>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
>> Attempting to fetch from ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/.
Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
439860 bytes transferred in 18.0 seconds (23.90 kBps)
===> Extracting for lsof-4.57
...
[extraction output snipped]
...
>> Checksum OK for lsof_4.57D.freebsd.tar.gz.
===> Patching for lsof-4.57
===> Applying FreeBSD patches for lsof-4.57
===> Configuring for lsof-4.57
...
[configure output snipped]
...
===> Building for lsof-4.57
...
[compilation output snipped]
...
===> Installing for lsof-4.57
...
[installation output snipped]
...
===> Generating temporary packing list
===> Compressing manual pages for lsof-4.57
===> Registering installation for lsof-4.57
===> SECURITY NOTE:
This port has installed the following binaries which execute with
increased privileges.
&prompt.root;As you can see, the only difference is the line that tells
you where the system is fetching the port distfile from.The ports system uses &man.fetch.1; to download the files,
which honours various environment variables, including
FTP_PASSIVE_MODE, FTP_PROXY,
and FTP_PASSWORD. You may need to set one or more
of these if you are behind a firewall, or need to use an FTP/HTTP
proxy. See &man.fetch.3; for the complete list.Removing Installed PortsportsremovingNow that you know how to install ports, you are probably
wondering how to remove them, just in case you install one and
later on you decide that you installed the wrong port.
We will remove our previous example (which was
lsof for
those of you not paying attention). As with installing ports,
the first thing you must do is change to the port directory,
/usr/ports/sysutils/lsof. After you change
directories, you are ready to uninstall lsof.
This is done with
the make deinstall command:&prompt.root; cd /usr/ports/sysutils/lsof
&prompt.root; make deinstall
===> Deinstalling for lsof-4.57That was easy enough. You have removed
lsof
from your system. If you would like to reinstall it, you can do
so by running make reinstall from the
/usr/ports/sysutils/lsof directory.The make deinstall and make
reinstall sequence does not work once you have run
make clean. If you want to deinstall a
port after cleaning, use &man.pkg.delete.1; as
discussed in the Packages
section of the Handbook.Post-installation activitiesAfter installing a new application you will normally want to read
any documentation it may have included, edit any configuration files
that are required, ensure that the application starts at boot time (if
it is a daemon), and so on.The exact steps you need to take to configure each application will
obviously be different. However, if you have just installed a new
application and are wondering What now? these tips might
help:Use &man.pkg.info.1; to find out which files were installed,
and where they were installed to. For example, if you have just
installed FooPackage version 1.0.0, then this command&prompt.root; pkg_info -L foopackage-1.0.0 | lesswill show all the files installed by the package. Pay special
attention to files in man/ directories, which
will be manual pages, etc/ directories, which
will be configuration files, and doc/, which will be
more comprehensive documentation.If you are not sure which version of the application was just
installed, a command like this&prompt.root; pkg_info | grep foopackagewill find all the installed packages that have
foopackage in the package name. Replace
foopackage in your commandline as
necessary.Once you have identified where the application's manual pages
have been installed, review them using &man.man.1;. Similarly,
look over the sample configuration files, and any additional
documentation that may have been provided.If the application has a web site, check it for additional
documentation, frequently asked question files, and so forth. If
you are not sure of the web site address it may be listed in the
output from&prompt.root; pkg_info foopackage-1.0.0will often include a WWW: line with the URL
of the application's web site.TroubleshootingThe following sections cover some of the more frequently asked
questions about the ports collection and some basic troubleshooting
techniques, and what do to if a port is broken.Some Questions and AnswersI thought this was going to be a discussion about
modems??!Ah, you must be thinking of the serial ports on the back
of your computer. We are using port here to
mean the result of porting a program from one
version of Unix to another.What is a patch?A patch is a small file that specifies how to go from
one version of a file to another. It contains plain text,
and basically says things like delete line 23,
add these two lines after line 468, or
change line 197 to this. They are also known
as diffs because they are generated by the
&man.diff.1; program.tarballWhat is all this about
tarballs?It is a file ending in .tar, or
with variations such as .tar.gz,
.tar.Z, .tar.bz2,
and even .tgz.Basically, it is a directory tree that has been archived
into a single file (.tar) and
optionally compressed (.gz). This
technique was originally used for Tape
ARchives (hence the name
tar), but it is a widely used way of
distributing program source code around the Internet.You can see what files are in them, or even extract
them yourself by using the standard Unix
&man.tar.1; program, which comes with the base
FreeBSD system, like this:&prompt.user; tar tvzf foobar.tar.gz
&prompt.user; tar xzvf foobar.tar.gz
&prompt.user; tar tvf foobar.tar
&prompt.user; tar xvf foobar.tarchecksumAnd a checksum?It is a number generated by adding up all the data in
the file you want to check. If any of the characters
change, the checksum will no longer be equal to the total,
so a simple comparison will allow you to spot the
difference.I did what you said for compiling ports from a CDROM and
it worked great until I tried to install the Kermit
port.&prompt.root; make install
>> cku190.tar.gz doesn't seem to exist on this system.
>> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.Why can it not be found? Have I got a dud CDROM?As explained in the installing ports from CDROM
section, some ports cannot be put on the CDROM set
due to licensing restrictions. Kermit is an example of
that. The licensing terms for Kermit do not allow us to put
the tarball for it on the CDROM, so you will have to fetch
it by hand—sorry!The reason why you got all those error messages was
because you were not connected to the Internet at the time.
Once you have downloaded it from any of the MASTER_SITES
(listed in the Makefile), you can restart the install
process.I did that, but when I tried to put it into
/usr/ports/distfiles I got some error
about not having permission.The ports mechanism will download distribution
tarballs into /usr/ports/distfiles,
but many system administrators will symlink this directory
to a remote file server or local read-only CDROM media.
If this is the case, then you should specify a different
directory to be used for storing distfiles with the
following command:&prompt.root; make DISTDIR=/local/dir/with/write/permission installDoes the ports scheme only work if you have everything
in /usr/ports? My system administrator
says I must put everything under
/u/people/guests/wurzburger, but it
does not seem to work.You can use the PORTSDIR and
PREFIX variables to tell the ports
mechanism to use different directories. For
instance,&prompt.root; make PORTSDIR=/u/people/guests/wurzburger/ports installwill compile the port in
/u/people/guests/wurzburger/ports and
install everything under
/usr/local.&prompt.root; make PREFIX=/u/people/guests/wurzburger/local installwill compile it in /usr/ports and
install it in
/u/people/guests/wurzburger/local.And of course,&prompt.root; make PORTSDIR=../ports PREFIX=../local installwill combine the two (it is too long to write fully on
the page, but it should give you the general idea).imakeSome ports that use &man.imake.1; (a part of the X Windows
System) do not work well with PREFIX, and will insist on
installing under /usr/X11R6. Similarly, some Perl ports
ignore PREFIX and install in the Perl tree. Making these
ports respect PREFIX is a difficult or impossible
job.If you do not fancy typing all that in every time you
install a port, it is a good idea to put these variables
into your environment. Read the manual page for your shell for
instructions on doing so.I do not have a FreeBSD CDROM, but I would like to have
all the tarballs handy on my system so I do not have to wait
for a download every time I install a port. Is there any
way to get them all at once?To get every single tarball for the ports collection,
do:&prompt.root; cd /usr/ports
&prompt.root; make fetchFor all the tarballs for a single ports directory,
do:&prompt.root; cd /usr/ports/directory
&prompt.root; make fetchand for just one port—well, you have probably
guessed already.I know it is probably faster to fetch the tarballs from
one of the FreeBSD mirror sites close by. Is there any way
to tell the port to fetch them from servers other than the
ones listed in the MASTER_SITES?Yes. If you know, for example, that ftp.FreeBSD.org is much closer to you
than the sites listed in MASTER_SITES,
do as follows:&prompt.root; cd /usr/ports/directory
&prompt.root; make MASTER_SITE_OVERRIDE= \
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetchI want to know what files make is
going to need before it tries to pull them down.make fetch-list will display a list
of the files needed for a port.Is there any way to stop the port from compiling? I
want to do some hacking on the source before I install it,
but it is a bit tiresome to watch it and hit
CtrlC
every time.Doing make extract will stop it
after it has fetched and extracted the source code.I am trying to make my own port and I want to be able
to stop it compiling until I have had a chance to see if my
patches worked properly. Is there something like
make extract, but for patches?Yes, make patch is what you want.
You will probably find the PATCH_DEBUG
option useful as well. And by the way, thank you for your
efforts!I have heard that some compiler options can cause bugs.
Is this true? How can I make sure that I compile ports
with the right settings?Yes, with version 2.6.3 of gcc (the
- version shipped with FreeBSD 2.1.0 and 2.1.5), the
+ version shipped with FreeBSD 2.1.0 and 2.1.5), the
option could result in buggy code
unless you used the
option as well. (Most of the ports do not use
). You should be
able to specify the compiler options used by something
like:&prompt.root; make CFLAGS='-O2 -fno-strength-reduce' installor by editing /etc/make.conf, but
unfortunately not all ports respect this. The surest way
is to do make configure, then go into
the source directory and inspect the Makefiles by hand, but
this can get tedious if the source has lots of
sub-directories, each with their own Makefiles.The default FreeBSD compiler options are quite conservative,
so if you have not changed them you should not have any
problems.There are so many ports it is hard to find the one I
want. Is there a list anywhere of what ports are
available?Look in the INDEX file in
/usr/ports. If you would like to
search the ports collection for a keyword, you can do that
too. For example, you can find ports relevant to the LISP
programming language using:&prompt.user; cd /usr/ports
&prompt.user; make search key=lispI went to install the foo port but
the system suddenly stopped compiling it and starting
compiling the bar port. What is going
on?The foo port needs something that is
supplied with bar — for instance,
if foo uses graphics,
bar might have a library with useful
graphics processing routines. Or bar
might be a tool that is needed to compile the
foo port. I installed the
grizzle program from the ports and
frankly it is a complete waste of disk space. I want to
delete it but I do not know where it put all the files.
Any clues?No problem, just type:&prompt.root; pkg_delete grizzle-6.5Alternatively, you can type:&prompt.root; cd /usr/ports/somewhere/grizzle
&prompt.root; make deinstallHang on a minute, you have to know the version number
to use that command. You do not seriously expect me to
remember that, do you?Not at all, you can find it out by doing:&prompt.root; pkg_info -I 'grizzle*'
Information for grizzle-6.5:
grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
arcade game.The version number can be found either by using the
pkg_info or by typing:
ls /var/db/pkgTalking of disk space, the ports directory seems to be
taking up an awful lot of room. Is it safe to go in there
and delete things?Yes, if you have installed a program and are fairly
certain you will not need the source again, there is no
point in keeping it hanging around. The surest way to do
this is:&prompt.root; cd /usr/ports
&prompt.root; make cleanwhich will go through all the ports subdirectories and
delete everything except the skeletons for each
port.It is possible to achieve the same effect without
recursively calling each Makefile. For example, you
can delete all of the work/ subdirectories directly
with the following command:
&prompt.root; find /usr/ports -depth -name work -exec rm -rf {} \;I tried that and it still left all those tarballs or
whatever you called them in the
distfiles directory. Can I delete
those as well?Yes, if you are sure you have finished with them,
those can go as well. They can be removed manually, or by
using make distclean.I like having lots and lots of programs to play with.
Is there any way of installing all the ports in one
go?Just do:&prompt.root; cd /usr/ports
&prompt.root; make installBe careful, as some ports may install files with the same
name. If you install two graphics ports and they both install
/usr/local/bin/plot then you will obviously
have problems.OK, I tried that, but I thought it would take a very
long time so I went to bed and left it to get on with it.
When I looked at the computer this morning, it had only
done three and a half ports. Did something go
wrong?No, the problem is that some of the ports need to ask
you questions that we cannot answer for you (e.g., Do
you want to print on A4 or US letter sized paper?)
and they need to have someone on hand to answer
them.I really do not want to spend all day staring at the
monitor. Any better ideas?OK, do this before you go to bed/work/the local
park:&prompt.root; cd /usr/ports
&prompt.root; make -DBATCH installThis will install every port that does
not require user input. Then, when
you come back, do:&prompt.root; cd /usr/ports
&prompt.root; make -DINTERACTIVE installto finish the job.At work, we are using frobble, which
is in your ports collection, but we have altered it quite a
bit to get it to do what we need. Is there any way of making
our own package, so we can distribute it more easily around
our sites?No problem, assuming you know how to make patches for
your changes:&prompt.root; cd /usr/ports/somewhere/frobble
&prompt.root; make extract
&prompt.root; cd work/frobble-2.8
[Apply your patches]
&prompt.root; cd ../..
&prompt.root; make packageThis ports stuff is really clever. I am desperate to
find out how you did it. What is the secret?Nothing secret about it at all, just look at the
bsd.port.mk and
bsd.port.subdir.mk files in
/usr/ports/Mk/.(Readers with an aversion to intricate shell-scripts are
advised not to look at the files in this directory.)Help! This Port Is Broken!If you come across a port that does not work for you, there are
a few things you can do, including:Fix it! The Porter's
Handbook includes detailed information on the
"Ports" infrastructure so that you can fix the occasional
broken port or even submit your own!Gripe—by email only! Send
email to the maintainer of the port first. Type make
maintainer or read the Makefile
to find the maintainer's email address. Remember to include
the name and version of the port (send the
$FreeBSD: line from the
Makefile) and the output leading up to the
error when you email the maintainer. If you do not get a
response from the maintainer, you can use
&man.send-pr.1; to submit a bug report.Grab the package from an FTP site near you. The
master package collection is on ftp.FreeBSD.org in the packages
directory, but be sure to check your local mirror
first! These are more likely to work
than trying to compile from source and are a lot faster as
well. Use the &man.pkg.add.1; program to install the package
on your system.
diff --git a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
index a0e628a9b5..e4324407d0 100644
--- a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
@@ -1,4891 +1,4891 @@
SeanKellyContributed by JimMockRestructured and updated by PrintingSynopsisLPD spooling systemprintingFreeBSD can be used to print to a wide variety of printers, from the
oldest impact printer to the latest laser printers, and everything in
between, allowing you to produce high quality printed output from the
applications you run.FreeBSD can also be configured to act as a print server on a
network; in this capacity FreeBSD can receive print jobs from a variety
of other computers, including other FreeBSD computers, Windows and MacOS
hosts. FreeBSD will ensure that one job at a time is printed, and can
keep statistics on which users and machines are doing the most printing,
produce banner pages showing who's printout is who's, and
more.After reading this chapter, you will know:How to configure the FreeBSD print spooler.How to install print filters, to handle special print jobs
differently, including converting incoming documents to print
formats that your printers understand.How to enable header, or banner pages on your printout.How to print to printers connected to other computers.How to print to printers connected directly to the
network.How to control printer restrictions, including limiting the size
of print jobs, and preventing certain users from printing.How to keep printer statistics, and account for printer
usage.How to troubleshoot printing problems.Before reading this chapter, you should:Know how to configure and install a new kernel
().IntroductionIn 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.LPD 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.centronicsparallel printersParallel 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 usually somewhat faster
but uses up a precious IRQ line. Some newer HP printers
are claimed not to work correctly in interrupt mode,
apparently due to some (not yet exactly understood) timing
problem. These printers need polled mode. You should use
whichever one works. Some printers will work in both
modes, but are painfully slow in interrupt mode.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 -d /dev/lptNto set interrupt-driven mode for
lptN.Type:&prompt.root; lptcontrol -p -d /dev/lptNto 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
+ 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:&prompt.user; $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:&prompt.user; >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 is 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 feed
# 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/ifhp: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 pagesheader pagesheader 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 section, 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 the Output Filters section 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 the Header Page Options section 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 the Simple
Printer Setup section. 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 is 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 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/bamboo/minfree
User 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 computer 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. An 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 file she is 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 take 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 is 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 is running, 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.