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 767f4c8e22..0c0f737bf5 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,4538 +1,4540 @@
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, but because of
trademark issues, Sun changed the name. The old term (and yp) is
still often seen and used.NISdomainsIt is a RPC-based client/server system that allows a group
of machines within an NIS domain to share a common set of
configuration files. This permits a system administrator to set
up NIS client systems with only minimal configuration data and
add, remove or modify configuration data from a single
location.Windows NTIt is similar to Windows NT's domain system; although the
internal implementation of the two 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 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 domain covered for the particular zone
filenamed, bind, name servercommon names for the BIND name server package within
FreeBSDresolverresolvera system process through which a
machine queries a 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
DNS
+ zonesexamplesExamples 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 serverName servers usually come in two forms: an authoritative
name server, and a caching nameserver.An authoritative name server is needed when:one wants to serve DNS information to the
world, replying authoritatively to queries.a domain, such as foobardomain.org, is
registered and IP addresses need to be assigned to hostnames
under it.an IP address block requires reverse DNS entries (IP to
hostname).a backup name server, called a slave, must reply to queries
when the primary is down or inaccessible.A caching name server is needed when:a local DNS server may cache and respond more quickly
then querying an outside name server.a reduction in overall network traffic is desired. (DNS
traffic has been measured to account for 5% or more of total
Internet traffic)When one queries for www.freebsd.org, the
resolver usually queries the uplink ISP's name server, and retrieves
the reply. With a local, caching DNS server, the query only has to
be made once to the outside world by the caching DNS server. Every
additional query will not have to look to the outside of the local
network, since the information is cached locally.How it worksIn FreeBSD, the BIND daemon is called
named for obvious reasons.FileDescriptionnamedthe BIND daemonndcname daemon control program/etc/namedbdirectory where BIND zone information resides/etc/namedb/named.confdaemon configuration file
Zone files are usually contained within the
/etc/namedb
directory, and contain the DNS zone information
served by the name server.
Starting BINDBINDstarting
Since BIND is installed by default, configuring it all is
relatively simple.
To ensure the named daemon is started at boot, put the following
modifications in /etc/rc.conf:
named_enable="YES"To start the daemon manually (after configuring it)&prompt.root; ndc startConfiguration filesBINDconfiguration filesmake-localhostBe sure to:
&prompt.root; cd /etc/namedb
&prompt.root; sh make-localhostto properly create the local reverse dns zone file in
/etc/namedb/localhost.rev.
/etc/namedb/named.conf// $FreeBSD$
//
// Refer to the named(8) 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)
- 5
+ 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.ChernLeeContributedinetd Super-ServerOverview&man.inetd.8; is referred to as the Internet
Super-Server because it manages connections for several
daemons. Programs that provide network service are commonly
known as daemons. inetd serves as a
managing server for other daemons. When a connection is
received by inetd, it determines
which daemon the connection is destined for, spawns the
particular daemon and delegates the socket to it. Running one
instance of inetd reduces the overall
system load as compared to running each daemon individually in
stand-alone mode.Primarily, inetd is used to
spawn other daemons, but several trivial protocols are handled
directly, such as chargen,
auth, and
daytime.This section will cover the basics in configuring
inetd through its command-line
options and it's configuration file,
/etc/inetd.conf.Settingsinetd is initialized through
the /etc/rc.conf system. The
inetd_enable option is set to
NO by default, but is often times turned on by
sysinstall with the medium security
profile. Placing:
inetd_enable="YES" or
inetd_enable="NO" into
/etc/rc.conf can enable or disable
inetd starting at boot time.Additionally, different command-line options can be passed
to inetd via the
inetd_flags option.Command-Line Optionsinetd sypnosis:-dTurn on debugging.-lTurn on logging of successful connections.-wTurn on TCP Wrapping for external services. (on by
default)-WTurn on TCP Wrapping for internal services which are
built in to inetd. (on by
default)-c maximumSpecify the default maximum number of simultaneous
invocations of each service; the default is unlimited.
May be overridden on a per-service basis with the
parameter.-C rateSpecify the default maximum number of times a
service can be invoked from a single IP address in one
minute; the default is unlimited. May be overridden on a
per-service basis with the
parameter.-R rateSpecify the maximum number of times a service can be
invoked in one minute; the default is 256. A rate of 0
allows an unlimited number of invocations.-aSpecify one specific IP address to bind to.
Alternatively, a hostname can be specified, in which case
the IPv4 or IPv6 address which corresponds to that
hostname is used. Usually a hostname is specified when
inetd is run inside a
&man.jail.8;, in which case the hostname corresponds to
the &man.jail.8; environment.When hostname specification is used and both IPv4
and IPv6 bindings are desired, one entry with the
appropriate protocol type for each binding is required for
each service in /etc/inetd.conf. For
example, a TCP-based service would need two entries, one
using ``tcp4'' for the protocol and the other using
``tcp6''.-pSpecify an alternate file in which to store the
process ID.These options can be passed to
inetd using the
inetd_flags option in
/etc/rc.conf. By default,
inetd_flags is set to -wW,
which turns on TCP wrapping for
inetd's internal and external
services. For novice users, these parameters usually do not need
to be modified or even entered in
/etc/rc.confAn external service is a daemon outside of
inetd, which is invoked when a
connection is received for it. On the other hand, an internal
service is one that inetd has the
facility of offering within itself.inetd.confConfiguration of inetd is
controlled through the /etc/inetd.conf
file.When a modification is made to
/etc/inetd.conf,
inetd can be forced to re-read its
configuration file by sending a HangUP signal to the
inetd process as shown:Sending inetd a HangUP signal&prompt.root kill -HUP `cat /var/run/inetd.pid`Each line of the configuration file specifies an
individual daemon. Comments in the file are preceded by a
#. The format of
/etc/inetd.conf is as follows:service-name
socket-type
protocol
{wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]
user[:group][/login-class]
server-program
server-program-argumentsAn example entry for the ftpd daemon
using IPv4:ftp stream tcp nowait root /usr/libexec/ftpd ftpd -lservice-nameThis is the service name of the particular daemon.
It must correspond to a service listed in
/etc/services. This determines which
port inetd must listen to. If
a new service is being created, it must be placed in
/etc/services
first.socket-typeEither stream,
dgram, raw, or
seqpacket. stream
must be used for connection-based, TCP daemons, while
dgram is used for daemons utilizing the
UDP transport protocol.protocolOne of the following:ProtocolExplanationtcp, tcp4TCP IPv4udp, udp4UDP IPv4tcp6TCP IPv6udp6UDP IPv6tcp46Both TCP IPv4 and v6udp46Both UDP IPv4 and v6
+
{wait|nowait}[/max-child[/max-connections-per-ip-per-minute]] indicates whether the
daemon invoked from inetd is
able to handle its own socket or not.
socket types must use the wait
option, while stream socket daemons, which are usually
multi-threaded, should use .
usually hands off multiple sockets
to a single daemon, while spawns a
child daemon for each new socket.The maximum number of child daemons
inetd may spawn can be set using
the option. If a limit of ten
instances of a particular daemon is needed, a
/10 would be placed after
.In addition to another
option limiting the maximum connections from a single
place to a particular daemon can be enabled.
does
just this. A value of ten here would limit any particular
IP address connecting to a particular service to ten
attempts per minute. This is useful to prevent
intentional or unintentional resource consumption and
Denial of Service (DoS) attacks to a machine.In this field, or
is mandatory.
and
are
optional.A stream-type multi-threaded daemon without any
or
limits
would simply be: nowaitThe same daemon with a maximum limit of ten daemons
would read: nowait/10Additionally, the same setup with a limit of twenty
connections per IP address per minute and a maximum
total limit of ten child daemons would read:
nowait/10/20These options are all utilized by the default
settings of the fingerd daemon,
as seen here:finger stream tcp nowait/3/10 nobody /usr/libexec/fingerd fingerd -suserThe user is the username that the particular daemon
should run as. Most commonly, daemons run as the
root user. For security purposes, it is
common to find some servers running as the
daemon user, or the least privileged
nobody user.server-programThe full path of the daemon to be executed when a
connection is received. If the daemon is a service
provided by inetd internally,
then should be
used.server-program-argumentsThis works in conjunction with
by specifying the
arguments, starting with argv[0], passed to the daemon on
invocation. If mydaemon -d is
the command line, mydaemon -d would be
the value of .
Again, if the daemon is an internal service, use
here.SecurityDepending on the security profile chosen at install, many
of inetd's daemons may be enabled by
default. If there is no apparent need for a particular daemon,
disable it! Place a # in front of the daemon in
question, and send a hangup signal
to inetd.
Some daemons, such as fingerd, may
not be desired at all because they provide an attacker with too
much information.Some daemons are not security-concious and have long, or
non-existent timeouts for connection attempts. This allows an
attacker to slowly send connections to a particular daemon, thus
saturating available resources. It may be a good idea to place
and
limitations on certain daemons.By default, TCP wrapping is turned on. Consult the
&man.hosts.access.5; man page for more information on placing
TCP restrictions on various inetd
- invoked daemons.
+ invoked daemons.Miscellaneousdaytime,
time,
echo,
discard,
chargen, and
auth are all internally provided
services of inetd.The auth service provides identity
(ident, identd) network services, and is configurable to a certain
degree.Consult the &man.inetd.8; man page for more in-depth
information.
diff --git a/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml b/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml
index 242d89f43c..e242a377f7 100644
--- a/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml
@@ -1,368 +1,368 @@
MosesMooreContributedSoundSynopsisFreeBSD supports a wide variety of sound cards, allowing you
to enjoy high fidelity output from your computer. This includes
the ability to record and playback audio in the MPEG Audio Layer
3 (MP3), WAV, and Ogg Vorbis formats as well as many other
formats. The FreeBSD Ports Collection also contains
applications allowing you to edit your recorded audio, add sound
effects, and control attached MIDI devices.After reading this chapter you will know:How to locate your sound card.How to configure your system so that your sound card is
recognized.Methods to test that your card is working using
sample applications.How to troubleshoot your sound setup.
- Before reading this chapter you should:
+ Before reading this chapter you should:Know how to configure and install a new kernel ()Locating the Correct DevicePCIISAsound cardsBefore you begin, you should know the model of the card you
have, the chip it uses, and whether it is a PCI or ISA card.
FreeBSD supports a wide variety of both PCI and ISA cards. If you
do not see your card in the following list, check the &man.pcm.4;
manual page. This is not a complete list; however, it does list
some of the most common cards.Crystal 4237, 4236, 4232, 4231Yamaha OPL-SAxOPTi931Ensoniq AudioPCI 1370/1371ESS Solo-1/1ENeoMagic 256AV/ZXSound Blaster Pro, 16, 32, AWE64, AWE128, LiveCreative ViBRA16Advanced Asound 100, 110, and Logic ALS120ES 1868, 1869, 1879, 1888Gravis UltraSoundAureal Vortex 1 or 2kernelconfigurationThe driver you use in your kernel depends on the kind of card
you have. The sections below provide more information and what
you will need to add to your kernel
configuration.Creative, Advance, and ESS Sound CardsIf you have one of the above cards, you will need to
adddevice pcmto your kernel. If you have a PnP ISA card, you will also
need to adddevice sbcto your kernel. For a non-PnP ISA card, adddevice pcmanddevice sbc0 at isa? port0x220 irq 5 drq 1 flags 0x15to your kernel. Those are the default settings. You may
need to change the IRQ, etc. See the &man.sbc.4; man page for
more information.The Sound Blaster Live is not supported under FreeBSD 4.0
without a patch, which this document will not cover. It is
recommended that you update to the latest -STABLE before
trying to use this card.Gravis UltraSound CardsFor a PnP ISA card, you will need to adddevice pcmanddevice guscto your kernel. If you have a non-PnP ISA card, you will
need to adddevice pcmanddevice gus0 at isa? port 0x220 irq 5 drq 1 flags 0x13to your kernel. You may need to change the IRQ, etc. See
the &man.gusc.4; man page for more information.Crystal Sound CardsFor Crystal cards, you will need bothdevice pcmanddevice csain your kernel.Generic SupportFor PnP ISA or PCI cards, you will need to adddevice pcmto your kernel configuration. If you have a non-PnP ISA
sound card that does not have a bridge driver, you will need
to adddevice pcm0 at isa? irq 10 drq 1 flags 0x0to your kernel configuration. You may need to change the
IRQ, etc., to match your hardware configuration.Recompiling the KernelAfter adding the driver(s) you need to your kernel
configuration, you will need to recompile your kernel. Please see
of the handbook for
more information.Creating and Testing the Device Nodesdevice nodesAfter you reboot, log in and run cat
/dev/sndstat. You should see output similar to the
following:FreeBSD Audio Driver (newpcm) Sep 21 2000 18:29:53
Installed devices:
pcm0: <Aureal Vortex 8830> at memory 0xfeb40000 irq 5 (4p/1r +channels duplex)If you see an error message, something went wrong earlier. If
that happens, go through your kernel configuration file again and
make sure you chose the correct device.If it reported no errors and returned
pcm0, su to
root and do the following:&prompt.root; cd /dev
&prompt.root; sh MAKEDEV snd0If it reported no errors and returned
pcm1, su to
root and do the following:&prompt.root; cd /dev
&prompt.root; sh MAKEDEV snd1Please note that either of the above commands will
not create a
/dev/snd device! Instead it creates a
group of device nodes including:DeviceDescription/dev/audioSPARC-compatible audio device/dev/dspDigitized voice device/dev/dspWLike /dev/dsp, but 16 bits
per sample/dev/midiRaw midi access device/dev/mixerControl port mixer device/dev/musicLevel 2 sequencer interface/dev/sequencerSequencer device/dev/pssProgrammable device interfaceIf all goes well, you should now have a functioning sound
card. If you do not, see the next section.Common Problemsdevice nodeI get an unsupported subdevice XX error!One or more of the device nodes wasn't created
correctly. Repeat the steps above.I/O portI get a sb_dspwr(XX) timed out error!The I/O port is not set correctly.IRQI get a bad irq XX error!The IRQ is set incorrectly. Make sure that the set IRQ
and the sound IRQ are the same.I get a xxx: gus pcm not attached, out of
memory
error. What causes that?If this happens, it is because there is not enough
available memory to use the device.
diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
index 7bb54e111a..39ed3aaae7 100644
--- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
@@ -1,2585 +1,2586 @@
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 communicationsWhen 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
will need 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.CablesThere are several different kinds of serial cables. The
two most common types for our purposes are null-modem cables
and standard ("straight") RS-232 cables. The documentation
for your hardware should describe the type of cable
required.Null-modem cablesnull-modem cableA 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, you can 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/ttydN
where N 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/cuaaN.
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.If you have connected a terminal to the first serial port
(COM1 in MS-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.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, 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.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 detailed information on
configuring your kernel, 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/ttydN (dial-in)
and /dev/cuaaN
(call-out) devices. FreeBSD also provides initialization devices
(/dev/ttyidN and
/dev/cuai0N) and
locking devices
(/dev/ttyldN and
/dev/cual0N). 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 FilesFreeBSD 5.0 includes the devfs
filesystem which automatically creates device nodes as
needed. If you are running a version of FreeBSD with
devfs enabled then you can safely skip
this section.A 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/ttydN device
special files, but also creates the
/dev/cuaaN,
/dev/cuaiaN,
/dev/cualaN,
/dev/ttyldN,
and
/dev/ttyidN
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 ttydN (or
cuaaN) 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 a 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.Adding an Entry to /etc/ttysThe /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 also 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
to one of those ports, you do not need to add another entry.Adding Terminal Entries to
/etc/ttysSuppose we would like to connect two terminals to the
system: a Wyse-50 and an 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). The corresponding
entries in the /etc/ttys file would
look like this:ttyd1 "/usr/libexec/getty std.38400" wy50 on insecure
ttyd5 "/usr/libexec/getty std.19200" vt100 on insecure
The first field normally specifies the name of
the terminal special file as it is found in
/dev.The second field is the command to execute for
this line, which is usually &man.getty.8;.
getty initializes and opens the
line, sets the speed, prompts for a user name and then
executes the &man.login.1; program.The getty program accepts 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.The third field is the type of terminal usually
connected to that tty line. For dial-up ports,
unknown or
dialup is typically used in this
field since users may dial up with practically any
type of terminal or software. For hardwired
terminals, the terminal type does not change, so you
can put a real terminal type from the &man.termcap.5;
database file in this field.For our example, the Wyse-50 uses the real
terminal type while the 286 PC running
Procomm will be set to
emulate at VT-100. The fourth field specifies if the port should be
enabled. Putting on here will have
the init process start the program
in the second field, getty. If you
put off in this field, there will
be no getty, and hence no logins on
the port.The final field is used to specify whether the
port is secure. Marking a port as secure means that
you trust it enough to allow 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 a
similar mechanism 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 su
if you need superuser privileges.
-
+
+
Force 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.Troubleshooting 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 .
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.
+ /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 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
ttydN 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/ttydN, 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.
diff --git a/en_US.ISO8859-1/books/handbook/sound/chapter.sgml b/en_US.ISO8859-1/books/handbook/sound/chapter.sgml
index 242d89f43c..e242a377f7 100644
--- a/en_US.ISO8859-1/books/handbook/sound/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/sound/chapter.sgml
@@ -1,368 +1,368 @@
MosesMooreContributedSoundSynopsisFreeBSD supports a wide variety of sound cards, allowing you
to enjoy high fidelity output from your computer. This includes
the ability to record and playback audio in the MPEG Audio Layer
3 (MP3), WAV, and Ogg Vorbis formats as well as many other
formats. The FreeBSD Ports Collection also contains
applications allowing you to edit your recorded audio, add sound
effects, and control attached MIDI devices.After reading this chapter you will know:How to locate your sound card.How to configure your system so that your sound card is
recognized.Methods to test that your card is working using
sample applications.How to troubleshoot your sound setup.
- Before reading this chapter you should:
+ Before reading this chapter you should:Know how to configure and install a new kernel ()Locating the Correct DevicePCIISAsound cardsBefore you begin, you should know the model of the card you
have, the chip it uses, and whether it is a PCI or ISA card.
FreeBSD supports a wide variety of both PCI and ISA cards. If you
do not see your card in the following list, check the &man.pcm.4;
manual page. This is not a complete list; however, it does list
some of the most common cards.Crystal 4237, 4236, 4232, 4231Yamaha OPL-SAxOPTi931Ensoniq AudioPCI 1370/1371ESS Solo-1/1ENeoMagic 256AV/ZXSound Blaster Pro, 16, 32, AWE64, AWE128, LiveCreative ViBRA16Advanced Asound 100, 110, and Logic ALS120ES 1868, 1869, 1879, 1888Gravis UltraSoundAureal Vortex 1 or 2kernelconfigurationThe driver you use in your kernel depends on the kind of card
you have. The sections below provide more information and what
you will need to add to your kernel
configuration.Creative, Advance, and ESS Sound CardsIf you have one of the above cards, you will need to
adddevice pcmto your kernel. If you have a PnP ISA card, you will also
need to adddevice sbcto your kernel. For a non-PnP ISA card, adddevice pcmanddevice sbc0 at isa? port0x220 irq 5 drq 1 flags 0x15to your kernel. Those are the default settings. You may
need to change the IRQ, etc. See the &man.sbc.4; man page for
more information.The Sound Blaster Live is not supported under FreeBSD 4.0
without a patch, which this document will not cover. It is
recommended that you update to the latest -STABLE before
trying to use this card.Gravis UltraSound CardsFor a PnP ISA card, you will need to adddevice pcmanddevice guscto your kernel. If you have a non-PnP ISA card, you will
need to adddevice pcmanddevice gus0 at isa? port 0x220 irq 5 drq 1 flags 0x13to your kernel. You may need to change the IRQ, etc. See
the &man.gusc.4; man page for more information.Crystal Sound CardsFor Crystal cards, you will need bothdevice pcmanddevice csain your kernel.Generic SupportFor PnP ISA or PCI cards, you will need to adddevice pcmto your kernel configuration. If you have a non-PnP ISA
sound card that does not have a bridge driver, you will need
to adddevice pcm0 at isa? irq 10 drq 1 flags 0x0to your kernel configuration. You may need to change the
IRQ, etc., to match your hardware configuration.Recompiling the KernelAfter adding the driver(s) you need to your kernel
configuration, you will need to recompile your kernel. Please see
of the handbook for
more information.Creating and Testing the Device Nodesdevice nodesAfter you reboot, log in and run cat
/dev/sndstat. You should see output similar to the
following:FreeBSD Audio Driver (newpcm) Sep 21 2000 18:29:53
Installed devices:
pcm0: <Aureal Vortex 8830> at memory 0xfeb40000 irq 5 (4p/1r +channels duplex)If you see an error message, something went wrong earlier. If
that happens, go through your kernel configuration file again and
make sure you chose the correct device.If it reported no errors and returned
pcm0, su to
root and do the following:&prompt.root; cd /dev
&prompt.root; sh MAKEDEV snd0If it reported no errors and returned
pcm1, su to
root and do the following:&prompt.root; cd /dev
&prompt.root; sh MAKEDEV snd1Please note that either of the above commands will
not create a
/dev/snd device! Instead it creates a
group of device nodes including:DeviceDescription/dev/audioSPARC-compatible audio device/dev/dspDigitized voice device/dev/dspWLike /dev/dsp, but 16 bits
per sample/dev/midiRaw midi access device/dev/mixerControl port mixer device/dev/musicLevel 2 sequencer interface/dev/sequencerSequencer device/dev/pssProgrammable device interfaceIf all goes well, you should now have a functioning sound
card. If you do not, see the next section.Common Problemsdevice nodeI get an unsupported subdevice XX error!One or more of the device nodes wasn't created
correctly. Repeat the steps above.I/O portI get a sb_dspwr(XX) timed out error!The I/O port is not set correctly.IRQI get a bad irq XX error!The IRQ is set incorrectly. Make sure that the set IRQ
and the sound IRQ are the same.I get a xxx: gus pcm not attached, out of
memory
error. What causes that?If this happens, it is because there is not enough
available memory to use the device.
diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
index f056c18c12..069f1a356f 100644
--- a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
@@ -1,1139 +1,1139 @@
The X Window SystemSynopsisFreeBSD uses XFree86 to provide users with a powerful
graphical user interface. XFree86 is a open-source
implementation of the X Window System. The following chapter
will cover installation and configuration of XFree86 on your
FreeBSD system. For more information on X11 and to see whether
your video card is supported, check the XFree86 web site.After reading this chapter you will know:How to install and configure XFree86.How to install and use different window managersHow to use TrueType fonts in XFree86How to setup your system for graphical logins (XDM).
- Before reading this chapter you should:
+ Before reading this chapter you should:Know how to install additional third-party
software ()Installing XFree86XFree86 is available as a port
and as a package, making it easy to install. You can also
download the binaries directly from the XFree86 organization and
install them by hand, following the instructions provided by the
XFree86 group.Your only decision is which version of XFree86 to run.
XFree86 3.X is the maintenance branch of XFree86 development.
It's very stable, and it supports a huge number of graphics
cards. However, no new development is happening there. XFree86
4.X is a redesign of XFree86. As well as introducing many new
features (including much better support for fonts and
anti-aliasing), XFree86 4.X supports slightly fewer graphics
cards.If your card is supported we recommend you run 4.X. If it
is not then run 3.X.The rest of this chapter will explain how to configure
XFree86, and suggest various programs for X that you might want
to try.ChristopherShumwayXFree86 ConfigurationIntroductionThis chapter will introduce the steps necessary to install
and configure the XFree86
X Windows System under FreeBSD.
Once the server is installed and configured properly. The user
can read to setup their desktop
environment.XFree86 4.XXFree86Before You StartBefore the user is to start configuration of
XFree86-4, the the following
information will need to be known about the target
system:Monitor specificationsVideo Adapter chipsetVideo Adapter memoryhorizontal scan ratevertical scan rateThe specifications for the target system's monitor are
used by XFree86 to determine the
resolution and refresh rate to run at. These specifications can
usually be obtained from the documentation that came with the
target system's monitor or from the manufacturer's website.
There are two ranges of numbers that are needed, the horizontal
scan rate and the vertical synchronization rate.The video adapter's chipset defines what driver module
XFree86 uses to talk to the graphics
hardware. With most chipsets, this can be automatically
determined, but it is still useful to know in case the automatic
detection doesn't work correctly.Video memory on the graphic adapter determines the
resolution and color depth the target system can run at. This
is important to know so the user knows the limitations of the
target system.Installing XFree86 4.X softwareXFree86 4 can be installed
using the FreeBSD ports system or using &man.pkg.add.1;. If the
user is building XFree86-4 from
source and has USA_RESIDENT set in
/etc/make.conf, the user may first have to
fetch Wraphelp.c if XDM-AUTHORIZATION-1
support is desired. This file is to be placed in the port's
files/ sub-directory before the port is
built.Configuring XFree86 4.XConfiguration of XFree86 4.X is
a several step process. The first step is to build an initial
configuration file with the configure option to
XFree86. As the super user, simply
run:&prompt.root; XFree86 -configureThis will generate a skeleton
XFree86 configuration file in the
current working directory called
XF86Config.new. The
XFree86 program will attempt to probe
the graphics hardware on the system and will write a
configuration file to load the proper drivers for the detected
hardware on the target system.The next step is to test the currently existing
configuration to verify that XFree86
can work with the graphics
hardware on the target system. To preform this task, the user
needs to run:&prompt.root; XFree86 -xf86config XF86Config.newIf the user is presented with a black and grey grid and an
X mouse cursor, then the configuration was successful. To exit
the test, just press ctrl, alt and backspace simultaneously.XFree86 4 TuningNext, the user needs to tune the
XF86Config.new configuration file to their
personal taste. Open up the file in a text editor such as
&man.emacs.1; or &man.ee.1;. The first thing the user will want to
do is add the frequencies for the target system's monitor.
These are usually expressed as a horizontal and vertical
synchronization rate. These values are added to the
XF86Config.new file under the "Monitor"
section as such:Section "Monitor"
Identifier "Monitor0"
VendorName "Monitor Vendor"
ModelName "Monitor Model"
Horizsync 30-107
VertRefresh 48-120
EndSectionThe Horizsync and
VertRefresh keywords may not exist in the
user's configuration file. If they do not, they need to be
added, with the correct horizontal synchronization rate placed
after the Horizsync keyword and the vertical
synchronization rate after the VertRefresh
keyword. In the example above the target monitor's rates where
entered.XF86ConfigWhile the XF86Config.new
configuration file is still open in an editor, next the user
needs to select what the default resolution and color depth is
desired. This is defined in the Screen
section.Section "Screen"
Identifier "Screen0"
Device "Card0"
Monitor "Monitor0"
DefaultColorDepth 24
SubSection "Display"
Depth 24
Modes "1024x768"
EndSubSection
EndSectionThe DefaultColorDepth keyword describes
the color depth the user wishes to run at by default. This can
be overridden with the -bpp command line
switch to XFree861. The Modes keyword describes the
resolution the user wishes to run at for the given color depth.
In the example above, the default color depth is twenty four
bits per pixel. At this color depth, the accepted resolution is
one thousand twenty four pixels by seven hundred and sixty eight
pixels.If a user wants to run at a resolution of one thousand
twenty four pixels by seven hundred sixty eight pixels at twenty
four bits per pixel, then the user needs to add the
DefaultColorDepth keyword with the value of
twenty four, and add to the "Display"
subsection with the desired Depth the Modes keyword with the
resolution the user wishes to run at. Note that only VESA
standard modes are supported as defined by the target system's
graphics hardware.Finally, the user can write out the configuration file and
test it using the test mode given above. If all is well, then
the configuration file needs to be installed in a common
location where XFree861 can source it in the future.
This is typically /etc/X11/XF86Config or
/usr/X11R6/etc/X11/XF86Config.&prompt.root; cp XF86Config.new /etc/X11/XF86ConfigOnce the configuration file has been placed in a common
location, XFree86 can then be used through &man.xdm.1;. In
order to use startx1 the user will have to install
the X11/wrapper port.Advanced Configuration TopicsConfiguration with Intel i810 graphics chipsetsIntel i810 graphic chipsetConfiguration with Intel i810 integrated chipsets
requires the agpgart AGP programming interface for
XFree86 to be able to drive the
card. To enable the agpgart programming
interface, the agp.ko kernel loadable
module needs to be loaded into the kernel with
&man.kldload.8;. This can be done automatically with the
&man.loader.8;. Simply add this line to
/boot/loader.conf to have the loader load
agp.ko at boot time:agp_load="YES"Next, a device node needs to be created for the
programming interface. To create the AGP device node, run
&man.MAKEDEV.8; in the /dev directory as
such:&prompt.root; cd /dev
&prompt.root; sh MAKEDEV agpgartThis will allow the user to configure the graphics
hardware as any other graphics board.MurrayStokelySection on fontsUsing Fonts in XFree86Type1 FontsThe default fonts that ship with
XFree86 are less than ideal for typical
desktop publishing applications. Large presentation fonts show up
jagged and unprofessional looking and small fonts in Netscape are
almost completely unintelligible. However, there are several
free, high quality Type1 (PostScript) fonts available which
can be readily used
with XFree86, either version 3.X or
version 4.X. For instance, the URW font collection
(x11-fonts/urwfonts) includes
high quality versions of standard type1 fonts (Times Roman,
Helvetica, Palatino and others). The Freefont collection
(x11-fonts/freefont) includes
many more fonts, but most of them are intended for use in
graphics software such as the Gimp, and are not complete
enough to serve as screen fonts. In addition,
XFree86 can be configured to use
TrueType fonts with a minimum of effort: see the
section on TrueType fonts later.To install the above Type1 font collections from the ports
collection you can run the following commands.&prompt.root; cd /usr/ports/x11-fonts/urwfonts
&prompt.root; make install cleanAnd likewise with the freefont or other collections. To tell the X server
that these fonts exist, you can add an appropriate line
to your XF86Config file (in
/etc/ for XFree86
version 3, or in /etc/X11/ for version 4),
which reads:FontPath "/usr/X11R6/lib/X11/fonts/URW/"Alternatively, at the command line in your X session you can
write:&prompt.user; xset fp+ /usr/X11R6/lib/X11/fonts/URW
&prompt.user; xset fp rehashThis will work but will be lost when you log out from this
session, unless you add it to your startup file
(~/.xinitrc for a normal
startx session,
or ~/.xsession when logging in through a
graphical login manager like XDM).
A third way is to use the new
XftConfig file: see the
section on anti-aliasing, later.
TrueType FontsXFree86 4.0 has built in support
for rendering TrueType fonts. There are two different modules
that can enable this functionality. The "freetype" module is used
in this example because it is more consistent with the other font
rendering back-ends. To enable the freetype module just add the
following line to the module section of your
/etc/X11/XF86Config file.Load "freetype"For XFree86 3.3.X you will need
to run a separate TrueType font
server. Xfstt is commonly used for
this purpose. To install x11-servers/Xfstt on
your FreeBSD system simply install the port from
/usr/ports/x11-servers/XfsttYou should now make a directory for your TrueType fonts
(e.g. /usr/X11R6/lib/X11/fonts/TrueType)
and copy all of your TrueType fonts into this directory. Keep in
mind that you cannot take TrueType fonts directly from a
Macintosh; they must be in Unix/DOS/Windows format for use by
XFree86. Once you have copied the
files into this directory you need to use
ttmkfdir to create a
fonts.dir file so that the X font renderer
knows that you've installed these new files. There is a FreeBSD
port for x11-fonts/ttmkfdir in
/usr/ports/x11-fonts/ttmkfdir.&prompt.root; cd /usr/X11R6/lib/X11/fonts/TrueType
&prompt.root; ttmkfdir > fonts.dirNow you need to add your TrueType directory to your fonts
path. This is just the same as described above for Type1 fonts, that is, use
&prompt.user; xset fp+ /usr/X11R6/lib/X11/fonts/TrueType
&prompt.user; xset fp rehash
or add a line to the
XF86Config file.That's it. Now Netscape,
Gimp,
StarOffice, and all of your other X
applications should now recognize your installed TrueType
fonts. Extremely small fonts (as with text in a high resolution
display on a web page) and extremely large fonts (within
StarOffice) will look much better
now.Anti-Aliasing your fontsStarting with version 4.0.2, XFree86
supports anti-aliased
fonts. Currently, most software has not been updated to take
advantage of this new functionality. However, Qt (the toolkit
for the KDE desktop) does; so if you
are running XFree86 4.0.2
(or higher), Qt 2.3 (or higher) and KDE,
all your KDE/Qt applications can be made to use anti-aliased
fonts.To configure anti-aliasing, you need to create (or edit, if
it already exists) the file
/usr/X11R6/lib/X11/XftConfig. Several
advanced things can be done with this file; this section
describes only the simplest possibilities.First, you need to tell the X server about the fonts which you
want anti-aliased. To do that, for each font directory you have
a line, which looks like this:dir "/usr/X11R6/lib/X11/Type1"And likewise for the other font directories (URW, truetype, etc)
containing fonts you'd like anti-aliased. Anti-aliasing makes
sense only for scalable fonts (basically, Type1 and TrueType) so
don't include bitmap font directories here. The
directories which you included here can now be commented out
of your XF86Config file.Next, you may not want to anti-alias normal-sized text.
(Antialiasing makes borders slightly fuzzy, which makes very
small text more readable and removes "staircases" from large text,
but can cause eyestrain if applied to normal text.) To exclude
point sizes between 9 and 13 from anti-aliasing, include these
lines:match
any size > 8
any size < 14
edit
antialias = false;You may also find that the spacing for some monospaced fonts
gets messed up when you turn on anti-aliasing. This seems to
be an issue with KDE, in particular.
One possible fix for this
is to force the spacing for such fonts to be 100: add the
following lines:match any family == "fixed" edit family =+ "mono";
match any family == "console" edit family =+ "mono";(this aliases the other common names for fixed fonts as "mono"),
and then add:match any family == "mono" edit spacing = 100;Supposing you want to use the
Lucidux fonts whenever
monospaced fonts are required (these look nice, and don't seem
to suffer from the spacing problem), you could replace that last
line with these:match any family == "mono" edit family += "LuciduxMono";
match any family == "Lucidux Mono" edit family += "LuciduxMono";
match any family == "LuciduxMono" edit family =+ "Lucidux Mono";(the last lines alias different equivalent family names).Finally, you want to allow users to add commands to this
file, via their personal .xftconfig
files. To do this, add a last line:includeif "~/.xftconfig"That's all; anti-aliasing should be enabled the next
time you start the X server. However, note that your programs must
know how to take advantage of it. At the present time, the toolkit
Qt does, so the entire KDE environment
can use anti-aliased fonts
(see on
KDE for
details); there are patches for gtk+ to do the same,
so if compiled against such a patched gtk+, the GNOME environment
and Mozilla can also use anti-aliased fonts.Anti-aliasing is still new to FreeBSD and
XFree86;
configuring it should get easier with time, and it will soon be
supported by many more applications.SethKingsleySection on XDMThe X Display ManagerOverviewThe X Display Manager (XDM) is
an optional part of the X Window System that is used for login
session management. This is useful for several types of
situations, including minimal X Terminals (see
), desktops, and large network display
servers. Since the X Window System is network and protocol
independent, there are a wide variety of possible configurations
for running X clients and servers on different machines
connected by a network. XDM provides
a graphical interface for choosing which display server to
connect to, and entering authorization information such as a
login and password combination.You may think of XDM as
providing the same functionality to the user as the
&man.getty.8; utility (see for
details). That is, it performs system logins to the display
being connected to and then runs a session manager on behalf of
the user (usually an X window
manager). XDM then waits for this
program to exit, signaling that the user is done and should be
logged out of the display. At this point,
XDM can display the login and display
chooser screens for the next user to login.Using XDMThe XDM daemon program is
located in /usr/X11R6/bin/xdm. You can run
this program at any time as root and it will start managing the
X display on the local machine. If you want
XDM to run in the background every
time the machine boots up, a convenient way to do this is by
adding an entry to /etc/ttys. For more
information about the format and usage of this file, see . There is a line in the default
/etc/ttys file for running the
XDM daemon on a virtual terminal:
ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure
By default this entry is disabled, and in order to enable it you
will need to change field 5 from off to
on and then restart &man.init.8; using the
directions in . The first field, the
name of the terminal this program will manage, is
ttyv8. This means that XDM
will start running on the 9th virtual terminal.Configuring XDMThe XDM configuration directory
is located in /usr/X11R6/lib/X11/xdm. In
this directory you will see several files used to change the
behavior and appearance of
XDM. Typically you will find these
files:FileDescriptionXaccessClient authorization ruleset.XresourcesDefault X resource values.XserversList of remote and local displays to manage.XsessionDefault session script for logins.Xsetup_*xdm-configGlobal configuration for all displays running on
this machine.xdm-errorsErrors generated by the server program.xdm-pidThe process ID of the currently running XDM.Also in this directory are a few scripts and programs used
to setup the desktop when XDM is
running. In the next few sections I will briefly describe the
purpose of each of these files. The exact syntax and usage of
all of these files is described in &man.xdm.1;The default configuration is a simple rectangular login
window with the hostname of the machine displayed at the top in
a large font and Login: and
Password: prompts below. This is a good starting
point if you are planning to design your own look and feel for
the XDM screens.XaccessThe protocol for connecting to
XDM controlled displays is called
the X Display Manager Connection Protocol (XDMCP). This file
is basically just a ruleset for controlling XDMCP connections
from remote machines. By default, it allows any client to
connect, but you will see this will not matter because the
default xdm-config file does not listen
for remote connections.XresourcesThis is an application-defaults file for the display
chooser and the login screens. This is where you can customize
the appearance of the login program. The format is identical
to the app-defaults file described in the XFree86
documentation.XserversThis is a list of the remote displays the chooser should
provide as choices.XsessionThis is the default session script for
XDM to run after a user has logged
in. Normally each user will have a customized session script
in ~/.xsessionrc that overrides this
script.Xsetup_*These files contain scripts that will be run automatically
before displaying the chooser or login interfaces. There is a
script for each display being used, named
Xsetup_followed by the local display
number (for instance Xsetup_0). Typically
these scripts will run one or two programs in the background
such as xconsole.xdm-configThis file contains settings in the form of app-defaults
that are applicable to every display that this installation
manages.xdm-errorsThis file contains the output of the X servers that
XDM is trying to run. If a display
that XDM is trying to start hangs
for some reason, this is a good place to look for error
messages. These messages are also written to the user's
~/.xsession-errors file on a per-session
basisRunning A Network Display ServerIn order for other clients to connect to your display
server, you will need to edit the access control rules, and
enable the connection listener. By default these are set to
conservative values, which is a good decision security-wise. To
get XDM to listen for connections
first comment out a line in the xdm-config
file:
! SECURITY: do not listen for XDMCP or Chooser requests
! Comment out this line if you want to manage X terminals with xdm
DisplayManager.requestPort: 0
and then restart XDM. Remember that
comments in app-defaults files begin with a !
character, not a #. After this, you may need to
put more strict access controls in place. Look at the example
entries in Xaccess file, and refer to the
&man.xdm.1; manual page.Replacements for XDMSeveral replacements for the default
XDM program exist. One of them,
KDM (bundled with
KDE) is described in a later section. Apart from various
visual improvements and cosmetic frills, it can be easily
configured to let users choose their window manager of choice
at the time they log in.Desktop EnvironmentsWritten by &a.logo;, June 2001This section describes the different desktop environments
available for X-Windows on FreeBSD. For our purposes a "desktop
environment" will mean anything ranging from a simple window
manager, to a complete suite of desktop applications such as
KDE or GNOME.
GNOMEAbout GNOMEGNOME is a user-friendly
desktop environment that enables users to easily use and
configure their computers. GNOME
includes a panel (for starting applications and displaying
status), a desktop (where data and applications can be
placed), a set of standard desktop tools and applications, and
a set of conventions that make it easy for applications to
cooperate and be consistent with each other. Users of other
operating systems or environments should feel right at home
using the powerful graphics-driven environment that
GNOME provides.Installing GNOMETo install GNOME from the network,
simply type:&prompt.root; pkg_add -r gnomeIf you would rather build
GNOME from source, then use the
ports tree:&prompt.root; cd /usr/ports/x11/gnome
&prompt.root; make install cleanOnce GNOME is installed, we
must have the X server start GNOME
instead of a default window manager. If you have already
customized your .xinitrc file then you
should simply replace the line that starts your current window
manager with one that starts
/usr/X11R6/bin/gnome-wm instead. If you
haven't added anything special to your configuration file,
then it is enough to simply type:&prompt.root; echo "/usr/X11R6/bin/gnome-wm" > ~/.xinitrcThat's it. Type startx and you will be in the
GNOME desktop environment.If you're running a display manager like
XDM, this will not work. Instead,
you should create an executable .xsession
file with the same command in it. To do this, edit your file
(if you already have one) and replace the existing
window manager command with
/usr/X11R6/bin/gnome-wm; or else,&prompt.root; echo "#!/bin/sh" > ~/.xsession
&prompt.root; echo "/usr/X11R6/bin/gnome-wm" >> ~/.xsession
&prompt.root; chmod +x ~/.xsessionAnother option is to configure your display manager to
allow choosing the window manager at login time; the section on
KDE2 details
explains how to do this for kdm, the
display manager of KDE.KDE2About KDE2KDE is an easy to use
contemporary desktop environment. Some of the things that
KDE brings to the user are:A beautiful contemporary desktopA desktop exhibiting complete network transparencyAn integrated help system allowing for convenient,
consistent access to help on the use of the
KDE desktop and its
applicationsConsistent look and feel of all
KDE applicationsStandardized menu and toolbars, keybindings, color-schemes, etc.Internationalization: KDE
is available in more than 40 languagesCentralized consisted dialog driven desktop configurationA great number of useful
KDE applicationsKDE has an office application
suite based on KDE's
KParts technology consisting
of a spread-sheet, a presentation application, an organizer, a
news client and more. KDE is also
comes with a web browser called
Konqeuror, which represents already
a solid competitor to other existing web browsers on Unix
systems. More information on KDE
can be found on the KDE
websiteInstalling KDE2At the time of writing, a package for kde2 doesn't
exist yet. No problem! The ports tree hides all the
complexity of building a package from source. To install
KDE2, do this :&prompt.root; cd /usr/ports/x11/kde2
&prompt.root; make install cleanThis command will fetch all the necessary files from the
Internet, configure and compile KDE2,
install the applications, and then clean up after itself.Now you're going to have to tell the X server to launch
KDE2 instead of a default window manager.
Do this by typing this:&prompt.root; echo "/usr/X11R6/bin/startkde" > ~/.xinitrcNow, whenever you go into X-Windows,
KDE2 will be your
desktop. (Note: this will not work if you're logging in via
a display manager like xdm. In that
case you have two options: create an
.xsession file as described in the
section on GNOME, but
with the /usr/X11R6/bin/startkde
command instead of the gnome-wm
command; or, configure your display manager to allow
choosing a desktop at login time. Below it is explained how
to do this for kdm,
KDE's display manager.)More details on KDE2Now that KDE2 is installed on
your system, you'll find that you can learn a lot from its
help pages, or just by pointing and clicking at various menus.
Windows or Mac users will feel quite at home.The best reference for KDE is
the on-line documentation. KDE
comes with its own web browser,
Konqueror, dozens of useful
applications, and extensive documentation. This section only
discusses somewhat technical things which are difficult to
learn just by random exploration.The KDE display managerIf you're an administrator on a multi-user system, you
may like to have a graphical login screen to welcome users.
You can use xdm, as described
earlier. However, KDE includes an
alternative, KDM, which is designed
to look more attractive and include more login-time options.
In particular, users can easily choose (via a menu) which
desktop environment (KDE2,
GNOME, or something else) to run
after logging on. If you're slightly adventurous and you want
this added flexibility and visual appeal, read on.To begin with, run the KDE2
control panel, kcontrol, as
root. Note: it is generally considered
unsafe to run your entire X environment as
root. Instead, run your window manager
as a normal user, open a terminal window (such as
xterm or KDE's
konsole, become root
with su (you need to be in the
wheel
group in /etc/group for this), and then
type kcontrol. Click on the icon on the left marked "System", then on
"Login manager". On the right you'll see various configurable
options, which the KDE manual will
explain in greater detail. Click on "sessions" on the right.
Depending on what window managers or desktop environments you
have currently installed, you can type their names in "New
type" and add them. (These are just labels so far, not
commands, so you can write KDE and
GNOME rather than
startkde or gnome-wm.)
Include a label failsafe. Play with the other menus as you like (those are mainly
cosmetic and self-explanatory). When you're done, click on
"Apply" at the bottom, and quit the control center. To make sure kdm understands
what your above labels (KDE,
GNOME etc) mean, you need to edit
some more files: the same ones used by xdm. In your terminal window, as root,
edit the file
/usr/X11R6/lib/X11/xdm/Xsession. You
will come across a section in the middle looking like this (by
default):case $# in
1)
case $1 in
failsafe)
exec xterm -geometry 80x24-0-0
;;
esac
esacYou will need to add a few lines to this section.
Assuming the labels you gave earlier were KDE2 and GNOME,
the following will do:case $# in
1)
case $1 in
KDE2)
exec /usr/X11R6/bin/startkde
;;
GNOME)
exec /usr/X11R6/bin/gnome-wm
;;
failsafe)
exec xterm -geometry 80x24-0-0
;;
esac
esacTo make sure your KDE choice
of a login-time desktop background is also honored, you will
need to add the following line to
/usr/X11R6/lib/X11/xdm/Xsetup_0:/usr/X11R6/bin/kdmdesktopNow, you need only to make sure
kdm is started at the next bootup.
To learn how to do this, read the section on xdm, and do the same thing replacing
references to the xdm program by
kdm.That's it. Your next login screen should have a pretty
face and lots of menus.Anti-aliased fontsTired of blocky staircase edges to your fonts under X11?
Tired of unreadable text in web browsers? Well, no
more.Starting with version 4.0.2,
XFree86 supports anti-aliasing via
its "RENDER" extension, and starting with version 2.3, Qt (the
toolkit used by KDE) supports this
extension. Configuring this is described in on antialiasing X11 fonts. So if you're
running up-to-date software, anti-aliasing is possible on your
KDE2 desktop. Just go to your KDE2
menu, go to Preferences -> Look and Feel -> Style, and click
on the checkbox "Use Anti-Aliasing for Fonts and Icons".
That's all. If you're running a Qt application which is not
part of KDE, you may need to set
the environment variable QT_XFT to true before starting your
program.XFCEAbout XFCEXFCE is based on the gtk+
toolkit used by GNOME, but is much
more lightweight and meant for those who want a simple,
efficient desktop which is nevertheless easy to use and
configure. Visually, it looks very much like
CDE, found on commercial Unix
systems. Some of XFCE's features
are:A simple, easy-to-handle desktopFully configurable via mouse, with drag and
drop, etc Main panel similar to CDE, with menus, applets and
app launchersIntegrated window manager, file manager,
sound manager, GNOME compliance module, and other things Themeable (since it uses gtk+) Fast, light and efficient: ideal for
older/slower machines or machines with memory limitations More information on XFCE
can be found on the XFCE
website.Installing XFCEA binary package for xfce
exists (at the time of writing). To install, simply do
this:&prompt.root; pkg_add -r xfce Alternatively, you may prefer to build from source.
The ports tree comes to the rescue again: &prompt.root; cd /usr/ports/x11-wm/xfce
&prompt.root; make install clean All necessary source packages (including dependencies)
will be automagically fetched, built and installed, and
the build areas cleaned up afterwards.Now you want to tell the X server to launch
XFCE the next time you start
X. Simply type this:&prompt.root; echo "/usr/X11R6/bin/startxfce" > ~/.xinitrcThe next time you start X, XFCE will be your
desktop. (Note, as before:
if you're logging in via a display manager like
xdm, you should either create an
.xsession, as described in the
section on GNOME, but
with the /usr/X11R6/bin/startxfce
command; or, configure your display manager to allow
choosing a desktop at login time, as explained in
the section on kdm.)