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 b2c496c953..b440520773 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,4106 +1,4106 @@
Advanced NetworkingSynopsisThe following chapter will cover some of the more frequently
used network services on Unix systems. This, of course, will
pertain to configuring said services on your FreeBSD system.CoranthGryphonContributedGateways and RoutesroutinggatewaysubnetFor one machine to be able to find another, there must be a
mechanism in place to describe how to get from one to the other. This is
called Routing. A route is a defined pair of addresses: a
destination and a gateway. The pair
indicates that if you are trying to get to this
destination, send along through this
gateway. There are three types of destinations:
individual hosts, subnets, and default. The
default route is used if none of the other routes apply.
We will talk a little bit more about default routes later on. There are
also three types of gateways: individual hosts, interfaces (also called
links), and Ethernet hardware addresses.An exampleTo illustrate different aspects of routing, we will use the
following example which is the output of the command netstat
-r:Destination Gateway Flags Refs Use Netif Expire
default outside-gw UGSc 37 418 ppp0
localhost localhost UH 0 181 lo0
test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77
10.20.30.255 link#1 UHLW 1 2421
foobar.com link#1 UC 0 0
host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0
host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 =>
host2.foobar.com link#1 UC 0 0
224 link#1 UC 0 0default routeThe first two lines specify the default route (which we will cover
in the next section) and the localhost route.loopback deviceThe interface (Netif column) that it specifies
to use for localhost is
lo0, also known as the loopback device. This
says to keep all traffic for this destination internal, rather than
sending it out over the LAN, since it will only end up back where it
started anyway.EthernetMAC addressThe next thing that stands out are the 0:e0:... addresses. These are Ethernet hardware
addresses. FreeBSD will automatically identify any hosts
(test0 in the example) on the local Ethernet and add
a route for that host, directly to it over the Ethernet interface,
ed0. There is also a timeout
(Expire column) associated with this type of route,
which is used if we fail to hear from the host in a specific amount of
time. In this case the route will be automatically deleted. These
hosts are identified using a mechanism known as RIP (Routing
Information Protocol), which figures out routes to local hosts based
upon a shortest path determination.subnetFreeBSD will also add subnet routes for the local subnet (10.20.30.255 is the broadcast address for the
subnet 10.20.30, and foobar.com is the domain name associated
with that subnet). The designation link#1 refers
to the first Ethernet card in the machine. You will notice no
additional interface is specified for those.Both of these groups (local network hosts and local subnets) have
their routes automatically configured by a daemon called
routed. If this is not run, then only routes which
are statically defined (ie. entered explicitly) will exist.The host1 line refers to our host, which it
knows by Ethernet address. Since we are the sending host, FreeBSD
knows to use the loopback interface (lo0)
rather than sending it out over the Ethernet interface.The two host2 lines are an example of what
happens when we use an &man.ifconfig.8; alias (see the section of Ethernet for
reasons why we would do this). The => symbol
after the lo0 interface says that not only
are we using the loopback (since this is address also refers to the
local host), but specifically it is an alias. Such routes only show
up on the host that supports the alias; all other hosts on the local
network will simply have a link#1 line for
such.The final line (destination subnet 224) deals
with MultiCasting, which will be covered in a another section.The other column that we should talk about are the
Flags. Each route has different attributes that
are described in the column. Below is a short table of some of these
flags and their meanings:UUp: The route is active.HHost: The route destination is a single host.GGateway: Send anything for this destination on to this
remote system, which will figure out from there where to send
it.SStatic: This route was configured manually, not
automatically generated by the system.CClone: Generates a new route based upon this route for
machines we connect to. This type of route is normally used
for local networks.WWasCloned: Indicated a route that was auto-configured
based upon a local area network (Clone) route.LLink: Route involves references to Ethernet
hardware.Default routesdefault routeWhen the local system needs to make a connection to remote host,
it checks the routing table to determine if a known path exists. If
the remote host falls into a subnet that we know how to reach (Cloned
routes), then the system checks to see if it can connect along that
interface.If all known paths fail, the system has one last option: the
default route. This route is a special type of gateway
route (usually the only one present in the system), and is always
marked with a c in the flags field. For hosts on a
local area network, this gateway is set to whatever machine has a
direct connection to the outside world (whether via PPP link, or your
hardware device attached to a dedicated data line).If you are configuring the default route for a machine which
itself is functioning as the gateway to the outside world, then the
default route will be the gateway machine at your Internet Service
Provider's (ISP) site.Let us look at an example of default routes. This is a common
configuration:
[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW]
The hosts Local1 and Local2 are
at your site, with the formed being your PPP connection to your ISP's
Terminal Server. Your ISP has a local network at their site, which
has, among other things, the server where you connect and a hardware
device (T1-GW) attached to the ISP's Internet feed.The default routes for each of your machines will be:hostdefault gatewayinterfaceLocal2Local1EthernetLocal1T1-GWPPPA common question is Why (or how) would we set the T1-GW to
be the default gateway for Local1, rather than the ISP server it is
connected to?.Remember, since the PPP interface is using an address on the ISP's
local network for your side of the connection, routes for any other
machines on the ISP's local network will be automatically generated.
Hence, you will already know how to reach the T1-GW machine, so there
is no need for the intermediate step of sending traffic to the ISP
server.As a final note, it is common to use the address ...1 as the gateway address for your local
network. So (using the same example), if your local class-C address
space was 10.20.30 and your ISP was
using 10.9.9 then the default routes
would be:
Local2 (10.20.30.2) --> Local1 (10.20.30.1)
Local1 (10.20.30.1, 10.9.9.30) --> T1-GW (10.9.9.1)
Dual homed hostsdual homed hostsThere is one other type of configuration that we should cover, and
that is a host that sits on two different networks. Technically, any
machine functioning as a gateway (in the example above, using a PPP
connection) counts as a dual-homed host. But the term is really only
used to refer to a machine that sits on two local-area
networks.In one case, the machine as two Ethernet cards, each having an
address on the separate subnets. Alternately, the machine may only
have one Ethernet card, and be using &man.ifconfig.8; aliasing. The former is
used if two physically separate Ethernet networks are in use, the
latter if there is one physical network segment, but two logically
separate subnets.Either way, routing tables are set up so that each subnet knows
that this machine is the defined gateway (inbound route) to the other
subnet. This configuration, with the machine acting as a Bridge
between the two subnets, is often used when we need to implement
packet filtering or firewall security in either or both
directions.Routing propagationrouting propogationWe have already talked about how we define our routes to the
outside world, but not about how the outside world finds us.We already know that routing tables can be set up so that all
traffic for a particular address space (in our examples, a class-C
subnet) can be sent to a particular host on that network, which will
forward the packets inbound.When you get an address space assigned to your site, your service
provider will set up their routing tables so that all traffic for your
subnet will be sent down your PPP link to your site. But how do sites
across the country know to send to your ISP?There is a system (much like the distributed DNS information) that
keeps track of all assigned address-spaces, and defines their point of
connection to the Internet Backbone. The Backbone are
the main trunk lines that carry Internet traffic across the country,
and around the world. Each backbone machine has a copy of a master
set of tables, which direct traffic for a particular network to a
specific backbone carrier, and from there down the chain of service
providers until it reaches your network.It is the task of your service provider to advertise to the
backbone sites that they are the point of connection (and thus the
path inward) for your site. This is known as route
propagation.TroubleshootingtracerouteSometimes, there is a problem with routing propagation, and some
sites are unable to connect to you. Perhaps the most useful command
for trying to figure out where a routing is breaking down is the
&man.traceroute.8; command. It is equally useful if you cannot seem
to make a connection to a remote machine (i.e. &man.ping.8;
fails).The &man.traceroute.8; command is run with the name of the remote
host you are trying to connect to. It will show the gateway hosts
along the path of the attempt, eventually either reaching the target
host, or terminating because of a lack of connection.For more information, see the manual page for
&man.traceroute.8;.StevePetersonWrittenBridgingIntroductionIP subnetbridgeIt is sometimes useful to divide one physical network (i.e., an
Ethernet segment) into two separate network segments, without having
to create IP subnets and use a router to connect the segments
together. A device that connects two networks together in this
fashion is called a bridge. and a FreeBSD system with two network
interface cards can act as a bridge.The bridge works by learning the MAC layer addresses (i.e.,
Ethernet addresses) of the devices on each of its network interfaces.
It forwards traffic between two networks only when its source and
destination are on different networks.In many respects, a bridge is like an Ethernet switch with very
few ports.Situations where bridging is appropriateThere are two common situations in which a bridge is used
today.High traffic on a segmentSituation one is where your physical network segment is
overloaded with traffic, but you don't want for whatever reason to
subnet the network and interconnect the subnets with a
router.Let's consider an example of a newspaper where the Editorial and
Production departments are on the same subnetwork. The Editorial
users all use server A for file service, and the Production users
are on server B. An Ethernet is used to connect all users together,
and high loads on the network are slowing things down.If the Editorial users could be segregated on one network
segment and the Production users on another, the two network
segments could be connected with a bridge. Only the network traffic
destined for interfaces on the "other" side of the bridge would be
sent to the other network, reducing congestion on each network
segment.Filtering/traffic shaping firewallfirewallIP MasqueradingThe second common situation is where firewall functionality is
needed without IP Masquerading (NAT).An example is a small company that is connected via DSL or ISDN
to their ISP. They have a 13 address global IP allocation for their
ISP and have 10 PCs on their network. In this situation, using a
router-based firewall is difficult because of subnetting
issues.routerDSLISDNA bridge-based firewall can be configured and dropped into the
path just downstream of their DSL/ISDN router without any IP
numbering issues.Configuring a bridgeNetwork interface card selectionA bridge requires at least two network cards to function.
Unfortunately, not all network interface cards as of FreeBSD 4.0
support bridging. Read &man.bridge.4; for details on the cards that
are supported.Install and test the two network cards before continuing.Kernel configuration changeskernel configurationkernel configurationoptions BRIDGETo enable kernel support for bridging, add theoptions BRIDGEstatement to your kernel configuration file, and rebuild your
kernel.Firewall supportfirewallIf you are planning to use the bridge as a firewall, you will
need to add the IPFIREWALL option as well. Read for general information on configuring the
bridge as a firewall.If you need to allow non-IP packets (such as ARP) to flow
through the bridge, there is an undocumented firewall option that
must be set. This option is
IPFIREWALL_DEFAULT_TO_ACCEPT. Note that this
changes the default rule for the firewall to accept any packet.
Make sure you know how this changes the meaning of your ruleset
before you set it.Traffic shaping supportIf you want to use the bridge as a traffic shaper, you will need
to add the DUMMYNET option to your kernel
configuration. Read &man.dummynet.4; for further
information.Enabling the bridgeAdd the linenet.link.ether.bridge=1to /etc/sysctl.conf to enable the bridge at
runtime. If you want the bridged packets to be filtered by &man.ipfw.8;,
you should also addnet.link.ether.bridge_ipfw=1as well.PerformanceMy bridge/firewall is a Pentium 90 with one 3Com 3C900B and one
3C905B. The protected side of the network runs at 10mbps half duplex
and the connection between the bridge and my router (a Cisco 675) runs
at 100mbps full duplex. With no filtering enabled, I've found that
the bridge adds about 0.4 milliseconds of latency to pings from the
protected 10mbps network to the Cisco 675.Other informationIf you want to be able to telnet into the bridge from the network,
it is OK to assign one of the network cards an IP address. The
consensus is that assigning both cards an address is a bad
idea.If you have multiple bridges on your network, there cannot be more
than one path between any two workstations. Technically, this means
that there is no support for spanning tree link management.BillSwingleWrittenNFSNFSAmong the many different file systems that FreeBSD supports is
a very unique type, the Network File System or NFS. NFS allows you
to share directories and files on one machine with one or more other
machines via the network they are attached to. Using NFS, users and
programs can access files on remote systems as if they were local
files.NFS has several benefits:Local workstations don't need as much disk space because
commonly used data can be stored on a single machine and still
remain accessible to everyone on the network.There is no need for users to have unique home directories
on every machine on your network. Once they have an established
directory that is available via NFS it can be accessed from
anywhere.Storage devices such as floppies and CDROM drives can be
used by other machines on the network eliminating the need for
extra hardware.How It WorksNFS is composed of two sides – a client side and a
server side. Think of it as a want/have relationship. The client
wants the data that the server side
has. The server shares its data with the
client. In order for this system to function properly a few
processes have to be configured and running properly.The server has to be running the following daemons:NFSserverportmapmountdnfsdnfsd - The NFS Daemon which services
requests from NFS clients.mountd - The NFS Mount Daemon which
actually carries out requests that &man.nfsd.8; passes on to
it.portmap - The
portmapper daemon which allows NFS
clients to find out which port the NFS server is
using.The client side only needs to run a single daemon:NFSclientnfsiodnfsiod - The NFS async I/O Daemon which
services requests from its NFS server.Configuring NFSNFSconfigurationLuckily for us, on a FreeBSD system this setup is a snap. The
processes that need to be running can all be run at boot time with
a few modifications to your /etc/rc.conf
file.On the NFS server make sure you have:portmap_enable="YES"
nfs_server_enable="YES"
nfs_server_flags="-u -t -n 4"
mountd_flags="-r"mountd is automatically run whenever the
NFS server is enabled. The and
flags to nfsd tell it to
serve UDP and TCP clients. The flag tells
nfsd to start 4 copies of itself.On the client, make sure you have:nfs_client_enable="YES"
nfs_client_flags="-n 4"Like nfsd, the tells
nfsiod to start 4 copies of itself.The last configuration step requires that you create a file
called /etc/exports. The exports file
specifies which file systems on your server will be shared
(a.k.a., exported) and with what clients they will
be shared. Each line in the file specifies a file system to be
shared. There are a handful of options that can be used in this
file but only a few will be mentioned here. You can find out
about the rest in the &man.exports.5; man page.Here are a few example /etc/exports
entries:NFSexporting filesystemsThe following line exports /cdrom to
three silly machines that have the same domain name as the server
(hence the lack of a domain name for each) or have entries in your
/etc/hosts file. The
flag makes the shared file system read-only. With this flag, the
remote system will not be able to make any changes to the
shared file system./cdrom -ro moe larry curlyThe following line exports /home to three
hosts by IP address. This is a useful setup if you have a
private network but do not have DNS running. The
flag allows all the directories below
the specified file system to be exported as well./home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4The following line exports /a to two
machines that have different domain names than the server. The
flag allows
the root user on the remote system to write to the shared
file system as root. Without the -maproot=0 flag even if
someone has root access on the remote system they won't
be able to modify files on the shared file system./a -maproot=0 host.domain.com box.example.comIn order for a client to share an exported file system it must
have permission to do so. Make sure your client is listed in your
/etc/exports file.It's important to remember that you must restart mountd
whenever you modify /etc/exports so that
your changes take effect. This can be accomplished by sending
the hangup signal to the mountd process :&prompt.root; kill -HUP `cat /var/run/mountd.pid`Now that you have made all these changes you can just reboot
and let FreeBSD start everything for you at boot time or you can
run the following commands as root:On the NFS server:&prompt.root; portmap
&prompt.root; nfsd -u -t -n 4
&prompt.root; mountd -rOn the NFS client:&prompt.root; nfsiod -n 4Now you should be ready to actually mount a remote file
system. This can be done one of two ways. In these examples the
server's name will be server and the client's
name will be client. If you just want to
temporarily mount a remote file system or just want to test out
your config you can run a command like this as root on the
client:NFSmounting filesystems&prompt.root; mount server:/home /mntThis will mount /home on the server on
/mnt on the client. If everything is setup
correctly you should be able to go into /mnt on the client and see
all the files that are on the server.If you want to permanently (each time you reboot) mount a
remote file system you need to add it to your
/etc/fstab file. Here is an example
line:server:/home /mnt nfs rw 0 0Read the &man.fstab.5; man page for more options.Practical UsesThere are many very cool uses for NFS. Some of the more common
ones are listed below.NFSusesHave several machines on a network and share a CDROM or
floppy drive among them. This is cheaper and often more
convenient.With so many machines on a network, it gets old having your
personal files strewn all over the place. You can have a
central NFS server that houses all user home directories and
shares them with the rest of the machines on the LAN, so no
matter where you log in you will have the same home
directory.When you get to reinstalling FreeBSD on one of your
machines, NFS is the way to go! Just pop your distribution
CDROM into your file server and away you go!Have a common /usr/ports/distfiles
directory that all your machines share. That way, when you go
to install a port that you've already installed on a different
machine, you do not have to download the source all over
again!JohnLindContributedProblems 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 file system with the option . These
options may be specified using the fourth field of the
fstab entry on the client for automatic
mounts, or by using the parameter of the mount
command for manual mounts.It should be noted that there is a different problem,
sometimes mistaken for this one, when the NFS servers and clients
are on different networks. If that is the case, make
certain that your routers are routing the
necessary UDP information, or you will not get anywhere, no matter
what else you are doing.In the following examples, fastws is the host
(interface) name of a high-performance workstation, and
freebox is the host (interface) name of a FreeBSD
system with a lower-performance Ethernet adapter. Also,
/sharedfs will be the exported NFS
filesystem (see man exports), and
/project will be the mount point on the
client for the exported file system. In all cases, note that
additional options, such as or
and may be desirable in
your application.Examples for the FreeBSD system (freebox) as
the client: in /etc/fstab on freebox:fastws:/sharedfs /project nfs rw,-r=1024 0 0As a manual mount command on freebox:&prompt.root; mount -t nfs -o -r=1024 fastws:/sharedfs /projectExamples for the FreeBSD system as the server: in
/etc/fstab on fastws:freebox:/sharedfs /project nfs rw,-w=1024 0 0As a manual mount command on fastws:&prompt.root; mount -t nfs -o -w=1024 freebox:/sharedfs /projectNearly any 16-bit Ethernet adapter will allow operation
without the above restrictions on the read or write size.For anyone who cares, here is what happens when the failure
occurs, which also explains why it is unrecoverable. NFS
typically works with a block size of 8k (though it
may do fragments of smaller sizes). Since the maximum Ethernet
packet is around 1500 bytes, the NFS block gets
split into multiple Ethernet packets, even though it is still a
single unit to the upper-level code, and must be received,
assembled, and acknowledged as a unit. The
high-performance workstations can pump out the packets which
comprise the NFS unit one right after the other, just as close
together as the standard allows. On the smaller, lower capacity
cards, the later packets overrun the earlier packets of the same
unit before they can be transferred to the host and the unit as a
whole cannot be reconstructed or acknowledged. As a result, the
workstation will time out and try again, but it will try again
with the entire 8K unit, and the process will be repeated, ad
infinitum.By keeping the unit size below the Ethernet packet size
limitation, we ensure that any complete Ethernet packet received
can be acknowledged individually, avoiding the deadlock
situation.Overruns may still occur when a high-performance workstations
is slamming data out to a PC system, but with the better cards,
such overruns are not guaranteed on NFS units. When
an overrun occurs, the units affected will be retransmitted, and
there will be a fair chance that they will be received, assembled,
and acknowledged.MartinRentersContributedDiskless Operationdiskless workstationnetboot.com/netboot.rom
allow you to boot your FreeBSD machine over the network and run FreeBSD
without having a disk on your client. Under 2.0 it is now possible to
have local swap. Swapping over NFS is also still supported.Supported Ethernet cards include: Western Digital/SMC 8003, 8013,
8216 and compatibles; NE1000/NE2000 and compatibles (requires
recompile)Setup InstructionsFind a machine that will be your server. This machine will
require enough disk space to hold the FreeBSD 2.0 binaries and
have bootp, tftp and NFS services available. Tested
machines:HP-UXHP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't
work)SolarisSun/Solaris 2.3. (you may need to get bootp)Set up a bootp server to provide the client with IP address, gateway,
netmask.diskless:\
:ht=ether:\
:ha=0000c01f848a:\
:sm=255.255.255.0:\
:hn:\
:ds=192.1.2.3:\
:ip=192.1.2.4:\
:gw=192.1.2.5:\
:vm=rfc1048:TFTPbootpSet up a TFTP server (on same machine as bootp server) to
provide booting information to client. The name of this file is
cfg.X.X.X.X (or
/tftpboot/cfg.X.X.X.X,
it will try both) where X.X.X.X is the
IP address of the client. The contents of this file can be any
valid netboot commands. Under 2.0, netboot has the following
commands:helpprint help listip
print/set client's IP addressserver
print/set bootp/tftp server addressnetmask
print/set netmaskhostname nameprint/set hostnamekernel
print/set kernel namerootfs
print/set root filesystemswapfs
print/set swap filesystemswapsize
set diskless swapsize in KBytesdiskbootboot from diskautobootcontinue boot processtrans
|turn transceiver on|offflags
set boot flagsA typical completely diskless config file might contain:rootfs 192.1.2.3:/rootfs/myclient
swapfs 192.1.2.3:/swapfs
swapsize 20000
hostname myclient.mydomainA config file for a machine with local swap might contain:rootfs 192.1.2.3:/rootfs/myclient
hostname myclient.mydomainEnsure that your NFS server has exported the root (and swap if
applicable) filesystems to your client, and that the client has
root access to these filesystems A typical
/etc/exports file on FreeBSD might look
like:/rootfs/myclient -maproot=0:0 myclient.mydomain
/swapfs -maproot=0:0 myclient.mydomainAnd on HP-UX:/rootfs/myclient -root=myclient.mydomain
/swapfs -root=myclient.mydomainNFSswapping overIf you are swapping over NFS (completely diskless
configuration) create a swap file for your client using
dd. If your swapfs
command has the arguments /swapfs and
the size 20000 as in the example above, the swapfile for
myclient will be called
/swapfs/swap.X.X.X.X
where X.X.X.X is the client's IP
address, e.g.:&prompt.root; dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000Also, the client's swap space might contain sensitive
information once swapping starts, so make sure to restrict read
and write access to this file to prevent unauthorized
access:&prompt.root; chmod 0600 /swapfs/swap.192.1.2.4Unpack the root filesystem in the directory the client will
use for its root filesystem (/rootfs/myclient
in the example above).On HP-UX systems: The server should be running HP-UX 9.04
or later for HP9000/800 series machines. Prior versions do not
allow the creation of device files over NFS.When extracting /dev in
/rootfs/myclient, beware that some
systems (HPUX) will not create device files that FreeBSD is
happy with. You may have to go to single user mode on the
first bootup (press control-c during the bootup phase), cd
/dev and do a sh ./MAKEDEV
all from the client to fix this.Run netboot.com on the client or make an
EPROM from the netboot.rom fileUsing Shared / and /usr
filesystemsAlthough this is not an officially sanctioned or supported way
of doing this, some people report that it works quite well. If
anyone has any suggestions on how to do this cleanly, please tell
&a.doc;.Compiling netboot for specific setupsNetboot can be compiled to support NE1000/2000 cards by changing
the configuration in
/sys/i386/boot/netboot/Makefile. See the
comments at the top of this file.ISDNA good resource for information on ISDN technology and hardware is
Dan Kegel's ISDN
Page.A quick simple road map to ISDN follows:If you live in Europe you might want to investigate the ISDN card
section.If you are planning to use ISDN primarily to connect to the
Internet with an Internet Provider on a dial-up non-dedicated basis,
you might look into Terminal Adapters. This will give you the
most flexibility, with the fewest problems, if you change
providers.If you are connecting two LANs together, or connecting to the
Internet with a dedicated ISDN connection, you might consider
the stand alone router/bridge option.Cost is a significant factor in determining what solution you will
choose. The following options are listed from least expensive to most
expensive.HellmuthMichaelisContributedISDN CardsISDNcardsThis section is really only relevant to ISDN users in countries
where the DSS1/Q.931 ISDN standard is supported.Some growing number of PC ISDN cards are supported under FreeBSD
2.2.X and up by the isdn4bsd driver package. It is still under
development but the reports show that it is successfully used all over
Europe.isdn4bsdThe latest isdn4bsd version is available from ftp://isdn4bsd@ftp.consol.de/pub/,
the main isdn4bsd FTP site (you have to log in as user
isdn4bsd , give your mail address as the password
and change to the pub directory. Anonymous FTP
as user ftp or anonymous
will not give the desired result).Isdn4bsd allows you to connect to other ISDN routers using either
IP over raw HDLC or by using synchronous PPP. A telephone answering
machine application is also available.Many ISDN PC cards are supported, mostly the ones with a Siemens
ISDN chipset (ISAC/HSCX), support for other chipsets (from Motorola,
Cologne Chip Designs) is currently under development. For an
up-to-date list of supported cards, please have a look at the README
file.In case you are interested in adding support for a different ISDN
protocol, a currently unsupported ISDN PC card or otherwise enhancing
isdn4bsd, please get in touch with hm@kts.org.A majordomo maintained mailing list is available. To join the
list, send mail to &a.majordomo; and
specify:subscribe freebsd-isdnin the body of your message.ISDN Terminal AdaptersTerminal adapters(TA), are to ISDN what modems are to regular
phone lines.modemMost TA's use the standard hayes modem AT command set, and can be
used as a drop in replacement for a modem.A TA will operate basically the same as a modem except connection
and throughput speeds will be much faster than your old modem. You
will need to configure PPP exactly the same
as for a modem setup. Make sure you set your serial speed as high as
possible.PPPThe main advantage of using a TA to connect to an Internet
Provider is that you can do Dynamic PPP. As IP address space becomes
more and more scarce, most providers are not willing to provide you
with a static IP anymore. Most stand-alone routers are not able to
accommodate dynamic IP allocation.TA's completely rely on the PPP daemon that you are running for
their features and stability of connection. This allows you to
upgrade easily from using a modem to ISDN on a FreeBSD machine, if you
already have PPP setup. However, at the same time any problems you
experienced with the PPP program and are going to persist.If you want maximum stability, use the kernel PPP option, not the user-land iijPPP.The following TA's are know to work with FreeBSD.Motorola BitSurfer and Bitsurfer ProAdtranMost other TA's will probably work as well, TA vendors try to make
sure their product can accept most of the standard modem AT command
set.The real problem with external TA's is like modems you need a good
serial card in your computer.You should read the FreeBSD Serial
Hardware tutorial for a detailed understanding of
serial devices, and the differences between asynchronous and
synchronous serial ports.A TA running off a standard PC serial port (asynchronous) limits
you to 115.2Kbs, even though you have a 128Kbs connection. To fully
utilize the 128Kbs that ISDN is capable of, you must move the TA to a
synchronous serial card.Do not be fooled into buying an internal TA and thinking you have
avoided the synchronous/asynchronous issue. Internal TA's simply have
a standard PC serial port chip built into them. All this will do, is
save you having to buy another serial cable, and find another empty
electrical socket.A synchronous card with a TA is at least as fast as a stand-alone
router, and with a simple 386 FreeBSD box driving it, probably more
flexible.The choice of sync/TA v.s. stand-alone router is largely a
religious issue. There has been some discussion of this in
the mailing lists. I suggest you search the archives for
the complete discussion.Stand-alone ISDN Bridges/RoutersISDNstand-alone bridges/routersISDN bridges or routers are not at all specific to FreeBSD
or any other operating system. For a more complete
description of routing and bridging technology, please refer
to a Networking reference book.In the context of this page, the terms router and bridge will
be used interchangeably.As the cost of low end ISDN routers/bridges comes down, it
will likely become a more and more popular choice. An ISDN
router is a small box that plugs directly into your local
Ethernet network(or card), and manages its own connection to
the other bridge/router. It has all the software to do PPP
and other protocols built in.A router will allow you much faster throughput that a
standard TA, since it will be using a full synchronous ISDN
connection.The main problem with ISDN routers and bridges is that
interoperability between manufacturers can still be a problem.
If you are planning to connect to an Internet provider, you
should discuss your needs with them.If you are planning to connect two LAN segments together,
ie: home LAN to the office LAN, this is the simplest lowest
maintenance solution. Since you are buying the equipment for
both sides of the connection you can be assured that the link
will work.For example to connect a home computer or branch office
network to a head office network the following setup could be
used.Branch office or Home network10 base 2Network uses a bus based topology with 10 base 2
Ethernet ("thinnet"). Connect router to network cable with
AUI/10BT transceiver, if necessary.---Sun workstation
|
---FreeBSD box
|
---Windows 95 (Do not admit to owning it)
|
Stand-alone router
|
ISDN BRI line10 Base 2 EthernetIf your home/branch office is only one computer you can use a
twisted pair crossover cable to connect to the stand-alone router
directly.Head office or other LAN10 base TNetwork uses a star topology with 10 base T Ethernet
("Twisted Pair"). -------Novell Server
| H |
| ---Sun
| |
| U ---FreeBSD
| |
| ---Windows 95
| B |
|___---Stand-alone router
|
ISDN BRI lineISDN Network DiagramOne large advantage of most routers/bridges is that they allow you
to have 2 separate independent PPP connections to
2 separate sites at the same time. This is not
supported on most TA's, except for specific(expensive) models that
have two serial ports. Do not confuse this with channel bonding, MPP
etc.This can be very useful feature, for example if you have an
dedicated ISDN connection at your office and would like to
tap into it, but don't want to get another ISDN line at work. A router
at the office location can manage a dedicated B channel connection
(64Kbs) to the Internet, as well as a use the other B channel for a
separate data connection. The second B channel can be used for
dial-in, dial-out or dynamically bond(MPP etc.) with the first B channel
for more bandwidth.IPX/SPXAn Ethernet bridge will also allow you to transmit more than just
IP traffic, you can also send IPX/SPX or whatever other protocols you
use.BillSwingleWrittenEricOgrenEnahancedUdoErdelhoffEnhancedNIS/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 (or yp), but due to
copyright violations, Sun was forced to change the name.NISdomainsIt is a RPC-based client/server system that allows a group
of machines within an NIS domain to share a common set of
configuration files. This permits a system administrator to set
up NIS client systems with only minimal configuration data and
add, remove or modify configuration data from a single
location.Windows NTIt is similar to Windows NT's domain system; although the
internal implementation of the two aren't at all similar,
the basic functionality can be compared.Terms/processes you should knowThere are several terms and several important user processes
that you will come across when
attempting to implement NIS on FreeBSD, whether you are trying to
create an NIS server or act an NIS client:The NIS domainname. An NIS master
server and all of its clients (including its slave servers) have
a NIS domainname. Similar to an NT domain name, the NIS
domainname does not have anything to do with DNS.portmapportmap. portmap
must be running in order to enable RPC (Remote Procedure Call, a
network protocol used by NIS). If portmap is
not running, it will be impossible to run an NIS server, or to
act as an NIS client.ypbind. ypbind
“binds” an NIS client to its NIS server.
It will take the NIS domainname from the system, and
using RPC, connect to the server. ypbind is
the core of client-server communication in an NIS environment; if
ypbind dies on a client machine, it will not
be able to access the NIS server.ypserv. ypserv,
which should only be running on NIS servers, is the NIS server
process itself. If &man.ypserv.8; dies, then the server will no longer be
able to respond to NIS requests (hopefully, there is a slave
server to take over for it).There are some implementations of NIS (but not the
FreeBSD one), that don't try to reconnect to another server
if the server it used before dies. Often, the only thing
that helps in this case is to restart the server process (or
even the whole server) or the ypbind process
on the client.rpc.yppasswdd.
rpc.yppasswdd, another process that should
only be running on NIS master servers, is a daemon that will
allow NIS clients to change their NIS passwords.
If this daemon is not running, users will have to login to the
NIS master server and change their passwords there.How does it work?There are three types of hosts in an NIS environment; master
servers, slave servers, and clients. Servers act as a central
repository for host configuration information. Master servers
hold the authoritative copy of this information, while slave
servers mirror this information for redundancy. Clients rely on
the servers to provide this information to them.Information in many files can be shared in this manner. The
master.passwd, group,
and hosts files are commonly shared via NIS.
Whenever a process on a client needs information that would
normally be found in these files locally, it makes a query to the
server it is bound to, to get this information.Machine typesNISmaster serverA NIS master server.
This server, analogous to a Windows
NT primary domain controller, maintains the files used by all
of the NIS clients. The passwd,
group, and other various files used by the
NIS clients live on the master server.It is possible for one machine to be an NIS
master server for more than one NIS domain. However, this will
not be covered in this introduction, which assumes a relatively
small-scale NIS environment.NISslave serverNIS slave servers.
Similar to NT's backup domain
controllers, NIS slave servers maintain copies of the NIS
master's data files. NIS slave servers provide the redundancy,
which is needed in important environments. They also help
to balance the load of the master server: NIS Clients always
attach to the NIS server whose response they get first, and
this includes slave-server-replies.NISclientNIS clients. NIS clients, like most
NT workstations, authenticate against the NIS server (or the NT
domain controller in the NT Workstation case) to log on.Using NIS/YPThis section will deal with setting up a sample NIS
environment.This section assumes that you are running FreeBSD 3.3
or later. The instructions given here will
probably work for any version of FreeBSD greater
than 3.0, but there are no guarantees that this is
true.PlanningLet's assume that you are the administrator of a small
university lab. This lab, which consists of 15 FreeBSD machines,
currently has no centralized point of administration; each machine
has its own /etc/passwd and
/etc/master.passwd. These files are kept in
sync with each other only through manual intervention;
currently, when you add a user to the lab, you must run
adduser on all 15 machines.
Clearly, this has to change, so you have decided to convert the
lab to use NIS, using two of the machines as servers.Therefore, the configuration of the lab now looks something
like:Machine nameIP addressMachine roleellington10.0.0.2NIS mastercoltrane10.0.0.3NIS slavebasie10.0.0.4Faculty workstationbird10.0.0.5Client machinecli[1-11]10.0.0.[6-17]Other client machinesIf you are setting up a NIS scheme for the first time, it
is a good idea to think through how you want to go about it. No
matter what the size of your network, there are a few decisions
that need to be made.Choosing a NIS Domain NameNISdomainnameThis might not be the domainname that you
are used to. It is more accurately called the
NIS domainname. When a client broadcasts its
requests for info, it includes the name of the NIS domain
that it is part of. This is how multiple servers on one
network can tell which server should answer which request.
Think of the NIS domainname as the name for a group of hosts
that are related in some way.Some organizations choose to use their Internet domainname
for their NIS domainname. This is not recommended as it can
cause confusion when trying to debug network problems. The
NIS domainname should be unique within your network and it is
helpful if it describes the group of machines it represents.
For example, the Art department at Acme Inc. might be in the
"acme-art" NIS domain. For this example, assume you have
chosen the name test-domain.SunOSHowever, some operating systems (notably SunOS) use their
NIS domain name as their Internet domain name.
If one or more machines on your network have this restriction,
you must use the Internet domain name as
your NIS domain name.Physical Server RequirementsThere are several things to keep in mind when choosing a
machine to use as a NIS server. One of the unfortunate things
about NIS is the level of dependency the clients have on the
server. If a client cannot contact the server for its NIS
domain, very often the machine becomes unusable. The lack of
user and group information causes most systems to temporarily
freeze up. With this in mind you should make sure to choose a
machine that won't be prone to being rebooted regularly, or
one that might be used for development. The NIS server should
ideally be a stand alone machine whose sole purpose in life is
to be an NIS server. If you have a network that is not very
heavily used, it is acceptable to put the NIS server on a
machine running other services, just keep in mind that if the
NIS server becomes unavailable, it will affect
all of your NIS clients adversely.NIS Servers The canonical copies of all NIS information are stored on
a single machine called the NIS master server. The databases
used to store the information are called NIS maps. In FreeBSD,
these maps are stored in
/var/yp/[domainname] where
[domainname] is the name of the NIS domain
being served. A single NIS server can support several domains
at once, therefore it is possible to have several such
directories, one for each supported domain. Each domain will
have its own independent set of maps.NIS master and slave servers handle all NIS requests with
the ypserv daemon. Ypserv
is responsible for receiving incoming requests from NIS clients,
translating the requested domain and map name to a path to the
corresponding database file and transmitting data from the
database back to the client.Setting up a NIS master serverNISserver configurationSetting up a master NIS server can be relatively straight
forward, depending on your needs. FreeBSD comes with support
for NIS out-of-the-box. All you need is to add the following
lines to /etc/rc.conf, and FreeBSD will
do the rest for you.nisdomainname="test-domain"
This line will set the NIS domainname to
test-domain
upon network setup (e.g. after reboot).nis_server_enable="YES"
This will tell FreeBSD to start up the NIS server processes
when the networking is next brought up.nis_yppasswdd_enable="YES"
This will enable the rpc.yppasswdd
daemon, which, as mentioned above, will allow users to
change their NIS password from a client machine.Now, all you have to do is to run the command
/etc/netstart as superuser. It will
setup everything for you, using the values you defined in
/etc/rc.conf.Initializing the NIS 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 don't want to propagate
passwords to your root and other administrative accounts to
all the servers in the NIS domain. Therefore, before we
initialize the NIS maps, you should:&prompt.root; cp /etc/master.passwd /var/yp/master.passwd
&prompt.root; cd /var/yp
&prompt.root; vi master.passwdYou should remove all entries regarding system accounts
(bin, tty, kmem, games, etc), as well as any accounts that you
don't want to be propagated to the NIS clients (for example
root and any other UID 0 (superuser) accounts).Make sure the
/var/yp/master.passwd is neither group
nor world readable (mode 600)! Use the
chmod command, if appropriate.Tru64 UnixWhen you have finished, it's time to initialize the NIS
maps! FreeBSD includes a script named
ypinit to do this for you
(see its man page for more information). Note that this
- script is available on most Unix OSs, but not on all.
+ 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 this is
not mandatory, because the master server
tries to make sure any changes to its NIS maps are
communicated to its slaves, the password
information is so vital to systems that depend on the server,
that it is a good idea to force the updates. This is more
important on busy networks where map updates might not always
complete.Now, run the command /etc/netstart on the
slave server as well, which again starts the NIS server.NIS Clients An NIS client establishes what is called a binding to a
particular NIS server using the
ypbind daemon.
ypbind checks the system's default
domain (as set by the domainname command),
and begins broadcasting RPC requests on the local network.
These requests specify the name of the domain for which
ypbind is attempting to establish a binding.
If a server that has been configured to serve the requested
domain receives one of the broadcasts, it will respond to
ypbind, which will record the server's
address. If there are several servers available (a master and
several slaves, for example), ypbind will
use the address of the first one to respond. From that point
on, the client system will direct all of its NIS requests to
that server. Ypbind will
occasionally ping the server to make sure it is
still up and running. If it fails to receive a reply to one of
its pings within a reasonable amount of time,
ypbind will mark the domain as unbound and
begin broadcasting again in the hopes of locating another
server.Setting up an NIS clientNISclient configurationSetting up a FreeBSD machine to be a NIS client is fairly
straightforward.Edit the file /etc/rc.conf and
add the following lines in order to set the NIS domainname
and start ypbind upon network
startup:nisdomainname="test-domain"
nis_client_enable="YES"To import all possible password entries from the NIS
server, add this line to your
/etc/master.passwd file, using
vipw:+:::::::::This line will afford anyone with a valid account in
the NIS server's password maps an account. There are
many ways to configure your NIS client by changing this
line. See the netgroups
part below for more information.
For more detailed reading see O'Reilly's book on
Managing NFS and NIS.To import all possible group entries from the NIS
server, add this line to your
/etc/group file:+:*::After completing these steps, you should be able to run
ypcat passwd and see the NIS server's
passwd map.NIS SecurityIn general, any remote user can issue an RPC to &man.ypserv.8; and
retrieve the contents of your NIS maps, provided the remote user
knows your domainname. To prevent such unauthorized transactions,
&man.ypserv.8; supports a feature called securenets which can be used to
restrict access to a given set of hosts. At startup, &man.ypserv.8; will
attempt to load the securenets information from a file called
/var/yp/securenets.This path varies depending on the path specified with the
option. This file contains entries that
consist of a network specification and a network mask separated
by white space. Lines starting with # are
considered to be comments. A sample securenets file might look
like this:# allow connections from local host -- mandatory
127.0.0.1 255.255.255.255
# allow connections from any host
# on the 192.168.128.0 network
192.168.128.0 255.255.255.0
# allow connections from any host
# between 10.0.0.0 to 10.0.15.255
# this includes the machines in the testlab
10.0.0.0 255.255.240.0If &man.ypserv.8; receives a request from an address that matches one
of these rules, it will process the request normally. If the
address fails to match a rule, the request will be ignored and a
warning message will be logged. If the
/var/yp/securenets file does not exist,
ypserv will allow connections from any host.The ypserv program also has support for Wietse Venema's
tcpwrapper package. This allows the
administrator to use the tcpwrapper configuration
files for access control instead of
/var/yp/securenets.While both of these access control mechanisms provide some
security, they, like the privileged port test, are
vulnerable to IP spoofing attacks. All
NIS-related traffic should be blocked at your firewall.Servers using /var/yp/securenets
may fail to serve legitimate NIS clients with archaic TCP/IP
implementations. Some of these implementations set all
host bits to zero when doing broadcasts and/or fail to
observe the subnet mask when calculating the broadcast
address. While some of these problems can be fixed by
changing the client configuration, other problems may force
the retirement of the client systems in question or the
abandonment of /var/yp/securenets.Using /var/yp/securenets on a
server with such an archaic implementation of TCP/IP is a
really bad idea and will lead to loss of NIS functionality
for large parts of your network.tcpwrapperThe use of the tcpwrapper
package increases the latency of your NIS server. The
additional delay may be long enough to cause timeouts in
client programs, especially in busy networks or with slow
NIS servers. If one or more of your client systems
suffers from these symptoms, you should convert the client
systems in question into NIS slave servers and force them
to bind to themselves.Barring some users from logging onIn our lab, there is a machine basie that is
supposed to be a faculty only workstation. We don't want to take this
machine out of the NIS domain, yet the passwd
file on the master NIS server contains accounts for both faculty and
students. What can we do?There is a way to bar specific users from logging on to a
machine, even if they are present in the NIS database. To do this,
all you must do is add
-username to the end of
the /etc/master.passwd file on the client
machine, where username is the username of
the user you wish to bar from logging in. This should preferably be
done using vipw, since vipw
will sanity check your changes to
/etc/master.passwd, as well as
automatically rebuild the password database when you
finish editing. For example, if we wanted to bar user
bill from logging on to basie
we would:basie&prompt.root; vipw[add -bill to the end, exit]
vipw: rebuilding the database...
vipw: done
basie&prompt.root; cat /etc/master.passwd
root:[password]:0:0::0:0:The super-user:/root:/bin/csh
toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
operator:*:2:5::0:0:System &:/:/sbin/nologin
bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
+:::::::::
-bill
basie&prompt.root;UdoErdelhoffContributedUsing netgroupsnetgroupsThe method shown in the previous chapter works reasonably
well if you need special rules for a very small number of
users and/or machines. On larger networks, you
will forget to bar some users from logging
onto sensitive machines, or you may even have to modify each
machine separately, thus losing the main benefit of NIS,
centralized administration.The NIS developers' solution for this problem is called
netgroups. Their purpose and semantics
can be compared to the normal groups used by Unix file
systems. The main differences are the lack of a numeric id
and the ability to define a netgroup by including both user
accounts and other netgroups.Netgroups were developed to handle large, complex networks
with hundreds of users and machines. On one hand, this is
a Good Thing if you are forced to deal with such a situation.
On the other hand, this complexity makes it almost impossible to
explain netgroups with really simple examples. The example
used in the remainder of this chapter demonstrates this
problem.Let us assume that your successful introduction of NIS in
your laboratory caught your superiors' interest. Your next
job is to extend your NIS domain to cover some of the other
machines on campus. The two tables contain the names of the
new users and new machines as well as brief descriptions of
them.User Name(s)Descriptionalpha, betaNormal employees of the IT departmentcharlie, deltaThe new apprentices of the IT departmentecho, foxtrott, golf, ...Ordinary employeesable, baker, ...The current internsMachine Name(s)Descriptionwar, death, famine, pollutionYour most important servers. Only the IT
employees are allowed to log onto these
machines.pride, greed, envy, wrath, lust, slothLess important servers. All members of the IT
department are allowed to login onto these machines.one, two, three, four, ...Ordinary workstations. Only the
real employees are allowed to use
these machines.trashcanA very old machine without any critical data.
Even the intern is allowed to use this box.If you tried to implement these restrictions by separately
blocking each user, you would have to add one
-user line to each system's
passwd
for each user who is not allowed to login onto that system.
If you forget just one entry, you could be in trouble. It may
be feasible to do this correctly during the initial setup,
however you will eventually forget to add
the lines for new users during day-to-day operations. After
all, Murphy was an optimist.Handling this situation with netgroups offers several
advantages. Each user need not be handled separately;
you assign a user to one or more netgroups and allow or forbid
logins for all members of the netgroup. If you add a new
machine, you will only have to define login restrictions for
netgroups. If a new user is added, you will only have to add
the user to one or more netgroups. Those changes are
independent of each other; no more for each combination
of user and machine do... If your NIS setup is planned
carefully, you will only have to modify exactly one central
configuration file to grant or deny access to machines.The first step is the initialization of the NIS map
netgroup. FreeBSD's &man.ypinit.8; does not create this map by
default, but its NIS implementation will support it once it has
been created. To create an empty map, simply typeellington&prompt.root; vi /var/yp/netgroupand start adding content. For our example, we need at
least four netgroups: IT employees, IT apprentices, normal
employees and interns.IT_EMP (,alpha,test-domain) (,beta,test-domain)
IT_APP (,charlie,test-domain) (,delta,test-domain)
USERS (,echo,test-domain) (,foxtrott,test-domain) \
(,golf,test-domain)
INTERNS (,able,test-domain) (,baker,test-domain)IT_EMP, IT_APP etc.
are the names of the netgroups. Each bracketed group adds
one or more user accounts to it. The three fields inside a
group are:The name of the host(s) where the following items are
valid. If you do not specify a hostname, the entry is
valid on all hosts. If you do specify a hostname, you
will enter a realm of darkness, horror and utter confusion.The name of the account that belongs to this
netgroup.The NIS domain for the account. You can import
accounts from other NIS domains into your netgroup if you
are one of unlucky fellows with more than one NIS
domain.Each of these fields can contain wildcards. See
&man.netgroup.5; for details.netgroupsNetgroup names longer than 8 characters should not be
used, especially if you have machines running other
operating systems within your NIS domain. The names are
case sensitive; using capital letters for your netgroup
names is an easy way to distinguish between user, machine
and netgroup names.Some NIS clients (other than FreeBSD) cannot handle
netgroups with a large number of entries. For example, some
older versions of SunOS start to cause trouble if a netgroup
contains more than 15 entries. You can
circumvent this limit by creating several sub-netgroups with
15 users or less and a real netgroup that consists of the
sub-netgroups:BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...]
BIGGRP2 (,joe16,domain) (,joe17,domain) [...]
BIGGRP3 (,joe31,domain) (,joe32,domain)
BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3You can repeat this process if you need more than 225
users within a single netgroup.Activating and distributing your new NIS map is
easy:ellington&prompt.root; cd /var/yp
ellington&prompt.root; makeThis will generate the three NIS maps
netgroup,
netgroup.byhost and
netgroup.byuser. Use &man.ypcat.1; to
check if your new NIS maps are available:ellington&prompt.user; ypcat -k netgroup
ellington&prompt.user; ypcat -k netgroup.byhost
ellington&prompt.user; ypcat -k netgroup.byuserThe output of the first command should resemble the
contents of /var/yp/netgroup. The second
command will not produce output if you have not specified
host-specific netgroups. The third command can be used to
get the list of netgroups for a user.The client setup is quite simple. To configure the server
war, you only have to start
&man.vipw.8; and replace the line+:::::::::with+@IT_EMP:::::::::Now, only the data for the users defined in the netgroup
IT_EMP is imported into
war's password database and only
these users are allowed to login.Unfortunately, this limitation also applies to the ~
function of the shell and all routines converting between user
names and numerical user ids. In other words,
cd ~user will not work,
ls -l will show the numerical id instead of
the username and find . -user joe -print will
fail with No such user. To fix this, you will
have to import all user entries without allowing them
to login onto your servers.This can be achieved by adding another line to
/etc/master.passwd. This line should
contain +:::::::::/sbin/nologin, meaning
Import all entries but replace the shell with
/sbin/nologin in the imported
entries. You can replace any field
in the passwd entry by placing a default value in your
/etc/master.passwd.Make sure that the line
+:::::::::/sbin/nologin is placed after
+@IT_EMP:::::::::. Otherwise, all user
accounts imported from NIS will have /sbin/nologin as their
login shell.After this change, you will only have to change one NIS
map if a new employee joins the IT department. You could use
a similar approach for the less important servers by replacing
the old +::::::::: in their local version
of /etc/master.passwd with something like
this:+@IT_EMP:::::::::
+@IT_APP:::::::::
+:::::::::/sbin/nologinThe corresponding lines for the normal workstations
could be:+@IT_EMP:::::::::
+@USERS:::::::::
+:::::::::/sbin/nologinAnd everything would be fine until there is a policy
change a few weeks later: The IT department starts hiring
interns. The IT interns are allowed to use the normal
workstations and the less important servers; and the IT
apprentices are allowed to login onto the main servers. You
add a new netgroup IT_INTERN, add the new IT interns to this
netgroup and start to change the config on each and every
machine... As the old saying goes: Errors in
centralized planning lead to global mess.NIS' ability to create netgroups from other netgroups can
be used to prevent situations like these. One possibility
is the creation of role-based netgroups. For example, you
could create a netgroup called
BIGSRV to define the login
restrictions for the important servers, another netgroup
called SMALLSRV for the less
important servers and a third netgroup called
USERBOX for the normal
workstations. Each of these netgroups contains the netgroups
that are allowed to login onto these machines. The new
entries for your NIS map netgroup should look like this:BIGSRV IT_EMP IT_APP
SMALLSRV IT_EMP IT_APP ITINTERN
USERBOX IT_EMP ITINTERN USERSThis method of defining login restrictions works
reasonably well if you can define groups of machines with
identical restrictions. Unfortunately, this is the exception
and not the rule. Most of the time, you will need the ability
to define login restrictions on a per-machine basis.Machine-specific netgroup definitions are the other
possibility to deal with the policy change outlined above. In
this scenario, the /etc/master.passwd of
each box contains two lines starting with ``+''. The first of
them adds a netgroup with the accounts allowed to login onto
this machine, the second one adds all other accounts with
/sbin/nologin as shell. It is a good
idea to use the ALL-CAPS version of the machine name as the
name of the netgroup. In other words, the lines should look
like this:+@BOXNAME:::::::::
+:::::::::/sbin/nologinOnce you have completed this task for all your machines,
you will not have to modify the local versions of
/etc/master.passwd ever again. All
further changes can be handled by modifying the NIS map. Here
is an example of a possible netgroup map for this
scenario with some additional goodies.# Define groups of users first
IT_EMP (,alpha,test-domain) (,beta,test-domain)
IT_APP (,charlie,test-domain) (,delta,test-domain)
DEPT1 (,echo,test-domain) (,foxtrott,test-domain)
DEPT2 (,golf,test-domain) (,hotel,test-domain)
DEPT3 (,india,test-domain) (,juliet,test-domain)
ITINTERN (,kilo,test-domain) (,lima,test-domain)
D_INTERNS (,able,test-domain) (,baker,test-domain)
#
# Now, define some groups based on roles
USERS DEPT1 DEPT2 DEPT3
BIGSRV IT_EMP IT_APP
SMALLSRV IT_EMP IT_APP ITINTERN
USERBOX IT_EMP ITINTERN USERS
#
# And a groups for a special tasks
# Allow echo and golf to access our anti-virus-machine
SECURITY IT_EMP (,echo,test-domain) (,golf,test-domain)
#
# machine-based netgroups
# Our main servers
WAR BIGSRV
FAMINE BIGSRV
# User india needs access to this server
POLLUTION BIGSRV (,india,test-domain)
#
# This one is really important and needs more access restrictions
DEATH IT_EMP
#
# The anti-virus-machine mentioned above
ONE SECURITY
#
# Restrict a machine to a single user
TWO (,hotel,test-domain)
# [...more groups to follow]If you are using some kind of database to manage your user
accounts, you should be able to create the first part of the
map with your database's report tools. This way, new users
will automatically have access to the boxes.One last word of caution: It may not always be advisable
to use machine-based netgroups. If you are deploying a couple
dozen or even hundreds of identical machines for student labs,
you should use role-based netgroups instead of machine-based
netgroups to keep the size of the NIS map within reasonable
limits.Important things to rememberThere are still a couple of things that you will need to do
differently now that you are in an NIS environment.Every time you wish to add a user to the lab, you
must add it to the master NIS server only,
and you must remember to rebuild the NIS
maps. If you forget to do this, the new user will
not be able to login anywhere except on the NIS master.
For example, if we needed to add a new user
“jsmith” to the lab, we would:&prompt.root; pw useradd jsmith
&prompt.root; cd /var/yp
&prompt.root; make test-domainYou could also run adduser jsmith instead
of pw useradd jsmith.Keep the administration accounts out of the NIS
maps. You don't want to be propagating administrative
accounts and passwords to machines that will have users that
shouldn't have access to those accounts.Keep the NIS master and slave
secure, and minimize their downtime.
If somebody either hacks or simply turns off
these machines, they have effectively rendered many people without
the ability to login to the lab.This is the chief weakness of any centralized administration
system, and it is probably the most important weakness. If you do
not protect your NIS servers, you will have a lot of angry
users!NIS v1 compatibility FreeBSD's ypserv has some support
for serving NIS v1 clients. FreeBSD's NIS implementation only
uses the NIS v2 protocol, however other implementations include
support for the v1 protocol for backwards compatibility with older
systems. The ypbind daemons supplied
with these systems will try to establish a binding to an NIS v1
server even though they may never actually need it (and they may
persist in broadcasting in search of one even after they receive a
response from a v2 server). Note that while support for normal
client calls is provided, this version of ypserv does not handle
v1 map transfer requests; consequently, it cannot be used as a
master or slave in conjunction with older NIS servers that only
support the v1 protocol. Fortunately, there probably are not any
such servers still in use today.NIS servers that are also NIS clients Care must be taken when running ypserv in a multi-server
domain where the server machines are also NIS clients. It is
generally a good idea to force the servers to bind to themselves
rather than allowing them to broadcast bind requests and possibly
become bound to each other. Strange failure modes can result if
one server goes down and others are dependent upon on it.
Eventually all the clients will time out and attempt to bind to
other servers, but the delay involved can be considerable and the
failure mode is still present since the servers might bind to each
other all over again.You can force a host to bind to a particular server by running
ypbind with the
flag.libscrypt v.s. libdescryptNIScrypto libraryOne of the most common issues that people run into when trying
to implement NIS is crypt library compatibility. If your NIS
server is using the DES crypt libraries, it will only support
clients that are using DES as well. To check which one your server
and clients are using look at the symlinks in
/usr/lib. If the machine is configured to
use the DES libraries, it will look something like this:&prompt.user; ls -l /usr/lib/*crypt*
lrwxrwxrwx 1 root wheel 13 Jul 15 08:55 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.GregSutterWrittenDHCPWhat 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 handbook section attempts to describe only the parts
of the DHCP system that are integrated with FreeBSD;
consequently, the server portions are not described. The DHCP
manual pages, in addition to the references below, are useful
resources.How it WorksUDPWhen dhclient, the DHCP client, is executed on the client
machine, it begins broadcasting requests for configuration
information. By default, these requests are on UDP port 68. The
server replies on UDP 67, giving the client an IP address and
other relevant network information such as netmask, router, and
DNS servers. All of this information comes in the form of a DHCP
"lease" and is only valid for a certain time (configured by the
DHCP server maintainer). In this manner, stale IP addresses for
clients no longer connected to the network can be automatically
reclaimed.DHCP clients can obtain a great deal of information from
the server. An exhaustive list may be found in
&man.dhcp-options.5;.FreeBSD IntegrationFreeBSD fully integrates the ISC DHCP client,
dhclient. DHCP client support is provided
within both the installer and the base system, obviating the need
for detailed knowledge of network configurations on any network
that runs a DHCP server. dhclient has been
included in all FreeBSD distributions since 3.2.sysinstallDHCP is supported by sysinstall.
When configuring a network interface within sysinstall,
the first question asked is, "Do you want to try dhcp
configuration of this interface?" Answering affirmatively will
execute dhclient, and if successful, will fill in the network
configuration information automatically.There are two things you must do to have your system use
DHCP upon startup:DHCPrequirementsMake sure that the bpf
device is compiled into your kernel. To do this, add
pseudo-device bpf to your kernel
configuration file, and rebuild the kernel. For more
information about building kernels, see .The bpf device is already
part of the GENERIC kernel that is
supplied with FreeBSD, so if you don't have a custom
kernel, you shouldn't need to create one in order to get
DHCP working.For those who are particularly security conscious,
you should be warned that bpf
is also the device that allows packet sniffers to work
correctly (although they still have to be run as
root). bpfis required to use DHCP, but if
you are very sensitive about security, you probably
shouldn't add bpf to your
kernel in the expectation that at some point in the
future you will be using DHCP.Edit your /etc/rc.conf to
include the following:ifconfig_fxp0="DHCP"Be sure to replace fxp0 with the
designation for the interface that you wish to dynamically
configure.If you are using a different location for
dhclient, or if you wish to pass additional
flags to dhclient, also include the
following (editing as necessary):dhcp_program="/sbin/dhclient"
dhcp_flags=""DHCPserverThe DHCP server, dhcpd, is included
as part of the isc-dhcp2 port in the ports
collection. This port contains the full ISC DHCP distribution,
consisting of client, server, relay agent and documentation.
FilesDHCPconfiguration files/etc/dhclient.confdhclient requires a configuration file,
/etc/dhclient.conf. Typically the file
contains only comments, the defaults being reasonably sane. This
configuration file is described by the &man.dhclient.conf.5;
man page./sbin/dhclientdhclient is statically linked and
resides in /sbin. The &man.dhclient.8;
manual page gives more information about
dhclient./sbin/dhclient-scriptdhclient-script is the FreeBSD-specific
DHCP client configuration script. It is described in
&man.dhclient-script.8;, but should not need any user
modification to function properly./var/db/dhclient.leasesThe DHCP client keeps a database of valid leases in this
file, which is written as a log. &man.dhclient.leases.5;
gives a slightly longer description.Further ReadingThe DHCP protocol is fully described in
RFC 2131.
An informational resource has also been set up at
dhcp.org.ChernLeeContributedDNSOverviewBINDFreeBSD 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
webpage, whereas, a query for ftp.freebsd.org
will return the IP
address of the corresponding FTP machine. Likewise, the opposite can
happen. A query for an IP address can resolve its hostname. It is
not necessary to run a nameserver 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 nameservers 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 point of start for the particular zonenamed, bind, name servercommon names for the BIND name server package within
FreeBSDresolverresolvera system process through which a
machine queries a nameserver 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 zonefoobardomain.org is a zone under the org. zonefoo.foobardomain.org. is a subdomain, a zone under the
foobardomain.org. zone
1.2.3.in-addr.arpa is a zone referencing all IP addresses
which fall under the 3.2.1.* IP space.
As one can see, the more specific part of a hostname appears to
its left. For example, foobardomain.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 server
A machine is needed to host DNS information to the world
An authoritative nameserver replies exclusively
to requests.
For example, foobardomain.org is
registered and IP addresses need to be assigned to hostnames
under this domain.
A slave nameserver, which replies to queries for a
domain when the primary is down or inaccessible.
The above two can also be done with reverse DNS (IP
to hostname entries)
A machine is needed to act as a local cache of DNS information
DNS traffic has been measured to be about 5% or more
of the total Internet traffic.
A local DNS server may have some added benefit by
providing a local cache of DNS information.
For example, when one queries for
www.freebsd.org,
the resolver usually queries the uplink ISP's name
server, and retrieves the query.
With a local, caching DNS server, the query only has to
be made once to the outside world. Every additional
query will not have to look to the outside of the local
network, since the information is cached.
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) man page for details. If you are ever going
// to setup a primary server, make sure you've understood the hairy
// details of how DNS is working. Even with simple mistakes, you can
// break connectivity for affected parties, or cause huge amount of
// useless Internet traffic.
options {
directory "/etc/namedb";
// In addition to the "forwarders" clause, you can force your name
// server to never initiate queries of its own, but always ask its
// forwarders only, by enabling the following line:
//
// forward only;
// If you've got a DNS server around at your upstream provider, enter
// its IP address here, and enable the line below. This will make you
// benefit from its cache, thus reduce overall DNS traffic in the
Internet.
/*
forwarders {
127.0.0.1;
};
*/
Just as the comment says, to benefit from an uplink's cache,
forwarders can be enabled here. Under normal
circumstances, a nameserver will recursively query the Internet
looking at certain nameservers until it finds the answer it is
looking for. Having this enabled will have it query the uplink's
nameserver (or nameserver provided) first, taking advantage of
its cache. If the uplink nameserver in question is a heavily
trafficked, fast nameserver, enabling this may be worthwhile.
127.0.0.1 will not work here.
Change this IP address to a nameserver at your uplink. /*
* If there is a firewall between you and nameservers you want
* to talk to, you might need to uncomment the query-source
* directive below. Previous versions of BIND always asked
* questions using port 53, but BIND 8.1 uses an unprivileged
* port by default.
*/
// query-source address * port 53;
/*
* If running in a sandbox, you may have to specify a different
* location for the dumpfile.
*/
// dump-file "s/named_dump.db";
};
// Note: the following will be supported in a future release.
/*
host { any; } {
topology {
127.0.0.0/8;
};
};
*/
// Setting up secondaries is way easier and the rough picture for this
// is explained below.
//
// If you enable a local name server, don't forget to enter 127.0.0.1
// into your /etc/resolv.conf so this server will be queried first.
// Also, make sure to enable it in /etc/rc.conf.
zone "." {
type hint;
file "named.root";
};
zone "0.0.127.IN-ADDR.ARPA" {
type master;
file "localhost.rev";
};
zone
"0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.INT" {
type master;
file "localhost.rev";
};
// NB: Do not use the IP addresses below, they are faked, and only
// serve demonstration/documentation purposes!
//
// Example secondary config entries. It can be convenient to become
// a secondary at least for the zone where your own domain is in. Ask
// your network administrator for the IP address of the responsible
// primary.
//
// Never forget to include the reverse lookup (IN-ADDR.ARPA) zone!
// (This is the first bytes of the respective IP address, in reverse
// order, with ".IN-ADDR.ARPA" appended.)
//
// Before starting to setup a primary zone, better make sure you fully
// understand how DNS and BIND works, however. There are sometimes
// unobvious pitfalls. Setting up a secondary is comparably simpler.
//
// NB: Don't blindly enable the examples below. :-) Use actual names
// and addresses instead.
//
// NOTE!!! FreeBSD runs bind in a sandbox (see named_flags in rc.conf).
// The directory containing the secondary zones must be write accessible
// to bind. The following sequence is suggested:
//
// mkdir /etc/namedb/s
// chown bind:bind /etc/namedb/s
// chmod 750 /etc/namedb/sFor more information on running BIND in a sandbox, see
Running named in a sandbox.
/*
zone "domain.com" {
type slave;
file "s/domain.com.bak";
masters {
192.168.1.1;
};
};
zone "0.168.192.in-addr.arpa" {
type slave;
file "s/0.168.192.in-addr.arpa.bak";
masters {
192.168.1.1;
};
};
*/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 foobardomain.org can
look like:zone "foobardomain.org" {
type master;
file "foobardomain.org";
};The zone is a master, as indicated by the
statement, holding its zone information in
/etc/namedb/foobardomain.org indicated by
the statement.zone "foobardomain.org" {
type slave;
file "foobardomain.org";
};In the slave case, the zone information is transferred from
the master nameserver for the particular zone, and saved in the
file specified. If and when the master server dies or is
unreachable, the slave nameserver will have the transferred
zone information and will be able to serve it.Zone files
An example master zone file for foobardomain.org
(existing within /etc/namedb/foobardomain.org)
is as follows:
$TTL 3600
foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
86400 ) ; Minimum TTL
; DNS Servers
@ IN NS ns1.foobardomain.org.
@ IN NS ns2.foobardomain.org.
; Machine Names
localhost IN A 127.0.0.1
ns1 IN A 3.2.1.2
ns2 IN A 3.2.1.3
mail IN A 3.2.1.10
@ IN A 3.2.1.30
; Aliases
www IN CNAME @
; MX Record
@ IN MX 10 mail.foobardomain.org.
Note that every hostname ending in a . is an
exact hostname, whereas everything without a trailing
. is referenced to the origin. For example,
www is translated into www +
origin. In our fictitious zone file, our origin
is foobardomain.org., so
www would translate to
www.foobardomain.org.
The format of a zone file follows:
recordname IN recordtype valueDNSrecords
The most commonly used DNS records:
SOAstart of zone authorityNSan authoritative nameserverAA host addressCNAMEthe canonical name for an aliasMXmail exchangePTRa domain name pointer (used in reverse dns)
foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh after 3 hours
3600 ; Retry after 1 hour
604800 ; Expire after 1 week
86400 ) ; Minimum TTL of 1 dayfoobardomain.org.the domain name, also the origin for this
zone file.ns1.foobardomain.org.the primary/authoritative nameserver for this
zoneadmin.foobardomain.org.the responsible person for this zone,
email address with @
replaced. (admin@foobardomain.org becomes
admin.foobardomain.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 nameservers for a zone when it is
updated.
@ IN NS ns1.foobardomain.org.
This is an NS entry. Every nameserver that is going to reply
authoritatively for the zone must have one of these entries.
The @ as seen here could have been
foobardomain.org.
The @ translates to the origin.
localhost IN A 127.0.0.1
ns1 IN A 3.2.1.2
ns2 IN A 3.2.1.3
mail IN A 3.2.1.10
@ IN A 3.2.1.30
The A record indicates machine names. As seen above,
ns1.foobardomain.org would resolve to
3.2.1.2. Again, the origin symbol, @, is
used here, thus meaning foobardomain.org
would resolve to 3.2.1.30.
www IN CNAME @
The canonical name record is usually used for giving aliases
to a machine. In the example, www is
aliased to the machine addressed to the origin, or
foobardomain.org (3.2.1.30).
CNAMEs can be used to provide alias
hostnames, or round robin one hostname among multiple
machines.
@ IN MX 10 mail.foobardomain.org.
The MX record indicates which mail servers are responsible
for handling incoming mail for the zone.
mail.foobardomain.org is the hostname of the mail server,
and 10 being the priority of that mailserver.
One can have several mailservers, with priorities of 3, 2,
1. A mail server attempting to deliver to foobardomain.org
would first try the highest priority MX, then the second
highest, etc, until the mail can be properly delivered.
For in-addr.arpa zone files (reverse dns), the same format is
used, except with PTR entries instead of
A or CNAME.
$TTL 3600
1.2.3.in-addr.arpa. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
3600 ) ; Minimum
@ IN NS ns1.foobardomain.org.
@ IN NS ns2.foobardomain.org.
2 IN PTR ns1.foobardomain.org.
3 IN PTR ns2.foobardomain.org.
10 IN PTR mail.foobardomain.org.
30 IN PTR foobardomain.org.
This file gives the proper IP address to hostname mappings of our above
fictitious domain.
Caching Name ServerBINDcaching name server
A caching nameserver is a nameserver that is not
authoritative for any zones. It simply asks queries of its own,
and remembers them for later use. To set one up, just configure
the name server as usual, omitting any inclusions of zones.
MikeMakonnenContributedRunning named in a SandboxBINDrunning in a sandboxchrootFor added security you may want to run &man.named.8; in a
sandbox. This will reduce the potential damage should it be
compromised. If you include a sandbox directory in its command
line, named will &man.chroot.8;
into that directory immediately upon finishing processing its
command line. It is also a good idea to have named run as a
non-privileged user in the sandbox. The default FreeBSD install
contains a user bind with group bind. If we wanted the sandbox in
the /etc/namedb/sandbox directory the command
line for named would look like this:
&prompt.root; /usr/sbin/named -u bind -g bind -t /etc/namedb/sandbox <path_to_named.conf> The following steps should be taken in order to
successfully run named in a sandbox. Throughout the following
discussion we will assume the path to your sandbox is
/etc/namedb/sandboxCreate the sandbox directory:
/etc/namedb/sandboxCreate other necessary directories off of the sandbox
directory: etc and
var/runcopy /etc/localtime to
sandbox/etcmake bind:bind the owner of all files and directories in
the sandbox:
&prompt.root; chown -R bind:bind /etc/namedb/sandbox&prompt.root; chmod -R 750 /etc/namedb/sandboxThere are some issues you need to be aware of when running
named in a sandbox.Your &man.named.conf.5; file and all your zone files must
be in the sandbox
sandbox/etc/localtime is needed
in order to have the correct time for your time zone in
log messages. &man.named.8; will write its process id to a file in
sandbox/var/runThe Unix socket used for communication by the &man.ndc.8;
utility will be created in
sandbox/var/runWhen using the &man.ndc.8; utility you need to specify the
location of the Unix socket created in the sandbox, by
&man.named.8;, by using the -c switch:
&prompt.root; ndc -c /etc/namedb/sandbox/var/run/ndcIf you enable logging to file, the log files must be
in the sandbox&man.named.8; can be started in a sandbox properly, if the
following is in /etc/rc.conf:
named_flags="-u bind -g bind -t /etc/namedb/sandbox <path_to_named.conf>"How to use the nameserverIf setup properly, the nameserver should be accessible through
the network and locally. /etc/resolv.conf must
contain a nameserver entry with the local IP address so it will query the
local name server first.
To access it over the network, the machine must have the
nameserver's IP address set properly in its own nameserver
configuration options.
SecurityAlthough BIND is the most common implementation of DNS,
there is always the issue of security. Possible and
exploitable security holes are sometimes found.
It is a good idea to subscribe to CERT and
freebsd-announce
to stay up to date with the current Internet and FreeBSD security
issues.
If a problem arises, keeping sources up to date and having a
fresh build of named would not hurt.Further Reading
BIND/named man 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 SpecificationChernLeeContributedNetwork Address Translation daemon (natd)OverviewnatdFreeBSD's Network Address Translation daemon, commonly known as
&man.natd.8; is a daemon that accepts incoming raw IP packets,
changes the source to the local machine and re-injects these packets
back into the outgoing IP packet stream. natd does this by changing
the source IP address and port such that when data is received back, it is
able to determine the original location of the data and forward it
back to its original requester.Internet connection sharingIP masqueradingThe most common use of NAT is to perform what is commonly known as
Internet Connection Sharing.SetupDue to the diminishing IP space in ipv4, and the increased number
of users on high-speed consumer lines such as cable or DSL, people are
in more and more need of an Internet Connection Sharing solution. The
ability to connect several computers online through one connection and
IP address makes &man.natd.8; a reasonable choice.Most commonly, a user has a machine connected to a cable or DSL
line with one IP address and wishes to use this one connected computer to
provide Internet access to several more over a LAN.To do this, the FreeBSD machine on the Internet must act as a
gateway. This gateway machine must have two NICs--one for connecting
to the Internet router, the other connecting to a LAN. All the
machines on the LAN are connected through a hub or switch. _______ __________ ________
| | | | | |
| Hub |-----| Client B |-----| Router |----- Internet
|_______| |__________| |________|
|
____|_____
| |
| Client A |
|__________|Network LayoutWith this setup, the machine without Internet access can use
the machine with access as a gateway to access the outside
world.kernelconfigurationConfigurationThe following options must be in the kernel configuration
file:options IPFIREWALL
options IPDIVERTAdditionally, at choice, the following may also be suitable:options IPFIREWALL_DEFAULT_TO_ACCEPT
options IPFIREWALL_VERBOSEThe following must be in /etc/rc.conf:gateway_enable="YES"
firewall_enable="YES"
firewall_type="OPEN"
natd_enable="YES"
natd_interface="fxp0"
natd_flags=""gateway_enable="YES"Sets up the machine to act as a gateway. Running
sysctl -w net.inet.ip.forwarding=1
would have the same effect.firewall_enable="YES"Enables the firewall rules in
/etc/rc.firewall at boot.firewall_type="OPEN"This specifies a predefined firewall ruleset that
allows anything in. See
/etc/rc.firewall for additional
types.natd_interface="fxp0"Indicates which interface to forward packets through.
(the interface connected to the Internet)natd_flags=""Any additional configuration options passed to
&man.natd.8; on boot.Having the previous options defined in
/etc/rc.conf would run
natd -interface fxp0 at boot. This can also
be run manually.Each machine and interface behind the LAN should be assigned IP address
numbers in the private network space as defined by
RFC 1918
and have a default gateway of the natd machine's internal IP address.For example, client a and b behind the LAN have IP addresses of 192.168.0.2
and 192.168.0.3, while the natd machine's LAN interface has an IP address of
192.168.0.1. Client a and b's default gateway must be set to that of
the natd machine, 192.168.0.1. The natd machine's external, or
Internet interface does not require any special modification for natd
to work.Port RedirectionThe drawback with natd is that the LAN clients are not accessible
from the Internet. Clients on the LAN can make outgoing connections to
the world but cannot receive incoming ones. This presents a problem
if trying to run Internet services on one of the LAN client machines.
A simple way around this is to redirect selected Internet ports on the
natd machine to a LAN client.
For example, an IRC server runs on Client A, and a web server runs
on Client B. For this to work properly, connections received on ports
6667 (irc) and 80 (web) must be redirected to the respective machines.
The -redirect_port must be passed to
&man.natd.8; with the proper options. The syntax is as follows: -redirect_port proto targetIP:targetPORT[-targetPORT]
[aliasIP:]aliasPORT[-aliasPORT]
[remoteIP[:remotePORT[-remotePORT]]]In the above example, the argument should be:
-redirect_port tcp 192.168.0.2:6667 6667
-redirect_port tcp 192.168.0.3:80 80
This will redirect the proper tcp ports to the
LAN client machines.
The -redirect_port argument can be used to indicate port
ranges over individual ports. For example, tcp
192.168.0.2:2000-3000 2000-3000 would redirect
all connections received on ports 2000 to 3000 to ports 2000
to 3000 on Client A.These options can be used when directly running
&man.natd.8; or placed within the
natd_flags="" option in
/etc/rc.conf.For further configuration options, consult &man.natd.8;Address Redirectionaddress redirectionAddress redirection is useful if several IP addresses are available, yet
they must be on one machine. With this, &man.natd.8; can assign each
LAN client its own external IP address. &man.natd.8; then rewrites outgoing
packets from the LAN clients with the proper external IP address and redirects
all traffic incoming on that particular IP address back to the specific LAN
client. This is also known as static NAT. For example, the IP addresses
128.1.1.1, 128.1.1.2, and 128.1.1.3 belong to the natd gateway
machine. 128.1.1.1 can be used as the natd gateway machine's external
IP address, while 128.1.1.2 and 128.1.1.3 are forwarded back to LAN
clients A and B.The -redirect_address syntax is as follows:localIPThe internal IP address of the LAN client.publicIPThe external IP address corresponding to the LAN client.In the example, this argument would read:Like -redirect_port, these arguments are also placed within
natd_flags of /etc/rc.conf. With address
redirection, there is no need for port redirection since all data
received on a particular IP address is redirected.The external IP addresses on the natd machine must be active and aliased
to the external interface. Look at &man.rc.conf.5; to do so.
diff --git a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
index bd13ef98f1..61287866ac 100644
--- a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
@@ -1,885 +1,885 @@
ChrisShumwayRewrittenUnix BasicsSynopsisbasicsThe following chapter will cover the basic commands and
functionality of the FreeBSD operating system. If you are new to
FreeBSD, you will definitely want to read through this chapter before
asking for help.PermissionsUnixFreeBSD, having its history rooted in BSD Unix, has its
fundamentals based on several key Unix concepts. The first, and
most pronounced, is that FreeBSD is a multi-user operating system.
The system can handle several users all working simultaneously on
completely unrelated tasks. The system is responsible for properly
sharing and managing requests for hardware devices, peripherals,
memory, and CPU time evenly to each user.Because the system is capable of supporting multiple users,
everything the system manages has a set of permissions governing who
can read, write, and execute the resource. These permissions are
stored as two octets broken into three pieces, one for the owner of
the file, one for the group that the file belongs to, and one for
everyone else. This numerical representation works like
this:permissionsfile permissionsValuePermissionDirectory Listing0No read, no write, no execute---1No read, no write, execute--x2No read, write, no execute-w-3No read, write, execute-wx4Read, no write, no executer--5Read, no write, executer-x6Read, write, no executerw-7Read, write, executerwxlsdirectoriesFor the long directory listing by ls -l, a
column will show a file's permissions for the owner, group, and
everyone else. Here's how it is broken up:-rw-r--r--The first character, from left to right, is a special character
that tells if this is a regular file, a directory, a special
character or block device, a socket, or any other special
pseudo-file device. The next three characters, designated as
rw- gives the permissions for the owner of the
file. The next three characters, r-- gives the
permissions for the group that the file belongs to. The final three
characters, r--, gives the permissions for the
rest of the world. A dash means that the permission is turned off.
In the case of this file, the permissions are set so the owner can
read and write to the file, the group can read the file, and the
rest of the world can only read the file. According to the table
above, the permissions for this file would be
644, where each digit represents the three parts
of the file's permission.This is all well and good, but how does the system control
permissions on devices? FreeBSD actually treats most hardware
devices as a file that programs can open, read, and write data to
just like any other file. These special device files are stored on
the /dev directory.Directories are also treated as files. They have read, write,
and execute permissions. The executable bit for a directory has a
slightly different meaning than that of files. When a directory is
marked executable, it means it can be searched into, for example, a
directory listing can be done in that directory.There are more to permissions, but they are primarily used in
special circumstances such as setuid binaries and sticky
directories. If you want more information on file permissions and
how to set them, be sure to look at the &man.chmod.1; man
page.Directory Structuresdirectory hierarchySince FreeBSD uses its file systems to determine many
fundamental system operations, the hierarchy of the file system is
extremely important. Due to the fact that the &man.hier.7; man page
provides a complete description of the directory structure, it will
not be duplicated here. Please read &man.hier.7; for more
information.Of significant importance is the root of all directories, the /
directory. This directory is the first directory mounted at boot
time and it contains the base system necessary at boot time. The
root directory also contains mount points for every other file
system that you want to mount.A mount point is a directory where additional file systems can
be grafted onto the root file system. Standard mount points include
/usr, /var,
/mnt, and /cdrom. These
directories are usually referenced to entries in the file
/etc/fstab. /etc/fstab is
a table of various file systems and mount points for reference by the
system. Most of the file systems in /etc/fstab
are mounted automatically at boot time from the script &man.rc.8;
unless they contain the option. Consult the
&man.fstab.5; manual page for more information on the format of the
/etc/fstab file and the options it
contains.ProcessesFreeBSD is a multi-tasking operating system. This means that it
seems as though more than one program is running at once. Each program
running at any one time is called a process.
Every command you run will start at least one new process, and there are
a number of system processes that run all the time, keeping the system
functional.Each process is uniquely identified by a number called a
process ID, or PID, and,
like files, each process also has one owner and group. The owner and
group information is used to determine what files and devices the
process can open, using the file permissions discussed earlier. Most
processes also have a parent process. The parent process is the process
that started them. For example, if you are typing commands to the shell
then the shell is a process, and any commands you run are also
processes. Each process you run in this way will have your shell as its
parent process. The exception to this is a special process called
init. init is always the first
process, so its PID is always 1. init is started
automatically by the kernel when FreeBSD starts.Two commands are particularly useful to see the processes on the
system, &man.ps.1; and &man.top.1;. The &man.ps.1; command is used to
show a static list of the currently running processes, and can show
their PID, how much memory they are using, the command line they were
started with, and so on. The &man.top.1; command displays all the
running processes, and updates the display every few seconds, so that
you can interactively see what your computer is doing.By default, &man.ps.1; only shows you the commands that are running
and are owned by you. For example;&prompt.user; ps
PID TT STAT TIME COMMAND
298 p0 Ss 0:01.10 tcsh
7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
48630 p0 S 2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
48730 p0 IW 0:00.00 (dns helper) (navigator-linux-)
72210 p0 R+ 0:00.00 ps
390 p1 Is 0:01.14 tcsh
7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y
6688 p3 IWs 0:00.00 tcsh
10735 p4 IWs 0:00.00 tcsh
20256 p5 IWs 0:00.00 tcsh
262 v0 IWs 0:00.00 -tcsh (tcsh)
270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc
285 v0 S 0:38.45 /usr/X11R6/bin/sawfishAs you can see in this example, the output from &man.ps.1; is
organized in to a number of columns. PID is the
process ID discussed earlier. PIDs are assigned starting from 1, go up
to 65536, and wrap around back to the beginning when you run out.
TT shows the tty the program is running on, and can
safely be ignore for the moment. STAT shows the
program's state, and again, can be safely ignored.
TIME is the amount of time the program has been
running on the CPU—this is not necessarily the elapsed time since
you started the program, as some programs spend a lot of time waiting
for things to happen before they need to spend time on the CPU.
Finally, COMMAND is the command line that was used to
run the program.&man.ps.1; supports a number of different options to change the
information that is displayed. One of the most useful sets is
auxww. displays information
about all the running processes, not just your own.
displays the username of the process' owner, as well as memory usage.
displays information about daemon processes, and
causes &man.ps.1; to display the full command line,
rather than truncating it once it gets too long to fit on the
screen.The output from &man.top.1; is similar. A sample session looks like
this;&prompt.user; top
last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10
47 processes: 1 running, 46 sleeping
CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle
Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND
72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top
7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14
281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA
296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm
48630 nik 2 0 29816K 9148K select 3:18 0.00% 0.00% navigator-linu
175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd
7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt
...The output is split in to two sections. The header (the first five
lines) shows the PID of the last process to run, the system load averages
(which are a measure of how busy the system is), the system uptime (time
since the last reboot) and the current time. The other figures in the
header relate to how many processes are running (47 in this case), how
much memory and swap space has been taken up, and how much time the
system is spending in different CPU states.Below that are a series of columns containing similar information
to the output from &man.ps.1;. As before you can see the PID, the
username, the amount of CPU time taken, and the command that was run.
&man.top.1; also defaults to showing you the amount of memory space
taken by the process. This is split in to two columns, one for total
size, and one for resident size—total size is how much memory the
application has needed, and the resident size is how much it is actually
using at the moment. In this example you can see that Netscape has
needed almost 30MB of RAM, and is currently only needing 9MB.&man.top.1; automatically updates this display every two seconds;
this can be changed with the option.Daemons, signals, and killing processesWhen you run an editor it is easy to control the editor, tell it to
load files, and so on. You can do this because the editor provides
facilities to do so, and because the editor is attached to a
terminal. Some programs are not designed to be
run with continuous user input, and so they disconnect from the terminal
at the first opportunity. For example, a web server spends all day
responding to web requests, it normally does not need any input from
you. Programs that transport email from site to site are another
example of this class of application.We call these programs daemons. Daemons were
characters in Greek mythology; neither good or evil, they were little
attendant spirits that, by and large, did useful things for mankind.
Much like the web servers and mail servers of today do useful things.
This is why the BSD mascot has, for a long time, been the cheerful
looking daemon with sneakers and a pitchfork.There is a convention to name programs that normally run as daemons
with a trailing d. BIND is the
Berkeley Internet Name Daemon (and the program you can is called
named), the Apache web
server program is called httpd, the line printer
spooling daemon is lpd and so on. This is a
convention, not a hard and fast rule; for example, the main mail daemon
for the Sendmail application is called
sendmail, and not maild, as you
might imagine.Sometimes you will need to communicate with a daemon process. These
- commmunications are called signals, and you can
+ communications are called signals, and you can
communicate with daemons (or with any running process) by sending it a
signal. There are a number if different signals that you can
send—some of them have a specific meaning, others are interpreted
by the application, and the application's documentation will tell you
how that application interprets signals. You can only send a signal to
a process that you own. If you try and send a signal to someone else's
process it will be ignored. The exception to this is the
root user, who can send signals to everyone's
processes.FreeBSD will also send applications signals in some cases. If an
application is badly written, and tries to access memory that it is not
supposed to, FreeBSD sends the process the Segmentation
Violation signal (SIGSEGV). If an
application has used the &man.alarm.3; system call to be alerted after a
period of time has elapsed then it will be sent the Alarm signal
(SIGALRM), and so on.Two signals can be used to stop a process,
SIGTERM and SIGKILL.
SIGTERM is the polite way to kill a process; the
- process can catch the signal, realise that you want
+ process can catch the signal, realize that you want
it to shut down, close any log files it may have open, and generally
finish whatever it is doing at the time before shutting down. In some
cases a process may even ignore SIGTERM if it is in
the middle of some task that can not be interrupted.SIGKILL can not be ignored by a process. This is
the I don't care what you are doing, stop right now
signal. If you send SIGKILL to a process then
FreeBSD will stop that process there and thenNot quite true—there are a few things that can not be
interrupted. For example, if the process is trying to read from a
file that is on another computer on the network, and the other
computer has gone away for some reason (been turned off, or the
network has a fault), then the process is said to be
uninterruptible. Eventually the process will time
out, typically after two minutes. As soon as this time out occurs
the process will be killed..The other signals you might want to use are
SIGHUP, SIGUSR1, and
SIGUSR2. These are general purpose signals, and
different applications will do different things when they are
sent.Suppose that you have changed your web server's configuration
file—you would like to tell the web server to re-read its
configuration. You could stop and restart httpd, but
this would result in a brief outage period on your webserver, which may
be undesirable. Most daemons are written to respond to the
SIGHUP signal by re-reading their configuration
file. So instead of killing and restarting httpd you
would send it the SIGHUP signal. Because there is no
standard way to respond to these signals, different daemons will have
- different behaviour, so be sure and read the documentation for the
+ different behavior, so be sure and read the documentation for the
daemon in question.Signals are sent using the &man.kill.1; command, as this example
shows.Sending a signal to a processThis example shows how to send a signal to &man.inetd.8;. The
&man.inetd.8; configuration file is
/etc/inetd.conf, and &man.inetd.8; will re-read
this configuration file when it is sent
SIGHUP.Find the process ID of the process you want to send the signal
to. Do this using &man.ps.1; and &man.grep.1;. The &man.grep.1;
command is used to search through output, looking for the string you
specify. This command is run as a normal user, and &man.inetd.8; is
run as root, so the options
must be given to &man.ps.1;.&prompt.user; ps -ax | grep inetd
198 ?? IWs 0:00.00 inetd -wWSo the &man.inetd.8; PID is 198. In some cases the
grep inetd command might also occur in this
output. This is because of the way &man.ps.1; has to find the list
of running processes.Use &man.kill.1; to send the signal. Because &man.inetd.8; is
being run by root you must use &man.su.1; to
become root first.&prompt.user; suPassword:
&prompt.root; /bin/kill -s HUP 198As is common with Unix commands, &man.kill.1; will not print any
output if it is successfully. If you try and send a signal to a
process that you do not own then you will see kill:
PID: Operation not
permitted. If you mistype the PID you will either
send the signal to the wrong process, which could be bad, or, if
you are lucky, you will have sent the signal to a PID that is not
currently in use, and you will see kill:
PID: No such process.Why use /bin/kill?Many shells provide the kill command as a
built in command; that is, the shell will send the signal
directly, rather than running /bin/kill.
This can be very useful, but different shells have a different
syntax for specifying the name of the signal to send. Rather than
try to learn all of them, it can be simpler just to use the
/bin/kill ...
command directly.Sending other signals is very similar, just substitute
TERM or KILL in the command line
as necessary.Killing random process on the system can be a bad idea. In
particular, &man.init.8;, process ID 1, is very special. Running
/bin/kill -s KILL 1 is a quick way to shutdown your
system. Always double check the arguments you
run &man.kill.1; with before you press
RETURN.Shellsshellscommand-lineIn FreeBSD, a lot of everyday work is done in a command line
interface called a shell. A shell's main job is to take commands
from the input channel and execute them. A lot of shells also have
built in functions to help everyday tasks such a file management,
file globing, command line editing, command macros, and environment
variables. FreeBSD comes with a set of shells, such as
sh, the Bourne Shell, and csh,
the C-shell. Many other shells are available
from the FreeBSD Ports Collection that have much more power, such as
tcsh and bash.Which shell do you use? It is really a matter of taste. If you
are a C programmer you might feel more comfortable with a C-like shell
such as tcsh. If you've come from Linux or are new
to a Unix command line interface you might try bash.
The point is that each
shell has unique properties that may or may not work with your
preferred working environment, and that you have a choice of what
shell to use.One common feature in a shell is file-name completion. Given
the typing of the first few letters of a command or filename, you
can usually have the shell automatically complete the rest of the
command or filename by hitting the TAB key on the keyboard. Here is
an example. Suppose you have two files called
foobar and foo.bar. You
want to delete foo.bar. So what you would type
on the keyboard is: rm fo[TAB].[TAB].The shell would print out rm
foo[BEEP].bar.The [BEEP] is the console bell, which is the shell telling me it
was unable to totally complete the filename because there is more
than one match. Both foobar and
foo.bar start with fo, but
it was able to complete to foo. If you type in
., then hit TAB again, the shell would be able to
fill in the rest of the filename for you.environment variablesAnother function of the shell is environment variables.
Environment variables are a variable key pair stored in the shell's
environment space. This space can be read by any program invoked by
the shell, and thus contains a lot of program configuration. Here
is a list of common environment variables and what they mean:environment variablesVariableDescriptionUSERCurrent logged in user's name.PATHColon separated list of directories to search for
binaries.DISPLAYNetwork name of the X11 display to connect to, if
available.SHELLThe current shell.TERMThe name of the user's terminal. Used to determine the
capabilities of the terminal.TERMCAPDatabase entry of the terminal escape codes to perform
various terminal functions.OSTYPEType of operating system. E.g., FreeBSD.MACHTYPEThe CPU architecture that the system is running
on.EDITORThe user's preferred text editor.PAGERThe user's preferred text pager.MANPATHColon separated list of directories to search for
manual pages.Bourne shellsTo view or set an environment variable differs somewhat from
shell to shell. For example, in the C-Style shells such as
tcsh and csh, you would use
setenv to set and view environment variables.
Under Bourne shells such as sh and
bash, you would use set and
export to view and set your current environment
variables. For example, to set or modify the
EDITOR environment variable, under csh or
tcsh a
command like this would set EDITOR to
/usr/local/bin/emacs:&prompt.user; setenv EDITOR /usr/local/bin/emacsUnder Bourne shells:&prompt.user; export EDITOR="/usr/local/bin/emacs"You can also make most shells expand the environment variable by
placing a $ character in front of it on the
command line. For example, echo $TERM would
print out whatever $TERM is set to, because the shell
expands $TERM and passes it on to echo.Shells treat a lot of special characters, called meta-characters
as special representations of data. The most common one is the
* character, which represents any number of
characters in a filename. These special meta-characters can be used
to do file name globing. For example, typing in
echo * is almost the same as typing in
ls because the shell takes all the files that
match * and puts them on the command line for
echo to see.To prevent the shell from interpreting these special characters,
they can be escaped from the shell by putting a backslash
(\) character in front of them. echo
$TERM prints whatever your terminal is set to.
echo \$TERM prints $TERM as
is.Changing your shellThe easiest way to change your shell is to use the
chsh command. Running chsh will
place you into the editor that is in your EDITOR
environment variable; if it is not set, you will be placed in
vi. Change the Shell: line
accordingly.You can also give chsh the
option; this will set your shell for you,
without requiring you to enter an editor.
For example, if you wanted to
change your shell to bash, the following should do the
trick:&prompt.user; chsh -s /usr/local/bin/bashRunning chsh with no parameters and editing
the shell from there would work also.The shell that you wish to use must be
present in the /etc/shells file. If you
have installed a shell from the ports
collection, then this should have been done for you
already. If you installed the shell by hand, you must do
this.For example, if you installed bash by hand
and placed it into /usr/local/bin, you would
want to:&prompt.root; echo "/usr/local/bin/bash" >> /etc/shellsThen rerun chsh.Text Editorstext editorseditorsA lot of configuration in FreeBSD is done by editing a text
file. Because of this, it would be a good idea to become familiar
with a text editor. FreeBSD comes with a few as part of the base
system, and many more are available in the ports collection.eeThe easiest and simplest editor to learn is an editor called
ee, which stands for easy editor. To
start ee, one would type at the command
line ee filename where
filename is the name of the file to be edited.
For example, to edit /etc/rc.conf, type in
ee /etc/rc.conf. Once inside of
ee, all of the
commands for manipulating the editor's functions are listed at the
top of the display. The caret ^ character means
the control key on the keyboard, so ^e expands to pressing the
control key plus the letter e. To leave
ee, hit the escape key, then choose leave
editor. The editor will prompt you to save any changes if the file
has been modified.vieditorsviemacseditorsemacsFreeBSD also comes with more powerful text editors such as
vi as part of the base system, and
emacs and vim
as part of the FreeBSD Ports Collection. These editors offer much
more functionality and power at the expense of being a little more
complicated to learn. However if you plan on doing a lot of text
editing, learning a more powerful editor such as
vim or emacs
will save you much more time in the long run.For More Information...Manual pagesman pagesThe most comprehensive documentation on FreeBSD is in the form
of man pages. Nearly every program on the system comes with a
short reference manual explaining the basic operation and various
arguments. These manuals can be viewed with the man command. Use
of the man command is simple:&prompt.user; man commandcommand is the name of the command you
wish to learn about. For example, to learn more about
ls command type:&prompt.user; man lsThe online manual is divided up into numbered sections:User commands.System calls and error numbers.Functions in the C libraries.Device drivers.File formats.Games and other diversions.Miscellaneous information.System maintenance and operation commands.Kernel developers.In some cases, the same topic may appear in more than one
section of the online manual. For example, there is a
chmod user command and a
chmod() system call. In this case, you can
tell the man command which one you want by specifying the
section:&prompt.user; man 1 chmodThis will display the manual page for the user command
chmod. References to a particular section of
the online manual are traditionally placed in parenthesis in
written documentation, so &man.chmod.1; refers to the
chmod user command and &man.chmod.2; refers to
the system call.This is fine if you know the name of the command and simply
wish to know how to use it, but what if you cannot recall the
command name? You can use man to search for keywords in the
command descriptions by using the
switch:&prompt.user; man -k mailWith this command you will be presented with a list of
commands that have the keyword mail in their
descriptions. This is actually functionally equivalent to using
the apropos command.So, you are looking at all those fancy commands in
/usr/bin but do not have the faintest idea
what most of them actually do? Simply do:&prompt.user; cd /usr/bin
&prompt.user; man -f *or&prompt.user; cd /usr/bin
&prompt.user; whatis *which does the same thing.GNU Info FilesFree Software FoundationFreeBSD includes many applications and utilities produced by
the Free Software Foundation (FSF). In addition to man pages,
these programs come with more extensive hypertext documents called
info files which can be viewed with the
info command or, if you installed
emacs, the info mode of
emacs.To use the &man.info.1; command, simply type:&prompt.user; infoFor a brief introduction, type h. For a
quick command reference, type ?.
diff --git a/en_US.ISO8859-1/books/handbook/boot/chapter.sgml b/en_US.ISO8859-1/books/handbook/boot/chapter.sgml
index d1f4d9c1a3..9161fbfb97 100644
--- a/en_US.ISO8859-1/books/handbook/boot/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/boot/chapter.sgml
@@ -1,664 +1,664 @@
The FreeBSD Booting ProcessSynopsisbootingbootstrapThe process of starting a computer and loading the operating system
is referred to as the bootstrap process, or simply
booting. FreeBSD's boot process provides a great deal of
- flexibility in customising what happens when you start the system,
+ flexibility in customizing what happens when you start the system,
allowing you to select from different operating systems installed on the
same computer, or even different versions of the same operating system
or installed kernel.This chapter details the configuration options you can set and how
- to customise the FreeBSD boot process. This includes everything that
+ to customize the FreeBSD boot process. This includes everything that
happens until the FreeBSD kernel has started, probed for devices, and
started &man.init.8;. If you are not quite sure when this happens, it
occurs when the text color changes from bright white to grey.After reading this chapter you will know:What the components of the FreeBSD bootstrap system are, and how
they interact.The options you can give to the components in the FreeBSD
bootstrap to control the boot process.x86 onlyThis chapter only describes the boot process for FreeBSD running
on Intel x86 systems.The Booting ProblemTurning on a computer and starting the operating system poses an
interesting dilemma. By definition, the computer does not know how to
do anything until the operating system is started. This includes
running programs from the disk. So if the computer can not run a
program from the disk without the operating system, and the operating
system programs are on the disk, how is the operating system
started?This problem parallels one in the book The Adventures of
Baron Munchausen. A character had fallen part way down a
manhole, and pulled himself out by grabbing his bootstraps, and
lifting. In the early days of computing the term
bootstrap was applied to the mechanism used to
load the operating system, which has become shortened to
booting.On x86 hardware the Basic Input/Output System (BIOS) is responsible
for loading the operating system. To do this, the BIOS looks on the
hard disk for the Master Boot Record (MBR), which must be located on a
specific place on the disk. The BIOS has enough knowledge to load and
run the MBR, and assumes that the MBR can then carry out the rest of the
tasks involved in loading the operating system.BIOSBasic Input/Output SystemIf you only have one operating system installed on your disks then
the standard MBR will suffice. This MBR searches for the first bootable
slice on the disk, and then runs the code on that slice to load the
remainder of the operating system.If you have installed multiple operating systems on your disks then
you can install a different MBR, one that can display a list of
different operating systems, and allows you to choose the one to boot
from. FreeBSD comes with one such MBR which can be installed, and other
operating system vendors also provide alternative MBRs.The remainder of the FreeBSD bootstrap system is divided into three
stages. The first stage is run by the MBR, which knows just enough to
get the computer into a specific state and run the second stage. The
second stage can do a little bit more, before running the third stage.
The third stage finishes the task of loading the operating system. The
work is split into these three stages because the PC standards put
limits on the size of the programs that can be run at stages one and
two. Chaining the tasks together allows FreeBSD to provide a more
flexible loader.kernelinitThe kernel is then started, which will then probe for devices
and initialize them for use. Once the kernel boot
process is finished, the kernel passes control to the user process
&man.init.8;, which then makes sure the disks are in a usable state.
&man.init.8; then starts the user-level resource configuration which
then mounts filesystems, sets up network cards to act on the
network, and generally starts all the processes that usually
are run on a FreeBSD system at startup.The MBR, and Boot Stages One, Two, and ThreeMBR, /boot/boot0Master Boot Record (MBR)The FreeBSD MBR is located in /boot/boot0.
This is a copy of the MBR, as the real MBR must
be placed on a special part of the disk, outside the FreeBSD
area.boot0 is very simple, since the
program in the MBR can only be 512 bytes in
size. If you have installed the FreeBSD MBR and have installed
multiple operating systems on your hard disks then you will see a
display similar to this one at boot time.boot0 screenshotF1 DOS
F2 FreeBSD
F3 Linux
F4 ??
F5 Drive 1
Default: F2Other operating systems, in particular Windows 95, have been known
to overwrite an existing MBR with their own. If this happens to you,
or you want to replace your existing MBR with the FreeBSD MBR then use
the following command.&prompt.root; fdisk -B -b /boot/boot0 deviceWhere device is the device that you
boot from, such as ad0 for the first IDE
disk, ad4 for the first IDE disk on a second
IDE controller, da0 for the first SCSI disk,
and so on.Stage One, /boot/boot1, and Stage Two,
/boot/boot2Conceptually the first and second stages are part of the same
program, on the same area of the disk. Because of space constraints
they have been split into two, but you would always install them
together.They are found on the boot sector of
the boot slice, which is where boot0, or any other program on the
MBR expects to find the program to run to
continue the boot process. The files in the
/boot directory are copies of the real files,
which are stored outside of the FreeBSD filesystem.boot1 is very simple, since it too
can only be 512 bytes
in size, and knows just enough about the FreeBSD
disklabel, which stores information
about the slice, to find and execute boot2.boot2 is slightly more sophisticated, and understands
the FreeBSD filesystem enough to find files on it, and can
provide a simple interface to choose the kernel or loader to
run.Since the loader is
much more sophisticated, and provides a nice easy-to-use
boot configuration, boot2 usually runs
it, but previously it
was tasked to run the kernel directly.boot2 screenshot>> FreeBSD/i386 BOOT
Default: 0:ad(0,a)/kernel
boot:If you ever need to replace the installed
boot1 and boot2 use
&man.disklabel.8;.&prompt.root; disklabel -B disksliceWhere diskslice is the disk and slice
you boot from, such as ad0s1 for the first
slice on the first IDE disk.Dangerously Dedicated ModeIf you use just the disk name, such as
ad0, in the &man.disklabel.8; command you
will create a dangerously dedicated disk, without slices. This is
almost certainly not what you want to do, so make sure you double
check the &man.disklabel.8; command before you press
RETURN.Stage Three, /boot/loaderboot-loaderThe loader is the final stage of the three-stage
bootstrap, and is located on the filesystem, usually as
/boot/loader.The loader is intended as a user-friendly method for
configuration, using an easy-to-use built-in command set,
backed up by a more powerful interpreter, with a more complex
command set.Loader Program FlowDuring initialization, the loader will probe for a
console and for disks, and figure out what disk it is
booting from. It will set variables accordingly, and then
the interpreter is started, and the easy-to-use commands are
passed to it.loaderloader configurationThe loader will then read
/boot/loader.rc, which by default reads
in /boot/defaults/loader.conf which
sets reasonable defaults for variables and reads
/boot/loader.conf for local changes to
those variables. loader.rc then acts
on these variables, loading whichever modules and kernel are
selected.Finally, by default, the loader issues a 10 second wait
for key presses, and boots the kernel if it is not interrupted.
If interrupted, the user is presented with a prompt which
understands the easy-to-use command set, where the user may
adjust variables, unload all modules, load modules, and then
finally boot or reboot.A more technical discussion of the process is available
in &man.loader.8;Loader Built-In CommandsThe easy-to-use command set comprises of:autoboot secondsProceeds to boot the kernel if not interrupted
within the time span given, in seconds. It displays a
countdown, and the default timespan is 10
seconds.boot
-optionskernelnameImmediately proceeds to boot the kernel, with the
given options, if any, and with the kernel name given,
if it is.boot-confGoes through the same automatic configuration of
modules based on variables as what happens at boot.
This only makes sense if you use
unload first, and change some
variables, most commonly kernel.help
topicShows help messages read from
/boot/loader.help. If the topic
given is index, then the list of
available topics is given.include filename
…Processes the file with the given filename. The
file is read in, and interpreted line by line. An
error immediately stops the include command.load typefilenameLoads the kernel, kernel module, or file of the
type given, with the filename given. Any arguments
after filename are passed to the file.ls pathDisplays a listing of files in the given path, or
the root directory, if the path is not specified. If
is specified, file sizes will be
shown too.lsdev Lists all of the devices from which it may be
possible to load modules. If is
specified, more details are printed.lsmod Displays loaded modules. If is
specified, more details are shown.more filenameDisplay the files specified, with a pause at each
LINES displayed.rebootImmediately reboots the system.set variableset
variable=valueSet loader's environment variables.unloadRemoves all loaded modules.Loader ExamplesHere are some practical examples of loader usage.single-user modeTo simply boot your usual kernel, but in single-user
mode:boot -sTo unload your usual kernel and modules, and then
load just your old (or another) kernel:kernel.oldunloadload kernel.oldYou can use kernel.GENERIC to
refer to the generic kernel that comes on the install
disk, or kernel.old to refer to
your previously installed kernel (when you've upgraded
or configured your own kernel, for example).Use the following to load your usual modules with
another kernel:unloadset kernel="kernel.old"boot-confTo load a kernel configuration script (an automated
script which does the things you'd normally do in the
kernel boot-time configurator):load -t userconfig_script
/boot/kernel.confKernel Interaction During Bootkernelboot interactionOnce the kernel is loaded by either loader (as usual) or boot2 (bypassing the loader), it
examines its boot flags, if any, and adjusts its behavior as
necessary.kernelbootflagsKernel Boot FlagsHere are the more common boot flags:during kernel initialization, ask for the device
to mount as the root file system.boot from CDROM.run UserConfig, the boot-time kernel
configuratorboot into single-user modebe more verbose during kernel startupThere are other boot flags, read &man.boot.8; for more
information on them.initInit: Process Control InitializationOnce the kernel has finished booting, it passes control to
the user process init, which is located at
/sbin/init, or the program path specified
in the init_path variable in
loader.Automatic Reboot SequenceThe automatic reboot sequence makes sure that the
filesystems available on the system are consistent. If they
are not, and fsck cannot fix the
inconsistencies, init drops the system
into single-user mode
for the system administrator to take care of the problems
directly.Single-User Modesingle-user modeconsoleThis mode can be reached through the automatic reboot
sequence, or by the user booting with the
option or setting the
boot_single variable in
loader.It can also be reached by calling
shutdown without the reboot
() or halt () options,
from multi-user
mode.If the system console is set
to insecure in
/etc/ttys, then the system prompts for
the root password before initiating single-user mode.An insecure console in /etc/ttys# name getty type status comments
#
# This entry needed for asking password when init goes to single-user mode
# If you want to be asked for password, change "secure" to "insecure" here
console none unknown off insecureAn insecure console means that you
consider your physical security to the console to be
insecure, and want to make sure only someone who knows the
root password may use single-user mode, and it does not
mean that you want to run your console insecurely. Thus,
if you want security, choose insecure,
not secure.Multi-User Modemulti-user modeIf init finds your filesystems to be
in order, or once the user has finished in single-user mode, the
system enters multi-user mode, in which it starts the
resource configuration of the system.rc filesResource Configuration (rc)The resource configuration system reads in
configuration defaults from
/etc/defaults/rc.conf, and
system-specific details from
/etc/rc.conf, and then proceeds to
mount the system filesystems mentioned in
/etc/fstab, start up networking
services, start up miscellaneous system daemons, and
finally runs the startup scripts of locally installed
packages.The &man.rc.8; manpage is a good reference to the resource
configuration system, as is examining the scripts
themselves.Shutdown SequenceshutdownUpon controlled shutdown, via shutdown,
init will attempt to run the script
/etc/rc.shutdown, and then proceed to send
all processes the TERM signal, and subsequently
the KILL signal to any that don't terminate
timely.
diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
index e0be143ef3..62e8b82459 100644
--- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
@@ -1,1311 +1,1311 @@
Configuring the FreeBSD KernelSynopsisUpdated and restructured by &a.jim;, March 2000.
Originally contributed by &a.jehamby;, 6 October
1995.kernelbuilding a custom kernelThe kernel is the core of the FreeBSD operating system. It is
responsible for managing memory, enforcing security controls,
networking, disk access, and much more. While more and more of FreeBSD
becomes dynamically configurable it is still occasionally necessary to
reconfigure and recompile your kernel.After reading this chapter you will know:Why you might need to build a custom kernelHow to write a kernel configuration file, or alter an existing
configuration fileHow to use the kernel configuration file to create and build a
new kernelHow to install the new kernelHow to create any entries in /dev that may
be requiredHow to troubleshoot if things go wrongWhy Build a Custom Kernel?Traditionally FreeBSD has had what is called a
monolithic kernel. This means that the kernel was one
large program, supported a fixed list of devices, and if you wanted to
- change the kernel's behaviour then you had to compile a new kernel, and
+ change the kernel's behavior then you had to compile a new kernel, and
then reboot your computer with the new kernel.Today, FreeBSD is rapidly moving to a model where much of the
kernel's functionality is contained in modules which can be dynamically
loaded and unloaded from the kernel as necessary. This allows the
kernel to adapt to new hardware suddenly becoming available (such as
PCMCIA cards in a laptop), or for new functionality to be bought in to
the kernel that was not necessary when the kernel was originally
compiled. Colloquially these are called KLDs.Despite this, it is still necessary to carry out some static kernel
configuration. In some cases this is because the functionality is so
tied to the kernel that it can not be made dynamically loadable. In
others it may simply be because no one has yet taken the time to write a
dynamic loadable kernel module for that functionality yet.Building a custom kernel is one of the most important rites of
passage nearly every Unix user must endure. This process, while
time consuming, will provide many benefits to your FreeBSD system.
Unlike the GENERIC kernel, which must support a
wide range of hardware, a custom kernel only contains support for
your PC's hardware. This has a number of
benefits, such as:Faster boot time. Since the kernel will only probe the
hardware you have on your system, the time it takes your system to
boot will decrease dramatically.Less memory use. A custom kernel often uses less memory
than the GENERIC kernel, which is important
because the kernel is one process that must always be present in
memory. For this reason, a custom kernel is especially useful
on a system with a small amount of RAM.Additional hardware support. A custom kernel allows you to
add in support for devices such as sound cards, which are not
present in the GENERIC kernel.Building and Installing a Custom Kernelkernelbuilding / installingFirst, let us take a quick tour of the kernel build directory.
All directories mentioned will be relative to the main
/usr/src/sys directory, which is also
accessible through /sys. There are a number of
subdirectories here representing different parts of the kernel, but
the most important, for our purposes, are
arch/conf, where you
will edit your custom kernel configuration, and
compile, which is the staging area where your
kernel will be built. arch represents
either i386, alpha, or
pc98 (an alternative development branch of PC
hardware, popular in Japan). Everything inside a particular
architecture's directory deals with that architecture only; the rest
of the code is common to all platforms to which FreeBSD could
potentially be ported. Notice the logical organization of the
directory structure, with each supported device, filesystem, and
option in its own subdirectory.If there is not a
/usr/src/sys directory on your system, then
the kernel source has not been installed. The easiest way to
do this is by running /stand/sysinstall as
root, choosing Configure,
then Distributions, then
src, then sys.Next, move to the
arch/conf directory
and copy the GENERIC configuration file to the
name you want to give your kernel. For example:&prompt.root; cd /usr/src/sys/i386/conf
&prompt.root; cp GENERIC MYKERNELTraditionally, this name is in all capital letters and, if you
are maintaining multiple FreeBSD machines with different hardware,
it is a good idea to name it after your machine's hostname. We will
call it MYKERNEL for the purpose of this
example.Storing your kernel config file directly under
/usr/src can be a bad idea. If you are
experiencing problems it can be tempting to just delete
/usr/src and start again. Five seconds after
- you do that you realise that you have deleted your custom kernel
+ you do that you realize that you have deleted your custom kernel
config file.You might want to keep your kernel config file elsewhere, and then
create a symbolic link to the file in the i386
directory.For example:&prompt.root; cd /usr/src/sys/i386/conf
&prompt.root; mkdir /root/kernels
&prompt.root; cp GENERIC /root/kernels/MYKERNEL
&prompt.root; ln -s /root/kernels/MYKERNELYou must execute these and all of the following commands under
the root account or you will get permission
denied errors.Now, edit MYKERNEL with your favorite text
editor. If you are just starting out, the only editor available
will probably be vi, which is too complex to
explain here, but is covered well in many books in the bibliography. However, FreeBSD does
offer an easier editor called ee which, if you are a
beginner, should be your editor of choice. Feel free to change the
comment lines at the top to reflect your configuration or the
changes you have made to differentiate it from
GENERIC.SunOSIf you have built a kernel under SunOS or some other BSD
operating system, much of this file will be very familiar to you.
If you are coming from some other operating system such as DOS, on
the other hand, the GENERIC configuration file
might seem overwhelming to you, so follow the descriptions in the
Configuration File
section slowly and carefully.Be sure to always check the file
/usr/src/UPDATING, before you perform any update
steps, in the case you sync your source-tree with the
latest sources of the FreeBSD project.
In this file all important issues with updating FreeBSD
are written down. /usr/src/UPDATING always fits
to your version of the FreeBSD source, and is therefore more accurate
for those information than the handbook.You must now compile the source code for the kernel. There are two
procedures you can use to do this, and the one you will use depends on
why you are rebuilding the kernel, and the version of FreeBSD you are
running.If you have installed only the kernel
source code, use procedure 1.If you are running a FreeBSD version prior to 4.0, and you are
not upgrading to FreeBSD 4.0 or higher using
the make world procedure, use procedure 1.If you are building a new kernel without updating the source
code (perhaps just to add a new option, such as
IPFIREWALL) you can use either procedure.If you are rebuilding the kernel as part of a make
world process, use procedure 2.Procedure 1. Building a kernel the traditional wayRun &man.config.8; to generate the kernel source code.&prompt.root; /usr/sbin/config MYKERNELChange in to the build directory.&prompt.root; cd ../../compile/MYKERNELCompile the kernel.&prompt.root; make depend
&prompt.root; makeInstall the new kernel.&prompt.root; make installProcedure 2. Building a kernel the new
wayChange to the /usr/src directory&prompt.root; cd /usr/srcCompile the kernel.&prompt.root; make buildkernel KERNCONF=MYKERNELInstall the new kernel.&prompt.root; make installkernel KERNCONF=MYKERNELIn FreeBSD 4.2 and older you must replace
KERNCONF= with KERNEL=.
4.2-STABLE that was fetched after Feb 2nd, 2001 does
recognize KERNCONF=cvsupanonymous CVSCTMCVSanonymousIf you have not upgraded your source
tree in any way (you have not run CVSup,
CTM, or used
anoncvs), then you should use the
config, make depend,
make, make install sequence.kernel.oldThe new kernel will be copied to the root directory as
/kernel and the old kernel will be moved to
/kernel.old. Now, shutdown the system and
reboot to use your kernel. In case something goes wrong, there are
some troubleshooting
instructions at the end of this document. Be sure to read the
section which explains how to recover in case your new kernel does not boot.If you have added any new devices (such as sound cards) you
may have to add some device
nodes to your /dev directory before
you can use them.The Configuration FilekernelLINTLINTkernelconfig fileThe general format of a configuration file is quite simple.
Each line contains a keyword and one or more arguments. For
simplicity, most lines only contain one argument. Anything
following a # is considered a comment and
ignored. The following sections describe each keyword, generally in
the order they are listed in GENERIC, although
some related keywords have been grouped together in a single section
(such as Networking) even though they are actually scattered
throughout the GENERIC file. An exhaustive list of options and more
detailed explanations of the device lines is present in the
LINT configuration file, located in the same
directory as GENERIC. If you are in doubt as
to the purpose or necessity of a line, check first in
LINT.Quoting numbersIn all versions of FreeBSD up to and including 3.X,
&man.config.8; required that any strings in the configuration file
that contained numbers used as text had to be enclosed in double
quotes.This requirement was removed in the 4.X branch, which this
book covers, so if you are on a pre-4.X system, see the
/usr/src/sys/i386/conf/LINT and
/usr/src/sys/i386/conf/GENERIC
files on your system for examples.kernelexample config fileThe following is an example GENERIC kernel
configuration file with various additional comments where needed for
clarity. This example should match your copy in
/usr/src/sys/i386/conf/GENERIC fairly
closely. For details of all the possible kernel options, see
/usr/src/sys/i386/conf/LINT.#
# GENERIC -- Generic kernel configuration file for FreeBSD/i386
#
# For more information on this file, please read the handbook section on
# Kernel Configuration Files:
#
# http://www.freebsd.org/handbook/kernelconfig-config.html
#
# The handbook is also available locally in /usr/share/doc/handbook
# if you've installed the doc distribution, otherwise always see the
# FreeBSD World Wide Web server (http://www.FreeBSD.ORG/) for the
# latest information.
#
# An exhaustive list of options and more detailed explanations of the
# device lines is also present in the ./LINT configuration file. If you are
# in doubt as to the purpose or necessity of a line, check first in LINT.
#
# $FreeBSD: src/sys/i386/conf/GENERIC,v 1.246 2000/03/09 16:32:55 jlemon Exp $The following are the mandatory keywords required in
every kernel you build:kernel optionsmachinemachine i386This is the machine architecture. It must be either
i386, alpha, or
pc98.kernel optionscpucpu I386_CPU
cpu I486_CPU
cpu I586_CPU
cpu I686_CPUThe above specifies the type of CPU you have in your system.
You may have multiple instances of the CPU line (i.e., you are not
sure whether you should use I586_CPU or
I686_CPU), however, for a custom kernel, it is
best to specify only the CPU you have. If you are unsure of your CPU type,
you can use the dmesg command to
view your boot up messages.kernel optionscpu typeThe Alpha architecture has different values for
cpu_type. They include:cpu EV4
cpu EV5If you are using an Alpha machine, you should be using one of
the above CPU types.kernel optionsidentident GENERICThis is the identification of the kernel. You should change
this to whatever you named your kernel, in our previous example,
MYKERNEL. The value you put in the
ident string will print when you boot up the
kernel, so it is useful to give a kernel a different name if you
want to keep it separate from your usual kernel (i.e., you want to
build an experimental kernel).kernel optionsmaxusersmaxusers 32The maxusers option sets the size of a number
of important system tables. This number is supposed to be roughly
equal to the number of simultaneous users you expect to have on your
machine. However, under normal circumstances, you will want to set
maxusers to at least 4, especially if you are
using the X Window System or compiling software. The reason is that
the most important table set by maxusers is the
maximum number of processes, which is set to 20 + 16 *
maxusers, so if you set maxusers to 1,
then you can only have 36 simultaneous processes, including the 18
or so that the system starts up at boot time, and the 15 or so you
will probably create when you start the X Window System. Even a
simple task like reading a man page will start up nine processes to
filter, decompress, and view it. Setting
maxusers to 64 will allow you to have up to 1044
simultaneous processes, which should be enough for nearly all uses.
If, however, you see the dreaded proc table
full error when trying to start another program, or are
running a server with a large number of simultaneous users (like
ftp.FreeBSD.org), you can always
increase the number and rebuild.maxusers does not
limit the number of users which can log into your machine. It
simply sets various table sizes to reasonable values considering
the maximum number of users you will likely have on your system
and how many processes each of them will be running. One keyword
which does limit the number of simultaneous
remote logins is pseudo-device pty
16.Everything that follows is more or less optional. See the notes
underneath or next to each option for more information.#makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
options MATH_EMULATE #Support for x87 emulationThis line allows the kernel to simulate a math co-processor if
your computer does not have one (386 or 486SX). If you have a
486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or
higher (Pentium, Pentium II, etc.), you can comment this line
out.The normal math co-processor emulation routines that come with
FreeBSD are not very accurate. If you do not
have a math co-processor, and you need the best accuracy, it is
recommended that you change this option to
GPL_MATH_EMULATION to use the GNU math support,
which is not included by default for licensing reasons.options INET #InterNETworkingNetworking support. Leave this in, even if you do not plan to
be connected to a network. Most programs require at least loopback
networking (i.e., making network connections within your PC), so
this is essentially mandatory.options INET6 #IPv6 communications protocolsThis enables the IPv6 communication protocols.options FFS #Berkeley Fast Filesystem
options FFS_ROOT #FFS usable as root device [keep this!]This is the basic hard drive filesystem. Leave it in if you
boot from the hard disk.options MFS #Memory Filesystem
options MD_ROOT #MD is a potential root deviceThis is the memory-mapped filesystem. This is basically a RAM
disk for fast storage of temporary files, useful if you have a lot
of swap space that you want to take advantage of. A perfect place
to mount an MFS partition is on the /tmp
directory, since many programs store temporary data here. To mount
an MFS RAM disk on /tmp, add the following line
to /etc/fstab:/dev/ad1s2b /tmp mfs rw 0 0Now you simply need to either reboot, or run the command
mount /tmp.kernel optionsNFSkernel optionsNFS_ROOToptions NFS #Network Filesystem
options NFS_ROOT #NFS usable as root device, NFS requiredThe network filesystem. Unless you plan to mount partitions
from a Unix file server over TCP/IP, you can comment these
out.kernel optionsMSDOSFSoptions MSDOSFS #MSDOS FilesystemThe MS-DOS filesystem. Unless you plan to mount a DOS formatted
hard drive partition at boot time, you can safely comment this out.
It will be automatically loaded the first time you mount a DOS
partition, as described above. Also, the excellent
mtools software (in the ports collection)
allows you to access DOS floppies without having to mount and
unmount them (and does not require MSDOSFS at
all).options CD9660 #ISO 9660 Filesystem
options CD9660_ROOT #CD-ROM usable as root, CD9660 requiredThe ISO 9660 filesystem for CDROMs. Comment it out if you do
not have a CDROM drive or only mount data CDs occasionally (since it
will be dynamically loaded the first time you mount a data CD).
Audio CDs do not need this filesystem.options PROCFS #Process filesystemThe process filesystem. This is a pretend
filesystem mounted on /proc which allows
programs like &man.ps.1; to give you more information on what
processes are running.options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]Compatibility with 4.3BSD. Leave this in; some programs will
act strangely if you comment this out.options SCSI_DELAY=15000 #Delay (in ms) before probing SCSIThis causes the kernel to pause for 15 seconds before probing
each SCSI device in your system. If you only have IDE hard drives,
you can ignore this, otherwise you will probably want to lower this
number, perhaps to 5 seconds, to speed up booting. Of course, if
you do this, and FreeBSD has trouble recognizing your SCSI devices,
you will have to raise it back up.options UCONSOLE #Allow users to grab the consoleAllow users to grab the console, which is useful for X users.
For example, you can create a console xterm by typing xterm
-C, which will display any write,
talk, and any other messages you receive, as well
as any console messages sent by the kernel.options USERCONFIG #boot -c editorThis option allows you to boot the configuration editor from the
boot menu.options VISUAL_USERCONFIG #visual boot -c editorThis option allows you to boot the visual configuration editor
from the boot menu.options KTRACE #ktrace(1) supportThis enables kernel process tracing, which is useful in
debugging.options SYSVSHM #SYSV-style shared memoryThis option provides for System V shared memory. The most
common use of this is the XSHM extension in X, which many
graphics-intensive programs will automatically take advantage of for
extra speed. If you use X, you'll definitely want to include
this.options SYSVSEM #SYSV-style semaphoresSupport for System V semaphores. Less commonly used but only
adds a few hundred bytes to the kernel.options SYSVMSG #SYSV-style message queuesSupport for System V messages. Again, only adds a few hundred
bytes to the kernel.The &man.ipcs.1; command will list any processes using each of
these System V facilities.options P1003_1B #Posix P1003_1B real-time extensions
options _KPOSIX_PRIORITY_SCHEDULINGReal-time extensions added in the 1993 POSIX. Certain
applications in the ports collection use these (such as Star
Office).kernel optionsICMP_BANDLIMoptions ICMP_BANDLIM #Rate limit bad repliesThis option enables ICMP error response bandwidth limiting. You
typically want this option as it will help protect the machine from
denial of service packet attacks.kernel optionsSMP# To make an SMP kernel, the next two are needed
#options SMP # Symmetric MultiProcessor Kernel
#options APIC_IO # Symmetric (APIC) I/OThe above are both required for SMP support.device isaAll PCs supported by FreeBSD have one of these. If you have an
IBM PS/2 (Micro Channel Architecture), you cannot run FreeBSD at
this time (support is being worked on).device eisaInclude this if you have an EISA motherboard. This enables
auto-detection and configuration support for all devices on the EISA
bus.device pciInclude this if you have a PCI motherboard. This enables
auto-detection of PCI cards and gatewaying from the PCI to ISA
bus.# Floppy drives
device fdc0 at isa? port IO_FD1 irq 6 drq 2
device fd0 at fdc0 drive 0
device fd1 at fdc0 drive 1This is the floppy drive controller. fd0 is
the A: floppy drive, and
fd1 is the B:
drive.device ataThis driver supports all ATA and ATAPI devices. You only need
one device ata line for the kernel to detect all
PCI ATA/ATAPI devices on modern machines.device atadisk # ATA disk drivesThis is needed along with device ata for
ATAPI disk drives.
device atapicd # ATAPI CDROM drivesThis is needed along with device ata for
ATAPI CDROM drives.device atapifd # ATAPI floppy drivesThis is needed along with device ata for
ATAPI floppy drives.device atapist # ATAPI tape drivesThis is needed along with device ata for
ATAPI tape drives.options ATA_STATIC_ID #Static device numberingThis makes the controller number static (like the old driver) or
else the device numbers are dynamically allocated.# ATA and ATAPI devices
device ata0 at isa? port IO_WD1 irq 14
device ata1 at isa? port IO_WD2 irq 15Use the above for older, non-PCI systems.# SCSI Controllers
device ahb # EISA AHA1742 family
device ahc # AHA2940 and onboard AIC7xxx devices
device amd # AMD 53C974 (Teckram DC-390(T))
device dpt # DPT Smartcache - See LINT for options!
device isp # Qlogic family
device ncr # NCR/Symbios Logic
device sym # NCR/Symbios Logic (newer chipsets)
device adv0 at isa?
device adw
device bt0 at isa?
device aha0 at isa?
device aic0 at isa?SCSI controllers. Comment out any you do not have in your
system. If you have an IDE only system, you can remove these
altogether.# SCSI peripherals
device scbus # SCSI bus (required)
device da # Direct Access (disks)
device sa # Sequential Access (tape etc)
device cd # CD
device pass # Passthrough device (direct SCSI
access)SCSI peripherals. Again, comment out any you do not have, or if
you have only IDE hardware, you can remove them completely.# RAID controllers
device ida # Compaq Smart RAID
device amr # AMI MegaRAID
device mlx # Mylex DAC960 familySupported RAID controllers. If you do not have any of these,
you can comment them out or remove them.# atkbdc0 controls both the keyboard and the PS/2 mouse
device atkbdc0 at isa? port IO_KBDThe keyboard controller (atkbdc) provides I/O
services for the AT keyboard and PS/2 style pointing devices. This
controller is required by the keyboard driver
(atkbd) and the PS/2 pointing device driver
(psm).device atkbd0 at atkbdc? irq 1The atkbd driver, together with
atkbdc controller, provides access to the AT 84
keyboard or the AT enhanced keyboard which is connected to the AT
keyboard controller.device psm0 at atkbdc? irq 12Use this device if your mouse plugs into the PS/2 mouse
port.device vga0 at isa?The video card driver.# splash screen/screen saver
pseudo-device splashSplash screen at start up! Screen savers require this
too.# syscons is the default console driver, resembling an SCO console
device sc0 at isa?sc0 is the default console driver, which
resembles a SCO console. Since most full-screen programs access the
console through a terminal database library like
termcap, it should not matter whether you use
this or vt0, the VT220
compatible console driver. When you log in, set your
TERM variable to scoansi if
full-screen programs have trouble running under this console.# Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
#device vt0 at isa?
#options XSERVER # support for X server on a vt console
#options FAT_CURSOR # start with block cursor
# If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
#options PCVT_SCANSET=2 # IBM keyboards are non-stdThis is a VT220-compatible console driver, backward compatible to
VT100/102. It works well on some laptops which have hardware
incompatibilities with sc0. Also set your
TERM variable to vt100 or
vt220 when you log in. This driver might also
prove useful when connecting to a large number of different machines
over the network, where termcap or
terminfo entries for the sc0
device are often not available — vt100
should be available on virtually any platform.# Floating point support - do not disable.
device npx0 at nexus? port IO_NPX irq 13npx0 is the interface to the floating point
math unit in FreeBSD, which is either the hardware co-processor or
the software math emulator. This is not
optional.# Power management support (see LINT for more options)
device apm0 at nexus? disable flags 0x20 # Advanced Power ManagementAdvanced Power Management support. Useful for laptops.# PCCARD (PCMCIA) support
device card
device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disablePCMCIA support. You need this if you are installing on a
laptop.# Serial (COM) ports
device sio0 at isa? port IO_COM1 flags 0x10 irq 4
device sio1 at isa? port IO_COM2 irq 3
device sio2 at isa? disable port IO_COM3 irq 5
device sio3 at isa? disable port IO_COM4 irq 9These are the four serial ports referred to as COM1 through COM4
in the MS-DOS/Windows world.If you have an internal modem on COM4 and a serial port at
COM2, you will have to change the IRQ of the modem to 2 (for
obscure technical reasons, IRQ2 = IRQ 9) in order to access it
from FreeBSD. If you have a multiport serial card, check the
manual page for &man.sio.4; for more information on the proper
values for these lines. Some video cards (notably those based on
S3 chips) use IO addresses in the form of
0x*2e8, and since many cheap serial cards do
not fully decode the 16-bit IO address space, they clash with
these cards making the COM4 port practically unavailable.Each serial port is required to have a unique IRQ (unless you
are using one of the multiport cards where shared interrupts are
supported), so the default IRQs for COM3 and COM4 cannot be
used.# Parallel port
device ppc0 at isa? irq 7This is the ISA-bus parallel port interface.device ppbus # Parallel port bus (required)Provides support for the parallel port bus.device lpt # PrinterSupport for parallel port printers.All three of the above are required to enable parallel printer
support.device plip # TCP/IP over parallelThis is the driver for the parallel network interface.device ppi # Parallel port interface deviceThe general-purpose I/O (geek port) + IEEE1284
I/O.#device vpo # Requires scbus and dazip driveThis is for an Iomega Zip drive. It requires
scbus and da support. Best
performance is achieved with ports in EPP 1.9 mode.# PCI Ethernet NICs.
device de # DEC/Intel DC21x4x (Tulip)
device fxp # Intel EtherExpress PRO/100B (82557, 82558)
device tx # SMC 9432TX (83c170 EPIC)
device vx # 3Com 3c590, 3c595 (Vortex)
device wx # Intel Gigabit Ethernet Card (Wiseman)Various PCI network card drivers. Comment out or remove any of
these not present in your system.# PCI Ethernet NICs that use the common MII bus controller code.
device miibus # MII bus supportMII bus support is required for some PCI 10/100 Ethernet NICs,
namely those which use MII-compliant transceivers or implement
transceiver control interfaces that operate like an MII. Adding
device miibus to the kernel config pulls in
support for the generic miibus API and all of the PHY drivers,
including a generic one for PHYs that are not specifically handled
by an individual driverdevice dc # DEC/Intel 21143 and various workalikes
device rl # RealTek 8129/8139
device sf # Adaptec AIC-6915 (Starfire)
device sis # Silicon Integrated Systems SiS 900/SiS 7016
device ste # Sundance ST201 (D-Link DFE-550TX)
device tl # Texas Instruments ThunderLAN
device vr # VIA Rhine, Rhine II
device wb # Winbond W89C840F
device xl # 3Com 3c90x (Boomerang, Cyclone)Drivers that use the MII bus controller code.# ISA Ethernet NICs.
device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
device ex
device ep
# WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
# exists only as a PCMCIA device, so there is no ISA attachment needed
# and resources will always be dynamically assigned by the pccard code.
device wi
# Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
# work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
# mode (the factory default). If you set the switches on your ISA
# card for a manually chosen I/O address and IRQ, you must specify
# those parameters here.
device an
# The probe order of these is presently determined by i386/isa/isa_compat.c.
device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
device fe0 at isa? port 0x300
device le0 at isa? port 0x300 irq 5 iomem 0xd0000
device lnc0 at isa? port 0x280 irq 10 drq 0
device cs0 at isa? port 0x300
device sn0 at isa? port 0x300 irq 10
# requires PCCARD (PCMCIA) support to be activated
#device xe0 at isa?ISA Ethernet drivers. See
/usr/src/sys/i386/conf/LINT for which cards are
supported by which driver.# Pseudo devices - the number indicates how many units to allocate.
pseudo-device loop # Network loopbackThis is the generic loopback device for TCP/IP. If you telnet
or FTP to localhost (a.k.a., 127.0.0.1) it will come back at you through
this pseudo-device. This is mandatory.pseudo-device ether # Ethernet supportether is only needed if you have an Ethernet
card. It includes generic Ethernet protocol code.pseudo-device sl 1 # Kernel SLIPsl is for SLIP support. This has been almost
entirely supplanted by PPP, which is easier to set up, better suited
for modem-to-modem connection, and more powerful. The
number after sl
specifies how many simultaneous SLIP sessions to support.pseudo-device ppp 1 # Kernel PPPThis is for kernel PPP support for dial-up connections. There
is also a version of PPP implemented as a userland application that
uses tun and offers more flexibility and features
such as demand dialing. The number after
ppp specifies how many simultaneous PPP
connections to support.pseudo-device tun # Packet tunnel.This is used by the userland PPP software. A
number after tun
specifies the number of simultaneous PPP sessions to support. See
the PPP section of this book for more
information.
pseudo-device pty # Pseudo-ttys (telnet etc)This is a pseudo-terminal or simulated login port.
It is used by incoming telnet and
rlogin sessions,
xterm, and some other applications such
as emacs. A
number after pty indicates the number of
ptys to create. If you need more than the
default of 16 simultaneous xterm windows
and/or remote logins, be sure to increase this number accordingly,
up to a maximum of 256.pseudo-device md # Memory disksMemory disk pseudo-devices.pseudo-device gif 4 # IPv6 and IPv4 tunnelingThis implements IPv6 over IPv4 tunneling, IPv4 over IPv6
tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6
tunneling.pseudo-device faith 1 # IPv6-to-IPv4 relaying (translation)This pseudo-device captures packets that are sent to it and
diverts them to the IPv4/IPv6 translation daemon.# The `bpf' pseudo-device enables the Berkeley Packet Filter.
# Be aware of the administrative consequences of enabling this!
pseudo-device bpf # Berkeley packet filterThis is the Berkeley Packet Filter. This pseudo-device allows
network interfaces to be placed in promiscuous mode, capturing every
packet on a broadcast network (e.g., an Ethernet). These packets
can be captured to disk and or examined with the &man.tcpdump.1;
program.The bpf pseudo-device is also used by
&man.dhclient.8; to obtain the IP address of the default router
(gateway) and so on. If you use DHCP, leave this
uncommented.# USB support
#device uhci # UHCI PCI->USB interface
#device ohci # OHCI PCI->USB interface
#device usb # USB Bus (required)
#device ugen # Generic
#device uhid # Human Interface Devices
#device ukbd # Keyboard
#device ulpt # Printer
#device umass # Disks/Mass storage - Requires scbus and da
#device ums # Mouse
# USB Ethernet, requires mii
#device aue # ADMtek USB ethernet
#device cue # CATC USB ethernet
#device kue # Kawasaki LSI USB ethernetSupport for various USB devices.For more information and additional devices supported by
FreeBSD, see
/usr/src/sys/i386/conf/LINT.Making Device Nodesdevice nodesMAKEDEVAlmost every device in the kernel has a corresponding
node entry in the /dev directory.
These nodes look like regular files, but are actually special
entries into the kernel which programs use to access the device.
The shell script /dev/MAKEDEV, which is
executed when you first install the operating system, creates
nearly all of the device nodes supported. However, it does not
create all of them, so when you add support for
a new device, it pays to make sure that the appropriate entries are
in this directory, and if not, add them. Here is a simple
example:Suppose you add the IDE CD-ROM support to the kernel. The line
to add is:device acd0This means that you should look for some entries that start with
acd0 in the /dev
directory, possibly followed by a letter, such as
c, or preceded by the letter
r, which means a raw device. It
turns out that those files are not there, so you must change to the
/dev directory and type:MAKEDEV&prompt.root; sh MAKEDEV acd0When this script finishes, you will find that there are now
acd0c and racd0c entries
in /dev so you know that it executed
correctly.For sound cards, the following command creates the appropriate
entries:&prompt.root; sh MAKEDEV snd0When creating device nodes for devices such as sound cards, if
other people have access to your machine, it may be desirable to
protect the devices from outside access by adding them to the
/etc/fbtab file. See &man.fbtab.5; for more
information.Follow this simple procedure for any other
non-GENERIC devices which do not have
entries.All SCSI controllers use the same set of
/dev entries, so you do not need to create
these. Also, network cards and SLIP/PPP pseudo-devices do not
have entries in /dev at all, so you do not
have to worry about these either.If Something Goes WrongThere are four categories of trouble that can occur when
building a custom kernel. They are:config failsIf the config command fails when you
give it your kernel description, you have probably made a
simple error somewhere. Fortunately,
config will print the line number that it
had trouble with, so you can quickly skip to it with
vi. For example, if you see:config: line 17: syntax errorYou can skip to the problem in vi by
typing 17G in command mode. Make sure the
keyword is typed correctly, by comparing it to the
GENERIC kernel or another
reference.make failsIf the make command fails, it usually
signals an error in your kernel description, but not severe
enough for config to catch it. Again, look
over your configuration, and if you still cannot resolve the
problem, send mail to the &a.questions; with your kernel
configuration, and it should be diagnosed very quickly.The kernel will not bootIf your new kernel does not boot, or fails to recognize
your devices, do not panic! Fortunately, BSD has an excellent
mechanism for recovering from incompatible kernels. Simply
choose the kernel you want to boot from at the FreeBSD boot
loader (i.e.,
boot kernel.old).
When reconfiguring a kernel, it is always a good idea to keep
a kernel that is known to work on hand.After booting with a good kernel you can check over your
configuration file and try to build it again. One helpful
resource is the /var/log/messages file
which records, among other things, all of the kernel messages
from every successful boot. Also, the &man.dmesg.8; command
will print the kernel messages from the current boot.If you are having trouble building a kernel, make sure
to keep a GENERIC, or some other kernel
that is known to work on hand as a different name that will
not get erased on the next build. You cannot rely on
kernel.old because when installing a
new kernel, kernel.old is overwritten
with the last installed kernel which may be non-functional.
Also, as soon as possible, move the working kernel to the
proper kernel location or commands such
as &man.ps.1; will not work properly. The proper command to
unlock the kernel file that
make installs (in order to move another
kernel back permanently) is:&prompt.root; chflags noschg /kernelIf you find you cannot do this, you are probably running
at a &man.securelevel.8; greater than zero. Edit
kern_securelevel in
/etc/rc.conf and set it to
-1, then reboot. You can change it back
to its previous setting when you are happy with your new
kernel.And, if you want to lock your new kernel
into place, or any file for that matter, so that it cannot
be moved or tampered with:&prompt.root; chflags schg /kernelThe kernel works, but ps does not work
any more!If you have installed a different version of the kernel
from the one that the system utilities have been built with,
for example, a 4.X kernel on a 3.X system, many system-status
commands like &man.ps.1; and &man.vmstat.8; will not work any
more. You must recompile the libkvm
library as well as these utilities. This is one reason it is
not normally a good idea to use a different version of the
kernel from the rest of the operating system.
diff --git a/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml b/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml
index d56fa5aaba..d29fc84ca2 100644
--- a/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kerneldebug/chapter.sgml
@@ -1,638 +1,638 @@
Kernel DebuggingContributed by &a.paul; and &a.joerg;Debugging a Kernel Crash Dump with gdbHere are some instructions for getting kernel debugging working on a
crash dump. They assume that you have enough swap space for a crash
dump. If you have multiple swap partitions and the first one is too
small to hold the dump, you can configure your kernel to use an
alternate dump device (in the config kernel line), or
you can specify an alternate using the
&man.dumpon.8; command. The best way to use &man.dumpon.8; is to set
the dumpdev variable in
/etc/rc.conf. Typically you want to specify one of
the swap devices specified in /etc/fstab. Dumps to
non-swap devices, tapes for example, are currently not supported. Config
your kernel using config . See Kernel Configuration for details on
configuring the FreeBSD kernel.Use the &man.dumpon.8; command to tell the kernel where to dump to
(note that this will have to be done after configuring the partition in
question as swap space via &man.swapon.8;). This is normally arranged
via /etc/rc.conf and /etc/rc.
Alternatively, you can hard-code the dump device via the
dump clause in the config line of
your kernel config file. This is deprecated and should be used only if
you want a crash dump from a kernel that crashes during booting.In the following, the term gdb refers to
the debugger gdb run in kernel debug
mode. This can be accomplished by starting the
gdb with the option . In
kernel debug mode, gdb changes its prompt to
(kgdb).If you are using FreeBSD 3 or earlier, you should make a stripped
copy of the debug kernel, rather than installing the large debug
kernel itself:&prompt.root; cp kernel kernel.debug
&prompt.root; strip -g kernelThis stage isn't necessary, but it is recommended. (In
FreeBSD 4 and later releases this step is performed automatically
at the end of the kernel make process.)
When the kernel has been stripped, either automatically or by
using the commands above, you may install it as usual by typing
make install.Note that older releases of FreeBSD (up to but not including
3.1) used a.out kernels by default, which must have their symbol
tables permanently resident in physical memory. With the larger
symbol table in an unstripped debug kernel, this is wasteful.
Recent FreeBSD releases use ELF kernels where this is no longer a
problem.If you are testing a new kernel, for example by typing the new
kernel's name at the boot prompt, but need to boot a different one in
order to get your system up and running again, boot it only into single
user state using the flag at the boot prompt, and
then perform the following steps:&prompt.root; fsck -p
&prompt.root; mount -a -t ufs # so your file system for /var/crash is writable
&prompt.root; savecore -N /kernel.panicked /var/crash
&prompt.root; exit # ...to multi-userThis instructs &man.savecore.8; to use another kernel for symbol
name extraction. It would otherwise default to the currently running
kernel and most likely not do anything at all since the crash dump and
the kernel symbols differ.Now, after a crash dump, go to
/sys/compile/WHATEVER and run
gdb . From gdb do:
symbol-file kernel.debugexec-file /var/crash/kernel.0core-file /var/crash/vmcore.0
and voila, you can debug the crash dump using the kernel sources just
like you can for any other program.Here is a script log of a gdb session
illustrating the procedure. Long lines have been folded to improve
readability, and the lines are numbered for reference. Despite this, it
is a real-world error trace taken during the development of the pcvt
console driver. 1:Script started on Fri Dec 30 23:15:22 1994
2:&prompt.root; cd /sys/compile/URIAH
3:&prompt.root; gdb -k kernel /var/crash/vmcore.1
4:Reading symbol data from /usr/src/sys/compile/URIAH/kernel
...done.
5:IdlePTD 1f3000
6:panic: because you said to!
7:current pcb at 1e3f70
8:Reading in symbols for ../../i386/i386/machdep.c...done.
9:(kgdb)where
10:#0 boot (arghowto=256) (../../i386/i386/machdep.c line 767)
11:#1 0xf0115159 in panic ()
12:#2 0xf01955bd in diediedie () (../../i386/i386/machdep.c line 698)
13:#3 0xf010185e in db_fncall ()
14:#4 0xf0101586 in db_command (-266509132, -266509516, -267381073)
15:#5 0xf0101711 in db_command_loop ()
16:#6 0xf01040a0 in db_trap ()
17:#7 0xf0192976 in kdb_trap (12, 0, -272630436, -266743723)
18:#8 0xf019d2eb in trap_fatal (...)
19:#9 0xf019ce60 in trap_pfault (...)
20:#10 0xf019cb2f in trap (...)
21:#11 0xf01932a1 in exception:calltrap ()
22:#12 0xf0191503 in cnopen (...)
23:#13 0xf0132c34 in spec_open ()
24:#14 0xf012d014 in vn_open ()
25:#15 0xf012a183 in open ()
26:#16 0xf019d4eb in syscall (...)
27:(kgdb)up 10
28:Reading in symbols for ../../i386/i386/trap.c...done.
29:#10 0xf019cb2f in trap (frame={tf_es = -260440048, tf_ds = 16, tf_\
30:edi = 3072, tf_esi = -266445372, tf_ebp = -272630356, tf_isp = -27\
31:2630396, tf_ebx = -266427884, tf_edx = 12, tf_ecx = -266427884, tf\
32:_eax = 64772224, tf_trapno = 12, tf_err = -272695296, tf_eip = -26\
33:6672343, tf_cs = -266469368, tf_eflags = 66066, tf_esp = 3072, tf_\
34:ss = -266427884}) (../../i386/i386/trap.c line 283)
35:283 (void) trap_pfault(&frame, FALSE);
36:(kgdb)frame frame->tf_ebp frame->tf_eip
37:Reading in symbols for ../../i386/isa/pcvt/pcvt_drv.c...done.
38:#0 0xf01ae729 in pcopen (dev=3072, flag=3, mode=8192, p=(struct p\
39:roc *) 0xf07c0c00) (../../i386/isa/pcvt/pcvt_drv.c line 403)
40:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
41:(kgdb)list
42:398
43:399 tp->t_state |= TS_CARR_ON;
44:400 tp->t_cflag |= CLOCAL; /* cannot be a modem (:-) */
45:401
46:402 #if PCVT_NETBSD || (PCVT_FREEBSD >= 200)
47:403 return ((*linesw[tp->t_line].l_open)(dev, tp));
48:404 #else
49:405 return ((*linesw[tp->t_line].l_open)(dev, tp, flag));
50:406 #endif /* PCVT_NETBSD || (PCVT_FREEBSD >= 200) */
51:407 }
52:(kgdb)print tp
53:Reading in symbols for ../../i386/i386/cons.c...done.
54:$1 = (struct tty *) 0x1bae
55:(kgdb)print tp->t_line
56:$2 = 1767990816
57:(kgdb)up
58:#1 0xf0191503 in cnopen (dev=0x00000000, flag=3, mode=8192, p=(st\
59:ruct proc *) 0xf07c0c00) (../../i386/i386/cons.c line 126)
60: return ((*cdevsw[major(dev)].d_open)(dev, flag, mode, p));
61:(kgdb)up
62:#2 0xf0132c34 in spec_open ()
63:(kgdb)up
64:#3 0xf012d014 in vn_open ()
65:(kgdb)up
66:#4 0xf012a183 in open ()
67:(kgdb)up
68:#5 0xf019d4eb in syscall (frame={tf_es = 39, tf_ds = 39, tf_edi =\
69: 2158592, tf_esi = 0, tf_ebp = -272638436, tf_isp = -272629788, tf\
70:_ebx = 7086, tf_edx = 1, tf_ecx = 0, tf_eax = 5, tf_trapno = 582, \
71:tf_err = 582, tf_eip = 75749, tf_cs = 31, tf_eflags = 582, tf_esp \
72:= -272638456, tf_ss = 39}) (../../i386/i386/trap.c line 673)
73:673 error = (*callp->sy_call)(p, args, rval);
74:(kgdb)up
75:Initial frame selected; you cannot go up.
76:(kgdb)quit
77:&prompt.root; exit
78:exit
79:
80:Script done on Fri Dec 30 23:18:04 1994Comments to the above script:line 6:This is a dump taken from within DDB (see below), hence the
panic comment because you said to!, and a rather
long stack trace; the initial reason for going into DDB has been a
page fault trap though.line 20:This is the location of function trap()
in the stack trace.line 36:Force usage of a new stack frame; this is no longer necessary
now. The stack frames are supposed to point to the right
locations now, even in case of a trap.
From looking at the code in source line 403, there is a
high probability that either the pointer access for
tp was messed up, or the array access was out of
bounds.line 52:The pointer looks suspicious, but happens to be a valid
address.line 56:However, it obviously points to garbage, so we have found our
error! (For those unfamiliar with that particular piece of code:
tp->t_line refers to the line discipline of
the console device here, which must be a rather small integer
number.)Debugging a Crash Dump with DDDExamining a kernel crash dump with a graphical debugger like
ddd is also possible. Add the
option to the ddd command line you would use
normally. For example;&prompt.root; ddd -k /var/crash/kernel.0 /var/crash/vmcore.0You should then be able to go about looking at the crash dump using
ddd's graphical interface.Post-Mortem Analysis of a DumpWhat do you do if a kernel dumped core but you did not expect it,
and it is therefore not compiled using config -g? Not
everything is lost here. Do not panic!Of course, you still need to enable crash dumps. See above on the
options you have to specify in order to do this.Go to your kernel config directory
(/usr/src/sys/arch/conf)
and edit your configuration file. Uncomment (or add, if it does not
exist) the following linemakeoptions DEBUG=-g #Build kernel with gdb(1) debug symbolsRebuild the kernel. Due to the time stamp change on the Makefile,
there will be some other object files rebuild, for example
trap.o. With a bit of luck, the added
option will not change anything for the generated
code, so you will finally get a new kernel with similar code to the
faulting one but some debugging symbols. You should at least verify the
old and new sizes with the &man.size.1; command. If there is a
mismatch, you probably need to give up here.Go and examine the dump as described above. The debugging symbols
might be incomplete for some places, as can be seen in the stack trace
in the example above where some functions are displayed without line
numbers and argument lists. If you need more debugging symbols, remove
the appropriate object files and repeat the gdb
session until you know enough.All this is not guaranteed to work, but it will do it fine in most
cases.On-Line Kernel Debugging Using DDBWhile gdb as an off-line debugger provides a very
high level of user interface, there are some things it cannot do. The
most important ones being breakpointing and single-stepping kernel
code.If you need to do low-level debugging on your kernel, there is an
on-line debugger available called DDB. It allows to setting
breakpoints, single-stepping kernel functions, examining and changing
kernel variables, etc. However, it cannot access kernel source files,
and only has access to the global and static symbols, not to the full
debug information like gdb.To configure your kernel to include DDB, add the option line
options DDB
to your config file, and rebuild. (See Kernel Configuration for details on
configuring the FreeBSD kernel.If you have an older version of the boot blocks, your
debugger symbols might not be loaded at all. Update the boot blocks;
the recent ones load the DDB symbols automagically.)Once your DDB kernel is running, there are several ways to enter
DDB. The first, and earliest way is to type the boot flag
right at the boot prompt. The kernel will start up
in debug mode and enter DDB prior to any device probing. Hence you can
even debug the device probe/attach functions.The second scenario is a hot-key on the keyboard, usually
Ctrl-Alt-ESC. For syscons, this can be remapped; some of the
distributed maps do this, so watch out. There is an option available
for serial consoles that allows the use of a serial line BREAK on the
console line to enter DDB (options BREAK_TO_DEBUGGER
in the kernel config file). It is not the default since there are a lot
- of crappy serial adapters around that gratuitously generate a BREAK
+ of low quality serial adapters around that gratuitously generate a BREAK
condition, for example when pulling the cable.The third way is that any panic condition will branch to DDB if the
kernel is configured to use it. For this reason, it is not wise to
configure a kernel with DDB for a machine running unattended.The DDB commands roughly resemble some gdb
commands. The first thing you probably need to do is to set a
breakpoint:b function-nameb addressNumbers are taken hexadecimal by default, but to make them distinct
from symbol names; hexadecimal numbers starting with the letters
a-f need to be preceded with 0x
(this is optional for other numbers). Simple expressions are allowed,
for example: function-name + 0x103.To continue the operation of an interrupted kernel, simply
type:cTo get a stack trace, use:traceNote that when entering DDB via a hot-key, the kernel is currently
servicing an interrupt, so the stack trace might be not of much use
for you.If you want to remove a breakpoint, usedeldel address-expressionThe first form will be accepted immediately after a breakpoint hit,
and deletes the current breakpoint. The second form can remove any
breakpoint, but you need to specify the exact address; this can be
obtained from:show bTo single-step the kernel, try:sThis will step into functions, but you can make DDB trace them until
the matching return statement is reached by:nThis is different from gdb's
next statement; it is like gdb's
finish.To examine data from memory, use (for example):
x/wx 0xf0133fe0,40x/hd db_symtab_spacex/bc termbuf,10x/s stringbuf
for word/halfword/byte access, and hexadecimal/decimal/character/ string
display. The number after the comma is the object count. To display
the next 0x10 items, simply use:x ,10Similarly, use
x/ia foofunc,10
to disassemble the first 0x10 instructions of
foofunc, and display them along with their offset
from the beginning of foofunc.To modify memory, use the write command:w/b termbuf 0xa 0xb 0w/w 0xf0010030 0 0The command modifier
(b/h/w)
specifies the size of the data to be written, the first following
expression is the address to write to and the remainder is interpreted
as data to write to successive memory locations.If you need to know the current registers, use:show regAlternatively, you can display a single register value by e.g.
p $eax
and modify it by:set $eax new-valueShould you need to call some kernel functions from DDB, simply
say:call func(arg1, arg2, ...)The return value will be printed.For a &man.ps.1; style summary of all running processes, use:psNow you have examined why your kernel failed, and you wish to
reboot. Remember that, depending on the severity of previous
malfunctioning, not all parts of the kernel might still be working as
expected. Perform one of the following actions to shut down and reboot
your system:panicThis will cause your kernel to dump core and reboot, so you can
later analyze the core on a higher level with gdb. This command
usually must be followed by another continue
statement.call boot(0)Which might be a good way to cleanly shut down the running system,
sync() all disks, and finally reboot. As long as
the disk and file system interfaces of the kernel are not damaged, this
might be a good way for an almost clean shutdown.call cpu_reset()is the final way out of disaster and almost the same as hitting the
Big Red Button.If you need a short command summary, simply type:helpHowever, it is highly recommended to have a printed copy of the
&man.ddb.4; manual page ready for a debugging
session. Remember that it is hard to read the on-line manual while
single-stepping the kernel.On-Line Kernel Debugging Using Remote GDBThis feature has been supported since FreeBSD 2.2, and it is
actually a very neat one.GDB has already supported remote debugging for
a long time. This is done using a very simple protocol along a serial
line. Unlike the other methods described above, you will need two
machines for doing this. One is the host providing the debugging
environment, including all the sources, and a copy of the kernel binary
with all the symbols in it, and the other one is the target machine that
simply runs a similar copy of the very same kernel (but stripped of the
debugging information).You should configure the kernel in question with config
-g, include into the configuration, and
compile it as usual. This gives a large blurb of a binary, due to the
debugging information. Copy this kernel to the target machine, strip
the debugging symbols off with strip -x, and boot it
using the boot option. Connect the serial line
of the target machine that has "flags 080" set on its sio device
to any serial line of the debugging host.
Now, on the debugging machine, go to the compile directory of the target
kernel, and start gdb:&prompt.user; gdb -k kernel
GDB is free software and you are welcome to distribute copies of it
under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-freebsd),
Copyright 1996 Free Software Foundation, Inc...
(kgdb)Initialize the remote debugging session (assuming the first serial
port is being used) by:(kgdb)target remote /dev/cuaa0Now, on the target host (the one that entered DDB right before even
starting the device probe), type:Debugger("Boot flags requested debugger")
Stopped at Debugger+0x35: movb $0, edata+0x51bc
db>gdbDDB will respond with:Next trap will enter GDB remote protocol modeEvery time you type gdb, the mode will be toggled
between remote GDB and local DDB. In order to force a next trap
immediately, simply type s (step). Your hosting GDB
will now gain control over the target kernel:Remote debugging using /dev/cuaa0
Debugger (msg=0xf01b0383 "Boot flags requested debugger")
at ../../i386/i386/db_interface.c:257
(kgdb)You can use this session almost as any other GDB session, including
full access to the source, running it in gud-mode inside an Emacs window
(which gives you an automatic source code display in another Emacs
window) etc.Debugging Loadable Modules Using GDBWhen debugging a panic that occurred within a module, or
using remote GDB against a machine that uses dynamic modules,
you need to tell GDB how to obtain symbol information for those
modules.First, you need to build the module(s) with debugging
information:&prompt.root; cd /sys/modules/linux
&prompt.root; make clean; make COPTS=-gIf you are using remote GDB, you can run
kldstat on the target machine to find out
where the module was loaded:&prompt.root; kldstat
Id Refs Address Size Name
1 4 0xc0100000 1c1678 kernel
2 1 0xc0a9e000 6000 linprocfs.ko
3 1 0xc0ad7000 2000 warp_saver.ko
4 1 0xc0adc000 11000 linux.koIf you are debugging a crash dump, you'll need to walk the
linker_files list, starting at
linker_files->tqh_first and following the
link.tqe_next pointers until you find the
entry with the filename you are looking for.
The address member of that entry is the load
address of the module.Next, you need to find out the offset of the text section
within the module:&prompt.root; objdump --section-headers /sys/modules/linux/linux.ko | grep text
3 .rel.text 000016e0 000038e0 000038e0 000038e0 2**2
10 .text 00007f34 000062d0 000062d0 000062d0 2**2The one you want is the .text section,
section 10 in the above example. The fourth hexadecimal field
(sixth field overall) is the offset of the text section within
the file. Add this offset to the load address of the module to
obtain the relocation address for the module's code. In our
example, we get 0xc0adc000 + 0x62d0 = 0xc0ae22d0. Use the
add-symbol-file command in GDB to tell the
debugger about the module:(kgdb)add-symbol-file /sys/modules/linux/linux.ko 0xc0ae22d0
add symbol table from file "/sys/modules/linux/linux.ko" at text_addr = 0xc0ae22d0?
(y or n) y
Reading symbols from /sys/modules/linux/linux.ko...done.
(kgdb)You should now have access to all the symbols in the
module.Debugging a Console DriverSince you need a console driver to run DDB on, things are more
complicated if the console driver itself is failing. You might remember
the use of a serial console (either with modified boot blocks, or by
specifying at the Boot: prompt),
and hook up a standard terminal onto your first serial port. DDB works
on any configured console driver, of course also on a serial
console.
diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
index 8e862faede..0335c400bc 100644
--- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
@@ -1,2638 +1,2638 @@
Serial CommunicationsSynopsisserial communicationsUnix has always had support for serial communications. In fact,
the very first Unix machines relied on serial lines for user input
and output. Things have changed a lot from the days when the average
terminal consisted of a 10-character-per-second serial
printer and a keyboard. This chapter will cover some of the ways in
which FreeBSD uses serial communications.After reading this chapter you will know:How to connect terminals to your FreeBSD
system.How to use a modem to dial out to remote
hosts.How to allow remote users to login to your
system with a modem.How to boot your system from a serial
console.Before reading this chapter you should:Know how to configure and install a new kernel ()Understand Unix permissions and processes ()Have access to the technical manual for the
serial hardware (modem or multi-port card) that you would like
to use with FreeBSD.IntroductionTerminologybits-per-secondbpsBits per Second — the rate at which data is
transmittedDTEDTEData Terminal Equipment — for example, your
computerDCEDCEData Communications Equipment — your modemRS-232RS-232C cablesEIA standard for hardware serial communicationsIf you need more information about these terms and data
communications in general, The RS-232
Bible is a good reference.When talking about communications data rates, the authors
do not use the term baud. Baud refers to the
number of electrical state transitions that may be made in a
period of time, while bps (bits per second) is
the correct term to use (at least it does not
seem to bother the curmudgeons quite a much).Cables and PortsTo connect a modem or terminal to your FreeBSD system, you
a serial port on your computer and the proper cable to connect
to your serial device. If you are already familiar with your
hardware and the cable it requires, you can safely skip this
section.CablesBecause terminals use serial ports, you need to use
serial—also known as RS-232C—cables to connect the
terminal to the FreeBSD system.There are a couple of kinds of serial cables. Which one
you'll use depends on the terminal you want to connect:null-modem cableIf you are connecting a personal computer to act as a
terminal, use a null-modem
cable. A null-modem cable connects two computers or terminals
together.If you have an actual terminal, your best source of
information on what cable to use is the documentation that
accompanied the terminal. If you do not have the documentation,
then try a null-modem cable.
If that does not work, then try a standard cable.Also, the serial port on both the terminal
and your FreeBSD system must have connectors that will fit the cable
you are using.Null-modem cablesA null-modem cable passes some signals straight through, like
signal ground, but switches other signals. For
example, the send data pin on one end goes to the
receive data pin on the other end.If you like making your own cables, here is a table showing a
recommended way to construct a null-modem cable for use with
terminals. This table shows the RS-232C signal names and the pin
numbers on a DB-25 connector.SignalPin #Pin #SignalTxD2connects to3RxDRxD3connects to2TxDDTR20connects to6DSRDSR6connects to20DTRSG7connects to7SGDCD8connects to4RTSRTS45CTSCTS5connects to8DCDFor DCD to RTS, connect pins 4 to 5 internally in the
connector hood, and then to pin 8 in the remote
hood.Standard RS-232C CablesRS-232C cablesA standard serial cable passes all the RS-232C signals
straight-through. That is, the send data pin on one
end of the cable goes to the send data pin on the
other end. This is the type of cable to connect a modem to your
FreeBSD system, and the type of cable needed for some
terminals.PortsSerial ports are the devices through which data is transferred
between the FreeBSD host computer and the terminal. This section
describes the kinds of ports that exist and how they are addressed
in FreeBSD.Kinds of PortsSeveral kinds of serial ports exist. Before you purchase or
construct a cable, you need to make sure it will fit the ports on
your terminal and on the FreeBSD system.Most terminals will have DB25 ports. Personal computers,
including PCs running FreeBSD, will have DB25 or DB9 ports. If you
have a multiport serial card for your PC, you may have RJ-12 or
RJ-45 ports.See the documentation that accompanied the hardware for
specifications on the kind of port in use. A visual inspection of
the port often works, too.Port NamesIn FreeBSD, you access each serial port through an entry in
the /dev directory. There are two different
kinds of entries:Call-in ports are named
/dev/ttydX
where X is the port number,
starting from zero. Generally, you use the call-in port for
terminals. Call-in ports require that the serial line assert
the data carrier detect (DCD) signal to work.Call-out ports are named
/dev/cuaaX.
You usually do not use the call-out port for terminals, just
for modems. You may use the call-out port if the serial cable
or the terminal does not support the carrier detect
signal.See the &man.sio.4; manual page for more information.If you have connected a terminal to the first serial port
(COM1 in DOS parlance), then you want to
use /dev/ttyd0 to refer to the terminal. If
it is on the second serial port (also known as
COM2), it is
/dev/ttyd1, and so forth.Note that you may have to configure your kernel to support
each serial port, especially if you have a multiport serial card.
See Configuring the FreeBSD
Kernel for more information.Kernel ConfigurationFreeBSD supports four serial ports by default. In the
MS-DOS world, these are known as
COM1:,
COM2:,
COM3:, and
COM4:. FreeBSD currently supports
dumb multiport serial interface cards, such as
the BocaBoard 1008 and 2016 (please see the &man.sio.4 manual
page for more information on these cards), as well as more
intelligent multi-port cards such as those made by Digiboard
and Stallion Technologies. The default kernel only looks for
the standard COM ports, though.To see if your kernel recognizes any of your serial ports, watch
for messages while the kernel is booting, or use the
/sbin/dmesg command to replay the kernel's boot
messages. In particular, look for messages that start with the
characters sio. Hint: to view just the messages
that have the word sio, use the command:&prompt.root; /sbin/dmesg | grep 'sio'For example, on a system with four serial ports, these are the
serial-port specific kernel boot messages:sio0 at 0x3f8-0x3ff irq 4 on isa
sio0: type 16550A
sio1 at 0x2f8-0x2ff irq 3 on isa
sio1: type 16550A
sio2 at 0x3e8-0x3ef irq 5 on isa
sio2: type 16550A
sio3 at 0x2e8-0x2ef irq 9 on isa
sio3: type 16550AIf your kernel does not recognize all of your serial
ports, you will probably need to configure a custom FreeBSD
kernel for your system. For more information about this
please see .The relevant device lines for your kernel configuration
file would look like this:device sio0 at isa? port "IO_COM1" tty irq 4 vector siointr
device sio1 at isa? port "IO_COM2" tty irq 3 vector siointr
device sio2 at isa? port "IO_COM3" tty irq 5 vector siointr
device sio3 at isa? port "IO_COM4" tty irq 9 vector siointrYou can comment-out or completely remove lines for devices
you do not have. Please see the &man.sio.4; manual page for
complete information on how to write configuration lines for
multiport boards. Be careful if you are using a configuration
file that was previously used for a different version of
FreeBSD because the device flags have changed between
versions.port "IO_COM1" is a substitution for
port 0x3f8, IO_COM2 is
0x2f8, IO_COM3 is
0x3e8, and IO_COM4 is
0x2e8, which are fairly common port addresses for
their respective serial ports; interrupts 4, 3, 5, and 9 are fairly
common interrupt request lines. Also note that regular serial ports
cannot share interrupts on ISA-bus PCs
(multiport boards have on-board electronics that allow all the
16550A's on the board to share one or two interrupt request
lines).Device Special FilesMost devices in the kernel are accessed through device
special files, which are located in the
/dev directory. The sio
devices are accessed through the
/dev/ttyd? (dial-in)
and /dev/cuaa?
(call-out) devices. FreeBSD also provides initialization devices
(/dev/ttyid? and
/dev/cuai0?) and
locking devices
(/dev/ttyld? and
/dev/cual0?). The
initialization devices are used to initialize communications port
parameters each time a port is opened, such as
crtscts for modems which use
CTS/RTS signaling for flow control. The locking
devices are used to lock flags on ports to prevent users or programs
changing certain parameters; see the manual pages &man.termios.4;,
&man.sio.4;, and &man.stty.1; for
information on the terminal settings, locking and initializing
devices, and setting terminal options, respectively.Making Device Special FilesA shell script called MAKEDEV in the
/dev directory manages the device special
files. To use MAKEDEV to make dial-up device
special files for COM1: (port 0),
cd to /dev and issue the
command MAKEDEV ttyd0. Likewise, to make dial-up
device special files for COM2: (port 1),
use MAKEDEV ttyd1.MAKEDEV not only creates the
/dev/ttyd? device
special files, but also creates the
/dev/cuaa?,
/dev/cuaia?,
/dev/cuala?,
/dev/ttyld?,
and
/dev/ttyid?
nodes.After making new device special files, be sure to check the
permissions on the files (especially the
/dev/cua* files) to make sure that only users
who should have access to those device special files can read and
write on them — you probably do not want to allow your average
user to use your modems to dial-out. The default permissions on the
/dev/cua* files should be sufficient:crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cuaa1
crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuaia1
crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cuala1These permissions allow the user uucp and
users in the group dialer to use the call-out
devices.Serial Port ConfigurationttydcuaaThe ttydX (or
cuaaX) device is the
regular device you will want to open for your applications. When a
process opens the device, it will have a default set of terminal I/O
settings. You can see these settings with the command&prompt.root; stty -a -f /dev/ttyd1When you change the settings to this device, the settings are in
effect until the device is closed. When it is reopened, it goes back to
the default set. To make changes to the default set, you can open and
adjust the settings of the initial state device. For
example, to turn on mode, 8 bit communication,
and flow control by default for ttyd5,
type:&prompt.root; stty -f /dev/ttyid5 clocal cs8 ixon ixoffrc filesrc.serialSystem-wide initialization of the serial devices is
controlled in /etc/rc.serial. This file
affects the default settings of serial devices.To prevent certain settings from being changed by an
application, make adjustments to the lock state
device. For example, to lock the speed of
ttyd5 to 57600 bps, type:&prompt.root; stty -f /dev/ttyld5 57600Now, an application that opens
ttyd5 and tries to change the speed of
the port will be stuck with 57600 bps.MAKEDEVNaturally, you should make the initial state and lock state devices
writable only by the root account.SeanKellyContributedTerminalsterminalsTerminals provide a convenient and low-cost way to access the power
of your FreeBSD system when you are not at the computer's console or on
a connected network. This section describes how to use terminals with
FreeBSD.Uses and Types of TerminalsThe original Unix systems did not have consoles. Instead, people
logged in and ran programs through terminals that were connected to
the computer's serial ports. It is quite similar to using a modem and
some terminal software to dial into a remote system to do text-only
work.Today's PCs have consoles capable of high quality graphics, but
the ability to establish a login session on a serial port still exists
in nearly every Unix-style operating system today; FreeBSD is no
exception. By using a terminal attached to a unused serial port, you
can log in and run any text program that you would normally run on the
console or in an xterm window in the X Window
System.For the business user, you can attach many terminals to a FreeBSD
system and place them on your employees' desktops. For a home user, a
spare computer such as an older IBM PC or a Macintosh can be a
terminal wired into a more powerful computer running FreeBSD. You can
turn what might otherwise be a single-user computer into a powerful
multiple user system.For FreeBSD, there are three kinds of terminals:Dumb terminalsPCs acting as terminalsX terminalsThe remaining subsections describe each kind.Dumb TerminalsDumb terminals are specialized pieces of hardware that let you
connect to computers over serial lines. They are called
dumb because they have only enough computational power
to display, send, and receive text. You cannot run any programs on
them. It is the computer to which you connect them that has all the
power to run text editors, compilers, email, games, and so
forth.There are hundreds of kinds of dumb terminals made by many
manufacturers, including Digital Equipment Corporation's VT-100 and
Wyse's WY-75. Just about any kind will work with FreeBSD. Some
high-end terminals can even display graphics, but only certain
software packages can take advantage of these advanced
features.Dumb terminals are popular in work environments where workers do
not need access to graphic applications such as those provided by
the X Window System.PCs Acting As TerminalsIf a dumb terminal has just
enough ability to display, send, and receive text, then certainly
any spare personal computer can be a dumb terminal. All you need is
the proper cable and some terminal emulation
software to run on the computer.Such a configuration is popular in homes. For example, if your
spouse is busy working on your FreeBSD system's console, you can do
some text-only work at the same time from a less powerful personal
computer hooked up as a terminal to the FreeBSD system.X TerminalsX terminals are the most sophisticated kind of terminal
available. Instead of connecting to a serial port, they usually
connect to a network like Ethernet. Instead of being relegated to
text-only applications, they can display any X application.We introduce X terminals just for the sake of completeness.
However, this chapter does not cover setup,
configuration, or use of X terminals.ConfigurationThis section describes what you need to configure on your FreeBSD
system to enable a login session on a terminal. It assumes you have
already configured your kernel to support the serial port to which the
terminal is connected—and that you have connected it.Recall from that the
init process is responsible for all process
control and initialization at system startup. One of the
tasks performed by init is to read the
/etc/ttys file and start a
getty process on the available terminals.
The getty process is responsible for
reading a login name and starting the login
program.Thus, to configure terminals for your FreeBSD system the
following steps should be taken as root :Add an line to /etc/ttys for the entry in
the /dev directory for the serial port if it
is not already there.Specify that /usr/libexec/getty be run on
the port, and specify the appropriate
getty type from the
/etc/gettytab file.Specify the default terminal type.Set the port to on.Specify whether the port should be
secure.Force init to reread the
/etc/ttys file.As an optional step, you may wish to create a custom
getty type for use in step 2 by making an
entry in /etc/gettytab. This chapter does
not explain how to do so; you are encouraged to see the
&man.gettytab.5; and the &man.getty.8; manual pages for more
information.To help illustrate this procedure, we will use a running
example throughout this section. In our example, we will
connect two terminals to the system: a Wyse-50 and a old 286
IBM PC running Procomm terminal
software emulating a VT-100 terminal. We connect the Wyse to
the second serial port and the 286 to the sixth serial port (a
port on a multiport serial card).Adding an Entry to /etc/ttysFirst, you need to add an entry to the
/etc/ttys file, unless one is already
there.The /etc/ttys file lists all of the ports
on your FreeBSD system where you want to allow logins. For example,
the first virtual console ttyv0 has an entry in
this file. You can log in on the console using this entry. This
file contains entries for the other virtual consoles, serial ports,
and pseudo-ttys. For a hardwired terminal, just list the serial
port's /dev entry without the
/dev part.A default FreeBSD install includes a
/etc/ttys file with support for the first
four serial ports: ttyd0 through
ttyd3. If you are attaching a terminal on one
of those ports, you do not need to add another entry.In our example, we attached a Wyse-50 to the second serial port,
ttyd1, which is already in the file. We need
to add an entry for the 286 PC connected to the sixth serial port.
Here is an excerpt of the /etc/ttys file after
we add the new entry:ttyd1 "/usr/libexec/getty std.9600" unknown off secure
ttyd5Specifying the getty TypeNext, we need to specify what program will be run to handle the
logins on a terminal. For FreeBSD, the standard program to do that
is /usr/libexec/getty. It is what provides the
login: prompt.The program getty takes one (optional)
parameter on its command line, the getty
type. A getty type tells about
characteristics on the terminal line, like bps rate and parity. The
getty program reads these characteristics from
the file /etc/gettytab.The file /etc/gettytab contains lots of
entries for terminal lines both old and new. In almost all cases,
the entries that start with the text std will
work for hardwired terminals. These entries ignore parity. There is
a std entry for each bps rate from 110 to 115200.
Of course, you can add your own entries to this file. The
&man.gettytab.5; manual page provides more information.When setting the getty type in the
/etc/ttys file, make sure that the
communications settings on the terminal match.For our example, the Wyse-50 uses no parity and connects at
38400 bps. The 286 PC uses no parity and connects at 19200 bps.
Here is the /etc/ttys file so far (showing just
the two terminals in which we are interested):ttyd1 "/usr/libexec/getty std.38400" unknown off secure
ttyd5 "/usr/libexec/getty std.19200"Note that the second field—where we specify what program
to run—appears in quotes. This is important, otherwise the
type argument to getty might be interpreted as
the next field.Specifying the Default Terminal TypeThe third field in the /etc/ttys file lists
the default terminal type for the port. For dial-up ports, you
typically put unknown or
dialup in this field because users may dial up
with practically any kind of terminal or software. For hardwired
terminals, the terminal type does not change, so you can put a real
terminal type in this field.Users will usually use the tset program in
their .login or .profile
files to check the terminal type and prompt for one if necessary.
By setting a terminal type in the /etc/ttys
file, users can forego such prompting.termcapTo find out what terminal types FreeBSD supports, see the
file /usr/share/misc/termcap. It lists
about 600 terminal types. You can add more if you wish. See
the &man.termcap.5; manual page for information.In our example, the Wyse-50 is a Wyse-50 type of terminal
(although it can emulate others, we will leave it in Wyse-50 mode).
The 286 PC is running Procomm which will be set to emulate a VT-100.
Here are the pertinent yet unfinished entries from the
/etc/ttys file:ttyd1 "/usr/libexec/getty std.38400" wy50 off secure
ttyd5 "/usr/libexec/getty std.19200" vt100Enabling the PortThe fourth field in /etc/ttys
specifies if the port should be enabled. Putting
on here will have the init
process start the program in the second field,
getty, which will prompt for a login. If you put
off in the fourth field, there will be no
getty, and hence no logins on the port.So, naturally, you want an on in this field.
Here again is the /etc/ttys file. We have
turned each port on.ttyd1 "/usr/libexec/getty std.38400" wy50 on secure
ttyd5 "/usr/libexec/getty std.19200" vt100 onSpecifying Secure PortsWe have arrived at the last field (well, almost: there is an
optional window specifier, but we will ignore
that). The last field tells whether the port is secure.Marking a port as secure means that you trust it enough
to allow the the root account (or any
account with a user ID of 0) to login from that port.
Insecure ports do not allow root
logins. On an insecure port, users must login from
unprivileged accounts and then use &man.su.1; or similar to
gain superuser privileges.It is highly recommended that you use
insecure even for terminals that are behind
locked doors. It is quite easy to login and use &man.su.1;
if you need superuser privileges.Here finally are the completed entries in the
/etc/ttys file, with comments added to describe
where the terminals are:ttyd1 "/usr/libexec/getty std.38400" wy50 on insecure # Kitchen
ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure # Guest bathroomForce init to Reread
/etc/ttysAfter making the necessary changes to the
/etc/ttys file you should send a SIGHUP
(hangup) signal to the init process to
force it to re-read its configuration file. For example :&prompt.root; kill -HUP 1If everything is set up correctly, all cables are in
place, and the terminals are powered up, then a
getty process should be running on each
terminal and you should see login prompts on your terminals
at this point.Debugging your connectionEven with the most meticulous attention to detail, something could
still go wrong while setting up a terminal. Here is a list of
symptoms and some suggested fixes.No login prompt appearsMake sure the terminal is plugged in and powered up. If it
is a personal computer acting as a terminal, make sure it is
running terminal emulation software on the correct serial
port.Make sure the cable is connected firmly to both the terminal
and the FreeBSD computer. Make sure it is the right kind of
cable.Make sure the terminal and FreeBSD agree on the bps rate and
parity settings. If you have a video display terminal, make
sure the contrast and brightness controls are turned up. If it
is a printing terminal, make sure paper and ink are in good
supply.Make sure that a getty process is running
and serving the terminal. For example, to get a list of
running getty processes with ps, type:&prompt.root; ps -axww|grep gettyYou should see an entry for the terminal. For
example, the following display shows that a
getty is running on the second serial
port ttyd1 and is using the
std.38400 entry in
/etc/gettytab:22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyd1If no getty process is running, make sure
you have enabled the port in /etc/ttys.
Also remember to run kill -HUP 1
after modifying the ttys file.Garbage appears instead of a login promptMake sure the terminal and FreeBSD agree on the bps rate and
parity settings. Check the getty processes to make sure the
correct getty type is in use. If
not, edit /etc/ttys and run kill
-HUP 1.Characters appear doubled; the password appears when
typedSwitch the terminal (or the terminal emulation software)
from half duplex or local echo to
full duplex.GuyHelmerContributedSeanKellyAdditionsDial-in Servicedial-in serviceConfiguring your FreeBSD system for dial-in service is very
similar to connecting terminals except that you're dealing with
modems instead of terminals.External v.s. Internal ModemsExternal modems seem to be more convenient for dial-up, because
external modems often can be semi-permanently configured via
parameters stored in non-volatile RAM and they usually provide
lighted indicators that display the state of important RS-232
signals. Blinking lights impress visitors, but lights are also very
useful to see whether a modem is operating properly.Internal modems usually lack non-volatile RAM, so their
configuration may be limited only to setting DIP switches. If your
internal modem has any signal indicator lights, it is probably
difficult to view the lights when the system's cover is in
place.Modems and CablesmodemIf you are using an external modem, then you will of
course need the proper cable. A standard RS-232C serial
cable should suffice as long as all of the normal signals
are wired :Transmitted Data (SD)Received Data (RD)Request to Send (RTS)Clear to Send (CTS)Data Set Ready (DSR)Data Terminal Ready (DTR)Carrier Detect (CD)Signal Ground (SG)FreeBSD needs the RTS and
CTS signals for flow-control at speeds above
2400bps, the CD signal to detect when a call has
been answered or the line has been hung up, and the
DTR signal to reset the modem after a session is
complete. Some cables are wired without all of the needed signals,
so if you have problems, such as a login session not going away when
the line hangs up, you may have a problem with your cable.Like other Unix-like operating systems, FreeBSD uses the
hardware signals to find out when a call has been answered
or a line has been hung up and to hangup and reset the modem
after a call. FreeBSD avoids sending commands to the modem
or watching for status reports from the modem. If you are
familiar with connecting modems to PC-based bulletin board
systems, this may seem awkward.Serial Interface ConsiderationsFreeBSD supports NS8250-, NS16450-, NS16550-, and NS16550A-based
EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and
16450 devices have single-character buffers. The 16550 device
provides a 16-character buffer, which allows for better system
performance. (Bugs in plain 16550's prevent the use of the
16-character buffer, so use 16550A's if possible). Because
single-character-buffer devices require more work by the operating
system than the 16-character-buffer devices, 16550A-based serial
interface cards are much preferred. If the system has many active
serial ports or will have a heavy load, 16550A-based cards are
better for low-error-rate communications.Quick OverviewgettyAs with terminals, init spawns a
getty process for each configured serial
port for dial-in connections. For example, if a modem is
attached to /dev/ttyd0, the command
ps ax might show this: 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0When a user dials the modem's line and the modems connect, the
CD line is asserted by the modem. The kernel
notices that carrier has been detected and completes
getty's open of the port. getty
sends a login: prompt at the specified initial line
speed. getty watches to see if legitimate
characters are received, and, in a typical configuration, if it finds
junk (probably due to the modem's connection speed being different
than getty's speed), getty tries
adjusting the line speeds until it receives reasonable
characters./usr/bin/loginAfter the user enters his/her login name,
getty executes
/usr/bin/login, which completes the login
by asking for the user's password and then starting the user's
shell.Configuration FilesThere are three system configuration files in the
/etc directory that you will probably need to
edit to allow dial-up access to your FreeBSD system. The first,
/etc/gettytab, contains configuration information
for the /usr/libexec/getty daemon. Second,
/etc/ttys holds information that tells
/sbin/init what tty devices
should have getty processes running on them.
Lastly, you can place port initialization commands in the
/etc/rc.serial script.There are two schools of thought regarding dial-up modems on Unix.
One group likes to configure their modems and systems so that no matter
at what speed a remote user dials in, the local computer-to-modem
RS-232 interface runs at a locked speed. The benefit of this
configuration is that the remote user always sees a system login
prompt immediately. The downside is that the system does not know
what a user's true data rate is, so full-screen programs like Emacs
will not adjust their screen-painting methods to make their response
better for slower connections.The other school configures their modems' RS-232 interface to vary
its speed based on the remote user's connection speed. For example,
V.32bis (14.4 Kbps) connections to the modem might make the modem run
its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the
modem's RS-232 interface run at 2400 bps. Because
getty does not understand any particular modem's
connection speed reporting, getty gives a
login: message at an initial speed and watches the
characters that come back in response. If the user sees junk, it is
assumed that they know they should press the
Enter key until they see a recognizable
prompt. If the data rates do not match, getty sees
anything the user types as junk, tries going to the next
speed and gives the login: prompt again. This
procedure can continue ad nauseam, but normally only takes a keystroke
or two before the user sees a good prompt. Obviously, this login
sequence does not look as clean as the former
locked-speed method, but a user on a low-speed
connection should receive better interactive response from full-screen
programs.The authors will try to give balanced configuration information,
but is biased towards having the modem's data rate follow the
connection rate./etc/gettytab/etc/gettytab/etc/gettytab is a &man.termcap.5;-style
file of configuration information for &man.getty.8;. Please see the
&man.gettytab.5; manual page for complete information on the
format of the file and the list of capabilities.Locked-Speed ConfigIf you are locking your modem's data communications rate at a
particular speed, you probably will not need to make any changes
to /etc/gettytab.Matching-Speed ConfigYou will need to setup an entry in
/etc/gettytab to give
getty information about the speeds you wish to
use for your modem. If you have a 2400 bps modem, you can
probably use the existing D2400 entry.#
# Fast dialup terminals, 2400/1200/300 rotary (can start either way)
#
D2400|d2400|Fast-Dial-2400:\
:nx=D1200:tc=2400-baud:
3|D1200|Fast-Dial-1200:\
:nx=D300:tc=1200-baud:
5|D300|Fast-Dial-300:\
:nx=D2400:tc=300-baud:If you have a higher speed modem, you will probably need to
add an entry in /etc/gettytab; here is an
entry you could use for a 14.4 Kbps modem with a top interface
speed of 19.2 Kbps:#
# Additions for a V.32bis Modem
#
um|V300|High Speed Modem at 300,8-bit:\
:nx=V19200:tc=std.300:
un|V1200|High Speed Modem at 1200,8-bit:\
:nx=V300:tc=std.1200:
uo|V2400|High Speed Modem at 2400,8-bit:\
:nx=V1200:tc=std.2400:
up|V9600|High Speed Modem at 9600,8-bit:\
:nx=V2400:tc=std.9600:
uq|V19200|High Speed Modem at 19200,8-bit:\
:nx=V9600:tc=std.19200:This will result in 8-bit, no parity connections.The example above starts the communications rate at 19.2 Kbps
(for a V.32bis connection), then cycles through 9600 bps (for
V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps.
Communications rate cycling is implemented with the
nx= (next table) capability.
Each of the lines uses a tc= (table
continuation) entry to pick up the rest of the
standard settings for a particular data rate.If you have a 28.8 Kbps modem and/or you want to take
advantage of compression on a 14.4 Kbps modem, you need to use a
higher communications rate than 19.2 Kbps. Here is an example of
a gettytab entry starting a 57.6 Kbps:#
# Additions for a V.32bis or V.34 Modem
# Starting at 57.6 Kbps
#
vm|VH300|Very High Speed Modem at 300,8-bit:\
:nx=VH57600:tc=std.300:
vn|VH1200|Very High Speed Modem at 1200,8-bit:\
:nx=VH300:tc=std.1200:
vo|VH2400|Very High Speed Modem at 2400,8-bit:\
:nx=VH1200:tc=std.2400:
vp|VH9600|Very High Speed Modem at 9600,8-bit:\
:nx=VH2400:tc=std.9600:
vq|VH57600|Very High Speed Modem at 57600,8-bit:\
:nx=VH9600:tc=std.57600:If you have a slow CPU or a heavily loaded system and you do
not have 16550A-based serial ports, you may receive sio
silo errors at 57.6 Kbps./etc/ttys/etc/ttysConfiguration of the /etc/ttys file
was covered in the last section for configuring terminals.
Configuration for modems is similar but we must pass a
different argument to getty and specify a
different terminal type. The general format for both
locked-speed and matching-speed configurations is:ttyd0 "/usr/libexec/getty xxx" dialup onThe first item in the above line is the device special file for
this entry — ttyd0 means
/dev/ttyd0 is the file that this
getty will be watching. The second item,
"/usr/libexec/getty
xxx"
(xxx will be replaced by the initial
gettytab capability) is the process
init will run on the device. The third item,
dialup, is the default terminal type. The fourth
parameter, on, indicates to
init that the line is operational. There can be
a fifth parameter, secure, but it should only be
used for terminals which are physically secure (such as the system
console).The default terminal type (dialup in the
example above) may depend on local preferences.
dialup is the traditional default terminal type
on dial-up lines so that users may customize their login scripts to
notice when the terminal is dialup and
automatically adjust their terminal type. However, the author finds
it easier at his site to specify vt102 as the
default terminal type, since the users just use VT102 emulation on
their remote systems.After you have made changes to /etc/ttys,
you may send the init process a
HUP signal to re-read the file. You can use the
command
&prompt.root; kill -HUP 1
to send the signal. If this is your first time setting up the
system, though, you may want to wait until your modem(s) are properly
configured and connected before signaling init.
Locked-Speed ConfigFor a locked-speed configuration, your
ttys entry needs to have a fixed-speed entry
provided to getty. For a modem whose port
speed is locked at 19.2 Kbps, the ttys entry
might look like this:ttyd0 "/usr/libexec/getty std.19200" dialup onIf your modem is locked at a different data rate,
substitute the appropriate value for
std.speed
instead of std.19200. Make sure that
you use a valid type listed in
/etc/gettytab.
Matching-Speed ConfigIn a matching-speed configuration, your
ttys entry needs to reference the appropriate
beginning auto-baud (sic) entry in
/etc/gettytab. For example, if you added the
above suggested entry for a matching-speed modem that starts at
19.2 Kbps (the gettytab entry containing the
V19200 starting point), your
ttys entry might look like this:ttyd0 "/usr/libexec/getty V19200" dialup on/etc/rc.serialrc filesrc.serialHigh-speed modems, like V.32, V.32bis, and V.34 modems,
need to use hardware (RTS/CTS) flow
control. You can add stty commands to
/etc/rc.serial to set the hardware flow
control flag in the FreeBSD kernel for the modem
ports.For example to set the termios flag
crtscts on serial port #1's
(COM2:) dial-in and dial-out initialization
- devices, the folling lines could be added to
+ devices, the following lines could be added to
/etc/rc.serial :# Serial port initial configuration
stty -f /dev/ttyid1 crtscts
stty -f /dev/cuai01 crtsctsModem SettingsIf you have a modem whose parameters may be permanently set in
non-volatile RAM, you will need to use a terminal program (such as
Telix under MS-DOS or tip under FreeBSD) to set the
parameters. Connect to the modem using the same communications speed
as the initial speed getty will use and configure
the modem's non-volatile RAM to match these requirements:CD asserted when connectedDTR asserted for operation; dropping DTR
hangs up line and resets modemCTS transmitted data flow controlDisable XON/XOFF flow controlRTS received data flow controlQuiet mode (no result codes)No command echoPlease read the documentation for your modem to find out what
commands and/or DIP switch settings you need to give it.For example, to set the above parameters on a USRobotics
Sportster 14,400 external modem, one could give these commands to
the modem:ATZ
AT&C1&D2&H1&I0&R2&WYou might also want to take this opportunity to adjust other
settings in the modem, such as whether it will use V.42bis and/or MNP5
compression.The USR Sportster 14,400 external modem also has some DIP switches
that need to be set; for other modems, perhaps you can use these
settings as an example:Switch 1: UP — DTR NormalSwitch 2: Do not care (Verbal Result Codes/Numeric Result
Codes)Switch 3: UP — Suppress Result CodesSwitch 4: DOWN — No echo, offline commandsSwitch 5: UP — Auto AnswerSwitch 6: UP — Carrier Detect NormalSwitch 7: UP — Load NVRAM DefaultsSwitch 8: Do not care (Smart Mode/Dumb Mode)Result codes should be disabled/suppressed for dial-up modems to
avoid problems that can occur if getty mistakenly
gives a login: prompt to a modem that is in command
mode and the modem echoes the command or returns a result
code. This sequence can result in a extended, silly conversation
between getty and the modem.Locked-speed ConfigFor a locked-speed configuration, you will need to configure the
modem to maintain a constant modem-to-computer data rate independent
of the communications rate. On a USR Sportster 14,400 external
modem, these commands will lock the modem-to-computer data rate at
the speed used to issue the commands:ATZ
AT&B1&WMatching-speed ConfigFor a variable-speed configuration, you will need to configure
your modem to adjust its serial port data rate to match the incoming
call rate. On a USR Sportster 14,400 external modem, these commands
will lock the modem's error-corrected data rate to the speed used to
issue the commands, but allow the serial port rate to vary for
non-error-corrected connections:ATZ
AT&B2&WChecking the Modem's ConfigurationMost high-speed modems provide commands to view the modem's
current operating parameters in a somewhat human-readable fashion.
On the USR Sportster 14,400 external modems, the command
ATI5 displays the settings that are stored in the
non-volatile RAM. To see the true operating parameters of the modem
(as influenced by the USR's DIP switch settings), use the commands
ATZ and then ATI4.If you have a different brand of modem, check your modem's
manual to see how to double-check your modem's configuration
parameters.TroubleshootingHere are a few steps you can follow to check out the dial-up modem
on your system.Checking out the FreeBSD systemHook up your modem to your FreeBSD system, boot the system, and,
if your modem has status indication lights, watch to see whether the
modem's DTR indicator lights when the
login: prompt appears on the system's console
— if it lights up, that should mean that FreeBSD has started a
getty process on the appropriate communications
port and is waiting for the modem to accept a call.If the DTR indicator doesn't light, login to
the FreeBSD system through the console and issue a ps
ax to see if FreeBSD is trying to run a
getty process on the correct port. You should see
a lines like this among the processes displayed: 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0
115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1If you see something different, like this: 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0and the modem has not accepted a call yet, this means that
getty has completed its open on the
communications port. This could indicate a problem with the cabling
or a mis-configured modem, because getty should
not be able to open the communications port until
CD (carrier detect) has been asserted by the
modem.If you do not see any getty processes waiting
to open the desired
ttyd? port,
double-check your entries in /etc/ttys to see
if there are any mistakes there. Also, check the log file
/var/log/messages to see if there are any log
messages from init or getty
regarding any problems. If there are any messages, triple-check the
configuration files /etc/ttys and
/etc/gettytab, as well as the appropriate
device special files /dev/ttyd?, for any
mistakes, missing entries, or missing device special files.Try Dialing InTry dialing into the system; be sure to use 8 bits, no parity, 1
stop bit on the remote system. If you do not get a prompt right
away, or get garbage, try pressing Enter
about once per second. If you still do not see a
login: prompt after a while, try sending a
BREAK. If you are using a high-speed modem to do
the dialing, try dialing again after locking the dialing modem's
interface speed (via AT&B1 on a USR
Sportster, for example).If you still cannot get a login: prompt, check
/etc/gettytab again and double-check
thatThe initial capability name specified in
/etc/ttys for the line matches a name of a
capability in /etc/gettytabEach nx= entry matches another
gettytab capability nameEach tc= entry matches another
gettytab capability nameIf you dial but the modem on the FreeBSD system will not answer,
make sure that the modem is configured to answer the phone when
DTR is asserted. If the modem seems to be
configured correctly, verify that the DTR line is
asserted by checking the modem's indicator lights (if it has
any).If you have gone over everything several times and it still does
not work, take a break and come back to it later. If it still does
not work, perhaps you can send an electronic mail message to the
&a.questions;describing your modem and your problem, and the good
folks on the list will try to help.Dial-out Servicedial-out serviceThe following are tips to getting your host to be able to connect
over the modem to another computer. This is appropriate for
establishing a terminal session with a remote host.This is useful to log onto a BBS.This kind of connection can be extremely helpful to get a file on
the Internet if you have problems with PPP. If you need to FTP
something and PPP is broken, use the terminal session to FTP it. Then
use zmodem to transfer it to your machine.My stock Hayes modem is not supported, what can I do?Actually, the man page for tip is out of date.
There is a generic Hayes dialer already built in. Just use
at=hayes in your /etc/remote
file.The Hayes driver is not smart enough to recognize some of the
advanced features of newer modems—messages like
BUSY, NO DIALTONE, or
CONNECT 115200 will just confuse it. You should
turn those messages off when you use tip (using
ATX0&W).Also, the dial timeout for tip is 60 seconds.
Your modem should use something less, or else tip will think there is
a communication problem. Try ATS7=45&W.Actually, as shipped tip does not yet support
it fully. The solution is to edit the file
tipconf.h in the directory
/usr/src/usr.bin/tip/tip Obviously you need the
source distribution to do this.Edit the line #define HAYES 0 to
#define HAYES 1. Then make and
make install. Everything works nicely after
that.How am I expected to enter these AT commands?/etc/remoteMake what is called a direct entry in your
/etc/remote file. For example, if your modem is
hooked up to the first serial port, /dev/cuaa0,
then put in the following line:cuaa0:dv=/dev/cuaa0:br#19200:pa=noneUse the highest bps rate your modem supports in the br capability.
Then, type tip cuaa0 and you will be connected to
your modem.If there is no /dev/cuaa0 on your system, do
this:&prompt.root; cd /dev
&prompt.root; MAKEDEV cuaa0Or use cu as root with the following command:&prompt.root; cu -lline -sspeedline is the serial port
(e.g./dev/cuaa0) and
speed is the speed
(e.g.57600). When you are done entering the AT
commands hit ~. to exit.The @ sign for the pn capability does not
work!The @ sign in the phone number capability tells
tip to look in /etc/phones for a phone number.
But the @ sign is also a special character in
capability files like /etc/remote. Escape it
with a backslash:pn=\@How can I dial a phone number on the command line?Put what is called a generic entry in your
/etc/remote file. For example:tip115200|Dial any phone number at 115200 bps:\
:dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du:
tip57600|Dial any phone number at 57600 bps:\
:dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du:Then you can things like:&prompt.root; tip -115200 5551234If you prefer cu over tip,
use a generic cu entry:cu115200|Use cu to dial any number at 115200bps:\
:dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du:and type:&prompt.root; cu 5551234 -s 115200Do I have to type in the bps rate every time I do that?Put in an entry for tip1200 or
cu1200, but go ahead and use whatever bps rate is
appropriate with the br capability. tip thinks a
good default is 1200 bps which is why it looks for a
tip1200 entry. You do not have to use 1200 bps,
though.I access a number of hosts through a terminal server.Rather than waiting until you are connected and typing
CONNECT <host> each time, use tip's
cm capability. For example, these entries in
/etc/remote:pain|pain.deep13.com|Forrester's machine:\
:cm=CONNECT pain\n:tc=deep13:
muffin|muffin.deep13.com|Frank's machine:\
:cm=CONNECT muffin\n:tc=deep13:
deep13:Gizmonics Institute terminal server:\
:dv=/dev/cuaa2:br#38400:at=hayes:du:pa=none:pn=5551234:will let you type tip pain or tip
muffin to connect to the hosts pain or muffin; and
tip deep13 to get to the terminal server.Can tip try more than one line for each site?This is often a problem where a university has several modem lines
and several thousand students trying to use them...Make an entry for your university in
/etc/remote and use @ for the
pn capability:big-university:\
:pn=\@:tc=dialout
dialout:\
:dv=/dev/cuaa3:br#9600:at=courier:du:pa=none:Then, list the phone numbers for the university in
/etc/phones:big-university 5551111
big-university 5551112
big-university 5551113
big-university 5551114tip will try each one in the listed order, then
give up. If you want to keep retrying, run tip in
a while loop.Why do I have to hit
CtrlP
twice to send
CtrlP
once?CtrlP is the default force character, used to tell
tip that the next character is literal data. You
can set the force character to any other character with the
~s escape, which means set a
variable.Type
~sforce=single-char
followed by a newline. single-char is any
single character. If you leave out
single-char, then the force character is
the nul character, which you can get by typing
Ctrl2
or
CtrlSPACE.
A pretty good value for single-char is
ShiftCtrl6, which is only used on some terminal
servers.You can have the force character be whatever you want by
specifying the following in your $HOME/.tiprc
file:force=<single-char>Suddenly everything I type is in UPPER CASE??You must have pressed
CtrlA, tip's
raise character, specially designed for people with
broken caps-lock keys. Use ~s as above and set the
variable raisechar to something reasonable. In
fact, you can set it to the same as the force character, if you never
expect to use either of these features.Here is a sample .tiprc file perfect for
Emacs users who need to type
Ctrl2
and
CtrlA
a lot:force=^^
raisechar=^^The ^^ is
ShiftCtrl6.How can I do file transfers with tip?If you are talking to another Unix system, you can send and
receive files with ~p (put) and
~t (take). These commands run
cat and echo on the remote
system to accept and send files. The syntax is:~plocal-fileremote-file~tremote-filelocal-fileThere is no error checking, so you probably should use another
protocol, like zmodem.How can I run zmodem with tip?To receive files, start the sending program on the remote end.
Then, type ~C rz to begin receiving them
locally.To send files, start the receiving program on the remote end.
Then, type ~C sz files
to send them to the remote system.KazutakaYOKOTAContributedBillPaulBased on a documentSetting Up the Serial Consoleserial consoleIntroductionFreeBSD boot on a system with only
a dumb terminal on a serial port as a console. Such a configuration
should be useful for two classes of people: system administrators who
wish to install FreeBSD on machines that have no keyboard or monitor
attached, and developers who want to debug the kernel or device
drivers.As described in , FreeBSD employs a three stage
bootstrap. The first two stages are in the boot block code which is
stored at the beginning of the FreeBSD slice on the boot disk. The
boot block will then load and run the boot loader
(/boot/loader) as the third stage code.In order to set up the serial console you must configure the boot
block code, the boot loader code and the kernel.Serial Console ConfigurationPrepare a serial cable.null-modem cableYou will need either a null-modem cable or a standard serial
cable and a null-modem adapter. See for
a discussion on serial cables.Unplug your keyboard.Most PC systems probe for the keyboard during the Power-On
Self-Test (POST) and will generate an error if the keyboard is not
detected. Some machines complain loudly about the lack of a
keyboard and will not continue to boot until it is plugged
in.If your computer complains about the error, but boots anyway,
then you do not have to do anything special. (Some machines with
Phoenix BIOS installed merely say Keyboard
failed and continue to boot normally.)If your computer refuses to boot without a keyboard attached
then you will have to configure the BIOS so that it ignores this
error (if it can). Consult your motherboard's manual for details
on how to do this.Setting the keyboard to Not installed in the
BIOS setup does not mean that you will not
be able to use your keyboard. All this does is tell the BIOS
not to probe for a keyboard at power-on so that it will not
complain if the keyboard is not plugged in. You can leave the
keyboard plugged in even with this flag set to Not
installed and the keyboard will still work.If your system has a PS/2 mouse, chances are very good that
you may have to unplug your mouse as well as your keyboard.
This is because PS/2 mice share some hardware with the keyboard,
and leaving the mouse plugged in can fool the keyboard probe
into thinking the keyboard is still there. It is said that a
Gateway 2000 Pentium 90MHz system with an AMI BIOS that behaves
this way. In general this is not a problem since the mouse is
not much good without the keyboard anyway.Plug a dumb terminal into COM1:
(sio0).If you do not have a dumb terminal, you can use an old PC/XT
with a modem program, or the serial port on another Unix box. If
you do not have a COM1:
(sio0), get one. At this time, there is
no way to select a port other than COM1:
for the boot blocks without recompiling the boot blocks. If you
are already using COM1: for another
device, you will have to temporarily remove that device and
install a new boot block and kernel once you get FreeBSD up and
running. (It is assumed that COM1: will
be available on a file/compute/terminal server anyway; if you
really need COM1: for something else
(and you cannot switch that something else to
COM2: (sio1)),
then you probably should not even be bothering with all this in
the first place.)Make sure the configuration file of your kernel has
appropriate flags set for COM1:
(sio0).Relevant flags are:0x10Enables console support for this unit. The other
console flags are ignored unless this is set. Currently, at
most one unit can have console support; the first one (in
config file order) with this flag set is preferred. This
option alone will not make the serial port the console. Set
the following flag or use the option
described below, together with this flag.0x20Forces this unit to be the console (unless there is
another higher priority console), regardless of the
option discussed below. This flag
replaces the COMCONSOLE option in FreeBSD
versions 2.X. The flag 0x20 must be used
together with the flag.0x40Reserves this unit (in conjunction with
0x10) and makes the unit
unavailable for normal access. You should not set
this flag to the serial port unit which you want to
use as the serial console. The only use of this
flag is to designate the unit for kernel remote
debugging. See The
Developer's Handbook for more information on
remote debugging.In FreeBSD 4.0-CURRENT or later the semantics of the
flag 0x40 are slightly different and
there is another flag to specify a serial port for remote
debugging.Example:device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4See the &man.sio.4; manual page for more details.If the flags were not set, you need to run UserConfig (on a
different console) or recompile the kernel.Create boot.config in the root directory
of the a partition on the boot drive.This file will instruct the boot block code how you would like
to boot the system. In order to activate the serial console, you
need one or more of the following options—if you want
multiple options, include them all on the same line:Toggles internal and serial consoles. You can use this
to switch console devices. For instance, if you boot from
the internal (video) console, you can use
to direct the boot loader and the kernel
to use the serial port as its console device. Alternatively,
if you boot from the serial port, you can use the
to tell the boot loader and the kernel
to use the video display as the console instead.Toggles single and dual console configurations. In the
single configuration the console will be either the internal
console (video display) or the serial port, depending on the
state of the option above. In the dual
console configuration, both the video display and the
serial port will become the console at the same time,
regardless of the state of the option.
However, that the dual console configuration takes effect
only during the boot block is running. Once the boot loader
gets control, the console specified by the
option becomes the only console.Makes the boot block probe the keyboard. If no keyboard
is found, the and
options are automatically set.Due to space constraints in the current version of the
boot blocks, the option is capable of
detecting extended keyboards only. Keyboards with less
than 101 keys (and without F11 and F12 keys) may not be
detected. Keyboards on some laptop computers may not be
properly found because of this limitation. If this is to
be the case with your system, you have to abandon using
the option. Unfortunately there is no
workaround for this problem.Use either the option to select the
console automatically, or the option to
activate the serial console.You may include other options described in &man.boot.8; as
well.The options, except for , will be passed to
the boot loader (/boot/loader). The boot
loader will determine which of the internal video or the serial
port should become the console by examining the state of the
option alone. This means that if you specify
the option but not the
option in /boot.config, you can use the
serial port as the console only during the boot block; the boot
loader will use the internal video display as the console.Boot the machine.When you start your FreeBSD box, the boot blocks will echo the
contents of /boot.config to the console. For
example;/boot.config: -P
Keyboard: noThe second line appears only if you put in
/boot.config and indicates presence/absence
of the keyboard. These messages go to either serial or internal
console, or both, depending on the option in
/boot.config.OptionsMessage goes tononeinternal consoleserial consoleserial and internal consolesserial and internal consoles, keyboard presentinternal console, keyboard absentserial consoleAfter the above messages, there will be a small pause before
the boot blocks continue loading the boot loader and before any
further messages printed to the console. Under normal
circumstances, you do not need to interrupt the boot blocks, but
you may want to do so in order to make sure things are set up
correctly.Hit any key, other than Enter, at the console to
interrupt the boot process. The boot blocks will then prompt you
for further action. You should now see something like:>> FreeBSD/i386 BOOT
Default: 0:wd(0,a)/boot/loader
boot:Verify the above message appears on either the serial or
internal console or both, according to the options you put in
/boot.config. If the message appears in the
correct console, hit Enter to continue the boot
process.If you want the serial console but you do not see the prompt
on the serial terminal, something is wrong with your settings. In
the meantime, you enter and hit Enter/Return
(if possible) to tell the boot block (and then the boot loader and
the kernel) to choose the serial port for the console. Once the
system is up, go back and check what went wrong.After the boot loader is loaded and you are in the third stage of
the boot process you can still switch between the internal console and
the serial console by setting appropriate environment variables in the
boot loader. See .SummaryHere is the summary of various settings discussed in this section
and the console eventually selected.Case 1: You set the flags to 0x10 for sio0device sio0 at isa? port "IO_COM1" tty flags 0x10 irq 4Options in /boot.configConsole during boot blocksConsole during boot loaderConsole in kernelnothinginternalinternalinternalserialserialserialserial and internalinternalinternalserial and internalserialserial, keyboard presentinternalinternalinternal, keyboard absentserial and internalserialserialCase 2: You set the flags to 0x30 for sio0device sio0 at isa? port "IO_COM1" tty flags 0x30 irq 4Options in /boot.configConsole during boot blocksConsole during boot loaderConsole in kernelnothinginternalinternalserialserialserialserialserial and internalinternalserialserial and internalserialserial, keyboard presentinternalinternalserial, keyboard absentserial and internalserialserialTips for the Serial ConsoleSetting A Faster Serial Port SpeedBy default the serial port settings are set to 9600 baud, 8
bits, no parity, 1 stop bit. If you wish to change the speed, you
need to recompile at least the boot blocks. Add the following line
to /etc/make.conf and compile new boot
blocks:BOOT_COMCONSOLE_SPEED=19200If the serial console is configured in some other way than by
booting with , or if the serial console used by
the kernel is different from the one used by the boot blocks, then
you must also add the following option to the kernel configuration
file and compile a new kernel:options CONSPEED=19200Using Serial Port Other Than sio0 For
The ConsoleUsing a port other than sio0 as the
console requires some recompiling. If you want to use another
serial port for whatever reasons, recompile the boot blocks, the
boot loader and the kernel as follows.Get the kernel source.Edit /etc/make.conf and set
BOOT_COMCONSOLE_PORT to the address of the
port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only
sio0 through
sio3 (COM1:
through COM4:) can be used; multiport
serial cards will not work. No interrupt setting is
needed.Create a custom kernel configuration file and add
appropriate flags for the serial port you want to use. For
example, if you want to make sio1
(COM2:) the console:device sio1 at isa? port "IO_COM2" tty flags 0x10 irq 3ordevice sio1 at isa? port "IO_COM2" tty flags 0x30 irq 3The console flags for the other serial ports should not be
set.Recompile and install the boot blocks:&prompt.root; cd /sys/boot/i386/boot2
&prompt.root; make
&prompt.root; make installRecompile and install the boot loader:&prompt.root; cd /sys/boot/i386/loader
&prompt.root; make
&prompt.root; make installRebuild and install the kernel.Write the boot blocks to the boot disk with
&man.disklabel.8; and boot from the new kernel.Entering the DDB Debugger from the Serial LineIf you wish to drop into the kernel debugger from the serial
console (useful for remote diagnostics, but also dangerous if you
generate a spurious BREAK on the serial port!) then you should
compile your kernel with the following options:options BREAK_TO_DEBUGGER
options DDBGetting a Login Prompt on the Serial ConsoleWhile this is not required, you may wish to get a
login prompt over the serial line, now that you
can see boot messages and can enter the kernel debugging session
through the serial console. Here is how to do it.Open the file /etc/ttys with an editor
and locate the lines:ttyd0 "/usr/libexec/getty std.9600" unknown off secure
ttyd1 "/usr/libexec/getty std.9600" unknown off secure
ttyd2 "/usr/libexec/getty std.9600" unknown off secure
ttyd3 "/usr/libexec/getty std.9600" unknown off securettyd0 through ttyd3
corresponds to COM1 through
COM4. Change off to
on for the desired port. If you have changed the
speed of the serial port, you need to change
std.9600 to match the current setting, e.g.
std.19200.You may also want to change the terminal type from
unknown to the actual type of your serial
terminal.After editing the file, you must kill -HUP 1
to make this change take effect.Changing Console from the Boot LoaderPrevious sections described how to set up the serial console by
tweaking the boot block. This section shows that you can specify the
console by entering some commands and environment variables in the
boot loader. As the boot loader is invoked as the third stage of the
boot process, after the boot block, the settings in the boot loader
will override the settings in the boot block.Setting Up the Serial ConsoleYou can easily specify the boot loader and the kernel to use the
serial console by writing just one line in
/boot/loader.rc:set console=comconsoleThis will take effect regardless of the settings in the boot
block discussed in the previous section.You had better put the above line as the first line of
/boot/loader.rc so as to see boot messages on
the serial console as early as possible.Likewise, you can specify the internal console as:set console=vidconsoleIf you do not set the boot loader environment variable
console, the boot loader, and subsequently the
kernel, will use whichever console indicated by the
option in the boot block.In versions 3.2 or later, you may specify the console in
/boot/loader.conf.local or
/boot/loader.conf, rather than in
/boot/loader.rc. In this method your
/boot/loader.rc should look like:include /boot/loader.4th
startThen, create /boot/loader.conf.local and
put the following line there.console=comconsoleorconsole=vidconsoleSee &man.loader.conf.5; for more information.At the moment, the boot loader has no option equivalent to the
option in the boot block, and there is no
provision to automatically select the internal console and the
serial console based on the presence of the keyboard.Using Serial Port Other than sio0 for
the ConsoleYou need to recompile the boot loader to use a serial port other
than sio0 for the serial console. Follow the
procedure described in .CaveatsThe idea here is to allow people to set up dedicated servers that
require no graphics hardware or attached keyboards. Unfortunately,
while most systems will let you boot without a keyboard, there
are quite a few that will not let you boot without a graphics adapter.
Machines with AMI BIOSes can be configured to boot with no graphics
adapter installed simply by changing the `graphics adapter' setting in
the CMOS configuration to `Not installed.'However, many machines do not support this option and will refuse
to boot if you have no display hardware in the system. With these
machines, you'll have to leave some kind of graphics card plugged in,
(even if it's just a junky mono board) although you will not have to
attach a monitor into it. You might also try installing an AMI
BIOS.