diff --git a/en_US.ISO8859-1/articles/contributing/article.sgml b/en_US.ISO8859-1/articles/contributing/article.sgml
index a9c7965141..b86deecb84 100644
--- a/en_US.ISO8859-1/articles/contributing/article.sgml
+++ b/en_US.ISO8859-1/articles/contributing/article.sgml
@@ -1,469 +1,477 @@
+
+
+
+ Jordan
+ Hubbard
+ Contributed by
+
+
+
+
Contributing to FreeBSD
- Contributed by &a.jkh;.
-
contributingSo you want to contribute something to FreeBSD? That is great! We can
always use the help, and FreeBSD is one of those systems that
relies on the contributions of its user base in order
to survive. Your contributions are not only appreciated, they are vital
to FreeBSD's continued growth!Contrary to what some people might also have you believe, you do not
need to be a hot-shot programmer or a close personal friend of the FreeBSD
core team in order to have your contributions accepted. The FreeBSD
Project's development is done by a large and growing number of
international contributors whose ages and areas of technical expertise
vary greatly, and there is always more work to be done than there are
people available to do it.Since the FreeBSD project is responsible for an entire operating
system environment (and its installation) rather than just a kernel or a
few scattered utilities, our TODO list also spans a
very wide range of tasks, from documentation, beta testing and
presentation to highly specialized types of kernel development. No matter
what your skill level, there is almost certainly something you can do to
help the project!Commercial entities engaged in FreeBSD-related enterprises are also
encouraged to contact us. Need a special extension to make your product
work? You will find us receptive to your requests, given that they are not
too outlandish. Working on a value-added product? Please let us know! We
may be able to work cooperatively on some aspect of it. The free software
world is challenging a lot of existing assumptions about how software is
developed, sold, and maintained throughout its life cycle, and we urge you
to at least give it a second look.What is NeededThe following list of tasks and sub-projects represents something of
an amalgam of the various core team TODO lists and
user requests we have collected over the last couple of months. Where
possible, tasks have been ranked by degree of urgency. If you are
interested in working on one of the tasks you see here, send mail to the
coordinator listed by clicking on their names. If no coordinator has
been appointed, maybe you would like to volunteer?Ongoing tasksMost of the tasks listed in the previous sections require either a
considerable investment of time or an in-depth knowledge of the
FreeBSD kernel (or both). However, there are also many useful tasks
which are suitable for "weekend hackers", or people without
programming skills.If you run FreeBSD-current and have a good Internet
connection, there is a machine current.FreeBSD.org which builds a full
release once a day — every now and again, try and install
the latest release from it and report any failures in the
process.Read the freebsd-bugs mailing list. There might be a
problem you can comment constructively on or with patches you
can test. Or you could even try to fix one of the problems
yourself.Read through the FAQ and Handbook periodically. If anything
is badly explained, out of date or even just completely wrong, let
us know. Even better, send us a fix (SGML is not difficult to
learn, but there is no objection to ASCII submissions).Help translate FreeBSD documentation into your native language
(if not already available) — just send an email to &a.doc;
asking if anyone is working on it. Note that you are not
committing yourself to translating every single FreeBSD document
by doing this — in fact, the documentation most in need of
translation is the installation instructions.Read the freebsd-questions mailing list and &ng.misc
occasionally (or even regularly). It can be very satisfying to
share your expertise and help people solve their problems;
sometimes you may even learn something new yourself! These forums
can also be a source of ideas for things to work on.If you know of any bug fixes which have been successfully
applied to -current but have not been merged into -stable after a
decent interval (normally a couple of weeks), send the committer a
polite reminder.Move contributed software to src/contrib
in the source tree.Make sure code in src/contrib is up to
date.Build the source tree (or just part of it) with extra warnings
enabled and clean up the warnings.Fix warnings for ports which do deprecated things like using
gets() or including malloc.h.If you have contributed any ports, send your patches back to
the original author (this will make your life easier when they
bring out the next version)Suggest further tasks for this list!Work through the PR databaseproblem reports databaseThe FreeBSD PR
list shows all the current active problem reports and
requests for enhancement that have been submitted by FreeBSD users.
Look through the open PRs, and see if anything there takes your
interest. Some of these might be very simple tasks, that just need an
extra pair of eyes to look over them and confirm that the fix in the
PR is a good one. Others might be much more complex.Start with the PRs that have not been assigned to anyone else, but
if one them is assigned to someone else, but it looks like something
you can handle, email the person it is assigned to and ask if you can
work on it—they might already have a patch ready to be tested,
or further ideas that you can discuss with them.How to ContributeContributions to the system generally fall into one or more of the
following 6 categories:Bug reports and general commentaryAn idea or suggestion of general technical
interest should be mailed to the &a.hackers;. Likewise, people with
an interest in such things (and a tolerance for a
high volume of mail!) may subscribe to the
hackers mailing list by sending mail to &a.majordomo;. See mailing lists for more information
about this and other mailing lists.If you find a bug or are submitting a specific change, please
report it using the &man.send-pr.1; program or its WEB-based
equivalent. Try to fill-in each field of the bug report.
Unless they exceed 65KB, include any patches directly in the report.
When including patches, do not use cut-and-paste
because cut-and-paste turns tabs into spaces and makes them unusable.
Consider compressing patches and using &man.uuencode.1; if they exceed
20KB. Upload very large submissions to ftp.FreeBSD.org:/pub/FreeBSD/incoming/.After filing a report, you should receive confirmation along with
a tracking number. Keep this tracking number so that you can update
us with details about the problem by sending mail to
bug-followup@FreeBSD.org. Use the number as the
message subject, e.g. "Re: kern/3377". Additional
information for any bug report should be submitted this way.If you do not receive confirmation in a timely fashion (3 days to
a week, depending on your email connection) or are, for some reason,
unable to use the &man.send-pr.1; command, then you may ask
someone to file it for you by sending mail to the &a.bugs;.Changes to the documentationdocumentation submissionsChanges to the documentation are overseen by the &a.doc;. Send
submissions and changes (even small ones are welcome!) using
send-pr as described in Bug Reports and General
Commentary.Changes to existing source codeFreeBSD-currentAn addition or change to the existing source code is a somewhat
trickier affair and depends a lot on how far out of date you are with
the current state of the core FreeBSD development. There is a special
on-going release of FreeBSD known as FreeBSD-current
which is made available in a variety of ways for the convenience of
developers working actively on the system. See Staying current with FreeBSD for more
information about getting and using FreeBSD-current.Working from older sources unfortunately means that your changes
may sometimes be too obsolete or too divergent for easy re-integration
into FreeBSD. Chances of this can be minimized somewhat by
subscribing to the &a.announce; and the &a.current; lists, where
discussions on the current state of the system take place.Assuming that you can manage to secure fairly up-to-date sources
to base your changes on, the next step is to produce a set of diffs to
send to the FreeBSD maintainers. This is done with the &man.diff.1;
command, with the context diff form
being preferred. For example:diff&prompt.user; diff -c oldfile newfile
or
&prompt.user; diff -c -r olddir newdir
would generate such a set of context diffs for the given source file
or directory hierarchy. See the man page for &man.diff.1; for more
details.Once you have a set of diffs (which you may test with the
&man.patch.1; command), you should submit them for inclusion with
FreeBSD. Use the &man.send-pr.1; program as described in Bug Reports and General Commentary.
Do not just send the diffs to the &a.hackers; or
they will get lost! We greatly appreciate your submission (this is a
volunteer project!); because we are busy, we may not be able to
address it immediately, but it will remain in the pr database until we
do.uuencodeIf you feel it appropriate (e.g. you have added, deleted, or
renamed files), bundle your changes into a tar file
and run the &man.uuencode.1; program on it. Shar archives are also
welcome.If your change is of a potentially sensitive nature, e.g. you are
unsure of copyright issues governing its further distribution or you
are simply not ready to release it without a tighter review first,
then you should send it to &a.core; directly rather than submitting it
with &man.send-pr.1;. The core mailing list reaches a much smaller
group of people who do much of the day-to-day work on FreeBSD. Note
that this group is also very busy and so you
should only send mail to them where it is truly necessary.Please refer to &man.intro.9; and &man.style.9; style for
some information on coding style. We would appreciate it if you
were at least aware of this information before submitting
code.New code or major value-added packagesIn the case of a significant contribution of a large body
work, or the addition of an important new feature to FreeBSD, it
becomes almost always necessary to either send changes as uuencoded
tar files or upload them to a web or FTP site for other people to
access. If you do not have access to a web or FTP site, ask on an
appropriate FreeBSD mailing list for someone to host the changes for
you.When working with large amounts of code, the touchy subject of
copyrights also invariably comes up. Acceptable copyrights for code
included in FreeBSD are:BSD copyrightThe BSD copyright. This copyright is most preferred due to
its no strings attached nature and general
attractiveness to commercial enterprises. Far from discouraging
such commercial use, the FreeBSD Project actively encourages such
participation by commercial interests who might eventually be
inclined to invest something of their own into FreeBSD.GPLGNU General Public LicenseGNU General Public LicenseThe GNU General Public License, or GPL.
This license is not quite as popular with us due to the amount
of extra effort demanded of anyone using the code for
commercial purposes, but given the sheer quantity of GPL'd code
we currently require (compiler, assembler, text formatter, etc)
it would be silly to refuse additional contributions under this
license. Code under the GPL also goes into a different part of
the tree, that being /sys/gnu or
/usr/src/gnu, and is therefore easily
identifiable to anyone for whom the GPL presents a
problem.Contributions coming under any other type of copyright must be
carefully reviewed before their inclusion into FreeBSD will be
considered. Contributions for which particularly restrictive
commercial copyrights apply are generally rejected, though the authors
are always encouraged to make such changes available through their own
channels.To place a BSD-style copyright on your work, include
the following text at the very beginning of every source code file you
wish to protect, replacing the text between the %%
with the appropriate information.Copyright (c) %%proper_years_here%%
%%your_name_here%%, %%your_state%% %%your_zip%%.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer as
the first lines of this file unmodified.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
$Id$For your convenience, a copy of this text can be found in
/usr/share/examples/etc/bsd-style-copyright.Money, Hardware or Internet accessWe are always very happy to accept donations to further the cause
of the FreeBSD Project and, in a volunteer effort like ours, a little
can go a long way! Donations of hardware are also very important to
expanding our list of supported peripherals since we generally lack
the funds to buy such items ourselves.Donating fundsThe FreeBSD Foundation is a non-profit, tax-exempt
foundation established to further the goals of the FreeBSD
Project. As a 501(c)3 entity, the Foundation is generally
exempt from US federal income tax as well as Colorado
State income tax. Donations to a tax-exempt entity are
often deductible from taxable federal income.Donations may be sent in check form to:
The FreeBSD Foundation
7321 Brockway Dr.Boulder, CO80303USA
The Foundation is not yet able to accept other forms
of payment such as credit cards and PayPal.More information about the FreeBSD Foundation can be
found in The
FreeBSD Foundation -- an Introduction. To contact
the Foundation by email, write to
bod@FreeBSDFoundation.org.Donating hardwaredonationsDonations of hardware in any of the 3 following categories are
also gladly accepted by the FreeBSD Project:General purpose hardware such as disk drives, memory or
complete systems should be sent to the FreeBSD, Inc. address
listed in the donating funds
section.Hardware for which ongoing compliance testing is desired.
We are currently trying to put together a testing lab of all
components that FreeBSD supports so that proper regression
testing can be done with each new release. We are still lacking
many important pieces (network cards, motherboards, etc) and if
you would like to make such a donation, please contact &a.dg;
for information on which items are still required.Hardware currently unsupported by FreeBSD for which you
would like to see such support added. Please contact the
&a.core; before sending such items as we will need to find a
developer willing to take on the task before we can accept
delivery of new hardware.Donating Internet accessWe can always use new mirror sites for FTP, WWW or
cvsup. If you would like to be such a mirror,
please contact the FreeBSD project administrators
hubs@FreeBSD.org for more information.
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 0c0f737bf5..54dcb8dc88 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,4540 +1,4541 @@
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.CoranthGryphon
- Contributed
+ Contributed by Gateways 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;.StevePeterson
- Written
+ Written by BridgingIntroductionIP 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.BillSwingle
- Written
+ Written by NFSNFSAmong 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!JohnLind
- Contributed
+ Contributed by Problems integrating with other systemsCertain Ethernet adapters for ISA PC systems have limitations
which can lead to serious network problems, particularly with NFS.
This difficulty is not specific to FreeBSD, but FreeBSD systems
are affected by it.The problem nearly always occurs when (FreeBSD) PC systems are
networked with high-performance workstations, such as those made
by Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS
mount will work fine, and some operations may succeed, but
suddenly the server will seem to become unresponsive to the
client, even though requests to and from other systems continue to
be processed. This happens to the client system, whether the
client is the FreeBSD system or the workstation. On many systems,
there is no way to shut down the client gracefully once this
problem has manifested itself. The only solution is often to
reset the client, because the NFS situation cannot be
resolved.Though the correct solution is to get a higher
performance and capacity Ethernet adapter for the FreeBSD system,
there is a simple workaround that will allow satisfactory
operation. If the FreeBSD system is the
server, include the option
on the mount from the client. If the
FreeBSD system is the client, then mount the
NFS 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.MartinRenters
- Contributed
+ Contributed by Diskless 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.HellmuthMichaelis
- Contributed
+ Contributed by ISDN 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.BillSwingle
- Written
-
+ Written by
+
+
+ EricOgren
- Enahanced
+ Enhanced by UdoErdelhoff
- EnhancedNIS/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;UdoErdelhoff
- Contributed
+ Contributed by Using 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.GregSutter
- Written
+ Written by DHCPWhat is DHCP?Dynamic Host Configuration ProtocolDHCPInternet Software Consortium (ISC)DHCP, the Dynamic Host Configuration Protocol, describes
the means by which a system can connect to a network and obtain the
necessary information for communication upon that network. FreeBSD
uses the ISC (Internet Software Consortium) DHCP implementation, so
all implementation-specific information here is for use with the ISC
distribution.What This Section CoversThis 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.ChernLee
- Contributed
+ Contributed by DNSOverviewBINDFreeBSD utilizes, by default, a version of BIND (Berkeley
Internet Name Domain), which is the most common implementation of the
DNS protocol. DNS is the protocol through which names are mapped to
IP addresses, and vice versa. For example, a query for
www.freebsd.org
will receive a reply with the IP address of The FreeBSD Project's
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
DNSzonesexamplesExamples of zones:
. is the root zoneorg. is a zone under the root zonefoobardomain.org is a zone under the org. zonefoo.foobardomain.org. is a subdomain, a zone under the
foobardomain.org. zone
1.2.3.in-addr.arpa is a zone referencing all IP addresses
which fall under the 3.2.1.* IP space.
As one can see, the more specific part of a hostname appears to
its left. For example, foobardomain.org. is more
specific than org., as org. is
more specific than the root zone. The layout of each part of
a hostname is much like a filesystem: the /dev
directory falls within the root, and so on.Reasons to run a name 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)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.
MikeMakonnen
- Contributed
+ Contributed by Running 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 SpecificationChernLee
- Contributed
+ Contributed by Network 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.ChernLee
- Contributed
+ Contributed by inetd Super-ServerOverview&man.inetd.8; is referred to as the Internet
Super-Server because it manages connections for several
daemons. Programs that provide network service are commonly
known as daemons. inetd serves as a
managing server for other daemons. When a connection is
received by inetd, it determines
which daemon the connection is destined for, spawns the
particular daemon and delegates the socket to it. Running one
instance of inetd reduces the overall
system load as compared to running each daemon individually in
stand-alone mode.Primarily, inetd is used to
spawn other daemons, but several trivial protocols are handled
directly, such as chargen,
auth, and
daytime.This section will cover the basics in configuring
inetd through its command-line
options and 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.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/basics/chapter.sgml b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
index 61287866ac..dc9d2a83f6 100644
--- a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml
@@ -1,885 +1,885 @@
ChrisShumway
- Rewritten
+ Rewritten by Unix BasicsSynopsisbasicsThe following chapter will cover the basic commands and
functionality of the FreeBSD operating system. If you are new to
FreeBSD, you will definitely want to read through this chapter before
asking for help.PermissionsUnixFreeBSD, having its history rooted in BSD Unix, has its
fundamentals based on several key Unix concepts. The first, and
most pronounced, is that FreeBSD is a multi-user operating system.
The system can handle several users all working simultaneously on
completely unrelated tasks. The system is responsible for properly
sharing and managing requests for hardware devices, peripherals,
memory, and CPU time evenly to each user.Because the system is capable of supporting multiple users,
everything the system manages has a set of permissions governing who
can read, write, and execute the resource. These permissions are
stored as two octets broken into three pieces, one for the owner of
the file, one for the group that the file belongs to, and one for
everyone else. This numerical representation works like
this:permissionsfile permissionsValuePermissionDirectory Listing0No read, no write, no execute---1No read, no write, execute--x2No read, write, no execute-w-3No read, write, execute-wx4Read, no write, no executer--5Read, no write, executer-x6Read, write, no executerw-7Read, write, executerwxlsdirectoriesFor the long directory listing by ls -l, a
column will show a file's permissions for the owner, group, and
everyone else. Here's how it is broken up:-rw-r--r--The first character, from left to right, is a special character
that tells if this is a regular file, a directory, a special
character or block device, a socket, or any other special
pseudo-file device. The next three characters, designated as
rw- gives the permissions for the owner of the
file. The next three characters, r-- gives the
permissions for the group that the file belongs to. The final three
characters, r--, gives the permissions for the
rest of the world. A dash means that the permission is turned off.
In the case of this file, the permissions are set so the owner can
read and write to the file, the group can read the file, and the
rest of the world can only read the file. According to the table
above, the permissions for this file would be
644, where each digit represents the three parts
of the file's permission.This is all well and good, but how does the system control
permissions on devices? FreeBSD actually treats most hardware
devices as a file that programs can open, read, and write data to
just like any other file. These special device files are stored on
the /dev directory.Directories are also treated as files. They have read, write,
and execute permissions. The executable bit for a directory has a
slightly different meaning than that of files. When a directory is
marked executable, it means it can be searched into, for example, a
directory listing can be done in that directory.There are more to permissions, but they are primarily used in
special circumstances such as setuid binaries and sticky
directories. If you want more information on file permissions and
how to set them, be sure to look at the &man.chmod.1; man
page.Directory Structuresdirectory hierarchySince FreeBSD uses its file systems to determine many
fundamental system operations, the hierarchy of the file system is
extremely important. Due to the fact that the &man.hier.7; man page
provides a complete description of the directory structure, it will
not be duplicated here. Please read &man.hier.7; for more
information.Of significant importance is the root of all directories, the /
directory. This directory is the first directory mounted at boot
time and it contains the base system necessary at boot time. The
root directory also contains mount points for every other file
system that you want to mount.A mount point is a directory where additional file systems can
be grafted onto the root file system. Standard mount points include
/usr, /var,
/mnt, and /cdrom. These
directories are usually referenced to entries in the file
/etc/fstab. /etc/fstab is
a table of various file systems and mount points for reference by the
system. Most of the file systems in /etc/fstab
are mounted automatically at boot time from the script &man.rc.8;
unless they contain the option. Consult the
&man.fstab.5; manual page for more information on the format of the
/etc/fstab file and the options it
contains.ProcessesFreeBSD is a multi-tasking operating system. This means that it
seems as though more than one program is running at once. Each program
running at any one time is called a process.
Every command you run will start at least one new process, and there are
a number of system processes that run all the time, keeping the system
functional.Each process is uniquely identified by a number called a
process ID, or PID, and,
like files, each process also has one owner and group. The owner and
group information is used to determine what files and devices the
process can open, using the file permissions discussed earlier. Most
processes also have a parent process. The parent process is the process
that started them. For example, if you are typing commands to the shell
then the shell is a process, and any commands you run are also
processes. Each process you run in this way will have your shell as its
parent process. The exception to this is a special process called
init. init is always the first
process, so its PID is always 1. init is started
automatically by the kernel when FreeBSD starts.Two commands are particularly useful to see the processes on the
system, &man.ps.1; and &man.top.1;. The &man.ps.1; command is used to
show a static list of the currently running processes, and can show
their PID, how much memory they are using, the command line they were
started with, and so on. The &man.top.1; command displays all the
running processes, and updates the display every few seconds, so that
you can interactively see what your computer is doing.By default, &man.ps.1; only shows you the commands that are running
and are owned by you. For example;&prompt.user; ps
PID TT STAT TIME COMMAND
298 p0 Ss 0:01.10 tcsh
7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14)
37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14)
48630 p0 S 2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi
48730 p0 IW 0:00.00 (dns helper) (navigator-linux-)
72210 p0 R+ 0:00.00 ps
390 p1 Is 0:01.14 tcsh
7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y
6688 p3 IWs 0:00.00 tcsh
10735 p4 IWs 0:00.00 tcsh
20256 p5 IWs 0:00.00 tcsh
262 v0 IWs 0:00.00 -tcsh (tcsh)
270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16
280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16
284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc
285 v0 S 0:38.45 /usr/X11R6/bin/sawfishAs you can see in this example, the output from &man.ps.1; is
organized in to a number of columns. PID is the
process ID discussed earlier. PIDs are assigned starting from 1, go up
to 65536, and wrap around back to the beginning when you run out.
TT shows the tty the program is running on, and can
safely be ignore for the moment. STAT shows the
program's state, and again, can be safely ignored.
TIME is the amount of time the program has been
running on the CPU—this is not necessarily the elapsed time since
you started the program, as some programs spend a lot of time waiting
for things to happen before they need to spend time on the CPU.
Finally, COMMAND is the command line that was used to
run the program.&man.ps.1; supports a number of different options to change the
information that is displayed. One of the most useful sets is
auxww. displays information
about all the running processes, not just your own.
displays the username of the process' owner, as well as memory usage.
displays information about daemon processes, and
causes &man.ps.1; to display the full command line,
rather than truncating it once it gets too long to fit on the
screen.The output from &man.top.1; is similar. A sample session looks like
this;&prompt.user; top
last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10
47 processes: 1 running, 46 sleeping
CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle
Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free
Swap: 256M Total, 38M Used, 217M Free, 15% Inuse
PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND
72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top
7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14
281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA
296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm
48630 nik 2 0 29816K 9148K select 3:18 0.00% 0.00% navigator-linu
175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd
7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt
...The output is split in to two sections. The header (the first five
lines) shows the PID of the last process to run, the system load averages
(which are a measure of how busy the system is), the system uptime (time
since the last reboot) and the current time. The other figures in the
header relate to how many processes are running (47 in this case), how
much memory and swap space has been taken up, and how much time the
system is spending in different CPU states.Below that are a series of columns containing similar information
to the output from &man.ps.1;. As before you can see the PID, the
username, the amount of CPU time taken, and the command that was run.
&man.top.1; also defaults to showing you the amount of memory space
taken by the process. This is split in to two columns, one for total
size, and one for resident size—total size is how much memory the
application has needed, and the resident size is how much it is actually
using at the moment. In this example you can see that Netscape has
needed almost 30MB of RAM, and is currently only needing 9MB.&man.top.1; automatically updates this display every two seconds;
this can be changed with the option.Daemons, signals, and killing processesWhen you run an editor it is easy to control the editor, tell it to
load files, and so on. You can do this because the editor provides
facilities to do so, and because the editor is attached to a
terminal. Some programs are not designed to be
run with continuous user input, and so they disconnect from the terminal
at the first opportunity. For example, a web server spends all day
responding to web requests, it normally does not need any input from
you. Programs that transport email from site to site are another
example of this class of application.We call these programs daemons. Daemons were
characters in Greek mythology; neither good or evil, they were little
attendant spirits that, by and large, did useful things for mankind.
Much like the web servers and mail servers of today do useful things.
This is why the BSD mascot has, for a long time, been the cheerful
looking daemon with sneakers and a pitchfork.There is a convention to name programs that normally run as daemons
with a trailing d. BIND is the
Berkeley Internet Name Daemon (and the program you can is called
named), the Apache web
server program is called httpd, the line printer
spooling daemon is lpd and so on. This is a
convention, not a hard and fast rule; for example, the main mail daemon
for the Sendmail application is called
sendmail, and not maild, as you
might imagine.Sometimes you will need to communicate with a daemon process. These
communications are called signals, and you can
communicate with daemons (or with any running process) by sending it a
signal. There are a number if different signals that you can
send—some of them have a specific meaning, others are interpreted
by the application, and the application's documentation will tell you
how that application interprets signals. You can only send a signal to
a process that you own. If you try and send a signal to someone else's
process it will be ignored. The exception to this is the
root user, who can send signals to everyone's
processes.FreeBSD will also send applications signals in some cases. If an
application is badly written, and tries to access memory that it is not
supposed to, FreeBSD sends the process the Segmentation
Violation signal (SIGSEGV). If an
application has used the &man.alarm.3; system call to be alerted after a
period of time has elapsed then it will be sent the Alarm signal
(SIGALRM), and so on.Two signals can be used to stop a process,
SIGTERM and SIGKILL.
SIGTERM is the polite way to kill a process; the
process can catch the signal, realize that you want
it to shut down, close any log files it may have open, and generally
finish whatever it is doing at the time before shutting down. In some
cases a process may even ignore SIGTERM if it is in
the middle of some task that can not be interrupted.SIGKILL can not be ignored by a process. This is
the I don't care what you are doing, stop right now
signal. If you send SIGKILL to a process then
FreeBSD will stop that process there and thenNot quite true—there are a few things that can not be
interrupted. For example, if the process is trying to read from a
file that is on another computer on the network, and the other
computer has gone away for some reason (been turned off, or the
network has a fault), then the process is said to be
uninterruptible. Eventually the process will time
out, typically after two minutes. As soon as this time out occurs
the process will be killed..The other signals you might want to use are
SIGHUP, SIGUSR1, and
SIGUSR2. These are general purpose signals, and
different applications will do different things when they are
sent.Suppose that you have changed your web server's configuration
file—you would like to tell the web server to re-read its
configuration. You could stop and restart httpd, but
this would result in a brief outage period on your webserver, which may
be undesirable. Most daemons are written to respond to the
SIGHUP signal by re-reading their configuration
file. So instead of killing and restarting httpd you
would send it the SIGHUP signal. Because there is no
standard way to respond to these signals, different daemons will have
different behavior, so be sure and read the documentation for the
daemon in question.Signals are sent using the &man.kill.1; command, as this example
shows.Sending a signal to a processThis example shows how to send a signal to &man.inetd.8;. The
&man.inetd.8; configuration file is
/etc/inetd.conf, and &man.inetd.8; will re-read
this configuration file when it is sent
SIGHUP.Find the process ID of the process you want to send the signal
to. Do this using &man.ps.1; and &man.grep.1;. The &man.grep.1;
command is used to search through output, looking for the string you
specify. This command is run as a normal user, and &man.inetd.8; is
run as root, so the options
must be given to &man.ps.1;.&prompt.user; ps -ax | grep inetd
198 ?? IWs 0:00.00 inetd -wWSo the &man.inetd.8; PID is 198. In some cases the
grep inetd command might also occur in this
output. This is because of the way &man.ps.1; has to find the list
of running processes.Use &man.kill.1; to send the signal. Because &man.inetd.8; is
being run by root you must use &man.su.1; to
become root first.&prompt.user; suPassword:
&prompt.root; /bin/kill -s HUP 198As is common with Unix commands, &man.kill.1; will not print any
output if it is successfully. If you try and send a signal to a
process that you do not own then you will see kill:
PID: Operation not
permitted. If you mistype the PID you will either
send the signal to the wrong process, which could be bad, or, if
you are lucky, you will have sent the signal to a PID that is not
currently in use, and you will see kill:
PID: No such process.Why use /bin/kill?Many shells provide the kill command as a
built in command; that is, the shell will send the signal
directly, rather than running /bin/kill.
This can be very useful, but different shells have a different
syntax for specifying the name of the signal to send. Rather than
try to learn all of them, it can be simpler just to use the
/bin/kill ...
command directly.Sending other signals is very similar, just substitute
TERM or KILL in the command line
as necessary.Killing random process on the system can be a bad idea. In
particular, &man.init.8;, process ID 1, is very special. Running
/bin/kill -s KILL 1 is a quick way to shutdown your
system. Always double check the arguments you
run &man.kill.1; with before you press
RETURN.Shellsshellscommand-lineIn FreeBSD, a lot of everyday work is done in a command line
interface called a shell. A shell's main job is to take commands
from the input channel and execute them. A lot of shells also have
built in functions to help everyday tasks such a file management,
file globing, command line editing, command macros, and environment
variables. FreeBSD comes with a set of shells, such as
sh, the Bourne Shell, and csh,
the C-shell. Many other shells are available
from the FreeBSD Ports Collection that have much more power, such as
tcsh and bash.Which shell do you use? It is really a matter of taste. If you
are a C programmer you might feel more comfortable with a C-like shell
such as tcsh. If you've come from Linux or are new
to a Unix command line interface you might try bash.
The point is that each
shell has unique properties that may or may not work with your
preferred working environment, and that you have a choice of what
shell to use.One common feature in a shell is file-name completion. Given
the typing of the first few letters of a command or filename, you
can usually have the shell automatically complete the rest of the
command or filename by hitting the TAB key on the keyboard. Here is
an example. Suppose you have two files called
foobar and foo.bar. You
want to delete foo.bar. So what you would type
on the keyboard is: rm fo[TAB].[TAB].The shell would print out rm
foo[BEEP].bar.The [BEEP] is the console bell, which is the shell telling me it
was unable to totally complete the filename because there is more
than one match. Both foobar and
foo.bar start with fo, but
it was able to complete to foo. If you type in
., then hit TAB again, the shell would be able to
fill in the rest of the filename for you.environment variablesAnother function of the shell is environment variables.
Environment variables are a variable key pair stored in the shell's
environment space. This space can be read by any program invoked by
the shell, and thus contains a lot of program configuration. Here
is a list of common environment variables and what they mean:environment variablesVariableDescriptionUSERCurrent logged in user's name.PATHColon separated list of directories to search for
binaries.DISPLAYNetwork name of the X11 display to connect to, if
available.SHELLThe current shell.TERMThe name of the user's terminal. Used to determine the
capabilities of the terminal.TERMCAPDatabase entry of the terminal escape codes to perform
various terminal functions.OSTYPEType of operating system. E.g., FreeBSD.MACHTYPEThe CPU architecture that the system is running
on.EDITORThe user's preferred text editor.PAGERThe user's preferred text pager.MANPATHColon separated list of directories to search for
manual pages.Bourne shellsTo view or set an environment variable differs somewhat from
shell to shell. For example, in the C-Style shells such as
tcsh and csh, you would use
setenv to set and view environment variables.
Under Bourne shells such as sh and
bash, you would use set and
export to view and set your current environment
variables. For example, to set or modify the
EDITOR environment variable, under csh or
tcsh a
command like this would set EDITOR to
/usr/local/bin/emacs:&prompt.user; setenv EDITOR /usr/local/bin/emacsUnder Bourne shells:&prompt.user; export EDITOR="/usr/local/bin/emacs"You can also make most shells expand the environment variable by
placing a $ character in front of it on the
command line. For example, echo $TERM would
print out whatever $TERM is set to, because the shell
expands $TERM and passes it on to echo.Shells treat a lot of special characters, called meta-characters
as special representations of data. The most common one is the
* character, which represents any number of
characters in a filename. These special meta-characters can be used
to do file name globing. For example, typing in
echo * is almost the same as typing in
ls because the shell takes all the files that
match * and puts them on the command line for
echo to see.To prevent the shell from interpreting these special characters,
they can be escaped from the shell by putting a backslash
(\) character in front of them. echo
$TERM prints whatever your terminal is set to.
echo \$TERM prints $TERM as
is.Changing your shellThe easiest way to change your shell is to use the
chsh command. Running chsh will
place you into the editor that is in your EDITOR
environment variable; if it is not set, you will be placed in
vi. Change the Shell: line
accordingly.You can also give chsh the
option; this will set your shell for you,
without requiring you to enter an editor.
For example, if you wanted to
change your shell to bash, the following should do the
trick:&prompt.user; chsh -s /usr/local/bin/bashRunning chsh with no parameters and editing
the shell from there would work also.The shell that you wish to use must be
present in the /etc/shells file. If you
have installed a shell from the ports
collection, then this should have been done for you
already. If you installed the shell by hand, you must do
this.For example, if you installed bash by hand
and placed it into /usr/local/bin, you would
want to:&prompt.root; echo "/usr/local/bin/bash" >> /etc/shellsThen rerun chsh.Text Editorstext editorseditorsA lot of configuration in FreeBSD is done by editing a text
file. Because of this, it would be a good idea to become familiar
with a text editor. FreeBSD comes with a few as part of the base
system, and many more are available in the ports collection.eeThe easiest and simplest editor to learn is an editor called
ee, which stands for easy editor. To
start ee, one would type at the command
line ee filename where
filename is the name of the file to be edited.
For example, to edit /etc/rc.conf, type in
ee /etc/rc.conf. Once inside of
ee, all of the
commands for manipulating the editor's functions are listed at the
top of the display. The caret ^ character means
the control key on the keyboard, so ^e expands to pressing the
control key plus the letter e. To leave
ee, hit the escape key, then choose leave
editor. The editor will prompt you to save any changes if the file
has been modified.vieditorsviemacseditorsemacsFreeBSD also comes with more powerful text editors such as
vi as part of the base system, and
emacs and vim
as part of the FreeBSD Ports Collection. These editors offer much
more functionality and power at the expense of being a little more
complicated to learn. However if you plan on doing a lot of text
editing, learning a more powerful editor such as
vim or emacs
will save you much more time in the long run.For More Information...Manual pagesman pagesThe most comprehensive documentation on FreeBSD is in the form
of man pages. Nearly every program on the system comes with a
short reference manual explaining the basic operation and various
arguments. These manuals can be viewed with the man command. Use
of the man command is simple:&prompt.user; man commandcommand is the name of the command you
wish to learn about. For example, to learn more about
ls command type:&prompt.user; man lsThe online manual is divided up into numbered sections:User commands.System calls and error numbers.Functions in the C libraries.Device drivers.File formats.Games and other diversions.Miscellaneous information.System maintenance and operation commands.Kernel developers.In some cases, the same topic may appear in more than one
section of the online manual. For example, there is a
chmod user command and a
chmod() system call. In this case, you can
tell the man command which one you want by specifying the
section:&prompt.user; man 1 chmodThis will display the manual page for the user command
chmod. References to a particular section of
the online manual are traditionally placed in parenthesis in
written documentation, so &man.chmod.1; refers to the
chmod user command and &man.chmod.2; refers to
the system call.This is fine if you know the name of the command and simply
wish to know how to use it, but what if you cannot recall the
command name? You can use man to search for keywords in the
command descriptions by using the
switch:&prompt.user; man -k mailWith this command you will be presented with a list of
commands that have the keyword mail in their
descriptions. This is actually functionally equivalent to using
the apropos command.So, you are looking at all those fancy commands in
/usr/bin but do not have the faintest idea
what most of them actually do? Simply do:&prompt.user; cd /usr/bin
&prompt.user; man -f *or&prompt.user; cd /usr/bin
&prompt.user; whatis *which does the same thing.GNU Info FilesFree Software FoundationFreeBSD includes many applications and utilities produced by
the Free Software Foundation (FSF). In addition to man pages,
these programs come with more extensive hypertext documents called
info files which can be viewed with the
info command or, if you installed
emacs, the info mode of
emacs.To use the &man.info.1; command, simply type:&prompt.user; infoFor a brief introduction, type h. For a
quick command reference, type ?.
diff --git a/en_US.ISO8859-1/books/handbook/config/chapter.sgml b/en_US.ISO8859-1/books/handbook/config/chapter.sgml
index 1d22f56c7d..85a2043f28 100644
--- a/en_US.ISO8859-1/books/handbook/config/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/config/chapter.sgml
@@ -1,890 +1,894 @@
ChernLee
- Written
+ Written by
+
+ MikeSmith
- Based on a tutorial written by
+ Based on a tutorial written by
+
+ MattDillon
- and tuning(7) written by
+ Also based on tuning(7) written by Configuration and TuningSynopsissystem configuration/optimizationConfiguring a system correctly can substantially reduce the
amount of work involved in maintaining and upgrading it
in the future. This chapter describes some of the aspects of
administrative configuration of FreeBSD systems.This chapter will also describe some of the parameters that
can be set to tune a FreeBSD system for optimum
performance.Initial ConfigurationPartition layoutPartition layout/etc/var/usrBase PartitionsWhen laying out your filesystem with &man.disklabel.8;
or &man.sysinstall.8;, it is important to remember that hard
drives can transfer data at a faster rate from the outer
tracks than the inner. Knowing this, you should place your
smaller, heavily-accessed filesystems, such as root and swap,
closer to the outside of the drive, while placing larger
partitions, such as /usr, towards the
inner. To do so, it is
a good idea to create partitions in a similar order: root,
swap, /var,
/usr.The size of your /var partition
reflects the intended use of your machine.
/var is primarily used to hold:
mailboxes, print spool and log files. Mail boxes and log
files, in particular, can grow to unexpected sizes based upon
how many users are on your system and how long your log files
are kept. If you intend to run a mailserver, a
/var partition of over a gigabyte can be
suitable. Additionally, /var/tmp must be
large enough to contain any packages you may wish to
add.The /usr partition holds the bulk
of the files required to support the system and a
subdirectory within it called
/usr/local holds the bulk of the files
installed from the &man.ports.7; hierarchy. If you do not
use ports all that much and do not intend to keep system
source (/usr/src) on the machine,
you can get away with a 1
gigabyte /usr partition. However,
if you install a lot of
ports (especially window managers and Linux binaries), we
recommend at least a two gigabyte /usr
and if you also
intend to keep system source on the machine, we recommend a
three gigabyte /usr. Do not
underestimate the amount of space you will need in this
partition, it can creep up and surprise you!When sizing your partitions, keep in mind the space
requirements for your system to grow. Running out of space in
one partition while having plenty in another can lead to much
frustration.Some users who have used &man.sysinstall.8;'s
Auto-defaults partition sizer have found
either their root or /var partitions too
small later on. Partition wisely and
generously.Swap Partitionswap sizingswap partitionAs a rule of thumb, your swap space should typically be
double the amount of main memory. For example, if the machine
has 128 megabytes of memory, the swap file should be 256
megabytes. Systems with lesser memory may perform better with
a lot more swap. It is not recommended that you configure any
less than 256 megabytes of swap on a system and you should
keep in mind future memory expansion when sizing the swap
partition. The kernel's VM paging algorithms are tuned to
perform best when the swap partition is at least two times the
size of main memory. Configuring too little swap can lead to
inefficiencies in the VM page scanning code as well as create
issues later on if you add more memory to your machine.Finally, on larger systems with multiple SCSI disks (or
multiple IDE disks operating on different controllers), it is
strongly recommend that you configure swap on each drive (up
to four drives). The swap partitions on the drives should be
approximately the same size. The kernel can handle arbitrary
sizes but internal data structures scale to 4 times the
largest swap partition. Keeping the swap partitions near the
same size will allow the kernel to optimally stripe swap space
across the disks. Do not worry about overdoing it a little,
swap space is the saving grace of Unix. Even if you don't
normally use much swap, it can give you more time to recover
from a runaway program before being forced to reboot.Why Partition? Why partition at all? Why not create one big root
partition and be done with it? Then I don't have to worry
about undersizing things!There are several reasons this is not a good idea.
First, each partition has different operational
characteristics and separating them allows the filesystem to
tune itself to those characteristics. For example, the root
and /usr partitions are read-mostly, with
very little writing, while a lot of reading and writing could
occur in /var and
/var/tmp.By properly partitioning your system, fragmentation
introduced in the smaller more heavily write-loaded partitions
will not bleed over into the mostly-read partitions.
Additionally, keeping the write-loaded partitions closer to
the edge of the disk, for example before the really big
partition instead of after in the partition table, will
increase I/O performance in the partitions where you need it
the most. Now it is true that you might also need I/O
performance in the larger partitions, but they are so large
that shifting them more towards the edge of the disk will not
lead to a significant performance improvement whereas moving
/var to the edge can have a huge impact.
Finally, there are safety concerns. Having a small neat root
partition that is essentially read-only gives it a greater
chance of surviving a bad crash intact.Core Configurationrc filesrc.confThe principal location for system configuration information
is within /etc/rc.conf. This file
contains a wide range of configuration information, principally
used at system startup to configure the system. Its name
directly implies this; it is configuration information for the
rc* files.An administrator should make entries in the
rc.conf file to
override the default settings from
/etc/defaults/rc.conf. The defaults file
should not be copied verbatim to /etc - it
contains default values, not examples. All system-specific
changes should be made in the rc.conf
file itself.A number of strategies may be applied in clustered
applications to separate site-wide configuration from
system-specific configuration in order to keep administration
overheads down. The recommended approach is to place site-wide
configuration into another file,
such as /etc/rc.conf.site, and then include
this file into /etc/rc.conf, which will
contain only system-specific information.As rc.conf is read by &man.sh.1; it is
trivial to achieve this. For example:rc.conf: . rc.conf.site
hostname="node15.webcompany.com"
network_interfaces="fxp0 lo0"
ifconfig_fxp0="inet 10.1.1.1"rc.conf.site: defaultrouter="10.1.1.254"
saver="daemon"
blanktime="100"The rc.conf.site file can then be
distributed to every system using rsync or similar
program, whilst the rc.conf file remains
unique.Upgrading the system using &man.sysinstall.8;
or 'make world' will not overwrite the rc.conf
file, so system configuration information will not be lost.Application ConfigurationTypically, installed applications have their own
configuration files, with their own syntax, etc. It is
important that these files be kept separate from the base
system, so that they may be easily located and managed by the
package management tools./usr/local/etcTypically, these files are installed in
/usr/local/etc. In the case where an
application has a large number of configuration files, a
subdirectory will be created to hold them.Normally, when a port or package is installed, sample
configuration files are also installed. These are usually
identified with a ".default" suffix. If there are no existing
configuration files for the application, they will be created by
copying the .default files.For example, here is
/usr/local/etc/apache:-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf
-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf.default
-rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf
-rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf.default
-rw-r--r-- 1 root wheel 12205 May 20 1998 magic
-rw-r--r-- 1 root wheel 12205 May 20 1998 magic.default
-rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types
-rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types.default
-rw-r--r-- 1 root wheel 7980 May 20 1998 srm.conf
-rw-r--r-- 1 root wheel 7933 May 20 1998 srm.conf.defaultIt can be quickly seen that only the srm.conf file has been
changed. A later update of the apache port would not overwrite
this changed file.Starting ServicesservicesIt is common for a system to host a number of services.
These may be started in several different fashions, each having
different advantages./usr/local/etc/rc.dSoftware installed from a port or the packages collection
will often place a script in
/usr/local/etc/rc.d which is invoked at
system startup with a 'start' argument, and at system shutdown
with a 'stop' argument. This is the recommended way for
starting system-wide services that are to be run as root, or that
expect to be started as root. These scripts are registered as
part of the installation of the package, and will be removed
when the package is removed.A generic startup script in
/usr/local/etc/rc.d looks like:#!/bin/sh
echo -n ' FooBar'
case "$1" in
start)
/usr/local/bin/foobar
;;
stop)
kill -9 `cat /var/run/foobar.pid`
;;
*)
echo "Usage: `basename $0` {start|stop}" >&2
exit 64
;;
esac
exit 0
This script is called with
at startup, and the at shutdown to allow
it to carry out its purpose.Some services expect to be invoked by &man.inetd.8; when a
connection is received on a suitable port. This is common for
mail reader servers (POP and IMAP, etc.). These services are
enabled by editing the file /etc/inetd.conf.
See &man.inetd.8; for details on editing this file.Some additional system services may not be covered by the
toggles in /etc/rc.conf. These are
traditionally enabled by placing the command(s) to invoke them
in /etc/rc.local. As of FreeBSD 3.1 there
is no default /etc/rc.local; if it is
created by the administrator it will however be honored in the
normal fashion. Note that rc.local is
generally regarded as the location of last resort; if there is a
better place to start a service, do it there.Do not place any commands in
/etc/rc.conf. To start daemons, or
run any commands at boot time, place a script in
/usr/local/etc/rc.d instead.It is also possible to use the &man.cron.8; daemon to start
system services. This approach has a number of advantages, not
least being that because &man.cron.8; runs these processes as the
owner of the crontab, services may be started
and maintained by non-root users.This takes advantage of an undocumented feature of &man.cron.8; the
time specification may be replaced by '@reboot', which will
cause the job to be run when &man.cron.8; is started shortly after
system boot.Virtual Hostsvirtual hostsip aliasesA very common use of FreeBSD is virtual site hosting, where
one server appears to the network as many servers. This is
achieved by assigning multiple network addresses to a single
interface.A given network interface has one "real" address, and may
have any number of "alias" addresses. These aliases are
normally added by placing alias entries in
/etc/rc.conf.An alias entry for the interface 'fxp0' looks like:ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"Note that alias entries must start with alias0 and proceed
upwards in order, (for example, _alias1, _alias2, and so on).
The configuration process will stop at the first missing number.
The calculation of alias netmasks is important, but
fortunately quite simple. For a given interface, there must be
one address which correctly represents the network's netmask.
Any other addresses which fall within this network must have a
netmask of all 1's.For example, consider the case where the fxp0 interface is
connected to two networks, the 10.1.1.0 network with a netmask
of 255.255.255.0 and the 202.0.75.16 network with a netmask of
255.255.255.240. We want the system to appear at 10.1.1.1
through 10.1.1.5 and at 202.0.75.17 through 202.0.75.20.The following entries configure the adapter correctly for
this arrangement: ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0"
ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255"
ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255"
ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255"
ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255"
ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240"
ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255"
ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255"
ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"Configuration Files/etc LayoutThere are a number of directories in which configuration
information is kept. These include:/etcGeneric system configuration information; data here is
system-specific./etc/defaultsDefault versions of system configuration files./etc/mailExtra sendmail configuration, other MTA configuration
files.
/etc/pppConfiguration for both user- and kernel-ppp programs.
/etc/namedbDefault location for bind(8) data. Normally the
boot file is located here, and contains a directive to
refer to other data in /var/db./usr/local/etcConfiguration files for installed applications.
May contain per-application subdirectories./usr/local/etc/rc.dStart/stop scripts for installed applications./var/dbPersistent system-specific data files, such as bind zone
files, database files, and so on.HostnameshostnameDNS/etc/resolv.confresolv.conf/etc/resolv.conf dictates how FreeBSD's
resolver accesses the Internet Domain Name System (DNS).The most common entries to resolv.conf are:
nameserverThe IP address of a nameserver the resolver
should query. The servers are queried in the order
listed with a maximum of three.searchSearch list hostname lookup. This is normally
determined by the domain of the local hostname.domainThe local domain name.A typical resolv.conf:search foobar.com
nameserver 147.11.1.11
nameserver 147.11.100.30If you are using DHCP, &man.dhclient.8; usually rewrites
resolv.conf with information received from the
DHCP server./etc/hostshosts/etc/hosts is a simple text database
reminiscent of the old Internet. It works in conjunction with DNS
and NIS providing name to IP address mappings. Local computers
connected via a LAN can be placed in here for simplistic naming
purposes instead of setting up a &man.named.8; server.
Additionally, /etc/hosts can be used to provide
a local record of Internet names, reducing the need to query
externally for commonly accessed names.# $FreeBSD$
#
# Host Database
# This file should contain the addresses and aliases
# for local hosts that share this file.
# In the presence of the domain name service or NIS, this file may
# not be consulted at all; see /etc/nsswitch.conf for the resolution order.
#
#
::1 localhost localhost.my.domain myname.my.domain
127.0.0.1 localhost localhost.my.domain myname.my.domain
#
# Imaginary network.
#10.0.0.2 myname.my.domain myname
#10.0.0.3 myfriend.my.domain myfriend
#
# According to RFC 1918, you can use the following IP networks for
# private nets which will never be connected to the Internet:
#
# 10.0.0.0 - 10.255.255.255
# 172.16.0.0 - 172.31.255.255
# 192.168.0.0 - 192.168.255.255
#
# In case you want to be able to connect to the Internet, you need
# real official assigned numbers. PLEASE PLEASE PLEASE do not try
# to invent your own network numbers but instead get one from your
# network provider (if any) or from the Internet Registry (ftp to
# rs.internic.net, directory `/templates').
#/etc/hosts takes on the simple format
of:[Internet address] [official hostname] [alias1] [alias2] ...For example:10.0.0.1 myRealHostname.foobar.com myRealHostname foobar1 foobar2Consult &man.hosts.5; for more information.Log File Configurationlog filessyslog.confsyslog.confsyslog.conf is the configuration file
for the &man.syslogd.8; program. It indicates which types
of syslog messages are logged to particular log files.# $FreeBSD$
#
# Spaces ARE valid field separators in this file. However,
# other *nix-like systems still insist on using tabs as field
# separators. If you are sharing this file between systems, you
# may want to use only tabs as field separators here.
# Consult the syslog.conf(5) manpage.
*.err;kern.debug;auth.notice;mail.crit /dev/console
*.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages
security.* /var/log/security
mail.info /var/log/maillog
lpr.info /var/log/lpd-errs
cron.* /var/log/cron
*.err root
*.notice;news.err root
*.alert root
*.emerg *
# uncomment this to log all writes to /dev/console to /var/log/console.log
#console.info /var/log/console.log
# uncomment this to enable logging of all log messages to /var/log/all.log
#*.* /var/log/all.log
# uncomment this to enable logging to a remote loghost named loghost
#*.* @loghost
# uncomment these if you're running inn
# news.crit /var/log/news/news.crit
# news.err /var/log/news/news.err
# news.notice /var/log/news/news.notice
!startslip
*.* /var/log/slip.log
!ppp
*.* /var/log/ppp.logConsult the &man.syslog.conf.5; manpage for more
information.newsyslog.confnewsyslog.confnewsyslog.conf is the configuration
file for &man.newsyslog.8;, a program that is scheduled to run
normally by &man.cron.8; &man.newsyslog.8; determines when log
files require archiving or rearranging.
logfile is moved to
logfile.1, logfile.1
is moved to logfile.2, and so on.
Additionally, the log files may be archived in &man.gzip.1; format
causing them to be named: logfile.0.gz, logfile.1.gz, and so
on.newsyslog.conf indicates which log
files are to be managed, how many are to be kept, and when
they are to be touched. Log files can be rearranged and/or
archived when they have either reached a certain size, or at a
certain periodic time/date.# configuration file for newsyslog
# $FreeBSD$
#
# filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num]
/var/log/cron 600 3 100 * Z
/var/log/amd.log 644 7 100 * Z
/var/log/kerberos.log 644 7 100 * Z
/var/log/lpd-errs 644 7 100 * Z
/var/log/maillog 644 7 * @T00 Z
/var/log/sendmail.st 644 10 * 168 B
/var/log/messages 644 5 100 * Z
/var/log/all.log 600 7 * @T00 Z
/var/log/slip.log 600 3 100 * Z
/var/log/ppp.log 600 3 100 * Z
/var/log/security 600 10 100 * Z
/var/log/wtmp 644 3 * @01T05 B
/var/log/daily.log 640 7 * @T00 Z
/var/log/weekly.log 640 5 1 $W6D0 Z
/var/log/monthly.log 640 12 * $M1D0 Z
/var/log/console.log 640 5 100 * ZConsult the &man.newsyslog.8; manpage for more
information.sysctl.confsysctl.confsysctlsysctl.conf looks much like
rc.conf. Values are set in a
variable=value
form. The specified values are set after the system goes into
multi-user mode. Not all variables are settable in this mode.A sample sysctl.conf turning off logging
of fatal signal exits and letting Linux programs know they are really
running under FreeBSD.kern.logsigexit=0 # Do not log fatal signal exits (e.g. sig 11)
compat.linux.osname=FreeBSD
compat.linux.osrelease=4.3-STABLETuning with sysctlsysctlTuning with sysctl&man.sysctl.8; is an interface that allows you to make changes
to a running FreeBSD system. This includes many advanced
options of the TCP/IP stack and virtual memory system that can
dramatically improve performance for an experienced system
administrator. Over five hundred system variables can be read
and set using &man.sysctl.8;.At its core, &man.sysctl.8; serves to do two functions: read and
modify system settings.To view all readable variables:&prompt.user; sysctl -aTo read a particular variable, for example,
kern.maxproc:&prompt.user; sysctl kern.maxproc
kern.maxproc: 1044To set a particular variable, use the =
option:&prompt.root; sysctl kern.maxfiles=5000
kern.maxfiles: 2088 -> 5000Settings of sysctl variables are usually either strings, numbers,
or booleans. A boolean being 1 for yes or a 0 for no.Tuning disksSysctl Variablesvfs.vmiodirenablevfs.vmiodirenableThe vfs.vmiodirenable sysctl variable
defaults to 0 (off) (though soon it will default to 1) and may
be set to 0 (off) or 1 (on). This parameter controls how
directories are cached by the system. Most directories are
small and use but a single fragment (typically 1K) in the
filesystem and even less (typically 512 bytes) in the buffer
cache. However, when operating in the default mode the buffer
cache will only cache a fixed number of directories even if
you have a huge amount of memory. Turning on this sysctl
allows the buffer cache to use the VM Page Cache to cache the
directories. The advantage is that all of memory is now
available for caching directories. The disadvantage is that
the minimum in-core memory used to cache a directory is the
physical page size (typically 4K) rather than 512 bytes. We
recommend turning this option on if you are running any
services which manipulate large numbers of files. Such
services can include web caches, large mail systems, and news
systems. Turning on this option will generally not reduce
performance even with the wasted memory but you should
experiment to find out.hw.ata.wchw.ata.wcFreeBSD 4.3 flirted with turning off IDE write caching.
This reduced write bandwidth to IDE disks but was considered
necessary due to serious data consistency issues introduced
by hard drive vendors. Basically the problem is that IDE
drives lie about when a write completes. With IDE write
caching turned on, IDE hard drives will not only write data
to disk out of order, they will sometimes delay some of the
blocks indefinitely when under heavy disk loads. A crash or
power failure can result in serious filesystem corruption.
So our default was changed to be safe. Unfortunately, the
result was such a huge loss in performance that we caved in
and changed the default back to on after the release. You
should check the default on your system by observing the
hw.ata.wc sysctl variable. If IDE write
caching is turned off, you can turn it back on by setting
the kernel variable back to 1. This must be done from the
boot loader at boot time. Attempting to do it after the
kernel boots will have no effect.For more information, please see &man.ata.4;.Soft UpdatesSoft UpdatestunefsThe &man.tunefs.8; program can be used to fine-tune a
filesystem. This program has many different options, but for
now we are only concerned with toggling Soft Updates on and
off, which is done by :&prompt.root; tunefs -n enable /filesystem
&prompt.root; tunefs -n disable /filesystemA filesystem cannot be modified with &man.tunefs.8; while
it is mounted. A good time to enable Soft Updates is before any
partitions have been mounted, in single-user mode.Soft Updates drastically improves meta-data performance, mainly
file creation and deletion, through the use of a memory cache. We
recommend turning Soft Updates on on all of your filesystems. There
are two downsides to Soft Updates that you should be aware of: First,
Soft Updates guarantees filesystem consistency in the case of a crash
but could very easily be several
seconds (even a minute!) behind updating the physical disk. If you
crash you may lose more work than otherwise. Secondly, Soft Updates
delays the freeing of filesystem blocks. If you have a filesystem
(such as the root filesystem) which is close to full, doing a major
update of it, e.g. make installworld, can run it
out of space and cause the update to fail.Tuning kernel limitsTuning kernel limitsFile/process limitskern.maxfileskern.maxfileskern.maxfiles can be raised or
lowered based upon your system requirements. This variable
indicates the maximum number of file descriptors on your
system. When the file descriptor table is full,
file: table is full will show up repeatedly
in the system message buffer, which can be viewed with the
dmesg command.Each open file, socket, or fifo uses one file
descriptor. A large-scale production server may easily
require many thousands of file descriptors, depending on the
kind and number of services running concurrently.kern.maxfile's default value is
dictated by the option in your
kernel config. kern.maxfiles grows
proportionally to the value of .
diff --git a/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml b/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
index a9c7965141..b86deecb84 100644
--- a/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/contrib/chapter.sgml
@@ -1,469 +1,477 @@
+
+
+
+ Jordan
+ Hubbard
+ Contributed by
+
+
+
+
Contributing to FreeBSD
- Contributed by &a.jkh;.
-
contributingSo you want to contribute something to FreeBSD? That is great! We can
always use the help, and FreeBSD is one of those systems that
relies on the contributions of its user base in order
to survive. Your contributions are not only appreciated, they are vital
to FreeBSD's continued growth!Contrary to what some people might also have you believe, you do not
need to be a hot-shot programmer or a close personal friend of the FreeBSD
core team in order to have your contributions accepted. The FreeBSD
Project's development is done by a large and growing number of
international contributors whose ages and areas of technical expertise
vary greatly, and there is always more work to be done than there are
people available to do it.Since the FreeBSD project is responsible for an entire operating
system environment (and its installation) rather than just a kernel or a
few scattered utilities, our TODO list also spans a
very wide range of tasks, from documentation, beta testing and
presentation to highly specialized types of kernel development. No matter
what your skill level, there is almost certainly something you can do to
help the project!Commercial entities engaged in FreeBSD-related enterprises are also
encouraged to contact us. Need a special extension to make your product
work? You will find us receptive to your requests, given that they are not
too outlandish. Working on a value-added product? Please let us know! We
may be able to work cooperatively on some aspect of it. The free software
world is challenging a lot of existing assumptions about how software is
developed, sold, and maintained throughout its life cycle, and we urge you
to at least give it a second look.What is NeededThe following list of tasks and sub-projects represents something of
an amalgam of the various core team TODO lists and
user requests we have collected over the last couple of months. Where
possible, tasks have been ranked by degree of urgency. If you are
interested in working on one of the tasks you see here, send mail to the
coordinator listed by clicking on their names. If no coordinator has
been appointed, maybe you would like to volunteer?Ongoing tasksMost of the tasks listed in the previous sections require either a
considerable investment of time or an in-depth knowledge of the
FreeBSD kernel (or both). However, there are also many useful tasks
which are suitable for "weekend hackers", or people without
programming skills.If you run FreeBSD-current and have a good Internet
connection, there is a machine current.FreeBSD.org which builds a full
release once a day — every now and again, try and install
the latest release from it and report any failures in the
process.Read the freebsd-bugs mailing list. There might be a
problem you can comment constructively on or with patches you
can test. Or you could even try to fix one of the problems
yourself.Read through the FAQ and Handbook periodically. If anything
is badly explained, out of date or even just completely wrong, let
us know. Even better, send us a fix (SGML is not difficult to
learn, but there is no objection to ASCII submissions).Help translate FreeBSD documentation into your native language
(if not already available) — just send an email to &a.doc;
asking if anyone is working on it. Note that you are not
committing yourself to translating every single FreeBSD document
by doing this — in fact, the documentation most in need of
translation is the installation instructions.Read the freebsd-questions mailing list and &ng.misc
occasionally (or even regularly). It can be very satisfying to
share your expertise and help people solve their problems;
sometimes you may even learn something new yourself! These forums
can also be a source of ideas for things to work on.If you know of any bug fixes which have been successfully
applied to -current but have not been merged into -stable after a
decent interval (normally a couple of weeks), send the committer a
polite reminder.Move contributed software to src/contrib
in the source tree.Make sure code in src/contrib is up to
date.Build the source tree (or just part of it) with extra warnings
enabled and clean up the warnings.Fix warnings for ports which do deprecated things like using
gets() or including malloc.h.If you have contributed any ports, send your patches back to
the original author (this will make your life easier when they
bring out the next version)Suggest further tasks for this list!Work through the PR databaseproblem reports databaseThe FreeBSD PR
list shows all the current active problem reports and
requests for enhancement that have been submitted by FreeBSD users.
Look through the open PRs, and see if anything there takes your
interest. Some of these might be very simple tasks, that just need an
extra pair of eyes to look over them and confirm that the fix in the
PR is a good one. Others might be much more complex.Start with the PRs that have not been assigned to anyone else, but
if one them is assigned to someone else, but it looks like something
you can handle, email the person it is assigned to and ask if you can
work on it—they might already have a patch ready to be tested,
or further ideas that you can discuss with them.How to ContributeContributions to the system generally fall into one or more of the
following 6 categories:Bug reports and general commentaryAn idea or suggestion of general technical
interest should be mailed to the &a.hackers;. Likewise, people with
an interest in such things (and a tolerance for a
high volume of mail!) may subscribe to the
hackers mailing list by sending mail to &a.majordomo;. See mailing lists for more information
about this and other mailing lists.If you find a bug or are submitting a specific change, please
report it using the &man.send-pr.1; program or its WEB-based
equivalent. Try to fill-in each field of the bug report.
Unless they exceed 65KB, include any patches directly in the report.
When including patches, do not use cut-and-paste
because cut-and-paste turns tabs into spaces and makes them unusable.
Consider compressing patches and using &man.uuencode.1; if they exceed
20KB. Upload very large submissions to ftp.FreeBSD.org:/pub/FreeBSD/incoming/.After filing a report, you should receive confirmation along with
a tracking number. Keep this tracking number so that you can update
us with details about the problem by sending mail to
bug-followup@FreeBSD.org. Use the number as the
message subject, e.g. "Re: kern/3377". Additional
information for any bug report should be submitted this way.If you do not receive confirmation in a timely fashion (3 days to
a week, depending on your email connection) or are, for some reason,
unable to use the &man.send-pr.1; command, then you may ask
someone to file it for you by sending mail to the &a.bugs;.Changes to the documentationdocumentation submissionsChanges to the documentation are overseen by the &a.doc;. Send
submissions and changes (even small ones are welcome!) using
send-pr as described in Bug Reports and General
Commentary.Changes to existing source codeFreeBSD-currentAn addition or change to the existing source code is a somewhat
trickier affair and depends a lot on how far out of date you are with
the current state of the core FreeBSD development. There is a special
on-going release of FreeBSD known as FreeBSD-current
which is made available in a variety of ways for the convenience of
developers working actively on the system. See Staying current with FreeBSD for more
information about getting and using FreeBSD-current.Working from older sources unfortunately means that your changes
may sometimes be too obsolete or too divergent for easy re-integration
into FreeBSD. Chances of this can be minimized somewhat by
subscribing to the &a.announce; and the &a.current; lists, where
discussions on the current state of the system take place.Assuming that you can manage to secure fairly up-to-date sources
to base your changes on, the next step is to produce a set of diffs to
send to the FreeBSD maintainers. This is done with the &man.diff.1;
command, with the context diff form
being preferred. For example:diff&prompt.user; diff -c oldfile newfile
or
&prompt.user; diff -c -r olddir newdir
would generate such a set of context diffs for the given source file
or directory hierarchy. See the man page for &man.diff.1; for more
details.Once you have a set of diffs (which you may test with the
&man.patch.1; command), you should submit them for inclusion with
FreeBSD. Use the &man.send-pr.1; program as described in Bug Reports and General Commentary.
Do not just send the diffs to the &a.hackers; or
they will get lost! We greatly appreciate your submission (this is a
volunteer project!); because we are busy, we may not be able to
address it immediately, but it will remain in the pr database until we
do.uuencodeIf you feel it appropriate (e.g. you have added, deleted, or
renamed files), bundle your changes into a tar file
and run the &man.uuencode.1; program on it. Shar archives are also
welcome.If your change is of a potentially sensitive nature, e.g. you are
unsure of copyright issues governing its further distribution or you
are simply not ready to release it without a tighter review first,
then you should send it to &a.core; directly rather than submitting it
with &man.send-pr.1;. The core mailing list reaches a much smaller
group of people who do much of the day-to-day work on FreeBSD. Note
that this group is also very busy and so you
should only send mail to them where it is truly necessary.Please refer to &man.intro.9; and &man.style.9; style for
some information on coding style. We would appreciate it if you
were at least aware of this information before submitting
code.New code or major value-added packagesIn the case of a significant contribution of a large body
work, or the addition of an important new feature to FreeBSD, it
becomes almost always necessary to either send changes as uuencoded
tar files or upload them to a web or FTP site for other people to
access. If you do not have access to a web or FTP site, ask on an
appropriate FreeBSD mailing list for someone to host the changes for
you.When working with large amounts of code, the touchy subject of
copyrights also invariably comes up. Acceptable copyrights for code
included in FreeBSD are:BSD copyrightThe BSD copyright. This copyright is most preferred due to
its no strings attached nature and general
attractiveness to commercial enterprises. Far from discouraging
such commercial use, the FreeBSD Project actively encourages such
participation by commercial interests who might eventually be
inclined to invest something of their own into FreeBSD.GPLGNU General Public LicenseGNU General Public LicenseThe GNU General Public License, or GPL.
This license is not quite as popular with us due to the amount
of extra effort demanded of anyone using the code for
commercial purposes, but given the sheer quantity of GPL'd code
we currently require (compiler, assembler, text formatter, etc)
it would be silly to refuse additional contributions under this
license. Code under the GPL also goes into a different part of
the tree, that being /sys/gnu or
/usr/src/gnu, and is therefore easily
identifiable to anyone for whom the GPL presents a
problem.Contributions coming under any other type of copyright must be
carefully reviewed before their inclusion into FreeBSD will be
considered. Contributions for which particularly restrictive
commercial copyrights apply are generally rejected, though the authors
are always encouraged to make such changes available through their own
channels.To place a BSD-style copyright on your work, include
the following text at the very beginning of every source code file you
wish to protect, replacing the text between the %%
with the appropriate information.Copyright (c) %%proper_years_here%%
%%your_name_here%%, %%your_state%% %%your_zip%%.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer as
the first lines of this file unmodified.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
$Id$For your convenience, a copy of this text can be found in
/usr/share/examples/etc/bsd-style-copyright.Money, Hardware or Internet accessWe are always very happy to accept donations to further the cause
of the FreeBSD Project and, in a volunteer effort like ours, a little
can go a long way! Donations of hardware are also very important to
expanding our list of supported peripherals since we generally lack
the funds to buy such items ourselves.Donating fundsThe FreeBSD Foundation is a non-profit, tax-exempt
foundation established to further the goals of the FreeBSD
Project. As a 501(c)3 entity, the Foundation is generally
exempt from US federal income tax as well as Colorado
State income tax. Donations to a tax-exempt entity are
often deductible from taxable federal income.Donations may be sent in check form to:
The FreeBSD Foundation
7321 Brockway Dr.Boulder, CO80303USA
The Foundation is not yet able to accept other forms
of payment such as credit cards and PayPal.More information about the FreeBSD Foundation can be
found in The
FreeBSD Foundation -- an Introduction. To contact
the Foundation by email, write to
bod@FreeBSDFoundation.org.Donating hardwaredonationsDonations of hardware in any of the 3 following categories are
also gladly accepted by the FreeBSD Project:General purpose hardware such as disk drives, memory or
complete systems should be sent to the FreeBSD, Inc. address
listed in the donating funds
section.Hardware for which ongoing compliance testing is desired.
We are currently trying to put together a testing lab of all
components that FreeBSD supports so that proper regression
testing can be done with each new release. We are still lacking
many important pieces (network cards, motherboards, etc) and if
you would like to make such a donation, please contact &a.dg;
for information on which items are still required.Hardware currently unsupported by FreeBSD for which you
would like to see such support added. Please contact the
&a.core; before sending such items as we will need to find a
developer willing to take on the task before we can accept
delivery of new hardware.Donating Internet accessWe can always use new mirror sites for FTP, WWW or
cvsup. If you would like to be such a mirror,
please contact the FreeBSD project administrators
hubs@FreeBSD.org for more information.
diff --git a/en_US.ISO8859-1/books/handbook/disks/chapter.sgml b/en_US.ISO8859-1/books/handbook/disks/chapter.sgml
index c63b10dff4..3f226ece20 100644
--- a/en_US.ISO8859-1/books/handbook/disks/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/disks/chapter.sgml
@@ -1,1257 +1,1275 @@
DisksSynopsisThis chapter covers how to use disks, whether physical,
memory, or networked, on FreeBSD.BIOS Drive NumberingBefore you install and configure FreeBSD on your system, there is an
important subject that you should be aware of, especially if you have
multiple hard drives.DOSMicrosoft WindowsIn a PC running DOS or any of the BIOS-dependent operating systems
(WINxxx), the BIOS is able to abstract the normal disk drive order, and
the operating system goes along with the change. This allows the user
to boot from a disk drive other than the so-called primary
master. This is especially convenient for some users who have
found that the simplest and cheapest way to keep a system backup is to
buy an identical second hard drive, and perform routine copies of the
first drive to the second drive using
Ghost or XCOPY
. Then, if the
first drive fails, or is attacked by a virus, or is scribbled upon by an
operating system defect, he can easily recover by instructing the BIOS
to logically swap the drives. It's like switching the cables on the
drives, but without having to open the case.SCSIBIOSMore expensive systems with SCSI controllers often include BIOS
extensions which allow the SCSI drives to be re-ordered in a similar
fashion for up to seven drives.A user who is accustomed to taking advantage of these features may
become surprised when the results with FreeBSD are not as expected.
FreeBSD does not use the BIOS, and does not know the logical BIOS
drive mapping. This can lead to very perplexing situations,
especially when drives are physically identical in geometry, and have
also been made as data clones of one another.When using FreeBSD, always restore the BIOS to natural drive
numbering before installing FreeBSD, and then leave it that way. If you
need to switch drives around, then do so, but do it the hard way, and
open the case and move the jumpers and cables.An illustration from the files of Bill and Fred's Exceptional
Adventures:Bill breaks-down an older Wintel box to make another FreeBSD box
for Fred. Bill installs a single SCSI drive as SCSI unit zero, and
installs FreeBSD on it.Fred begins using the system, but after several days notices that
the older SCSI drive is reporting numerous soft errors, and reports
this fact to Bill.After several more days, Bill decides it's time to address the
situation, so he grabs an identical SCSI drive from the disk drive
"archive" in the back room. An initial surface scan indicates that
this drive is functioning well, so Bill installs this drive as SCSI
unit four, and makes an image copy from drive zero to drive four. Now
that the new drive is installed and functioning nicely, Bill decides
that it's a good idea to start using it, so he uses features in the
SCSI BIOS to re-order the disk drives so that the system boots from
SCSI unit four. FreeBSD boots and runs just fine.Fred continues his work for several days, and soon Bill and Fred
decide that it's time for a new adventure -- time to upgrade to a
newer version of FreeBSD. Bill removes SCSI unit zero because it was
a bit flaky, and replaces it with another identical disk drive from
the "archive." Bill then installs the new version of FreeBSD onto the
new SCSI unit zero using Fred's magic Internet FTP floppies. The
installation goes well.Fred uses the new version of FreeBSD for a few days, and certifies
that it is good enough for use in the engineering department...it's
time to copy all of his work from the old version. So Fred mounts
SCSI unit four (the latest copy of the older FreeBSD version). Fred
is dismayed to find that none of his precious work is present on SCSI
unit four.Where did the data go?When Bill made an image copy of the original SCSI unit zero onto
SCSI unit four, unit four became the "new clone," When Bill
re-ordered the SCSI BIOS so that he could boot from SCSI unit four, he
was only fooling himself. FreeBSD was still running on SCSI unit zero.
Making this kind of BIOS change will cause some or all of the Boot and
Loader code to be fetched from the selected BIOS drive, but when the
FreeBSD kernel drivers take-over, the BIOS drive numbering will be
ignored, and FreeBSD will transition back to normal drive numbering.
In the illustration at hand, the system continued to operate on the
original SCSI unit zero, and all of Fred's data was there, not on SCSI
unit four. The fact that the system appeared to be running on SCSI
unit four was simply an artifact of human expectations.We are delighted to mention that no data bytes were killed or
harmed in any way by our discovery of this phenomenon. The older SCSI
unit zero was retrieved from the bone pile, and all of Fred's work was
returned to him, (and now Bill knows that he can count as high as
zero).Although SCSI drives were used in this illustration, the concepts
apply equally to IDE drives.Disk NamingIDESCSIRAIDfash memoryPhysical drives come in two main flavors,
IDE, or SCSI; but there
are also drives backed by RAID controllers, flash memory, and so
forth. Since these behave quite differently, they have their
own drivers and devices.
Physical Disk Naming ConventionsDrive typeDrive device nameIDE hard drivesad in 4.0-RELEASE,
wd before 4.0-RELEASE.IDE CDROM drivesacd from 4.1-RELEASE,
wcd before 4.0-RELEASE.SCSI hard drivesda from 3.0-RELEASE,
sd before 3.0-RELEASE.SCSI CDROM drivescdAssorted non-standard CDROM drivesmcd for Mitsumi CD-ROM,
scd for Sony CD-ROM,
matcd for Matsushita/Panasonic CD-ROM
Floppy drivesfdSCSI tape drivessa from 3.0-RELEASE,
st before 3.0-RELEASE.IDE tape drivesast from 4.0-RELEASE,
wst before 4.0-RELEASE.Flash drivesfla for DiskOnChip Flash device
from 3.3-RELEASE.RAID drivesmyxd for Mylex, and
amrd for AMI MegaRAID,
idad for Compaq Smart RAID.
from 4.0-RELEASE. id between
3.2-RELEASE and 4.0-RELEASE.
Slices and Partitionsslicespartitionsdangerously dedicatedPhysical disks usually contain
slices, unless they are
dangerously dedicated. Slice numbers follow
the device name, prefixed with an s:
da0s1.Slices, dangerously dedicated physical
drives, and other drives contain
partitions, which represented as
letters from a to h.
b is reserved for swap partitions, and
c is an unused partition the size of the
entire slice or drive. This is explained in .Mounting and Unmounting FilesystemsThe filesystem is best visualized as a tree,
rooted, as it were, at /.
/dev, /usr, and the
other directories in the root directory are branches, which may
have their own branches, such as
/usr/local, and so on.root filesystemThere are various reasons to house some of these
directories on separate filesystems. /var
contains the directories log/,
spool/,
and various types of temporary files, and
as such, may get filled up. Filling up the root filesystem
isn't a good idea, so splitting /var from
/ is often favorable.Another common reason to contain certain directory trees on
other filesystems is if they are to be housed on separate
physical disks, or are separate virtual disks, such as Network File System mounts, or CDROM
drives.The fstab Filefilesystemsmounted with fstabDuring the boot process,
filesystems listed in /etc/fstab are
automatically mounted (unless they are listed with
).The /etc/fstab file contains a list
of lines of the following format:device/mount-pointfstypeoptionsdumpfreqpassnodeviceA device name (which should exist), as explained in
the Disk naming
conventions above.mount-pointA directory (which should exist), on which
to mount the filesystem.fstypeThe filesystem type to pass to
&man.mount.8;. The default FreeBSD filesystem is
ufs.optionsEither for read-write
filesystems, or for read-only
filesystems, followed by any other options that may be
needed. A common option is for
filesystems not normally mounted during the boot sequence.
Other options in the &man.mount.8; manual page.dumpfreqThe number of days the filesystem should be
dumped, and passno is the pass number
during which the filesystem is checked during the boot
sequence.The mount CommandfilesystemsmountingThe &man.mount.8; command is what is ultimately used to
mount filesystems.In its most basic form, you use:&prompt.root; mount devicemountpointThere are plenty of options, as mentioned in the
&man.mount.8; manual page, but the most common are:Mount OptionsMount all filesystems in
/etc/fstab, as modified by
, if given.Do everything but actually mount the
filesystem.Force the mounting the filesystem.Mount the filesystem read-only.fstypeMount the given filesystem as the given filesystem
type, or mount only filesystems of the given type, if
given the option.ufs is the default filesystem
type.Update mount options on the filesystem.Be verbose.Mount the filesystem read-write.The takes a comma-separated list of
the options, including the following:nodevDo not interpret special devices on the
filesystem. Useful security option.noexecDo not allow execution of binaries on this
filesystem. Useful security option.nosuidDo not interpret setuid or setgid flags on the
filesystem. Useful security option.The umount CommandfilesystemsunmountingThe &man.umount.8; command takes, as a parameter, one of a
mountpoint, a device name, or the or
option.All forms take to force unmounting,
and for verbosity. and are used to
unmount all mounted filesystems, possibly modified by the
filesystem types listed after .
, however, doesn't attempt to unmount the
root filesystem.
+
+
+
+ David
+ O'Brien
+ Originally contributed by
+
+
+
+
+
Adding Disks
+
disksadding
- Originally contributed by &a.obrien; 26 April
- 1998
-
Lets say we want to add a new SCSI disk to a machine that
currently only has a single drive. First turn off the computer
and install the drive in the computer following the instructions
of the computer, controller, and drive manufacturer. Due the
wide variations of procedures to do this, the details are beyond
the scope of this document.Login as user root. After you've installed the
drive, inspect /var/run/dmesg.boot to ensure the new
disk was found. Continuing with our example, the newly added drive will
be da1 and we want to mount it on
/1 (if you are adding an IDE drive, the device name
will be wd1 in pre-4.0 systems, or
ad1 in most 4.X systems).partitionsslicesfdiskBecause FreeBSD runs on IBM-PC compatible computers, it must
take into account the PC BIOS partitions. These are different
from the traditional BSD partitions. A PC disk has up to four
BIOS partition entries. If the disk is going to be truly
dedicated to FreeBSD, you can use the
dedicated mode. Otherwise, FreeBSD will
have to live within one of the PC BIOS partitions. FreeBSD
calls the PC BIOS partitions slices so as
not to confuse them with traditional BSD partitions. You may
also use slices on a disk that is dedicated to FreeBSD, but used
in a computer that also has another operating system installed.
This is to not confuse the fdisk utility of
the other operating system.In the slice case the drive will be added as
/dev/da1s1e. This is read as: SCSI disk,
unit number 1 (second SCSI disk), slice 1 (PC BIOS partition 1),
and e BSD partition. In the dedicated
case, the drive will be added simply as
/dev/da1e.Using &man.sysinstall.8;sysinstalladding disksNavigating SysinstallYou may use /stand/sysinstall to
partition and label a new disk using its easy to use menus.
Either login as user root or use the
su command. Run
/stand/sysinstall and enter the
Configure menu. Within the
FreeBSD Configuration Menu, scroll down and
select the Partition item. Next you should
be presented with a list of hard drives installed in your
system. If you do not see da1 listed, you
need to recheck your physical installation and
dmesg output in the file
/var/run/dmesg.boot.FDISK Partition EditorSelect da1 to enter the FDISK
Partition Editor. Type A to
use the entire disk for FreeBSD. When asked if you want to
remain cooperative with any future possible operating
systems, answer YES. Write the
changes to the disk using W. Now exit the
FDISK editor by typing q. Next you will be
asked about the Master Boot Record. Since you are adding a
disk to an already running system, choose
None.Disk Label EditorBSD partitionsNext, Sysinstall will
enter the Disk Label Editor. This
is where you will create the traditional BSD partitions. A
disk can have up to eight partitions, labeled
a-h.
A few of
the partition labels have special uses. The
a partition is used for the root partition
(/). Thus only your system disk (e.g,
the disk you boot from) should have an a
partition. The b partition is used for
swap partitions, and you may have many disks with swap
partitions. The c partition addresses the
entire disk in dedicated mode, or the entire FreeBSD slice in
slice mode. The other partitions are for general use.Sysinstall's Label editor
favors the e
partition for non-root, non-swap partitions. Within the
Label editor, create a single file system by typing
C. When prompted if this will be a FS
(file system) or swap, choose FS and type in a
mount point (e.g, /mnt). When adding a
disk in post-install mode, Sysinstall
will not create entries
in /etc/fstab for you, so the mount point
you specify isn't important.You are now ready to write the new label to the disk and
create a file system on it. Do this by typing
W. Ignore any errors from
Sysinstall that
it could not mount the new partition. Exit the Label Editor
and Sysinstall completely.FinishThe last step is to edit /etc/fstab
to add an entry for your new disk.Using Command Line UtilitiesUsing SlicesThis setup will allow your disk to work correctly with
other operating systems that might be installed on your
computer and will not confuse other operating systems'
fdisk utilities. It is recommended
to use this method for new disk installs. Only use
dedicated mode if you have a good reason
to do so!&prompt.root; dd if=/dev/zero of=/dev/rda1 bs=1k count=1
&prompt.root; fdisk -BI da1 #Initialize your new disk
&prompt.root; disklabel -B -w -r da1s1 auto #Label it.
&prompt.root; disklabel -e da1s1 # Edit the disklabel just created and add any partitions.
&prompt.root; mkdir -p /1
&prompt.root; newfs /dev/da1s1e # Repeat this for every partition you created.
&prompt.root; mount -t ufs /dev/da1s1e /1 # Mount the partition(s)
&prompt.root; vi /etc/fstab # Add the appropriate entry/entries to your /etc/fstab.If you have an IDE disk, substitute ad
for da. On pre-4.X systems use
wd.DedicatedOS/2If you will not be sharing the new drive with another operating
system, you may use the dedicated mode. Remember
this mode can confuse Microsoft operating systems; however, no damage
will be done by them. IBM's OS/2 however, will
appropriate any partition it finds which it doesn't
understand.&prompt.root; dd if=/dev/zero of=/dev/rda1 bs=1k count=1
&prompt.root; disklabel -Brw da1 auto
&prompt.root; disklabel -e da1 # create the `e' partition
&prompt.root; newfs -d0 /dev/rda1e
&prompt.root; mkdir -p /1
&prompt.root; vi /etc/fstab # add an entry for /dev/da1e
&prompt.root; mount /1An alternate method is:&prompt.root; dd if=/dev/zero of=/dev/rda1 count=2
&prompt.root; disklabel /dev/rda1 | disklabel -BrR da1 /dev/stdin
&prompt.root; newfs /dev/rda1e
&prompt.root; mkdir -p /1
&prompt.root; vi /etc/fstab # add an entry for /dev/da1e
&prompt.root; mount /1Virtual Disks: Network, Memory, and File-Based Filesystemsvirtual disksdisksvirtualAside from the disks you physically insert into your computer:
floppies, CDs, hard drives, and so forth; other forms of disks
are understood by FreeBSD - the virtual
disks.NFSCodadisksmemoryThese include network filesystems such as the Network Filesystem and Coda, memory-based
filesystems such as md and
file-backed filesystems created by vnconfig.vnconfig: File-Backed Filesystemdisksfile-backed&man.vnconfig.8; configures and enables vnode pseudo-disk
devices. A vnode is a representation
of a file, and is the focus of file activity. This means that
&man.vnconfig.8; uses files to create and operate a
filesystem. One possible use is the mounting of floppy or CD
images kept in files.To mount an existing filesystem image:Using vnconfig to mount an existing filesystem
image&prompt.root; vnconfig vn0diskimage
&prompt.root; mount /dev/vn0c /mntTo create a new filesystem image with vnconfig:Creating a New File-Backed Disk with vnconfig&prompt.root; dd if=/dev/zero of=newimage bs=1k count=5k
5120+0 records in
5120+0 records out
&prompt.root; vnconfig -s labels -c vn0newimage
&prompt.root; disklabel -r -w vn0 auto
&prompt.root; newfs vn0c
Warning: 2048 sector(s) in last cylinder unallocated
/dev/rvn0c: 10240 sectors in 3 cylinders of 1 tracks, 4096 sectors
5.0MB in 1 cyl groups (16 c/g, 32.00MB/g, 1280 i/g)
super-block backups (for fsck -b #) at:
32
&prompt.root; mount /dev/vn0c /mnt
&prompt.root; df /mnt
Filesystem 1K-blocks Used Avail Capacity Mounted on
/dev/vn0c 4927 1 4532 0% /mntmd: Memory Filesystemdisksmemory filesystemmd is a simple, efficient means to do memory
filesystems.Simply take a filesystem you've prepared with, for
example, &man.vnconfig.8;, and:md memory disk&prompt.root; dd if=newimage of=/dev/md0
5120+0 records in
5120+0 records out
&prompt.root; mount /dev/md0c/mnt
&prompt.root; df /mnt
Filesystem 1K-blocks Used Avail Capacity Mounted on
/dev/md0c 4927 1 4532 0% /mntDisk Quotasaccountingdisk spacedisk quotasQuotas are an optional feature of the operating system that
allow you to limit the amount of disk space and/or the number of
files a user, or members of a group, may allocate on a per-file
system basis. This is used most often on timesharing systems where
it is desirable to limit the amount of resources any one user or
group of users may allocate. This will prevent one user from
consuming all of the available disk space.Configuring Your System to Enable Disk QuotasBefore attempting to use disk quotas it is necessary to make
sure that quotas are configured in your kernel. This is done by
adding the following line to your kernel configuration
file:options QUOTAThe stock GENERIC kernel does not have
this enabled by default, so you will have to configure, build and
install a custom kernel in order to use disk quotas. Please refer
to the Configuring the FreeBSD
Kernel section for more information on kernel
configuration.Next you will need to enable disk quotas in
/etc/rc.conf. This is done by adding the
line:enable_quotas=YESdisk quotascheckingFor finer control over your quota startup, there is an
additional configuration variable available. Normally on bootup,
the quota integrity of each file system is checked by the
quotacheck program. The
quotacheck facility insures that the data in
the quota database properly reflects the data on the file system.
This is a very time consuming process that will significantly
affect the time your system takes to boot. If you would like to
skip this step, a variable in /etc/rc.conf
is made available for the purpose:check_quotas=NOIf you are running FreeBSD prior to 3.2-RELEASE, the
configuration is simpler, and consists of only one variable. Set
the following in your /etc/rc.conf:check_quotas=YESFinally you will need to edit /etc/fstab
to enable disk quotas on a per-file system basis. This is where
you can either enable user or group quotas or both for all of your
file systems.To enable per-user quotas on a file system, add the
userquota option to the options field in the
/etc/fstab entry for the file system you want
to enable quotas on. For example:/dev/da1s2g /home ufs rw,userquota 1 2Similarly, to enable group quotas, use the
groupquota option instead of the
userquota keyword. To enable both user and
group quotas, change the entry as follows:/dev/da1s2g /home ufs rw,userquota,groupquota 1 2By default the quota files are stored in the root directory of
the file system with the names quota.user and
quota.group for user and group quotas
respectively. See &man.fstab.5; for more
information. Even though the &man.fstab.5; man page says that
you can specify
an alternate location for the quota files, this is not recommended
because the various quota utilities do not seem to handle this
properly.At this point you should reboot your system with your new
kernel. /etc/rc will automatically run the
appropriate commands to create the initial quota files for all of
the quotas you enabled in /etc/fstab, so
there is no need to manually create any zero length quota
files.In the normal course of operations you should not be required
to run the quotacheck,
quotaon, or quotaoff
commands manually. However, you may want to read their man pages
just to be familiar with their operation.Setting Quota Limitsdisk quotaslimitsOnce you have configured your system to enable quotas, verify
that they really are enabled. An easy way to do this is to
run:&prompt.root; quota -vYou should see a one line summary of disk usage and current
quota limits for each file system that quotas are enabled
on.You are now ready to start assigning quota limits with the
edquota command.You have several options on how to enforce limits on the
amount of disk space a user or group may allocate, and how many
files they may create. You may limit allocations based on disk
space (block quotas) or number of files (inode quotas) or a
combination of both. Each of these limits are further broken down
into two categories; hard and soft limits.hard limitA hard limit may not be exceeded. Once a user reaches his
hard limit he may not make any further allocations on the file
system in question. For example, if the user has a hard limit of
500 blocks on a file system and is currently using 490 blocks, the
user can only allocate an additional 10 blocks. Attempting to
allocate an additional 11 blocks will fail.soft limitSoft limits, on the other hand, can be exceeded for a limited
amount of time. This period of time is known as the grace period,
which is one week by default. If a user stays over his or her
soft limit longer than the grace period, the soft limit will
turn into a hard limit and no further allocations will be allowed.
When the user drops back below the soft limit, the grace period
will be reset.The following is an example of what you might see when you run
the edquota command. When the
edquota command is invoked, you are placed into
the editor specified by the EDITOR environment
variable, or in the vi editor if the
EDITOR variable is not set, to allow you to edit
the quota limits.&prompt.root; edquota -u testQuotas for user test:
/usr: blocks in use: 65, limits (soft = 50, hard = 75)
inodes in use: 7, limits (soft = 50, hard = 60)
/usr/var: blocks in use: 0, limits (soft = 50, hard = 75)
inodes in use: 0, limits (soft = 50, hard = 60)You will normally see two lines for each file system that has
quotas enabled. One line for the block limits, and one line for
inode limits. Simply change the value you want updated to modify
the quota limit. For example, to raise this users block limit
from a soft limit of 50 and a hard limit of 75 to a soft limit of
500 and a hard limit of 600, change:/usr: blocks in use: 65, limits (soft = 50, hard = 75)to: /usr: blocks in use: 65, limits (soft = 500, hard = 600)The new quota limits will be in place when you exit the
editor.Sometimes it is desirable to set quota limits on a range of
uids. This can be done by use of the option
on the edquota command. First, assign the
desired quota limit to a user, and then run
edquota -p protouser startuid-enduid. For
example, if user test has the desired quota
limits, the following command can be used to duplicate those quota
limits for uids 10,000 through 19,999:&prompt.root; edquota -p test 10000-19999See the &man.edquota.8; for more detailed
information.Checking Quota Limits and Disk Usagedisk quotascheckingYou can use either the quota or the
repquota commands to check quota limits and
disk usage. The quota command can be used to
check individual user and group quotas and disk usage. Only the
super-user may examine quotas and usage for other users, or for
groups that they are not a member of. The
repquota command can be used to get a summary
of all quotas and disk usage for file systems with quotas
enabled.The following is some sample output from the
quota -v command for a user that has quota
limits on two file systems.Disk quotas for user test (uid 1002):
Filesystem blocks quota limit grace files quota limit grace
/usr 65* 50 75 5days 7 50 60
/usr/var 0 50 75 0 50 60grace periodOn the /usr file system in the above
example this user is currently 15 blocks over the soft limit of
50 blocks and has 5 days of the grace period left. Note the
asterisk * which indicates that the user is
currently over his quota limit.Normally file systems that the user is not using any disk
space on will not show up in the output from the
quota command, even if he has a quota limit
assigned for that file system. The option
will display those file systems, such as the
/usr/var file system in the above
example.Quotas over NFSNFSQuotas are enforced by the quota subsystem on the NFS server.
The &man.rpc.rquotad.8; daemon makes quota information available
to the &man.quota.1; command on NFS clients, allowing users on
those machines to see their quota statistics.Enable rpc.rquotad in
/etc/inetd.conf like so:rquotad/1 dgram rpc/udp wait root /usr/libexec/rpc.rquotad rpc.rquotadNow restart inetd:&prompt.root; kill -HUP `cat /var/run/inetd.pid`
+
+
+
+ Mike
+ Meyer
+ Contributed by
+
+
+
+
+
+
Creating CDsCDROMscreating
- Contributed by Mike Meyer
- mwm@mired.org, April 2001.
-
IntroductionCDs have a number of features that differentiate them from
conventional disks. Initially, they weren't writable by the
user. They are designed so that they can be read continuously without
delays to move the head between tracks. They are also much easier
to transport between systems than similarly sized media were at the
time.CDs do have tracks, but this refers to a section of data to
be read continuously and not a physical property of the disk. To
produce a CD on FreeBSD, you prepare the data files that are going
to make up the tracks on the CD, then write the tracks to the
CD.ISO 9660filesystemsISO-9660The ISO 9660 file system was designed to deal with these
differences. It unfortunately codifies file system limits that were
common then. Fortunately, it provides an extension mechanism that
allows properly written CDs to exceed those limits while still
working with systems that do not support those extensions.mkisofsThe mkisofs
program is used to produce a data file containing an ISO 9660 file
system. It has options that support various extensions, and is
described below. You can install it with the
sysutils/mkisofs port.CD burnerATAPIWhich tool to use to burn the CD depends on whether your CD burner
is ATAPI or something else. ATAPI CD burners use the burncd program that is part of
the base system. SCSI and USB CD burners should use the
cdrecord from
the sysutils/cdrtools port.burncd has a limited number of
supported drives. To find out if a drive is supported, see
CD-R/RW supported
drives.mkisofsmkisofs produces an ISO 9660 file system
that is an image of a directory tree in the Unix file system name
space. The simplest usage is:&prompt.root; mkisofs imagefile.iso/path/to/treefilesystemsISO-9660This command will create an imagefile
containing an ISO 9660 file system that is a copy of the tree at
/path/to/tree. In the process, it will
map the file names to names that fit the limitations of the
standard ISO 9660 file system, and will exclude files that have
names uncharacteristic of ISO file systems.filesystemsHFSfilesystemsJolietA number of options are available to overcome those
restrictions. In particular, enables the
Rock Ridge extensions common to Unix systems,
enables Joliet extensions used by Microsoft systems, and
can be used to create HFS file systems used
by MacOS.For CDs that are going to be used only on FreeBSD systems,
can be used to disable all filename
restrictions. When used with , it produces a
file system image that is identical to the FreeBSD tree you started
from, though it may violate the ISO 9660 standard in a number of
ways.CDROMscreating bootableThe last option of general use is . This is
used to specify the location of the boot image for use in producing an
El Torito bootable CD. This option takes an
argument which is the path to a boot image from the top of the
tree being written to the CD. So, given that
/tmp/myboot holds a bootable FreeBSD system
with the boot image in
/tmp/myboot/boot/cdboot, you could produce the
image of an ISO 9660 file system in
/tmp/bootable.iso like so:&prompt.root; mkisofs boot/cdboot/tmp/bootable.iso/tmp/mybootHaving done that, if you have vn
configured in your kernel, you can mount the file system with:&prompt.root; vnconfig vn0c/tmp/bootable.iso
&prompt.root; mount cd9660 /dev/vn0c/mntAt which point you can verify that /mnt
and /tmp/myboot are identical.There are many other options you can use with
mkisofs to fine-tune its behavior. In particular:
modifications to an ISO 9660 layout and the creation of Joilet
and HFS discs. See the &man.mkisofs.8; man page for details.burncdCDROMsburningIf you have an ATAPI CD burner, you can use the
burncd command to burn an ISO image onto a
CD. burncd is part of the base system, installed
as /usr/sbin/burncd. Usage is very simple, as
it has few options:&prompt.root; burncd cddevice data imagefile.iso fixateWill burn a copy of imagefile.iso on
cddevice. The default device is
/dev/acd0. See &man.burncd.8; for options to
set the write speed, eject the CD after burning, and write audio
data.cdrecordIf you do not have an ATAPI CD burner, you will have to use
cdrecord to burn your
CDs. cdrecord is not part of the base system;
you must install it from either the port at sysutils/cdrtools
or the appropriate
package. Changes to the base system can cause binary versions of
this program to fail, possibly resulting in a
coaster. You should therefore either upgrade the
port when you upgrade your system, or if you are tracking -STABLE, upgrade the port when a
new version becomes available.While cdrecord has many options, basic usage
is even simpler than burncd. Burning an ISO 9660
image is done with:&prompt.root; cdrecord deviceimagefile.isoThe tricky part of using cdrecord is finding
the to use. To find the proper setting, use
the flag of cdrecord,
which might produce results like this:CDROMsburning&prompt.root; cdrecord
Cdrecord 1.9 (i386-unknown-freebsd4.2) Copyright (C) 1995-2000 Jörg Schilling
Using libscg version 'schily-0.1'
scsibus0:
0,0,0 0) 'SEAGATE ' 'ST39236LW ' '0004' Disk
0,1,0 1) 'SEAGATE ' 'ST39173W ' '5958' Disk
0,2,0 2) *
0,3,0 3) 'iomega ' 'jaz 1GB ' 'J.86' Removable Disk
0,4,0 4) 'NEC ' 'CD-ROM DRIVE:466' '1.26' Removable CD-ROM
0,5,0 5) *
0,6,0 6) *
0,7,0 7) *
scsibus1:
1,0,0 100) *
1,1,0 101) *
1,2,0 102) *
1,3,0 103) *
1,4,0 104) *
1,5,0 105) 'YAMAHA ' 'CRW4260 ' '1.0q' Removable CD-ROM
1,6,0 106) 'ARTEC ' 'AM12S ' '1.06' Scanner
1,7,0 107) *This lists the appropriate value for the
devices on the list. Locate your CD burner, and use the three
numbers separated by commas as the value for
. In this case, the CRW device is 1,5,0, so the
appropriate input would be
=1,5,0. There are easier
ways to specify this value; see &man.cdrecord.1; for
details. That is also the place to look for information on writing
audio tracks, controlling the speed, and other things.
diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.sgml b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
index d6f0698638..3855287e37 100644
--- a/en_US.ISO8859-1/books/handbook/install/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/install/chapter.sgml
@@ -1,2121 +1,2130 @@
JimMockRestructured, reorganized, and parts
- rewritten
+ rewritten by
Installing FreeBSDSynopsisinstallationThe following chapter will attempt to guide you through the
installation of FreeBSD on your system. It can be installed through a
variety of methods, including anonymous FTP (assuming you have
network connectivity via modem or local network), CDROM, floppy
disk, tape, an MS-DOS partition, or even NFS.No matter which method you choose, you will need to get started
by creating the installation disks as described
in the next section.
Booting into the FreeBSD installer, even if you are not planning on
installing FreeBSD right away, will provide important information
about compatibility with your hardware. This information may
dictate which installation options are even possible for you. It
can also provide clues early-on in the process to potential problems
you may come across later.installationnetworkanonymous FTPIf you plan to install FreeBSD via anonymous FTP, the only
things you will need are the installation floppies. The
installation program itself will handle anything else that is
required.For more information about obtaining FreeBSD, see the Obtaining FreeBSD section of the
Appendix.By now, you are probably wondering what exactly it is you need
to do. Continue on to the installation guide.Installation GuideThe following sections will guide you through preparing for and
actually installing FreeBSD. If you find something missing, please
let us know about it by sending email to the &a.doc;.Preparing for the InstallationThere are various things you should do in preparation for the
installation. The following describes what needs to be done prior to
each type of installation.The first thing to do is to make sure your hardware is
supported by FreeBSD. The list of supported hardware should
come in handy here. It would also be a good idea to make a
list of any special cards you have installed,
such as SCSI controllers, Ethernet cards, sound cards, etc..
The list should include their IRQs and IO port addresses.Creating the Installation Floppiesinstallationboot floppiesinstallationCDROMYou may need to prepare some floppy disks. These disks will
be used to boot your computer in to the FreeBSD install process.
This step is not necessary if you are
installing from CDROM, and your computer
supports booting from the CDROM. If you do not meet these
requirements then you will need to create some floppies to boot
from.If you are not sure whether your computer can boot from the
CDROM it does not hurt to try. Just insert the CDROM as
normal and restart your computer. You might need to adjust some
options in your BIOS so that your computer will try and boot
from the CDROM drive before the hard disk.Even if you have the CDROM it might make sense for you to
download the files. There have been occasions where bugs in the
FreeBSD installer have been discovered after the CDs have been
released. When this happens the copies of the images on the FTP
site will be fixed as soon as possible. Obviously, it is not
possible to update the CDs after they have been pressed.Acquire the boot floppy imagesThese are files with a .flp
extension. If you have a CDROM release of FreeBSD then you
will find the files in the floppies
subdirectory. Alternatively, you can download the images from
the floppies directory of the FreeBSD FTP site or your local mirror.The names of the files you will need varies between
FreeBSD releases (sometimes) and the architecture you will be
installing on. The installation
boot image information on the FTP site provides
up-to-the-minute information about the specific files you will
need.Prepare the floppy disksYou must prepare one floppy disk per image file you had to
download. It is imperative that these disks are free from
defects. The easiest way to test this is to format the disks
for yourself. Do not trust pre-formatted floppies.If you try to install FreeBSD and the installation
program crashes, freezes, or otherwise misbehaves one of
the first things to suspect is the floppies. Try writing
the floppy image files to some other disks, and try
again.Write the image files to the floppy disks.The image files, such as kern.flp,
are not regular files you copy to the
disk. Instead, they are images of the complete contents of
the disk.This means that you can not use
commands like DOS' copy to write the
files. Instead, you must use specific tools to write the
images directly to the disk.DOSIf you are creating the floppies on a computer running DOS
then we provide a tool to do this called
fdimage.If you are using the floppies from the CDROM, and your
CDROM is the E: drive then you would
run this:E:\>tools\fdimage floppies\kern.flp A:Repeat this command for each .flp
file, replacing the floppy disk each time. Adjust the command
line as necessary, depending on where you have placed the
.flp files. If you do not have the
CDROM then fdimage can be downloaded from
the tools directory on the FreeBSD FTP site.If you are writing the floppies on a Unix system (such as
another FreeBSD system) you can use the &man.dd.1; command to
write the image files directly to disk. On FreeBSD you would
run:&prompt.root; dd if=kern.flp of=/dev/fd0On FreeBSD /dev/fd0 refers to the
first floppy disk (the A: drive).
/dev/fd1 would be the
B: drive, and so on. Other Unix
variants might have different names for the floppy disk
devices, and you will need to check the documentation for the
system as necessary.Before Installing from CDROMIf your CDROM is of an unsupported type, please skip ahead
to the MS-DOS Preparation
section.There is not a whole lot of preparation needed if you are
installing from a FreeBSD CDROM. You can either boot into the
CD installation directly from DOS using the
install.bat or you can make floppies with
the makeflp.bat command.If the CD has El Torito boot support and your system
supports booting directly from the CDROM drive (many older
systems do NOT), simply insert the first
CD of the set into the drive and reboot your system. You
will be put into the installation menu directly from the CD.DOSIf you are installing from an MS-DOS partition and have
the proper drivers to access your CD, run the
install.bat script provided on the CDROM.
This will attempt to boot the FreeBSD installation directly
from DOS.You must do this from actual DOS (i.e., boot in DOS
mode) and not from a DOS window under Windows.For the easiest interface of all (from DOS), type
view. This will bring up a DOS menu utility
that leads you through all of the available options.UnixIf you are creating the boot floppies from a Unix machine,
see the Creating the Boot
Floppies section of this guide for examples.Once you have booted from DOS or floppy, you should then be
able to select CDROM as the media type during the install
process and load the entire distribution from CDROM. No other
types of installation media should be required.After your system is fully installed and you have rebooted
(from the hard disk), you can mount the CDROM at any time by
typing:&prompt.root; mount /cdromBefore removing the CD from the drive again, you must first
unmount it. This is done with the following command:&prompt.root; umount /cdromDo not just remove it from the drive!Before invoking the installation, be sure that the CDROM
is in the drive so that the install probe can find it. This
is also true if you wish the CDROM to be added to the default
system configuration automatically during the installation (whether
or not you actually use it as the installation media).installationnetworkFTPFinally, if you would like people to be able to FTP install
FreeBSD directly from the CDROM in your machine, you will find
it quite easy. After the machine is fully installed, you simply
need to add the following line to the password file (using the
vipw command):ftp:*:99:99::0:0:FTP:/cdrom:/nonexistentAnyone with network connectivity to your machine can now
chose a media type of FTP and type in
ftp://your machine
after picking Other in the FTP sites menu during
the install.If you choose to enable anonymous FTP during the
installation of your system, the installation program will do
the above for you.Before installing from FloppiesinstallationfloppiesIf you must install from floppy disk (which we suggest you
do NOT do), either due to unsupported
hardware or simply because you insist on doing things the hard
way, you must first prepare some floppies for the installation.At a minimum, you will need as many 1.44MB or 1.2MB floppies
as it takes to hold all the files in the
bin (binary distribution) directory. If
you are preparing the floppies from DOS, then they
MUST be formatted using the MS-DOS
FORMAT command. If you are using Windows,
use Explorer to format the disks (right-click on the
A: drive, and select "Format".Do NOT trust factory pre-formatted
floppies! Format them again yourself, just to be sure. Many
problems reported by our users in the past have resulted from
the use of improperly formatted media, which is why we are
making a point of it now.If you are creating the floppies on another FreeBSD machine,
a format is still not a bad idea, though you do not need to put
a DOS filesystem on each floppy. You can use the
disklabel and newfs
commands to put a UFS filesystem on them instead, as the
following sequence of commands (for a 3.5" 1.44MB floppy)
illustrates:&prompt.root; fdformat -f 1440 fd0.1440
&prompt.root; disklabel -w -r fd0.1440 floppy3
&prompt.root; newfs -t 2 -u 18 -l 1 -i 65536 /dev/fd0Use fd0.1200 and
floppy5 for 5.25" 1.2MB disks.Then you can mount and write to them like any other
filesystem.After you have formatted the floppies, you will need to copy
the files to them. The distribution files are split into chunks
conveniently sized so that 5 of them will fit on a conventional
1.44MB floppy. Go through all your floppies, packing as many
files as will fit on each one, until you have all of the
distributions you want packed up in this fashion. Each
distribution should go into a subdirectory on the floppy, e.g.:
a:\bin\bin.aa,
a:\bin\bin.ab, and so on.Once you come to the Media screen during the install
process, select Floppy and you will be prompted
for the rest.Before Installing from MS-DOSinstallationfrom MS-DOSTo prepare for an installation from an MS-DOS partition,
copy the files from the distribution into a directory named,
for example, c:\FreeBSD. The directory
structure of the CDROM or FTP site must be partially reproduced
within this directory, so we suggest using the DOS
xcopy command if you are copying it from a
CD. For example, to prepare for a minimal installation of
FreeBSD:C:\>md c:\FreeBSDC:\>xcopy e:\bin c:\FreeBSD\bin\ /sC:\>xcopy e:\manpages c:\FreeBSD\manpages\ /sAssuming that C: is where you have
free space and E: is where your CDROM
is mounted.If you do not have a CDROM drive, you can download the
distribution from
ftp.FreeBSD.org. Each distribution is in its own directory;
for example, the bin distribution can be
found in the &rel.current;/bin directory.For as many distributions you wish to install from an MS-DOS
partition (and you have the free space for), install each one
under c:\FreeBSD — the
BIN distribution is the only one required for
a minimum installation.Before Installing from QIC/SCSI Tapeinstallationfrom QIC/SCSI TapeInstalling from tape is probably the easiest method, short
of an online FTP install or CDROM install. The installation
program expects the files to be simply tarred onto the tape, so
after getting all of the distribution files you are interested
in, simply tar them onto the tape like so:&prompt.root; cd /freebsd/distdir
&prompt.root; tar cvf /dev/rwt0 dist1 ... dist2When you go to do the installation, you should also make
sure that you leave enough room in some temporary directory
(which you will be allowed to choose) to accommodate the
full contents of the tape you have created.
Due to the non-random access nature of tapes, this method of
installation requires quite a bit of temporary storage. You
should expect to require as much temporary storage as you have
stuff written on tape.When starting the installation, the tape must be in the
drive before booting from the boot
floppy. The installation probe may otherwise fail to find
it.Before Installing over a Networkinstallationnetworkserial (SLIP or PPP)installationnetworkparallel (PLIP)installationnetworkEthernetThere are three types of network installations you can do.
Serial port (SLIP or PPP), Parallel port (PLIP (laplink cable)),
or Ethernet (a standard Ethernet controller (includes some
PCMCIA)).The SLIP support is rather primitive, and limited primarily
to hard-wired links, such as a serial cable running between a
laptop computer and another computer. The link should be
hard-wired as the SLIP installation does not currently offer a
dialing capability; that facility is provided with the PPP
utility, which should be used in preference to SLIP whenever
possible.If you are using a modem, then PPP is almost certainly
your only choice. Make sure that you have your service
provider's information handy as you will need to know it fairly
early in the installation process.If you use PAP or CHAP to connect your ISP (in other
words, if you can connect to the ISP in Windows without
using a script), then all you will need to do is type in
dial at the
ppp prompt. Otherwise,
you will need to know
how to dial your ISP using the AT commands
specific to your modem, as the PPP dialer provides only a very
simple terminal emulator. Please refer
to the user-ppp handbook and FAQ entries for further
information. If you have problems, logging can be directed to
the screen using the command set log local
....If a hard-wired connection to another FreeBSD (2.0-R or
later) machine is available, you might also consider installing
over a laplink parallel port cable. The data rate
over the parallel port is much higher than what is typically
possible over a serial line (up to 50kbytes/sec), thus resulting
in a quicker installation.Finally, for the fastest possible network installation, an
Ethernet adapter is always a good choice! FreeBSD supports most
common PC Ethernet cards; a table of supported cards (and their
required settings) is provided in the Supported Hardware list. If you are
using one of the supported PCMCIA Ethernet cards, also be sure
that it is plugged in before the laptop is
powered on! FreeBSD does not, unfortunately, currently support
hot insertion of PCMCIA cards during installation.You will also need to know your IP address on the network,
the netmask value for your address class, and the name of your
machine. If you are installing over a PPP connection and do not
have a static IP, fear not, the IP address can be dynamically
assigned by your ISP. Your system administrator can tell you
which values to use for your particular network setup. If you
will be referring to other hosts by name rather than IP address,
you will also need a name server and possibly the address of a
gateway (if you are using PPP, it is your provider's IP address)
to use in talking to it. If you want to install by FTP via a
HTTP proxy (see below), you will also need the proxy's address.
If you do not know the answers to all or most of these questions,
then you should really probably talk to your system administrator
or ISP before trying this type of
installation.Before Installing via NFSinstallationnetworkNFSThe NFS installation is fairly straight-forward. Simply
copy the FreeBSD distribution files you want onto a server
somewhere and then point the NFS media selection at it.If this server supports only privileged port
(as is generally the default for Sun workstations), you will
need to set this option in the Options menu before
installation can proceed.If you have a poor quality Ethernet card which suffers
from very slow transfer rates, you may also wish to toggle the
appropriate Options flag.In order for NFS installation to work, the server must
support subdir mounts, e.g., if your FreeBSD 3.4 distribution
directory lives
on:ziggy:/usr/archive/stuff/FreeBSD, then
ziggy will have to allow the direct mounting
of /usr/archive/stuff/FreeBSD, not just
/usr or
/usr/archive/stuff.In FreeBSD's /etc/exports file, this
is controlled by the . Other NFS
servers may have different conventions. If you are getting
permission denied messages from the server, then
it is likely that you do not have this enabled
properly.Before Installing via FTPinstallationnetworkFTPFTP installation may be done from any FreeBSD mirror site
containing a reasonably up-to-date version of FreeBSD. A full
list of FTP mirrors located all over the world is provided
during the install process.If you are installing from an FTP site not listed in this
menu, or are having trouble getting your name server
configured properly, you can also specify a URL to use by
selecting the choice labeled Other in that menu.
You can also use the IP address of a machine you wish to
install from, so the following would work in the absence of a
name server:ftp://209.55.82.20/pub/FreeBSD/&rel.current;-RELEASEThere are three FTP installation modes you can choose from:
active or passive FTP or via a HTTP proxy.FTP ActiveThis option will make all FTP transfers
use Active
mode. This will not work through firewalls, but will
often work with older FTP servers that do not support
passive mode. If your connection hangs with passive
mode (the default), try active!FTP PassiveFTPPassive modeThis option instructs FreeBSD to use
Passive mode for all FTP operations.
This allows the user to pass through firewalls
that do not allow incoming connections on random port
addresses.FTP via a HTTP proxyFTPvia a HTTP proxyThis option instructs FreeBSD to use the HTTP
protocol (like a web browser) to connect to a proxy
for all FTP operations. The proxy will translate
the requests and send them to the FTP server.
This allows the user to pass through firewalls
that do not allow FTP at all, but offer a HTTP
proxy.
In this case, you have to specify the proxy in
addition to the FTP server.There is another type of FTP proxy other tha HTTP
proxies. This type is very uncommon, though. If you
are not absolutely certain, you can assume that you
have a HTTP proxy as described above.For a proxy FTP server, you should usually give the name
of the server you really want as a part of the username, after
an @ sign. The proxy server then
fakes the real server. For example, assuming
you want to install from ftp.FreeBSD.org, using the proxy FTP
server foo.bar.com, listening on
port 1024.In this case, you go to the options menu, set the FTP
username to ftp@ftp.FreeBSD.org, and the password to your
email address. As your installation media, you specify FTP
(or passive FTP, if the proxy supports it), and the URL
ftp://foo.bar.com:1234/pub/FreeBSD.Since /pub/FreeBSD from ftp.FreeBSD.org is proxied under foo.bar.com, you are able to install from
that machine (which will fetch the files
from ftp.FreeBSD.org as your
installation requests them.Check your BIOS drive numberingIf you have used features in your BIOS to renumber your disk
drives without re-cabling them then you should read first to avoid confusion.Installing FreeBSDOnce you have completed the pre-installation step relevant to
your situation, you are ready to install FreeBSD!Although you should not experience any difficulty, there is
always the chance that you may, no matter how slight it is. If this
is the case in your situation, then you may wish to go back and
re-read the relevant preparation section or sections. Perhaps you
will come across something you missed the first time. If you are
having hardware problems, or FreeBSD refuses to boot at all, read
the Hardware Guide for a
list of possible solutions.sysinstallThe FreeBSD boot floppies contain all of the online
documentation you should need to be able to navigate through an
installation. If it does not, please let us know what you found
to be the most confusing or most lacking. Send your comments to
the &a.doc;. It is the objective of the installation program
(sysinstall) to be self-documenting enough that painful
step-by-step guides are no longer necessary. It may
take us a little while to reach that objective, but nonetheless,
it is still our objective.Meanwhile, you may also find the following typical
installation sequence to be helpful:Boot the kern.flp floppy and when
asked, remove it and insert the
mfsroot.flp and hit return. After a
boot sequence which can take anywhere from 30 seconds to 3
minutes, depending on your hardware, you should be presented
with a menu of initial choices. If the
kern.flp floppy does not boot at all or
the boot hangs at some stage, read the Q&A section of the
Hardware Guide for
possible causes.Press F1. You should see some basic usage instructions on
the menu screen and general navigation. If you have not used
this menu system before then please read
this thoroughly.Select the Options item and set any special preferences
you may have.installationstandardinstallationexpressinstallationcustomSelect a Standard, Express, or Custom install, depending on
whether or not you would like the installation to help you
through a typical installation, give you a high degree of
control over each step, or simply whiz through it (using
reasonable defaults when possible) as fast as possible. If
you have never used FreeBSD before, the Standard installation
method is most recommended.The final configuration menu choice allows you to further
configure your FreeBSD installation by giving you menu-driven
access to various system defaults. Some items, like
networking, may be especially important if you did a CDROM,
tape, or floppy install and have not yet configured your
network interfaces (assuming you have any). Properly
configuring such interfaces here will allow FreeBSD to come up
on the network when you first reboot from the hard
disk.Supported HardwarehardwareFreeBSD currently runs on a wide variety of ISA, VLB, EISA, and
PCI bus based PCs, ranging from the 386SX to Pentium class machines
(though the 386SX is not recommended). Support for generic IDE or
ESDI drive configurations, various SCSI controllers, and network and
serial cards is also provided. FreeBSD also supports IBM's
microchannel (MCA) bus.In order to run FreeBSD, a recommended minimum of eight
megabytes of RAM is suggested. Sixteen megabytes is the preferred
amount of RAM as you may have some trouble with anything less than
sixteen depending on your hardware.What follows is a list of hardware currently known to work with
FreeBSD. There may be other hardware that works as well, but we
have simply not received any confirmation of it.Disk Controllersdisk controllersWD1003 (any generic MFM/RLL)WD1007 (any generic IDE/ESDI)IDEATAAdaptec 1535 ISA SCSI controllersAdaptec 154X series ISA SCSI controllersAdaptec 174X series EISA SCSI controllers in standard and
enhanced modeAdaptec 274X/284X/2920C/294X/2950/3940/3950
(Narrow/Wide/Twin) series EISA/VLB/PCI SCSI controllersAdaptec AIC-7850, AIC-7860, AIC-7880, AIC-789X on-board SCSI
controllersAdaptec 1510 series ISA SCSI controllers (not for bootable
devices)Adaptec 152X series ISA SCSI controllersAdaptec AIC-6260 and AIC-6360 based boards, which include
the AHA-152X and SoundBlaster SCSI cardsAdvanSys SCSI controllers (all models)BusLogic MultiMaster W Series Host Adapters
including BT-948, BT-958, BT-9580BusLogic MultiMaster C Series Host Adapters
including BT-946C, BT-956C, BT-956CD, BT-445C, BT-747C,
BT-757C, BT-757CD, BT-545C, BT-540CFBusLogic MultiMaster S Series Host Adapters
including BT-445S, BT-747S, BT-747D, BT-757S, BT-757D,
BT-545S, BT-542D, BT-742A, BT-542BBusLogic MultiMaster A Series Host Adapters
including BT-742A, BT-542BAMI FastDisk controllers that are true BusLogic
MultiMaster clones are also supported.BusLogic/Mylex Flashpoint adapters are NOT
yet supported.DPT SmartCACHE Plus, SmartCACHE III, SmartRAID III,
SmartCACHE IV, and SmartRAID IV SCSI/RAID are supported. The
DPT SmartRAID/CACHE V is not yet supported. The DPT PM3754U2-16M
SCSI RAID Controller is also supported.Compaq Intelligent Disk Array Controllers: IDA, IDA-2, IAES,
SMART, SMART-2/E, Smart-2/P, SMART-2SL, Integrated Array, and
Smart Arrays 3200, 3100ES, 221, 4200, 4200, 4250ES.SymBios (formerly NCR) 53C810, 53C810a, 53C815, 53C820,
53C825a, 53C860, 53C875, 53C875j, 53C885, and 53C896 PCI SCSI
controllers including ASUS SC-200, Data Technology DTC3130
(all variants), Diamond FirePort (all), NCR cards (all),
SymBios cards (all), Tekram DC390W, 390U, and 390F, and Tyan
S1365QLogic 1020, 1040, 1040B, and 2100 SCSI and Fibre
Channel AdaptersDTC 3290 EISA SCSI controller in 1542 evaluation
modeWith all supported SCSI controllers, full support is provided
for SCSI-I and SCSI-II peripherals, including hard disks, optical
disks, tape drives (including DAT and 8mm Exabyte), medium
changers, processor target devices, and CDROM drives. WORM
devices that support CDROM commands are supported for read-only
access by the CDROM driver. WORM/CD-R/CD-RW writing support is
provided by cdrecord, which is in the ports tree.The following CDROM type systems are supported at this
time:cd - SCSI interface (includes
ProAudio Spectrum and SoundBlaster SCSI)matcd - Matsushita/Panasonic
(Creative SoundBlaster) proprietary interface (562/563
models)scd - Sony proprietary interface
(all models)acd - ATAPI IDE interfaceThe following drivers were supported under the old SCSI
subsystem, but are NOT YET supported under the new CAM SCSI
subsystem:NCR5380/NCR53400 (ProAudio Spectrum) SCSI
controllerUltraStor 14F, 24F, and 34F SCSI controllersSeagate ST01/02 SCSI controllersFuture Domain 8XX/950 series SCSI controllersWD7000 SCSI controllerThere is work-in-progress to port the UltraStor driver
to the new CAM framework, but no estimates on when or if it
will be completed.Unmaintained drivers, which might or might not work for your
hardware:Floppy tape interface (Colorado/Mountain/Insight)mcd - Mitsumi proprietary CDROM
interface (all models)Network Cardsnetwork cardsAdaptec Duralink PCI fast ethernet adapters based on the
Adaptec AIC-6195 fast ethernet controller chip, including the
following:ANA-62011 64-bit single port 10/100baseTX
adapterANA-62022 64-bit dual port 10/100baseTX adapterANA-62044 64-bit quad port 10/100baseTX adapterANA-69011 32-bit single port 10/100baseTX
adapterANA-62020 64-bit single port 100baseFX adapterAllied-Telesyn AT1700 and RE2000 cardsAlteon Networks PCI gigabit ethernet NICs based on the
Tigon 1 and Tigon 2 chipsets including the Alteon AceNIC
(Tigon 1 and 2), 3Com 3c985-SX (Tigon 1 and 2), Netgear GA620
(Tigon 2), Silicon Graphics Gigabit Ethernet, DEC/Compaq
EtherWORKS 1000, NEC Gigabit EthernetAMD PCnet/PCI (79c970 and 53c974 or 79c974)RealTek 8129/8139 fast ethernet NICs including the
following:Allied-Telesyn AT2550Allied-Telesyn AT2500TXGenius GF100TXR (RTL8139)NDC Communications NE100TX-EOvisLink LEF-8129TXOvisLink LEF-8139TXNetronix Inc. EA-1210 NetEther 10/100KTX-9130TX 10/100 Fast EthernetAccton Cheetah EN1207D (MPX 5030/5038;
RealTek 8139 clone)SMC EZ Card 10/100 PCI 1211-TXLite-On 98713, 98713A, 98715, and 98725 fast ethernet
NICs, including the LinkSys EtherFast LNE100TX, NetGear
FA310-TX Rev. D1, Matrox FastNIC 10/100, Kingston
KNE110TXMacronix 98713, 98713A, 98715, 98715A, and 98725 fast
ethernet NICs including the NDC Communications SFA100A
(98713A), CNet Pro120A (98713 or 98713A), CNet Pro120B
(98715), SVEC PN102TX (98713)Macronix/Lite-On PNIC II LC82C115 fast ethernet NICs
including the LinkSys EtherFast LNE100TX version 2Winbond W89C840F fast ethernet NICs including the
Trendware TE100-PCIEVIA Technologies VT3043 Rhine I and
VT86C100A Rhine II fast ethernet NICs including
the Hawking Technologies PN102TX and D-Link DFE-530TXSilicon Integrated Systems SiS 900 and SiS 7016 PCI fast
ethernet NICsSundance Technologies ST201 PCI fast ethernet NICs
including the D-Link DFE-550TXSysKonnect SK-984x PCI gigabit ethernet cards including
the SK-9841 1000baseLX (single mode fiber, single port),
the SK-9842 1000baseSX (multimode fiber, single port), the
SK-9843 1000baseLX (single mode fiber, dual port), and the
SK-9844 1000baseSX (multimode fiber, dual port).Texas Instruments ThunderLAN PCI NICs, including the
Compaq Netelligent 10, 10/100, 10/100 Proliant, 10/100
Dual-Port, 10/100 TX Embedded UTP, 10 T PCI UTP/Coax, and
10/100 TX UTP, the Compaq NetFlex 3P, 3P Integrated, and 3P
w/BNC, the Olicom OC-2135/2138, OC-2325, OC-2326 10/100 TX
UTP, and the Racore 8165 10/100baseTX and 8148
10baseT/100baseTX/100baseFX multi-personality cardsADMtek AL981-based and AN985-based PCI fast ethernet
NICsASIX Electronics AX88140A PCI NICs including the Alfa Inc.
GFC2204 and CNet Pro110BDEC EtherWORKS III NICs (DE203, DE204, and DE205)DEC EtherWORKS II NICs (DE200, DE201, DE202, and
DE422)DEC DC21040, DC21041, or DC21140 based NICs (SMC
Etherpower 8432T, DE245, etc.)DEC FDDI (DEFPA/DEFEA) NICsEfficient ENI-155p ATM PCIFORE PCA-200E ATM PCIFujitsu MB86960A/MB86965AHP PC Lan+ cards (model numbers: 27247B and 27252A)Intel EtherExpress ISA (not recommended due to driver
instability)Intel EtherExpress Pro/10Intel EtherExpress Pro/100B PCI Fast EthernetIsolan AT 4141-0 (16 bit)Isolink 4110 (8 bit)Novell NE1000, NE2000, and NE2100 Ethernet
interfacesPCI network cards emulating the NE2000, including the
RealTek 8029, NetVin 5000, Winbond W89C940, Surecom NE-34, VIA
VT86C9263Com 3C501, 3C503 Etherlink II, 3C505 Etherlink/+, 3C507
Etherlink 16/TP, 3C509, 3C579, 3C589 (PCMCIA),
3C590/592/595/900/905/905B/905C PCI and EISA (Fast) Etherlink
III / (Fast) Etherlink XL, 3C980/3C980B Fast Etherlink XL
server adapter, 3CSOHO100-TX OfficeConnect adapterToshiba ethernet cardsPCMCIA ethernet cards from IBM and National Semiconductor
are also supportedUSB PeripheralsUSB PeripheralsA wide range of USB peripherals are supported. Owing to the
generic nature of most USB devices, with some exceptions any
device of a given class will be supported even if not explicitly
listed here.USB keyboardsUSB miceUSB printers and USB to parallel printer conversion
cablesUSB hubsMotherboard chipsets:ALi Aladdin-VIntel 82371SB (PIIX3) and 82371AB and EB (PIIX4)
chipsetsNEC uPD 9210 Host ControllerVIA 83C572 USB Host Controllerand any other UHCI or OHCI compliant motherboard chipset
(no exceptions known).PCI plug-in USB host controllersADS Electronics PCI plug-in card (2 ports)Entrega PCI plug-in card (4 ports)Specific USB devices reported to be working:Agiler Mouse 29UOAndromeda hubApple iMac mouse and keyboardATen parallel printer adapterBelkin F4U002 parallel printer adapter and Belkin
mouseBTC BTC7935 keyboard with mouse portCherry G81-3504Chic mouseCypress mouseEntrega USB-to-parallel printer adapterGenius Niche mouseIomega USB Zip 100 MBKensington Mouse-in-a-BoxLogitech M2452 keyboardLogitech wheel mouse (3 buttons)Logitech PS/2 / USB mouse (3 buttons)MacAlly mouse (3 buttons)MacAlly self-powered hub (4 ports)Microsoft Intellimouse (3 buttons)Microsoft keyboardNEC hubTrust Ami Mouse (3 buttons)ISDN (European DSS1 [Q.921/Q.931] protocol)ISDNAsuscom I-IN100-ST-DV (experimental, may work)Asuscom ISDNlink 128KAVM A1AVM Fritz!Card classicAVM Fritz!Card PCIAVM Fritz!Card PCMCIA (currently FreeBSD 3.X only)AVM Fritz!Card PnP (currently FreeBSD 3.X only)Creatix ISDN-S0/8Creatix ISDN-S0/16Creatix ISDN-S0 PnPDr.Neuhaus Niccy 1008Dr.Neuhaus Niccy 1016Dr.Neuhaus Niccy GO@ (ISA PnP)Dynalink IS64PH (no longer maintained)ELSA 1000pro ISAELSA 1000pro PCIELSA PCC-16ITK ix1 micro (currently FreeBSD 3.X only)ITK ix1 micro V.3 (currently FreeBSD 3.X only)Sagem Cybermod (ISA PnP, may work)Sedlbauer Win SpeedSiemens I-Surf 2.0Stollman Tina-pp (under development)Teles S0/8Teles S0/16Teles S0/16.3 (the c Versions - like 16.3c
- are unsupported!)Teles S0 PnP (experimental, may work)3Com/USRobotics Sportster ISDN TA intern (non-PnP
version)Sound DevicesThe following soundcards or codecs are supported (devices marked
'experimental' are only supported in FreeBSD-CURRENT and might
work only unstably):sound cards16550 UART (Midi) (experimental, needs a trick in the hints
file)Advance Asound 100, 110 and Logic ALS120Aureal Vortex1/Vortex2 and Vortex Advantage based soundcards
by a
third
party driverCreative Labs SB16, SB32, SB AWE64 (including Gold),
Vibra16, SB PCI (experimental), SB Live! (experimental)
and most SoundBlaster compatible cardsCreative Labs SB Midi Port (experimental), SB OPL3
Synthesizer (experimental)Crystal Semiconductor CS461x/462x Audio Accelerator,
the support for the CS461x Midi port is experimentalCrystal Semiconductor CS428x Audio ControllerCS4237, CS4236, CS4232, CS4231 (ISA)ENSONIQ AudioPCI ES1370/1371ESS ES1868, ES1869, ES1879, ES1888Gravis UltraSound PnP, MAXNeoMagic 256AV/ZX (PCI)OPTi931 (ISA)OSS-compatible sequencer (Midi) (experimental)Trident 4DWave DX/NX (PCI)Yahama OPL-SAx (ISA)Miscellaneous DevicesAST 4 port serial card using shared IRQARNET 8 port serial card using shared IRQARNET (now Digiboard) Sync 570/i high-speed serialBoca BB1004 4-Port serial card (Modems NOT
supported)Boca IOAT66 6-Port serial card (Modems supported)Boca BB1008 8-Port serial card (Modems NOT
supported)Boca BB2016 16-Port serial card (Modems supported)Cyclades Cyclom-y Serial BoardMoxa SmartIO CI-104J 4-Port serial cardSTB 4 port card using shared IRQSDL Communications RISCom/8 Serial BoardSDL Communications RISCom/N2 and N2pci high-speed sync
serial boardsSpecialix SI/XIO/SX multiport serial cards, with both the
older SIHOST2.x and the new enhanced
(transputer based, aka JET) host cards; ISA, EISA and PCI are
supportedStallion multiport serial boards: EasyIO, EasyConnection
8/32 & 8/64, ONboard 4/16 and BrumbyAdlib, SoundBlaster, SoundBlaster Pro, ProAudioSpectrum,
Gravis UltraSound, and Roland MPU-401 sound cardsConnectix QuickCamMatrox Meteor Video frame grabberCreative Labs Video Spigot frame grabberCortex1 frame grabberVarious frame grabbers based on the Brooktree Bt848
and Bt878 chipHP4020, HP6020, Philips CDD2000/CDD2660 and Plasmon CD-R
drivesBus micePS/2 miceStandard PC JoystickX-10 power controllersGPIB and Transputer drivesGenius and Mustek hand scannersFloppy tape drives (some rather old models only, driver is
rather stale)Lucent Technologies WaveLAN/IEEE 802.11 PCMCIA and ISA
standard speed (2Mbps) and turbo speed (6Mbps) wireless
network adapters and workalikes (NCR WaveLAN/IEEE 802.11,
Cabletron RoamAbout 802.11 DS)The ISA versions of these adapters are actually PCMCIA
cards combined with an ISA to PCMCIA bridge card, so both
kinds of devices work with the same driver.TroubleshootinginstallationtroubleshootingThe following section covers basic installation troubleshooting,
such as common problems people have reported. There are also a few
questions and answers for people wishing to dual-boot FreeBSD with
MS-DOS.What to do if something goes wrong...Due to various limitations of the PC architecture, it is
impossible for probing to be 100% reliable, however, there are a
few things you can do if it fails.Check the supported
hardware list to make sure your hardware is
supported.If your hardware is supported and you still experience
lock-ups or other problems, reset your computer, and when the
visual kernel configuration option is given, choose it. This will
allow you to go through your hardware and supply information to the
system about it. The kernel on the boot disks is configured
assuming that most hardware devices are in their factory default
configuration in terms of IRQs, IO addresses, and DMA channels. If
your hardware has been reconfigured, you will most likely need to
use the configuration editor to tell FreeBSD where to find
things.It is also possible that a probe for a device not present will
cause a later probe for another device that is present to fail. In
that case, the probes for the conflicting driver(s) should be
disabled.Do not disable any drivers you will need during the
installation, such as your screen (sc0).
If the installation wedges or fails mysteriously after leaving
the configuration editor, you have probably removed or changed
something you should not have. Reboot and try again.In configuration mode, you can:List the device drivers installed in the kernel.Change device drivers for hardware that is not present in
your system.Change IRQs, DRQs, and IO port addresses used by a device
driver.After adjusting the kernel to match your hardware
configuration, type Q to boot with the new
settings. Once the installation has completed, any changes you
made in the configuration mode will be permanent so you do not have
to reconfigure every time you boot. It is still highly likely that
you will eventually want to build a custom kernel.MS-DOS User's Questions and AnswersDOSMany users wish to install FreeBSD on PCs inhabited by MS-DOS.
Here are some commonly asked questions about installing FreeBSD on
such systems.Help, I have no space! Do I need to delete everything
first?If your machine is already running MS-DOS and has little
or no free space available for the FreeBSD installation, all
hope is not lost! You may find the FIPS utility, provided
in the tools directory on the FreeBSD
CDROM or various FreeBSD FTP sites to be quite
useful.FIPSFIPS allows you to split an existing MS-DOS partition
into two pieces, preserving the original partition and
allowing you to install onto the second free piece. You
first defragment your MS-DOS partition using the Windows
DEFRAG utility (go into Explorer, right-click on the
hard drive, and choose to defrag your
hard drive), or Norton Disk Tools. You then must run FIPS. It
will prompt you for the rest of the information it needs.
Afterwards, you can reboot and install FreeBSD on the new
free slice. See the Distributions menu
for an estimate of how much free space you will need for the
kind of installation you want.Partition MagicThere is also a very useful
product from PowerQuest
called Partition Magic. This
application has far more functionality than FIPS, and is
highly recommended if you plan to often add/remove
operating systems (like me). However, it does cost
money, and if you plan to install FreeBSD once and then
leave it there, FIPS will probably be fine for you.Can I use compressed MS-DOS filesystems from
FreeBSD?No. If you are using a utility such as Stacker(tm) or
DoubleSpace(tm), FreeBSD will only be able to use whatever
portion of the filesystem you leave uncompressed. The rest
of the filesystem will show up as one large file (the
stacked/double spaced file!). Do not remove that
file or you will probably regret it
greatly!It is probably better to create another uncompressed
primary MS-DOS partition and use this for communications
between MS-DOS and FreeBSD.Can I mount my extended MS-DOS partition?partitionsslicesYes. DOS extended partitions are mapped in at the end
of the other slices in FreeBSD, e.g., your
D: drive might be
/dev/da0s5, your
E: drive,
/dev/da0s6, and so on. This example
assumes, of course, that your extended partition is on SCSI
drive 0. For IDE drives, substitute ad
for da appropriately if installing
4.0-RELEASE or later, and substitute
wd for da if you
are installing a version of FreeBSD prior to 4.0. You otherwise
mount extended partitions exactly like you would any other
DOS drive, for example:&prompt.root; mount -t msdos /dev/ad0s5 /dos_d
- Advanced Installation Guide
+
+
+
+ Valentino
+ Vaschetto
+ Contributed by
+
+
+
+
- Written by &a.logo;, May 2001.
+ Advanced Installation GuideThis section describes how to install FreeBSD in exceptional
cases.Installing FreeBSD on a system without a monitor or
keyboardinstallationheadless (serial console)serial consoleThis type of installation is called a "headless install",
because the machine that you are trying to install FreeBSD on
either doesnt have a monitor attached to it, or doesnt even
have a VGA output. How is this possible you ask? Using a
serial console. A serial console is basically using another
machine to act as the main display and keyboard for a
system. To do this, just follow these steps:Fetch the right boot floppy imagesFirst you will need to get the right disk images so
that you can boot into the install program. The secret
with using a serial console is that you tell the boot
loader to send I/O through a serial port instead of
displaying console output to the VGA device and trying to
read input from a local keyboard. Enough of that now,
let's get back to getting these disk images.You will need to get kern.flp and
mfsroot.flp from the
floppies directory.Write the image files to the floppy disks.The image files, such as
kern.flp, are
not regular files that you copy to
the disk. Instead, they are images of the complete
contents of the disk.This means that you can not use
commands like DOS' copy to write the
files. Instead, you must use specific tools to write the
images directly to the disk.fdimageIf you are creating the floppies on a computer running
DOS then we provide a tool to do this called
fdimage.If you are using the floppies from the CDROM, and
your CDROM is the E: drive then
you would run this:E:\>tools\fdimage floppies\kern.flp A:Repeat this command for each .flp
file, replacing the floppy disk each time. Adjust the
command line as necessary, depending on where you have
placed the .flp files. If you do not
have the CDROM then fdimage can be
downloaded from the tools
directory on the FreeBSD FTP site.If you are writing the floppies on a Unix system (such
as another FreeBSD system) you can use the &man.dd.1;
command to write the image files directly to disk. On
FreeBSD you would run:&prompt.root; dd if=kern.flp of=/dev/fd0On FreeBSD /dev/fd0 refers to
the first floppy disk (the A:
drive). /dev/fd1 would be the
B: drive, and so on. Other Unix
variants might have different names for the floppy disk
devices, and you will need to check the documentation for
the system as necessary.Enabling the boot floppies to boot into a serial
consoleDo not try to mount the floppy if it is write-protectedmountIf you were to boot into the floppies that you just
made, FreeBSD would boot into its normal install mode. We
want FreeBSD to boot into a serial console for our
install. To do this, you have to mount the
kern.flp floppy onto your FreeBSD
system using the &man.mount.8; command.&prompt.root; mount /dev/fd0 /mntNow that you have the floppy mounted, you must
change into the floppy directory&prompt.root; cd /mntHere is where you must set the floppy to boot into a
serial console. You have to make a file called
boot.config containing "/boot/loader
-h". All this does is pass a flag to the bootloader to
boot into a serial console.&prompt.root; echo "/boot/loader -h" > boot.configNow that you have your floppy configured correctly,
you must unmount the floppy using the &man.umount.8;
command&prompt.root; cd /
&prompt.root; umount /mntNow you can remove the floppy from the floppy
driveConnecting your null modem cablenull-modem cableYou now need to connect a null modem cable between
the two machines. Just connect the cable to the serial
ports of the 2 machines. A normal serial cable
will not work here, you need a null modem
cable because it has some of the wires inside crossed
over.Booting up for the installIt's now time to go ahead and start the install. Put
the kern.flp floppy in the floppy
drive of the machine you're doing the headless install
on, and power on the machine.Connecting to your headless machinecuNow you have to connect to that machine with
&man.cu.1;:&prompt.root; cu -l /dev/cuaa0That's it! You should be able to control the headless
machine through your cu session now. It will ask you to put
in the mfsroot.flp, and then it will come
up with a selection of what kind of terminal to use. Just
select the FreeBSD color console and proceed with your
install!
diff --git a/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
index 178b6e7766..d384aa241b 100644
--- a/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml
@@ -1,882 +1,890 @@
JimMockRestructured, reorganized, and parts
- rewritten
+ rewritten by
IntroductionSynopsisThank you for your interest in FreeBSD! The following chapter
covers various items about the FreeBSD Project, such as its history,
goals, development model, and so on.4.4BSD-LiteFreeBSD is a 4.4BSD-Lite based operating system for the Intel
architecture (x86) and DEC Alpha based systems. Ports to other
architectures are also underway. For a brief overview of FreeBSD,
see the next section. You can also
read about the history of FreeBSD,
or the current release. If you
are interested in contributing something to the Project (code,
hardware, unmarked bills), see the contributing to FreeBSD section.Welcome to FreeBSD!Since you are still here reading this, you most likely have some
idea as to what FreeBSD is and what it can do for you. If you are
new to FreeBSD, read on for more information.What is FreeBSD?Intel architecture (x86)DEC Alpha architectureIn general, FreeBSD is a state-of-the-art operating system
based on 4.4BSD-Lite. It runs on computer systems based on the
Intel architecture (x86), and also the DEC Alpha
architecture.FreeBSD is used to power some of the biggest sites on the
Internet, including:Yahoo!Yahoo!ApacheApacheBe, Inc.Be, Inc.Blue Mountain ArtsBlue Mountain
ArtsPair NetworksPair
NetworksWhistle CommunicationsWhistle
CommunicationsMicrosoftMicrosoftHotmailHotmailSony JapanSony
Japanand many more.What can FreeBSD do?FreeBSD has many noteworthy features. Some of these
are:preemptive multitaskingPreemptive multitasking with
dynamic priority adjustment to ensure smooth and fair
sharing of the computer between applications and users, even
under the heaviest of loads.multi-user facilitiesMulti-user facilities which allow many
people to use a FreeBSD system simultaneously for a variety
of things. This means, for example, that system peripherals
such as printers and tape drives are properly shared between
all users on the system or the network and that individual
resource limits can be placed on users or groups of users,
protecting critical system resources from over-use.TCP/IP networkingStrong TCP/IP networking with
support for industry standards such as SLIP, PPP, NFS, DHCP,
and NIS. This means that your FreeBSD machine can
interoperate easily with other systems as well as act as an
enterprise server, providing vital functions such as NFS
(remote file access) and email services or putting your
organization on the Internet with WWW, FTP, routing and
firewall (security) services.memory protectionMemory protection ensures that
applications (or users) cannot interfere with each other. One
application crashing will not affect others in any way.FreeBSD is a 32-bit operating
system (64-bit on the Alpha) and was
designed as such from the ground up.X Window SystemXFree86The industry standard X Window System
(X11R6) provides a graphical user interface (GUI) for the cost
of a common VGA card and monitor and comes with full
sources.binary compatibilityLinuxbinary compatibilitySCObinary compatibilitySVR4binary compatibilityBSD/OSbinary compatibilityNetBSDBinary compatibility with many
programs built for Linux, SCO, SVR4, BSDI and NetBSD.Thousands of ready-to-run
applications are available from the FreeBSD
ports and packages
collection. Why search the net when you can find it all right
here?Thousands of additional and
easy-to-port applications are available
on the Internet. FreeBSD is source code compatible with most
popular commercial Unix systems and thus most applications
require few, if any, changes to compile.virtual memoryDemand paged virtual memory and
merged VM/buffer cache design efficiently
satisfies applications with large appetites for memory while
still maintaining interactive response to other users.Symetric Multi-Processing (SMP)SMP support for machines with
multiple CPUs.compilersCcompilersC++compilersFortranA full complement of C,
C++, Fortran, and
Perl development tools.
Many additional languages for advanced research
and development are also available in the ports and packages
collection.source codeSource code for the entire system
means you have the greatest degree of control over your
environment. Why be locked into a proprietary solution
at the mercy of your vendor when you can have a truly open
system?Extensive online
documentation.And many more!4.4BSD-LiteComputer Systems Resarch Group (CSRG)U.C. BerkeleyFreeBSD is based on the 4.4BSD-Lite release from Computer
Systems Research Group (CSRG) at the University of California at
Berkeley, and carries on the distinguished tradition of BSD
systems development. In addition to the fine work provided by
CSRG, the FreeBSD Project has put in many thousands of hours in
fine tuning the system for maximum performance and reliability in
real-life load situations. As many of the commercial giants
struggle to field PC operating systems with such features,
performance and reliability, FreeBSD can offer them
now!The applications to which FreeBSD can be put are truly
limited only by your own imagination. From software development
to factory automation, inventory control to azimuth correction of
remote satellite antennae; if it can be done with a commercial
Unix product then it is more than likely that you can do it with
FreeBSD too! FreeBSD also benefits significantly from the
literally thousands of high quality applications developed by
research centers and universities around the world, often
available at little to no cost. Commercial applications are also
available and appearing in greater numbers every day.Because the source code for FreeBSD itself is generally
available, the system can also be customized to an almost unheard
of degree for special applications or projects, and in ways not
generally possible with operating systems from most major
commercial vendors. Here is just a sampling of some of the
applications in which people are currently using FreeBSD:Internet Services: The robust TCP/IP
networking built into FreeBSD makes it an ideal platform for a
variety of Internet services such as:FTP serversFTP serversweb serversWorld Wide Web servers (standard or secure
[SSL])firewallIP masqueradingFirewalls and NAT (IP masquerading)
gatewayselectronic mailElectronic Mail serversUSENETUSENET News or Bulletin Board SystemsAnd more...With FreeBSD, you can easily start out small with an
inexpensive 386 class PC and upgrade all the way up to a
quad-processor Xeon with RAID storage as your enterprise
grows.Education: Are you a student of
computer science or a related engineering field? There is no
better way of learning about operating systems, computer
architecture and networking than the hands on, under the hood
experience that FreeBSD can provide. A number of freely
available CAD, mathematical and graphic design packages also
make it highly useful to those whose primary interest in a
computer is to get other work
done!Research: With source code for the
entire system available, FreeBSD is an excellent platform for
research in operating systems as well as other branches of
computer science. FreeBSD's freely available nature also makes
it possible for remote groups to collaborate on ideas or
shared development without having to worry about special
licensing agreements or limitations on what may be discussed
in open forums.routerDNS ServerNetworking: Need a new router? A
name server (DNS)? A firewall to keep people out of your
internal network? FreeBSD can easily turn that unused 386 or
486 PC sitting in the corner into an advanced router with
sophisticated packet-filtering capabilities.X Window SystemXFree86X Window SystemAccellerated-XX Window workstation: FreeBSD is a
fine choice for an inexpensive X terminal solution, either
using the freely available XFree86 server or one of the
excellent commercial servers provided by X Inside. Unlike an
X terminal, FreeBSD allows many applications to be run
locally, if desired, thus relieving the burden on a central
server. FreeBSD can even boot diskless, making
individual workstations even cheaper and easier to
administer.GNU Compiler CollectionSoftware Development: The basic
FreeBSD system comes with a full complement of development
tools including the renowned GNU C/C++ compiler and
debugger.FreeBSD is available in both source and binary form on CDROM
and via anonymous FTP. Please see
for more information about obtaining FreeBSD.About the FreeBSD ProjectThe following section provides some background information on
the project, including a brief history, project goals, and the
development model of the project.
- A Brief History of FreeBSD
+
+
+
+ Jordan
+ Hubbard
+ Contributed by
+
+
+
- Contributed by &a.jkh;.
+ A Brief History of FreeBSD386BSD PatchkitHubbard, JordanWilliams, NateGrimes, RodFreeBSD ProjectHistoryThe FreeBSD project had its genesis in the early part of 1993,
partially as an outgrowth of the Unofficial 386BSD
Patchkit by the patchkit's last 3 coordinators: Nate
Williams, Rod Grimes and myself.386BSDOur original goal was to produce an intermediate snapshot of
386BSD in order to fix a number of problems with it that the
patchkit mechanism just was not capable of solving. Some of you
may remember the early working title for the project being
386BSD 0.5 or 386BSD Interim in
reference to that fact.Jolitz, Bill386BSD was Bill Jolitz's operating system, which had been up
to that point suffering rather severely from almost a year's worth
of neglect. As the patchkit swelled ever more uncomfortably with
each passing day, we were in unanimous agreement that something
had to be done and decided to try and assist Bill by providing
this interim cleanup snapshot. Those plans came to
a rude halt when Bill Jolitz suddenly decided to withdraw his
sanction from the project without any clear indication of what
would be done instead.Greenman, DavidWalnut Creek CDROMIt did not take us long to decide that the goal remained
worthwhile, even without Bill's support, and so we adopted the
name FreeBSD, coined by David Greenman. Our initial
objectives were set after consulting with the system's current
users and, once it became clear that the project was on the road
to perhaps even becoming a reality, I contacted Walnut Creek CDROM
with an eye towards improving FreeBSD's distribution channels for
those many unfortunates without easy access to the Internet.
Walnut Creek CDROM not only supported the idea of distributing
FreeBSD on CD but also went so far as to provide the project with a
machine to work on and a fast Internet connection. Without Walnut
Creek CDROM's almost unprecedented degree of faith in what was, at
the time, a completely unknown project, it is quite unlikely that
FreeBSD would have gotten as far, as fast, as it has today.4.3BSD-LiteNet/2U.C. Berkeley386BSDFree Software FoundationThe first CDROM (and general net-wide) distribution was
FreeBSD 1.0, released in December of 1993. This was based on the
4.3BSD-Lite (Net/2) tape from U.C. Berkeley, with
many components also provided by 386BSD and the Free Software
Foundation. It was a fairly reasonable success for a first
offering, and we followed it with the highly successful FreeBSD
1.1 release in May of 1994.NovellU.C. BerkeleyNet/2AT&TAround this time, some rather unexpected storm clouds formed
on the horizon as Novell and U.C. Berkeley settled their
long-running lawsuit over the legal status of the Berkeley Net/2
tape. A condition of that settlement was U.C. Berkeley's
concession that large parts of Net/2 were encumbered
code and the property of Novell, who had in turn acquired it from
AT&T some time previously. What Berkeley got in return was
Novell's blessing that the 4.4BSD-Lite release, when
it was finally released, would be declared unencumbered and all
existing Net/2 users would be strongly encouraged to switch. This
included FreeBSD, and the project was given until the end of July
1994 to stop shipping its own Net/2 based product. Under the
terms of that agreement, the project was allowed one last release
before the deadline, that release being FreeBSD 1.1.5.1.FreeBSD then set about the arduous task of literally
re-inventing itself from a completely new and rather incomplete
set of 4.4BSD-Lite bits. The Lite releases were
light in part because Berkeley's CSRG had removed large chunks of
code required for actually constructing a bootable running system
(due to various legal requirements) and the fact that the Intel
port of 4.4 was highly incomplete. It took the project until
November of 1994 to make this transition, at which point it
released FreeBSD 2.0 to the net and on CDROM (in late December).
Despite being still more than a little rough around the edges,
the release was a significant success and was followed by the
more robust and easier to install FreeBSD 2.0.5 release in June of
1995.We released FreeBSD 2.1.5 in August of 1996, and it appeared
to be popular enough among the ISP and commercial communities that
another release along the 2.1-STABLE branch was merited. This was
FreeBSD 2.1.7.1, released in February 1997 and capping the end of
mainstream development on 2.1-STABLE. Now in maintenance mode,
only security enhancements and other critical bug fixes will be
done on this branch (RELENG_2_1_0).FreeBSD 2.2 was branched from the development mainline
(-CURRENT) in November 1996 as the RELENG_2_2
branch, and the first full release (2.2.1) was released in April
1997. Further releases along the 2.2 branch were done in the
summer and fall of '97, the last of which (2.2.8) appeared in
November 1998. The first official 3.0 release appeared in
October 1998 and spelled the beginning of the end for the 2.2
branch.The tree branched again on Jan 20, 1999, leading to the
4.0-CURRENT and 3.X-STABLE branches. From 3.X-STABLE, 3.1 was
released on February 15, 1999, 3.2 on May 15, 1999, 3.3 on
September 16, 1999, 3.4 on December 20, 1999, and 3.5 on
June 24, 2000, which was followed a few days later by a minor
point release update to 3.5.1, to incorporate some last-minute
security fixes to Kerberos. This will be the final release in the
3.X branch.There was another branch on March 13, 2000, which saw the
emergence of the 4.X-STABLE branch, now considered to be the
"current -stable branch". There have been several releases
from it so far: 4.0-RELEASE came out in March 2000, 4.1 was
released in July 2000, 4.2 in November 2000, and 4.3 in April
2001. There will be more releases along the 4.X-stable
(RELENG_4) branch throughout 2001.Long-term development projects continue to take place in the
5.0-CURRENT (trunk) branch, and SNAPshot releases of 5.0 on
CDROM (and, of course, on the net) are continually made available
from
the snapshot server as work progresses.JordanHubbard
- Contributed
+ Contributed by FreeBSD Project GoalsFreeBSD ProjectGoalsThe goals of the FreeBSD Project are to provide software that
may be used for any purpose and without strings attached. Many of
us have a significant investment in the code (and project) and
would certainly not mind a little financial compensation now and
then, but we are definitely not prepared to insist on it. We
believe that our first and foremost mission is to
provide code to any and all comers, and for whatever purpose, so
that the code gets the widest possible use and provides the widest
possible benefit. This is, I believe, one of the most fundamental
goals of Free Software and one that we enthusiastically
support.GNU General Public License (GPL)GNU Lesser General Public License (LGPL)BSD CopyrightThat code in our source tree which falls under the GNU
General Public License (GPL) or Library General Public License
(LGPL) comes with slightly more strings attached, though at
least on the side of enforced access rather than the usual
opposite. Due to the additional complexities that can evolve
in the commercial use of GPL software we do, however, prefer
software submitted under the more relaxed BSD copyright when
it's a reasonable option to do so.SatoshiAsami
- Contributed
+ Contributed by The FreeBSD Development ModelFreeBSD ProjectDevelopment ModelThe development of FreeBSD is a very open and flexible
process, FreeBSD being literally built from the contributions
of hundreds of people around the world, as can be seen from
our our list of
contributors. We are constantly on the lookout for
new developers and ideas, and those interested in becoming
more closely involved with the project need simply contact us
at the &a.hackers;. The &a.announce; is also available to
those wishing to make other FreeBSD users aware of major areas
of work.Useful things to know about the FreeBSD project and its
development process, whether working independently or in close
cooperation:The CVS repositoryCVSrepositoryConcurrent Versions SystemCVSThe central source tree for FreeBSD is maintained by
CVS
(Concurrent Versions System), a freely available source code
control tool that comes bundled with FreeBSD. The primary
CVS
repository resides on a machine in Santa Clara CA, USA
from where it is replicated to numerous mirror machines
throughout the world. The CVS tree, as well as the -CURRENT and -STABLE trees which are checked out
of it, can be easily replicated to your own machine as well.
Please refer to the Synchronizing
your source tree section for more information on
doing this.The committers listcommittersThe committers
are the people who have write access to
the CVS tree, and are thus authorized to make modifications
to the FreeBSD source (the term committer
comes from the &man.cvs.1; commit
command, which is used to bring new changes into the CVS
repository). The best way of making submissions for review
by the committers list is to use the &man.send-pr.1;
command, though if something appears to be jammed in the
system then you may also reach them by sending mail to
cvs-committers@FreeBSD.org.The FreeBSD core teamcore teamThe FreeBSD core team
would be equivalent to the board of directors if the FreeBSD
Project were a company. The primary task of the core team
is to make sure the project, as a whole, is in good shape
and is heading in the right directions. Inviting dedicated
and responsible developers to join our group of committers
is one of the functions of the core team, as is the
recruitment of new core team members as others move on.
The current core team was elected from a pool of committer
candidates in October 2000. Elections are held every 2 years.
Some core team members also have specific areas of
responsibility, meaning that they are committed to
ensuring that some large portion of the system works as
advertised. For a complete list of FreeBSD developers
and their areas of responsibility, please see the Contributors
ListMost members of the core team are volunteers when it
comes to FreeBSD development and do not benefit from the
project financially, so commitment should
also not be misconstrued as meaning guaranteed
support. The board of directors
analogy above is not actually very accurate, and it may be
more suitable to say that these are the people who gave up
their lives in favor of FreeBSD against their better
judgment!Outside contributorscontributorsLast, but definitely not least, the largest group of
developers are the users themselves who provide feedback and
bug fixes to us on an almost constant basis. The primary
way of keeping in touch with FreeBSD's more non-centralized
development is to subscribe to the &a.hackers; (see mailing list info) where
such things are discussed.The
FreeBSD Contributors List is a long
and growing one, so why not join it by contributing
something back to FreeBSD today?Providing code is not the only way of contributing to
the project; for a more complete list of things that need
doing, please refer to the how to
contribute section in this handbook.In summary, our development model is organized as a loose set
of concentric circles. The centralized model is designed for the
convenience of the users of FreeBSD, who are
thereby provided with an easy way of tracking one central code
base, not to keep potential contributors out! Our desire is to
present a stable operating system with a large set of coherent
application programs that the users
can easily install and use, and this model works very well in
accomplishing that.All we ask of those who would join us as FreeBSD developers is
some of the same dedication its current people have to its
continued success!The Current FreeBSD ReleaseNetBSDOpenBSD386BSDFree Software FoundationU.C. BerkeleyComputer Systems Resarch Group (CSRG)FreeBSD is a freely available, full source 4.4BSD-Lite based
release for Intel i386, i486, Pentium, Pentium Pro, Celeron,
Pentium II, Pentium III (or compatible) and DEC Alpha based computer
systems. It is based primarily on software from U.C. Berkeley's
CSRG group, with some enhancements from NetBSD, OpenBSD, 386BSD, and
the Free Software Foundation.Since our release of FreeBSD 2.0 in late 94, the performance,
feature set, and stability of FreeBSD has improved dramatically.
The largest change is a revamped virtual memory system with a merged
VM/file buffer cache that not only increases performance, but also
reduces FreeBSD's memory footprint, making a 5MB configuration a
more acceptable minimum. Other enhancements include full NIS client
and server support, transaction TCP support, dial-on-demand PPP,
integrated DHCP support, an improved SCSI subsystem, ISDN support,
support for ATM, FDDI, Fast and Gigabit Ethernet (1000Mbit)
adapters, improved support for the latest Adaptec controllers, and
many hundreds of bug fixes.We have also taken the comments and suggestions of many of our
users to heart and have attempted to provide what we hope is a more
sane and easily understood installation process. Your feedback on
this (constantly evolving) process is especially welcome!In addition to the base distributions, FreeBSD offers a
ported software collection with thousands of commonly
sought-after programs. At the time of this printing, there
were over &os.numports; ports! The list of ports ranges from
http (WWW) servers, to games, languages, editors, and almost
everything in between. The entire ports collection requires
approximately 100MB of storage, all ports being expressed as
deltas to their original sources. This makes
it much easier for us to update ports, and greatly reduces the
disk space demands made by the older 1.0 ports collection. To
compile a port, you simply change to the directory of the
program you wish to install, type make
install, and let the system do the rest. The full
original distribution for each port you build is retrieved
dynamically off the CDROM or a local FTP site, so you need
only enough disk space to build the ports you want. Almost
every port is also provided as a pre-compiled
package, which can be installed with a simple
command (pkg_add) by those who do not wish
to compile their own ports from source.A number of additional documents which you may find very helpful
in the process of installing and using FreeBSD may now also be found
in the /usr/share/doc directory on any machine
running FreeBSD 2.1 or later. You may view the locally installed
manuals with any HTML capable browser using the following
URLs:The FreeBSD Handbook/usr/share/doc/handbook/index.htmlThe FreeBSD FAQ/usr/share/doc/faq/index.htmlYou can also view the master (and most frequently updated)
copies at http://www.FreeBSD.org/.
diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
index 62e8b82459..2030c3bc00 100644
--- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
@@ -1,1311 +1,1327 @@
+
+
+
+ Jim
+ Mock
+ Updated and restructured by
+
+
+
+
+
+ Jake
+ Hamby
+ Originally contributed by
+
+
+
+
+
Configuring the FreeBSD KernelSynopsis
- Updated and restructured by &a.jim;, March 2000.
- Originally contributed by &a.jehamby;, 6 October
- 1995.kernelbuilding a custom kernelThe kernel is the core of the FreeBSD operating system. It is
responsible for managing memory, enforcing security controls,
networking, disk access, and much more. While more and more of FreeBSD
becomes dynamically configurable it is still occasionally necessary to
reconfigure and recompile your kernel.After reading this chapter you will know:Why you might need to build a custom kernelHow to write a kernel configuration file, or alter an existing
configuration fileHow to use the kernel configuration file to create and build a
new kernelHow to install the new kernelHow to create any entries in /dev that may
be requiredHow to troubleshoot if things go wrongWhy Build a Custom Kernel?Traditionally FreeBSD has had what is called a
monolithic kernel. This means that the kernel was one
large program, supported a fixed list of devices, and if you wanted to
change the kernel's behavior then you had to compile a new kernel, and
then reboot your computer with the new kernel.Today, FreeBSD is rapidly moving to a model where much of the
kernel's functionality is contained in modules which can be dynamically
loaded and unloaded from the kernel as necessary. This allows the
kernel to adapt to new hardware suddenly becoming available (such as
PCMCIA cards in a laptop), or for new functionality to be bought in to
the kernel that was not necessary when the kernel was originally
compiled. Colloquially these are called KLDs.Despite this, it is still necessary to carry out some static kernel
configuration. In some cases this is because the functionality is so
tied to the kernel that it can not be made dynamically loadable. In
others it may simply be because no one has yet taken the time to write a
dynamic loadable kernel module for that functionality yet.Building a custom kernel is one of the most important rites of
passage nearly every Unix user must endure. This process, while
time consuming, will provide many benefits to your FreeBSD system.
Unlike the GENERIC kernel, which must support a
wide range of hardware, a custom kernel only contains support for
your PC's hardware. This has a number of
benefits, such as:Faster boot time. Since the kernel will only probe the
hardware you have on your system, the time it takes your system to
boot will decrease dramatically.Less memory use. A custom kernel often uses less memory
than the GENERIC kernel, which is important
because the kernel is one process that must always be present in
memory. For this reason, a custom kernel is especially useful
on a system with a small amount of RAM.Additional hardware support. A custom kernel allows you to
add in support for devices such as sound cards, which are not
present in the GENERIC kernel.Building and Installing a Custom Kernelkernelbuilding / installingFirst, let us take a quick tour of the kernel build directory.
All directories mentioned will be relative to the main
/usr/src/sys directory, which is also
accessible through /sys. There are a number of
subdirectories here representing different parts of the kernel, but
the most important, for our purposes, are
arch/conf, where you
will edit your custom kernel configuration, and
compile, which is the staging area where your
kernel will be built. arch represents
either i386, alpha, or
pc98 (an alternative development branch of PC
hardware, popular in Japan). Everything inside a particular
architecture's directory deals with that architecture only; the rest
of the code is common to all platforms to which FreeBSD could
potentially be ported. Notice the logical organization of the
directory structure, with each supported device, filesystem, and
option in its own subdirectory.If there is not a
/usr/src/sys directory on your system, then
the kernel source has not been installed. The easiest way to
do this is by running /stand/sysinstall as
root, choosing Configure,
then Distributions, then
src, then sys.Next, move to the
arch/conf directory
and copy the GENERIC configuration file to the
name you want to give your kernel. For example:&prompt.root; cd /usr/src/sys/i386/conf
&prompt.root; cp GENERIC MYKERNELTraditionally, this name is in all capital letters and, if you
are maintaining multiple FreeBSD machines with different hardware,
it is a good idea to name it after your machine's hostname. We will
call it MYKERNEL for the purpose of this
example.Storing your kernel config file directly under
/usr/src can be a bad idea. If you are
experiencing problems it can be tempting to just delete
/usr/src and start again. Five seconds after
you do that you realize that you have deleted your custom kernel
config file.You might want to keep your kernel config file elsewhere, and then
create a symbolic link to the file in the i386
directory.For example:&prompt.root; cd /usr/src/sys/i386/conf
&prompt.root; mkdir /root/kernels
&prompt.root; cp GENERIC /root/kernels/MYKERNEL
&prompt.root; ln -s /root/kernels/MYKERNELYou must execute these and all of the following commands under
the root account or you will get permission
denied errors.Now, edit MYKERNEL with your favorite text
editor. If you are just starting out, the only editor available
will probably be vi, which is too complex to
explain here, but is covered well in many books in the bibliography. However, FreeBSD does
offer an easier editor called ee which, if you are a
beginner, should be your editor of choice. Feel free to change the
comment lines at the top to reflect your configuration or the
changes you have made to differentiate it from
GENERIC.SunOSIf you have built a kernel under SunOS or some other BSD
operating system, much of this file will be very familiar to you.
If you are coming from some other operating system such as DOS, on
the other hand, the GENERIC configuration file
might seem overwhelming to you, so follow the descriptions in the
Configuration File
section slowly and carefully.Be sure to always check the file
/usr/src/UPDATING, before you perform any update
steps, in the case you sync your source-tree with the
latest sources of the FreeBSD project.
In this file all important issues with updating FreeBSD
are written down. /usr/src/UPDATING always fits
to your version of the FreeBSD source, and is therefore more accurate
for those information than the handbook.You must now compile the source code for the kernel. There are two
procedures you can use to do this, and the one you will use depends on
why you are rebuilding the kernel, and the version of FreeBSD you are
running.If you have installed only the kernel
source code, use procedure 1.If you are running a FreeBSD version prior to 4.0, and you are
not upgrading to FreeBSD 4.0 or higher using
the make world procedure, use procedure 1.If you are building a new kernel without updating the source
code (perhaps just to add a new option, such as
IPFIREWALL) you can use either procedure.If you are rebuilding the kernel as part of a make
world process, use procedure 2.Procedure 1. Building a kernel the traditional wayRun &man.config.8; to generate the kernel source code.&prompt.root; /usr/sbin/config MYKERNELChange in to the build directory.&prompt.root; cd ../../compile/MYKERNELCompile the kernel.&prompt.root; make depend
&prompt.root; makeInstall the new kernel.&prompt.root; make installProcedure 2. Building a kernel the new
wayChange to the /usr/src directory&prompt.root; cd /usr/srcCompile the kernel.&prompt.root; make buildkernel KERNCONF=MYKERNELInstall the new kernel.&prompt.root; make installkernel KERNCONF=MYKERNELIn FreeBSD 4.2 and older you must replace
KERNCONF= with KERNEL=.
4.2-STABLE that was fetched after Feb 2nd, 2001 does
recognize KERNCONF=cvsupanonymous CVSCTMCVSanonymousIf you have not upgraded your source
tree in any way (you have not run CVSup,
CTM, or used
anoncvs), then you should use the
config, make depend,
make, make install sequence.kernel.oldThe new kernel will be copied to the root directory as
/kernel and the old kernel will be moved to
/kernel.old. Now, shutdown the system and
reboot to use your kernel. In case something goes wrong, there are
some troubleshooting
instructions at the end of this document. Be sure to read the
section which explains how to recover in case your new kernel does not boot.If you have added any new devices (such as sound cards) you
may have to add some device
nodes to your /dev directory before
you can use them.The Configuration FilekernelLINTLINTkernelconfig fileThe general format of a configuration file is quite simple.
Each line contains a keyword and one or more arguments. For
simplicity, most lines only contain one argument. Anything
following a # is considered a comment and
ignored. The following sections describe each keyword, generally in
the order they are listed in GENERIC, although
some related keywords have been grouped together in a single section
(such as Networking) even though they are actually scattered
throughout the GENERIC file. An exhaustive list of options and more
detailed explanations of the device lines is present in the
LINT configuration file, located in the same
directory as GENERIC. If you are in doubt as
to the purpose or necessity of a line, check first in
LINT.Quoting numbersIn all versions of FreeBSD up to and including 3.X,
&man.config.8; required that any strings in the configuration file
that contained numbers used as text had to be enclosed in double
quotes.This requirement was removed in the 4.X branch, which this
book covers, so if you are on a pre-4.X system, see the
/usr/src/sys/i386/conf/LINT and
/usr/src/sys/i386/conf/GENERIC
files on your system for examples.kernelexample config fileThe following is an example GENERIC kernel
configuration file with various additional comments where needed for
clarity. This example should match your copy in
/usr/src/sys/i386/conf/GENERIC fairly
closely. For details of all the possible kernel options, see
/usr/src/sys/i386/conf/LINT.#
# GENERIC -- Generic kernel configuration file for FreeBSD/i386
#
# For more information on this file, please read the handbook section on
# Kernel Configuration Files:
#
# http://www.freebsd.org/handbook/kernelconfig-config.html
#
# The handbook is also available locally in /usr/share/doc/handbook
# if you've installed the doc distribution, otherwise always see the
# FreeBSD World Wide Web server (http://www.FreeBSD.ORG/) for the
# latest information.
#
# An exhaustive list of options and more detailed explanations of the
# device lines is also present in the ./LINT configuration file. If you are
# in doubt as to the purpose or necessity of a line, check first in LINT.
#
# $FreeBSD: src/sys/i386/conf/GENERIC,v 1.246 2000/03/09 16:32:55 jlemon Exp $The following are the mandatory keywords required in
every kernel you build:kernel optionsmachinemachine i386This is the machine architecture. It must be either
i386, alpha, or
pc98.kernel optionscpucpu I386_CPU
cpu I486_CPU
cpu I586_CPU
cpu I686_CPUThe above specifies the type of CPU you have in your system.
You may have multiple instances of the CPU line (i.e., you are not
sure whether you should use I586_CPU or
I686_CPU), however, for a custom kernel, it is
best to specify only the CPU you have. If you are unsure of your CPU type,
you can use the dmesg command to
view your boot up messages.kernel optionscpu typeThe Alpha architecture has different values for
cpu_type. They include:cpu EV4
cpu EV5If you are using an Alpha machine, you should be using one of
the above CPU types.kernel optionsidentident GENERICThis is the identification of the kernel. You should change
this to whatever you named your kernel, in our previous example,
MYKERNEL. The value you put in the
ident string will print when you boot up the
kernel, so it is useful to give a kernel a different name if you
want to keep it separate from your usual kernel (i.e., you want to
build an experimental kernel).kernel optionsmaxusersmaxusers 32The maxusers option sets the size of a number
of important system tables. This number is supposed to be roughly
equal to the number of simultaneous users you expect to have on your
machine. However, under normal circumstances, you will want to set
maxusers to at least 4, especially if you are
using the X Window System or compiling software. The reason is that
the most important table set by maxusers is the
maximum number of processes, which is set to 20 + 16 *
maxusers, so if you set maxusers to 1,
then you can only have 36 simultaneous processes, including the 18
or so that the system starts up at boot time, and the 15 or so you
will probably create when you start the X Window System. Even a
simple task like reading a man page will start up nine processes to
filter, decompress, and view it. Setting
maxusers to 64 will allow you to have up to 1044
simultaneous processes, which should be enough for nearly all uses.
If, however, you see the dreaded proc table
full error when trying to start another program, or are
running a server with a large number of simultaneous users (like
ftp.FreeBSD.org), you can always
increase the number and rebuild.maxusers does not
limit the number of users which can log into your machine. It
simply sets various table sizes to reasonable values considering
the maximum number of users you will likely have on your system
and how many processes each of them will be running. One keyword
which does limit the number of simultaneous
remote logins is pseudo-device pty
16.Everything that follows is more or less optional. See the notes
underneath or next to each option for more information.#makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols
options MATH_EMULATE #Support for x87 emulationThis line allows the kernel to simulate a math co-processor if
your computer does not have one (386 or 486SX). If you have a
486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or
higher (Pentium, Pentium II, etc.), you can comment this line
out.The normal math co-processor emulation routines that come with
FreeBSD are not very accurate. If you do not
have a math co-processor, and you need the best accuracy, it is
recommended that you change this option to
GPL_MATH_EMULATION to use the GNU math support,
which is not included by default for licensing reasons.options INET #InterNETworkingNetworking support. Leave this in, even if you do not plan to
be connected to a network. Most programs require at least loopback
networking (i.e., making network connections within your PC), so
this is essentially mandatory.options INET6 #IPv6 communications protocolsThis enables the IPv6 communication protocols.options FFS #Berkeley Fast Filesystem
options FFS_ROOT #FFS usable as root device [keep this!]This is the basic hard drive filesystem. Leave it in if you
boot from the hard disk.options MFS #Memory Filesystem
options MD_ROOT #MD is a potential root deviceThis is the memory-mapped filesystem. This is basically a RAM
disk for fast storage of temporary files, useful if you have a lot
of swap space that you want to take advantage of. A perfect place
to mount an MFS partition is on the /tmp
directory, since many programs store temporary data here. To mount
an MFS RAM disk on /tmp, add the following line
to /etc/fstab:/dev/ad1s2b /tmp mfs rw 0 0Now you simply need to either reboot, or run the command
mount /tmp.kernel optionsNFSkernel optionsNFS_ROOToptions NFS #Network Filesystem
options NFS_ROOT #NFS usable as root device, NFS requiredThe network filesystem. Unless you plan to mount partitions
from a Unix file server over TCP/IP, you can comment these
out.kernel optionsMSDOSFSoptions MSDOSFS #MSDOS FilesystemThe MS-DOS filesystem. Unless you plan to mount a DOS formatted
hard drive partition at boot time, you can safely comment this out.
It will be automatically loaded the first time you mount a DOS
partition, as described above. Also, the excellent
mtools software (in the ports collection)
allows you to access DOS floppies without having to mount and
unmount them (and does not require MSDOSFS at
all).options CD9660 #ISO 9660 Filesystem
options CD9660_ROOT #CD-ROM usable as root, CD9660 requiredThe ISO 9660 filesystem for CDROMs. Comment it out if you do
not have a CDROM drive or only mount data CDs occasionally (since it
will be dynamically loaded the first time you mount a data CD).
Audio CDs do not need this filesystem.options PROCFS #Process filesystemThe process filesystem. This is a pretend
filesystem mounted on /proc which allows
programs like &man.ps.1; to give you more information on what
processes are running.options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!]Compatibility with 4.3BSD. Leave this in; some programs will
act strangely if you comment this out.options SCSI_DELAY=15000 #Delay (in ms) before probing SCSIThis causes the kernel to pause for 15 seconds before probing
each SCSI device in your system. If you only have IDE hard drives,
you can ignore this, otherwise you will probably want to lower this
number, perhaps to 5 seconds, to speed up booting. Of course, if
you do this, and FreeBSD has trouble recognizing your SCSI devices,
you will have to raise it back up.options UCONSOLE #Allow users to grab the consoleAllow users to grab the console, which is useful for X users.
For example, you can create a console xterm by typing xterm
-C, which will display any write,
talk, and any other messages you receive, as well
as any console messages sent by the kernel.options USERCONFIG #boot -c editorThis option allows you to boot the configuration editor from the
boot menu.options VISUAL_USERCONFIG #visual boot -c editorThis option allows you to boot the visual configuration editor
from the boot menu.options KTRACE #ktrace(1) supportThis enables kernel process tracing, which is useful in
debugging.options SYSVSHM #SYSV-style shared memoryThis option provides for System V shared memory. The most
common use of this is the XSHM extension in X, which many
graphics-intensive programs will automatically take advantage of for
extra speed. If you use X, you'll definitely want to include
this.options SYSVSEM #SYSV-style semaphoresSupport for System V semaphores. Less commonly used but only
adds a few hundred bytes to the kernel.options SYSVMSG #SYSV-style message queuesSupport for System V messages. Again, only adds a few hundred
bytes to the kernel.The &man.ipcs.1; command will list any processes using each of
these System V facilities.options P1003_1B #Posix P1003_1B real-time extensions
options _KPOSIX_PRIORITY_SCHEDULINGReal-time extensions added in the 1993 POSIX. Certain
applications in the ports collection use these (such as Star
Office).kernel optionsICMP_BANDLIMoptions ICMP_BANDLIM #Rate limit bad repliesThis option enables ICMP error response bandwidth limiting. You
typically want this option as it will help protect the machine from
denial of service packet attacks.kernel optionsSMP# To make an SMP kernel, the next two are needed
#options SMP # Symmetric MultiProcessor Kernel
#options APIC_IO # Symmetric (APIC) I/OThe above are both required for SMP support.device isaAll PCs supported by FreeBSD have one of these. If you have an
IBM PS/2 (Micro Channel Architecture), you cannot run FreeBSD at
this time (support is being worked on).device eisaInclude this if you have an EISA motherboard. This enables
auto-detection and configuration support for all devices on the EISA
bus.device pciInclude this if you have a PCI motherboard. This enables
auto-detection of PCI cards and gatewaying from the PCI to ISA
bus.# Floppy drives
device fdc0 at isa? port IO_FD1 irq 6 drq 2
device fd0 at fdc0 drive 0
device fd1 at fdc0 drive 1This is the floppy drive controller. fd0 is
the A: floppy drive, and
fd1 is the B:
drive.device ataThis driver supports all ATA and ATAPI devices. You only need
one device ata line for the kernel to detect all
PCI ATA/ATAPI devices on modern machines.device atadisk # ATA disk drivesThis is needed along with device ata for
ATAPI disk drives.
device atapicd # ATAPI CDROM drivesThis is needed along with device ata for
ATAPI CDROM drives.device atapifd # ATAPI floppy drivesThis is needed along with device ata for
ATAPI floppy drives.device atapist # ATAPI tape drivesThis is needed along with device ata for
ATAPI tape drives.options ATA_STATIC_ID #Static device numberingThis makes the controller number static (like the old driver) or
else the device numbers are dynamically allocated.# ATA and ATAPI devices
device ata0 at isa? port IO_WD1 irq 14
device ata1 at isa? port IO_WD2 irq 15Use the above for older, non-PCI systems.# SCSI Controllers
device ahb # EISA AHA1742 family
device ahc # AHA2940 and onboard AIC7xxx devices
device amd # AMD 53C974 (Teckram DC-390(T))
device dpt # DPT Smartcache - See LINT for options!
device isp # Qlogic family
device ncr # NCR/Symbios Logic
device sym # NCR/Symbios Logic (newer chipsets)
device adv0 at isa?
device adw
device bt0 at isa?
device aha0 at isa?
device aic0 at isa?SCSI controllers. Comment out any you do not have in your
system. If you have an IDE only system, you can remove these
altogether.# SCSI peripherals
device scbus # SCSI bus (required)
device da # Direct Access (disks)
device sa # Sequential Access (tape etc)
device cd # CD
device pass # Passthrough device (direct SCSI
access)SCSI peripherals. Again, comment out any you do not have, or if
you have only IDE hardware, you can remove them completely.# RAID controllers
device ida # Compaq Smart RAID
device amr # AMI MegaRAID
device mlx # Mylex DAC960 familySupported RAID controllers. If you do not have any of these,
you can comment them out or remove them.# atkbdc0 controls both the keyboard and the PS/2 mouse
device atkbdc0 at isa? port IO_KBDThe keyboard controller (atkbdc) provides I/O
services for the AT keyboard and PS/2 style pointing devices. This
controller is required by the keyboard driver
(atkbd) and the PS/2 pointing device driver
(psm).device atkbd0 at atkbdc? irq 1The atkbd driver, together with
atkbdc controller, provides access to the AT 84
keyboard or the AT enhanced keyboard which is connected to the AT
keyboard controller.device psm0 at atkbdc? irq 12Use this device if your mouse plugs into the PS/2 mouse
port.device vga0 at isa?The video card driver.# splash screen/screen saver
pseudo-device splashSplash screen at start up! Screen savers require this
too.# syscons is the default console driver, resembling an SCO console
device sc0 at isa?sc0 is the default console driver, which
resembles a SCO console. Since most full-screen programs access the
console through a terminal database library like
termcap, it should not matter whether you use
this or vt0, the VT220
compatible console driver. When you log in, set your
TERM variable to scoansi if
full-screen programs have trouble running under this console.# Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver
#device vt0 at isa?
#options XSERVER # support for X server on a vt console
#options FAT_CURSOR # start with block cursor
# If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines
#options PCVT_SCANSET=2 # IBM keyboards are non-stdThis is a VT220-compatible console driver, backward compatible to
VT100/102. It works well on some laptops which have hardware
incompatibilities with sc0. Also set your
TERM variable to vt100 or
vt220 when you log in. This driver might also
prove useful when connecting to a large number of different machines
over the network, where termcap or
terminfo entries for the sc0
device are often not available — vt100
should be available on virtually any platform.# Floating point support - do not disable.
device npx0 at nexus? port IO_NPX irq 13npx0 is the interface to the floating point
math unit in FreeBSD, which is either the hardware co-processor or
the software math emulator. This is not
optional.# Power management support (see LINT for more options)
device apm0 at nexus? disable flags 0x20 # Advanced Power ManagementAdvanced Power Management support. Useful for laptops.# PCCARD (PCMCIA) support
device card
device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000
device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disablePCMCIA support. You need this if you are installing on a
laptop.# Serial (COM) ports
device sio0 at isa? port IO_COM1 flags 0x10 irq 4
device sio1 at isa? port IO_COM2 irq 3
device sio2 at isa? disable port IO_COM3 irq 5
device sio3 at isa? disable port IO_COM4 irq 9These are the four serial ports referred to as COM1 through COM4
in the MS-DOS/Windows world.If you have an internal modem on COM4 and a serial port at
COM2, you will have to change the IRQ of the modem to 2 (for
obscure technical reasons, IRQ2 = IRQ 9) in order to access it
from FreeBSD. If you have a multiport serial card, check the
manual page for &man.sio.4; for more information on the proper
values for these lines. Some video cards (notably those based on
S3 chips) use IO addresses in the form of
0x*2e8, and since many cheap serial cards do
not fully decode the 16-bit IO address space, they clash with
these cards making the COM4 port practically unavailable.Each serial port is required to have a unique IRQ (unless you
are using one of the multiport cards where shared interrupts are
supported), so the default IRQs for COM3 and COM4 cannot be
used.# Parallel port
device ppc0 at isa? irq 7This is the ISA-bus parallel port interface.device ppbus # Parallel port bus (required)Provides support for the parallel port bus.device lpt # PrinterSupport for parallel port printers.All three of the above are required to enable parallel printer
support.device plip # TCP/IP over parallelThis is the driver for the parallel network interface.device ppi # Parallel port interface deviceThe general-purpose I/O (geek port) + IEEE1284
I/O.#device vpo # Requires scbus and dazip driveThis is for an Iomega Zip drive. It requires
scbus and da support. Best
performance is achieved with ports in EPP 1.9 mode.# PCI Ethernet NICs.
device de # DEC/Intel DC21x4x (Tulip)
device fxp # Intel EtherExpress PRO/100B (82557, 82558)
device tx # SMC 9432TX (83c170 EPIC)
device vx # 3Com 3c590, 3c595 (Vortex)
device wx # Intel Gigabit Ethernet Card (Wiseman)Various PCI network card drivers. Comment out or remove any of
these not present in your system.# PCI Ethernet NICs that use the common MII bus controller code.
device miibus # MII bus supportMII bus support is required for some PCI 10/100 Ethernet NICs,
namely those which use MII-compliant transceivers or implement
transceiver control interfaces that operate like an MII. Adding
device miibus to the kernel config pulls in
support for the generic miibus API and all of the PHY drivers,
including a generic one for PHYs that are not specifically handled
by an individual driverdevice dc # DEC/Intel 21143 and various workalikes
device rl # RealTek 8129/8139
device sf # Adaptec AIC-6915 (Starfire)
device sis # Silicon Integrated Systems SiS 900/SiS 7016
device ste # Sundance ST201 (D-Link DFE-550TX)
device tl # Texas Instruments ThunderLAN
device vr # VIA Rhine, Rhine II
device wb # Winbond W89C840F
device xl # 3Com 3c90x (Boomerang, Cyclone)Drivers that use the MII bus controller code.# ISA Ethernet NICs.
device ed0 at isa? port 0x280 irq 10 iomem 0xd8000
device ex
device ep
# WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really
# exists only as a PCMCIA device, so there is no ISA attachment needed
# and resources will always be dynamically assigned by the pccard code.
device wi
# Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will
# work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP
# mode (the factory default). If you set the switches on your ISA
# card for a manually chosen I/O address and IRQ, you must specify
# those parameters here.
device an
# The probe order of these is presently determined by i386/isa/isa_compat.c.
device ie0 at isa? port 0x300 irq 10 iomem 0xd0000
device fe0 at isa? port 0x300
device le0 at isa? port 0x300 irq 5 iomem 0xd0000
device lnc0 at isa? port 0x280 irq 10 drq 0
device cs0 at isa? port 0x300
device sn0 at isa? port 0x300 irq 10
# requires PCCARD (PCMCIA) support to be activated
#device xe0 at isa?ISA Ethernet drivers. See
/usr/src/sys/i386/conf/LINT for which cards are
supported by which driver.# Pseudo devices - the number indicates how many units to allocate.
pseudo-device loop # Network loopbackThis is the generic loopback device for TCP/IP. If you telnet
or FTP to localhost (a.k.a., 127.0.0.1) it will come back at you through
this pseudo-device. This is mandatory.pseudo-device ether # Ethernet supportether is only needed if you have an Ethernet
card. It includes generic Ethernet protocol code.pseudo-device sl 1 # Kernel SLIPsl is for SLIP support. This has been almost
entirely supplanted by PPP, which is easier to set up, better suited
for modem-to-modem connection, and more powerful. The
number after sl
specifies how many simultaneous SLIP sessions to support.pseudo-device ppp 1 # Kernel PPPThis is for kernel PPP support for dial-up connections. There
is also a version of PPP implemented as a userland application that
uses tun and offers more flexibility and features
such as demand dialing. The number after
ppp specifies how many simultaneous PPP
connections to support.pseudo-device tun # Packet tunnel.This is used by the userland PPP software. A
number after tun
specifies the number of simultaneous PPP sessions to support. See
the PPP section of this book for more
information.
pseudo-device pty # Pseudo-ttys (telnet etc)This is a pseudo-terminal or simulated login port.
It is used by incoming telnet and
rlogin sessions,
xterm, and some other applications such
as emacs. A
number after pty indicates the number of
ptys to create. If you need more than the
default of 16 simultaneous xterm windows
and/or remote logins, be sure to increase this number accordingly,
up to a maximum of 256.pseudo-device md # Memory disksMemory disk pseudo-devices.pseudo-device gif 4 # IPv6 and IPv4 tunnelingThis implements IPv6 over IPv4 tunneling, IPv4 over IPv6
tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6
tunneling.pseudo-device faith 1 # IPv6-to-IPv4 relaying (translation)This pseudo-device captures packets that are sent to it and
diverts them to the IPv4/IPv6 translation daemon.# The `bpf' pseudo-device enables the Berkeley Packet Filter.
# Be aware of the administrative consequences of enabling this!
pseudo-device bpf # Berkeley packet filterThis is the Berkeley Packet Filter. This pseudo-device allows
network interfaces to be placed in promiscuous mode, capturing every
packet on a broadcast network (e.g., an Ethernet). These packets
can be captured to disk and or examined with the &man.tcpdump.1;
program.The bpf pseudo-device is also used by
&man.dhclient.8; to obtain the IP address of the default router
(gateway) and so on. If you use DHCP, leave this
uncommented.# USB support
#device uhci # UHCI PCI->USB interface
#device ohci # OHCI PCI->USB interface
#device usb # USB Bus (required)
#device ugen # Generic
#device uhid # Human Interface Devices
#device ukbd # Keyboard
#device ulpt # Printer
#device umass # Disks/Mass storage - Requires scbus and da
#device ums # Mouse
# USB Ethernet, requires mii
#device aue # ADMtek USB ethernet
#device cue # CATC USB ethernet
#device kue # Kawasaki LSI USB ethernetSupport for various USB devices.For more information and additional devices supported by
FreeBSD, see
/usr/src/sys/i386/conf/LINT.Making Device Nodesdevice nodesMAKEDEVAlmost every device in the kernel has a corresponding
node entry in the /dev directory.
These nodes look like regular files, but are actually special
entries into the kernel which programs use to access the device.
The shell script /dev/MAKEDEV, which is
executed when you first install the operating system, creates
nearly all of the device nodes supported. However, it does not
create all of them, so when you add support for
a new device, it pays to make sure that the appropriate entries are
in this directory, and if not, add them. Here is a simple
example:Suppose you add the IDE CD-ROM support to the kernel. The line
to add is:device acd0This means that you should look for some entries that start with
acd0 in the /dev
directory, possibly followed by a letter, such as
c, or preceded by the letter
r, which means a raw device. It
turns out that those files are not there, so you must change to the
/dev directory and type:MAKEDEV&prompt.root; sh MAKEDEV acd0When this script finishes, you will find that there are now
acd0c and racd0c entries
in /dev so you know that it executed
correctly.For sound cards, the following command creates the appropriate
entries:&prompt.root; sh MAKEDEV snd0When creating device nodes for devices such as sound cards, if
other people have access to your machine, it may be desirable to
protect the devices from outside access by adding them to the
/etc/fbtab file. See &man.fbtab.5; for more
information.Follow this simple procedure for any other
non-GENERIC devices which do not have
entries.All SCSI controllers use the same set of
/dev entries, so you do not need to create
these. Also, network cards and SLIP/PPP pseudo-devices do not
have entries in /dev at all, so you do not
have to worry about these either.If Something Goes WrongThere are four categories of trouble that can occur when
building a custom kernel. They are:config failsIf the config command fails when you
give it your kernel description, you have probably made a
simple error somewhere. Fortunately,
config will print the line number that it
had trouble with, so you can quickly skip to it with
vi. For example, if you see:config: line 17: syntax errorYou can skip to the problem in vi by
typing 17G in command mode. Make sure the
keyword is typed correctly, by comparing it to the
GENERIC kernel or another
reference.make failsIf the make command fails, it usually
signals an error in your kernel description, but not severe
enough for config to catch it. Again, look
over your configuration, and if you still cannot resolve the
problem, send mail to the &a.questions; with your kernel
configuration, and it should be diagnosed very quickly.The kernel will not bootIf your new kernel does not boot, or fails to recognize
your devices, do not panic! Fortunately, BSD has an excellent
mechanism for recovering from incompatible kernels. Simply
choose the kernel you want to boot from at the FreeBSD boot
loader (i.e.,
boot kernel.old).
When reconfiguring a kernel, it is always a good idea to keep
a kernel that is known to work on hand.After booting with a good kernel you can check over your
configuration file and try to build it again. One helpful
resource is the /var/log/messages file
which records, among other things, all of the kernel messages
from every successful boot. Also, the &man.dmesg.8; command
will print the kernel messages from the current boot.If you are having trouble building a kernel, make sure
to keep a GENERIC, or some other kernel
that is known to work on hand as a different name that will
not get erased on the next build. You cannot rely on
kernel.old because when installing a
new kernel, kernel.old is overwritten
with the last installed kernel which may be non-functional.
Also, as soon as possible, move the working kernel to the
proper kernel location or commands such
as &man.ps.1; will not work properly. The proper command to
unlock the kernel file that
make installs (in order to move another
kernel back permanently) is:&prompt.root; chflags noschg /kernelIf you find you cannot do this, you are probably running
at a &man.securelevel.8; greater than zero. Edit
kern_securelevel in
/etc/rc.conf and set it to
-1, then reboot. You can change it back
to its previous setting when you are happy with your new
kernel.And, if you want to lock your new kernel
into place, or any file for that matter, so that it cannot
be moved or tampered with:&prompt.root; chflags schg /kernelThe kernel works, but ps does not work
any more!If you have installed a different version of the kernel
from the one that the system utilities have been built with,
for example, a 4.X kernel on a 3.X system, many system-status
commands like &man.ps.1; and &man.vmstat.8; will not work any
more. You must recompile the libkvm
library as well as these utilities. This is one reason it is
not normally a good idea to use a different version of the
kernel from the rest of the operating system.
diff --git a/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml
index e091d006fd..1957bbb647 100644
--- a/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/kernelopts/chapter.sgml
@@ -1,160 +1,168 @@
+
+
+
+ Jörg
+ Wunsch
+ Contributed by
+
+
+
+
Adding New Kernel Configuration Options
- Contributed by &a.joerg;
-
You should be familiar with the section about kernel configuration before reading
here.What's a Kernel Option, Anyway?The use of kernel options is basically described in the kernel configuration section.
There's also an explanation of historic and
new-style options. The ultimate goal is to eventually
turn all the supported options in the kernel into new-style ones, so for
people who correctly did a make depend in their
kernel compile directory after running
&man.config.8;, the build process will automatically pick up modified
options, and only recompile those files where it is necessary. Wiping
out the old compile directory on each run of &man.config.8; as it is
still done now can then be eliminated again.Basically, a kernel option is nothing else than the definition of a
C preprocessor macro for the kernel compilation process. To make the
build truly optional, the corresponding part of the kernel source (or
kernel .h file) must be written with the option
concept in mind, i.e., the default can be overridden by the
config option. This is usually done with something like:#ifndef THIS_OPTION
#define THIS_OPTION (some_default_value)
#endif /* THIS_OPTION */This way, an administrator mentioning another value for the option
in his config file will take the default out of effect, and replace it
with his new value. Clearly, the new value will be substituted into the
source code during the preprocessor run, so it must be a valid C
expression in whatever context the default value would have been
used.It is also possible to create value-less options that simply enable
or disable a particular piece of code by embracing it in#ifdef THAT_OPTION
[your code here]
#endifSimply mentioning THAT_OPTION in the config file
(with or without any value) will then turn on the corresponding piece of
code.People familiar with the C language will immediately recognize that
everything could be counted as a config option where there
is at least a single #ifdef referencing it...
However, it's unlikely that many people would putoptions notyet,notdefin their config file, and then wonder why the kernel compilation
falls over.Clearly, using arbitrary names for the options makes it very hard to
track their usage throughout the kernel source tree. That is the
rationale behind the new-style option scheme, where
each option goes into a separate .h file in the
kernel compile directory, which is by convention named
opt_foo.h. This way,
the usual Makefile dependencies could be applied, and
make can determine what needs to be recompiled once
an option has been changed.The old-style option mechanism still has one advantage for local
options or maybe experimental options that have a short anticipated
lifetime: since it is easy to add a new #ifdef to the
kernel source, this has already made it a kernel config option. In this
case, the administrator using such an option is responsible himself for
knowing about its implications (and maybe manually forcing the
recompilation of parts of his kernel). Once the transition of all
supported options has been done, &man.config.8; will warn whenever an
unsupported option appears in the config file, but it will nevertheless
include it into the kernel Makefile.Now What Do I Have to Do for it?First, edit sys/conf/options (or
sys/<arch>/conf/options.<arch>,
e. g. sys/i386/conf/options.i386), and select an
opt_foo.h file where
your new option would best go into.If there is already something that comes close to the purpose of the
new option, pick this. For example, options modifying the overall
behavior of the SCSI subsystem can go into
opt_scsi.h. By default, simply mentioning an
option in the appropriate option file, say FOO,
implies its value will go into the corresponding file
opt_foo.h. This can be overridden on the
right-hand side of a rule by specifying another filename.If there is no
opt_foo.h already
available for the intended new option, invent a new name. Make it
meaningful, and comment the new section in the
options[.<arch>]
file. &man.config.8; will automagically pick up the change, and create
that file next time it is run. Most options should go in a header file
by themselves..Packing too many options into a single
opt_foo.h will cause too
many kernel files to be rebuilt when one of the options has been changed
in the config file.Finally, find out which kernel files depend on the new option.
Unless you have just invented your option, and it does not exist
anywhere yet, &prompt.user; find /usr/src/sys -type f | xargs fgrep NEW_OPTION
is your friend in finding them. Go and edit all those files, and add
#include "opt_foo.h"on
top before all the #include <xxx.h> stuff.
This sequence is most important as the options could override defaults
from the regular include files, if the defaults are of the form
#ifndef NEW_OPTION #define NEW_OPTION (something)
#endif in the regular header.Adding an option that overrides something in a system header file
(i.e., a file sitting in /usr/include/sys/) is
almost always a mistake.
opt_foo.h cannot be
included into those files since it would break the headers more
seriously, but if it is not included, then places that include it may
get an inconsistent value for the option. Yes, there are precedents for
this right now, but that does not make them more correct.
diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
index 70a032d27a..147543afa5 100644
--- a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml
@@ -1,1014 +1,1035 @@
- Localization - I18N/L10N Usage and Setup
-
- Contributed by &a.ache;
+
+
+
+ Andrey A.
+ Chernov
+ Contributed by
+
+
+
+
+ Michael C.
+ Wu
+ Rewritten by
+
+
+
+
- Rewritten by &a.keichii;, 30 Nov 2000.
+ Localization - I18N/L10N Usage and SetupSynopsisThis section of the handbook discusses the internationalization
and localization of FreeBSD to different countries and different
settings. If the users wish to use languages other than the system
default English, he/she will have to setup the system accordingly.
Please note that language support for each language varies in level.
Hence, the user should contact the respective FreeBSD local group
that is responsible for each language.The author realizes that he may have been incomplete in the
description of the I18N process in FreeBSD. Due to the various
levels of I18N implementation in both the system and application
levels, we advise you to refer to individual documentation, man
pages, READMEs, and so forth.Should you have any questions or suggestions regarding this
chapter, please email the author.The BasicsWhat is I18N/L10N?internationalizationlocalizationDevelopers shortened internationalization into the term I18N,
counting the number of letters between the first and the last
letters of internationalization. L10N uses the same naming
scheme, coming from "localization". Combined
together, I18N/L10N methods, protocols, and applications allow
users to use languages of their choice.I18N applications are programmed using I18N kits under
libraries. It allows for developers to write a simple file and
translate displayed menus and texts to each language. We strongly
encourage programmers to follow this convention.Why should I use I18N/L10N?I18N/L10N is used whenever you wish to either view, input, or
process data in non-English languages.What languages are supported in the I18N effort?I18N and L10N are not FreeBSD specific. Currently, one can
choose from most of the major languages of the World, including
but not limited to: Chinese, German, Japanese, Korean, French,
Russian, Vietnamese and others.Using LocalizationIn all its splendor, I18N is not FreeBSD-specific and is a
convention. We encourage you to help FreeBSD in following this
convention.localeLocalization settings are based on three main terms:
Language Code, Country Code, and Encoding. Locale names are
constructed from these parts as follows:LanguageCode_CountryCode.EncodingLanguage and Country Codeslanguage codescountry codesIn order to localize a FreeBSD system to a specific language
(or any other I18N-supporting Unixes), the user needs to find out
the codes for the specify country and language (country
codes tell applications what variation of given
language to use). In addition, web
browsers, SMTP/POP servers, web servers, etc. make decisions based on
them. The following are examples of language/country codes:Language/Country CodeDescriptionen_USEnglish - United Statesru_RURussian for Russiazh_TWTraditional Chinese for TaiwanEncodingsencodingsASCIISome languages use non-ASCII encodings that are 8-bit, wide
or multibyte characters, see &man.multibyte.3; for more
details. Older applications do not recognize them
and mistake them for control characters. Newer applications
usually do recognize 8-bit characters. Depending on the
implementation, users may be required to compile an application
with wide or multibyte characters support, or configure it correctly.
To be able to input and process wide or multibyte characters, the FreeBSD Ports collection has provided
each language with different programs. Refer to the I18N
documentation in the respective FreeBSD Port.Specifically, the user needs to look at the application
documentation to decide on how to configure it correctly or to
pass correct values into the configure/Makefile/compiler.Some things to keep in mind are:Language specific single C chars character sets
(see &man.multibyte.3;), i.e.,
ISO-8859-1, ISO-8859-15, KOI8-R, CP437.Wide or multibyte encodings, f.e. EUC, Big5.You can check the active list of character sets at the
IANA Registry.FreeBSD versions 5.0 and up use X11-compatible locale
encodings instead.I18N applicationsIn the FreeBSD Ports and Package system, I18N applications
have been named with I18N in their names for
easy identification. However, they do not always support the
language needed.Setting LocaleTheoretically, one only needs to export the value of his/her
locale name as LANG in the login shell and is
usually done through the user's
~/.login_conf or the user login shell
configuration (~/.profile,
~/.bashrc, ~/.cshrc).
This should set all of the locale subsets (such as
LC_CTYPE, LC_CTIME, etc.). Please
refer to language-specific FreeBSD documentation for more
information.You should set the following two values in your configuration
files:POSIXLANG for POSIX &man.setlocale.3; family
functionsMIMEMM_CHARSET for applications' MIME character
setThis includes the user shell config, the specific application
config, and the X11 config.Setting Locale Methodslocalelogin classThere are two methods for setting locale, and both are
described below. The first (recommended one) is by assigning
the environment variables in login
class, and the second is by adding the environment
variable assignments to the system's shell startup file.Login Classes MethodThis method allows environment variables needed for locale
name and MIME character sets to be assigned once for every
possible shell instead of adding specific shell assignments to
each shell's startup file. User
Level Setup can be done by an user himself and Administrator Level Setup require
superuser privileges.User Level SetupHere is a minimal example of a
.login_conf file in user's home
directory which has both variables set for Latin-1
encoding:german:German User:\
:charset=ISO-8859-1:\
:lang=de_DE.ISO_8859-1:de_DE.ISO8859-1 for FreeBSD
versions 5.0 and up.Traditional Chinese / BIG-5 encodingHere is an example of a
.login_conf that sets the variables
for Traditional Chinese in BIG-5 encoding. Notice the many
more variables set because some software does not respect
locale variables correctly for Chinese, Japanese, and Korean.#Users who do not wish to use monetary units or time formats
#of Taiwan can manually change each variable
taiwan:Taiwanese User:\
lang=zh_TW.Big5:\
lc_all=zh_TW.Big:\
lc_collate=zh_TW.Big5:\
lc_ctype=zh_TW.Big5:\
lc_messages=zh_TW.Big5:\
lc_monetary=zh_TW.Big5:\
lc_numeric=zh_TW.Big5:\
lc_time=zh_TW.Big5:\
charset=big5:\
xmodifiers="@im=xcin": #Setting the XIM Input ServerSee Administrator Level
Setup and &man.login.conf.5; for more details.Administrator Level SetupCheck that /etc/login.conf have the
correct language user's class. Make sure these settings
appear in /etc/login.conf:language_name:accounts_title:\
:charset=MIME_charset:\
:lang=locale_name:\
:tc=default:So sticking with our previous example using Latin-1, it
would look like this:german:German Users Accounts:\
:charset=ISO-8859-1:\
:lang=de_DE.ISO_8859-1:\
:tc=default:de_DE.ISO8859-1 for FreeBSD
versions 5.0 and up.Changing Login Classes with &man.vipw.8;vipwUse vipw to add new users, and make
the entry look like this:user:password:1111:11:language:0:0:User Name:/home/user:/bin/shChanging Login Classes with &man.adduser.8;adduserlogin classUse adduser to add new users, and do
the following:Set defaultclass =
language in
/etc/adduser.conf. Keep in mind
you must enter a default class for
all users of other languages in this case.An alternative variant is answering the specified
language each time that
Enter login class: default []:
appears from &man.adduser.8;Another alternative is to use the following for each
user of a different language that you wish to
add:&prompt.root; adduser -class languageChanging Login Classes with &man.pw.8;pwIf you use &man.pw.8; for adding new users, call it in
this form:&prompt.root; pw useradd user_name -L languageShell Startup File MethodThis method is not recommended because it requires a
different setup for each possible login program chosen. Use
the Login Class Method
instead.MIMElocaleTo add the locale name and MIME character set, just set
the two environment variables shown below in the
/etc/profile and/or
/etc/csh.login shell startup files. We
will use the German language as an example below:In /etc/profile:LANG=de_DE.ISO_8859-1; export LANGMM_CHARSET=ISO-8859-1; export MM_CHARSETOr in /etc/csh.login:setenv LANG de_DE.ISO_8859-1setenv MM_CHARSET ISO-8859-1de_DE.ISO8859-1 for FreeBSD
versions 5.0 and up.Alternatively, you can add the above instructions to
/usr/share/skel/dot.profile (similar to
what was used in /etc/profile above), or
/usr/share/skel/dot.login (similar to
what was used in /etc/csh.login
above).For X11:In $HOME/.xinitrc:LANG=de_DE.ISO_8859-1; export LANGOr:setenv LANG de_DE.ISO_8859-1Depending on your shell (see above).de_DE.ISO8859-1 for FreeBSD
versions 5.0 and up.Console SetupFor all single C chars character sets, set the correct
console fonts in /etc/rc.conf for the
language in question with:font8x16=font_name
font8x14=font_name
font8x8=font_nameThe font_name here is taken from
the /usr/share/syscons/fonts directory,
without the .fnt suffix.sysinstallkeymapscreenmapAlso be sure to set the correct keymap and screenmap for your
single C chars character set through
/stand/sysinstall.
Once inside sysinstall, choose Configure, then
Console. Alternatively, you can add the
following to /etc/rc.conf:scrnmap=screenmap_name
keymap=keymap_name
keychange="fkey_number sequence"The screenmap_name here is taken
from the /usr/share/syscons/scrnmaps
directory, without the .scm suffix. A
screenmap with a corresponding mapped font is usually needed as a
workaround for expanding bit 8 to bit 9 on a VGA adapter's font
character matrix in pseudographics area, i.e., to move letters out
of that area if screen font uses a bit 8 column.If you have the moused daemon
enabled by setting the following
in your /etc/rc.conf:moused_enable="YES"then examine the mouse cursor information in the next
paragraph.mousedBy default the mouse cursor of the syscons driver occupies the
0xd0-0xd3 range in the character set. If your language uses this
range, you need to move the cursor's range outside of it. To enable
the workaround for FreeBSD versions before 5.0, insert the following
line into your kernel config:options SC_MOUSE_CHAR=0x03For the FreeBSD versions 5.0 and up insert the following line
into /etc/rc.conf:mousechar_start=3The keymap_name here is taken from
the /usr/share/syscons/keymaps directory,
without the .kbd suffix.The keychange is usually needed to program
function keys to match the selected terminal type because
function key sequences cannot be defined in the key map.Also be sure to set the correct console terminal type in
/etc/ttys for all ttyv*
entries. Current pre-defined correspondences are:Character SetTerminal TypeISO-8859-1 or ISO-8859-15cons25l1ISO-8859-2cons25l2KOI8-Rcons25rKOI8-Ucons25uCP437 (hardware default) or US-ASCIIcons25For wide or multibyte characters languages, use the correct
FreeBSD port in your
/usr/ports/language
directory. Some ports appear as console while the system sees it
as serial vtty's, hence you must reserve enough vtty's for both
X11 and the pseudo-serial console. Here is a partial list of
applications for using other languages in console:LanguageLocationTraditional Chinese (BIG-5)chinese/big5conJapanesejapanese/ja-kon2-* or
japanese/Mule_WnnKoreankorean/ko-hanX11 SetupAlthough X11 is not part of the FreeBSD Project, we have
included some information here for FreeBSD users. For more
details, refer to the XFree86
web site or whichever X11 Server you use.In ~/.Xresources, you can additionally
tune application specific I18N settings (e.g., fonts, menus,
etc.).Displaying FontsX11 True Type font serverInstall the X11 True Type-Common server (XTT-common) and
install the language truetype fonts. Setting the correct
locale should allow you to view your selected language in menus
and such.Inputting Non-English CharactersX11 Input Method (XIM)The X11 Input Method (XIM) Protocol is a new standard for
all X11 clients. All X11 applications should be written as XIM
clients that take input from XIM Input servers. There are
several XIM servers available for different languages.Printer SetupSome single C chars character sets are usually hardware
coded into printers. Wide or multibyte
character sets require special setup and we recommend using
apsfilter. You may also convert the
document to PostScript or PDF formats using language specific
converters.Kernel and File SystemsThe FreeBSD FFS filesystem is 8-bit clean, so it can be used
with any single C chars character set (see &man.multibyte.3;),
but there is no character set
name stored in the filesystem; i.e., it is raw 8-bit and does not
know anything about encoding order. Officially, FFS does not
support any form of wide or multibyte character sets yet. However, some
wide or multibyte character sets have independent patches for FFS
enabling such support. They are only temporary unportable
solutions or hacks and we have decided to not include them in the
source tree. Refer to respective languages' web sites for more
informations and the patch files.DOSUnicodeThe FreeBSD MS-DOS filesystem has the configurable ability to
convert between MS-DOS, Unicode character sets and chosen
FreeBSD filesystem character sets. See &man.mount.msdos.8; for
details.Advanced TopicsIf you wish to compile I18N applications or program I18N
compliant applications, please read this section.Compiling I18N ProgramsMany FreeBSD Ports have been ported with I18N support. Some
of them are marked with -I18N in the port name. These and many
other programs have built in support for I18N and need no special
consideration.MySQLHowever, some applications such as
MySQL need to be have the
Makefile configured with the specific
charset. This is usually done in the
Makefile or done by passing a value to
configure in the source.Programming I18N Compliant ApplicationsQtGTKTo make your application more useful for speakers of other
languages, we hope that you will program I18N compliant. The GNU
gcc compiler, GUI Libraries like QT and GTK support I18N through
special handling of strings. Making a program I18N compliant is
very easy. It allows contributors to port your application to
other languages quickly. Refer to library specific I18N
documentation for more details.To the contrary of common perception, I18N compliant code is
easy to write. Usually, it only involves wrapping your strings
with library specific functions. In addition, please be sure to
allow for wide or multibyte characters support.A Call to Unify the I18N effortIt has come to our attention that the individual I18N/L10N
efforts for each country has been repeating each others'
efforts. Many of us have been reinventing the wheel repeatedly
and inefficiently. We hope that the various major groups in
I18N could congregate into a group effort similar to the Core
Team's responsibility.Currently, we hope that, when you write or port I18N
programs, you would send it out to each country's related
FreeBSD mailing lists for testing. In the future, we hope to
create applications that work in all the languages
out-of-the-box without dirty hacks.The mailing list FreeBSD-I18N@FreeBSD.org
has been established. If you are an I18N/L10N developer,
please send your comments, ideas, questions, and anything
you deem related to it. Michael C. Wu will be maintaining an I18N works in progress
homepage at http://www.FreeBSD.org/~keichii/i18n/index.html
Please also read the BSDCon2000 I18N paper and presentations
by Clive Lin, Chia-Liang Kao, and Michael C. Wu at http://www.FreeBSD.org/~keichii/papers/Perl and PythonPerlPythonPerl and Python have I18N and wide characters handling
libraries. Please use them for I18N compliance.In older FreeBSD versions,
Perl may gives warning about not having a wide characters locale
that is already installed in your system. You can set the
environmental variable LD_PRELOAD to
/usr/lib/libxpg4.so in your shell.In sh-based shells:LD_PRELOAD=/usr/lib/libxpg4.soIn C-based shells:setenv LD_PRELOAD /usr/lib/libxpg4.so
-
+ Localizing FreeBSD to Specific Languages
+
+
+
+ Andrey A.
+ Chernov
+ Originally contributed by
+
+
+ Russian Language (KOI8-R encoding)Russian localization
- Originally contributed by
- &a.ache;.For more information about KOI8-R encoding, see the KOI8-R References
(Russian Net Character Set).Locale SetupPut the following lines into your
~/.login_conf file:me:My Account:\
:charset=KOI8-R:\
:lang=ru_RU.KOI8-R:See earlier in this chapter for examples of setting up the
locale.Console SetupFor the FreeBSD versions before 5.0 add the following line
to your kernel configuration file:options SC_MOUSE_CHAR=0x03For the FreeBSD versions 5.0 and up insert the following
line into /etc/rc.conf:mousechar_start=3Use following settings in
/etc/rc.conf:keymap="ru.koi8-r"
scrnmap="koi8-r2cp866"
font8x16="cp866b-8x16"
font8x14="cp866-8x14"
font8x8="cp866-8x8"For each ttyv* entry in
/etc/ttys, use
cons25r as the terminal type.See earlier in this chapter for examples of setting up the
console.Printer SetupprintersSince most printers with Russian characters come with
hardware code page CP866, a special output filter is needed for
KOI8-R -> CP866 conversion. Such a filter is installed by
default as /usr/libexec/lpr/ru/koi2alt.
A Russian printer /etc/printcap entry
should look like:lp|Russian local line printer:\
:sh:of=/usr/libexec/lpr/ru/koi2alt:\
:lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:See &man.printcap.5; for a detailed description.MS-DOS FS and Russian FilenamesThe following example &man.fstab.5; entry enables support
for Russian filenames in mounted MS-DOS filesystems:/dev/ad0s2 /dos/c msdos rw,-Wkoi2dos,-Lru_RU.KOI8-R 0 0See &man.mount.msdos.8; for a detailed description of the
and options.X11 SetupDo non-X locale
setup first as described.The Russian KOI8-R locale
may not work with old XFree86 releases (lower than 3.3).
The XFree86 port from
x11/XFree86 already is the
most recent XFree86 version, so it will work if you
install XFree86 from the port. This should not be an
issue unless you are using an old version of
FreeBSD.Go to the
russian/X.language directory
and issue the following command:&prompt.root; make installThe above port installs the latest version of the KOI8-R
fonts. XFree86 3.3 already has some KOI8-R fonts, but these
are scaled better.Check the "Files" section
in your /etc/XF86Config file.
The following
lines must be added before any other
FontPath entries:FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi"
FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi"If you use a high resolution video mode, swap the 75 dpi
and 100 dpi lines.To activate a Russian keyboard, add the following to the
"Keyboard" section of your
XF86Config file.For XFree86 v3.*:XkbLayout "ru"
XkbOptions "grp:caps_toggle"For XFree86 v4.*:Option "XkbLayout" "ru"
Option "XkbOptions" "grp:caps_toggle"Also make sure that XkbDisable is
turned off (commented out) there.The RUS/LAT switch will be CapsLock.
The old CapsLock function is still
available via Shift+CapsLock (in LAT mode
only).If you have Windows keys on your keyboard,
and notice that some non-alphabetical keys are mapped
incorrectly in RUS mode, add the following line in your
XF86Config file.For XFree86 v3.*:XkbVariant "winkeys"For XFree86 v4.*:Option "XkbVariant" "winkeys"The Russian XKB keyboard may not work with old XFree86
versions, see the above
note for more information. The Russian XKB
keyboard may also not work with non-localized
applications as well. Minimally localized applications
should call a XtSetLanguageProc (NULL, NULL,
NULL); function early in the program.
See
KOI8-R for X-Window for more instructions on
localizing X11 applications.Traditional Chinese Localization for TaiwanTraditional Chinese localizationThe FreeBSD-Taiwan Project has an I18N/L10N tutorial for
FreeBSD at http://freebsd.sinica.edu.tw/~ncvs/zh-l10n-tut/index.html
using many chinese/* applications.
The editor for the zh-L10N-tut is Clive Lin
Clive@CirX.org. You can also cvsup the following
collections at freebsd.sinica.edu.tw:CollectionDescriptionoutta-port tag=.Beta-quality ports collection for Chinesezh-L10N-tut tag=.Localizing FreeBSD Tutorial in BIG-5 Traditional
Chinesezh-doc tag=.FreeBSD Documentation Translation to BIG-5 Traditional
ChineseChuan-Hsing Shen s874070@mail.yzu.edu.tw has
created the Chinese
FreeBSD Collection (CFC) using FreeBSD-Taiwan's
zh-L10N-tut. The packages and the script files
are available at ftp://ftp.csie.ncu.edu.tw/OS/FreeBSD/taiwan/CFC/.German Language Localization (For All ISO 8859-1
Languages)German localizationSlaven Rezic eserte@cs.tu-berlin.de wrote a
tutorial how to use umlauts on a FreeBSD machine. The tutorial
is written in German and available at http://www.de.FreeBSD.org/de/umlaute/.Japanese and Korean Language LocalizationJapanese localizationKorean localizationFor Japanese, refer to http://www.jp.FreeBSD.org/,
and for Korean, refer to http://www.kr.FreeBSD.org/.Non-English FreeBSD DocumentationSome FreeBSD contributors have translated parts of FreeBSD to
other languages. They are available through links on the main site or in
/usr/share/doc.
diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
index a57611ac60..78144c8eae 100644
--- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml
@@ -1,2286 +1,2325 @@
- Linux Binary Compatibility
+
+
+
+ Jim
+ Mock
+ Restructured and parts updated by
+
+
+
+
+
+ Brian N.
+ Handy
+ Originally contributed by
+
+
+
- Restructured and parts updated by &a.jim;, 22 March
- 2000. Originally contributed by &a.handy; and
- &a.rich;
+ Linux Binary CompatibilitySynopsisLinux binary compatibilitybinary compatibilityLinuxThe following chapter will cover FreeBSD's Linux binary
compatibility features, how to install it, and how it works.At this point, you may be asking yourself why exactly, does
FreeBSD need to be able to run Linux binaries? The answer to that
question is quite simple. Many companies and developers develop
only for Linux, since it is the latest hot thing in
the computing world. That leaves the rest of us FreeBSD users
bugging these same companies and developers to put out native
FreeBSD versions of their applications. The problem is, that most
of these companies do not really realize how many people would use
their product if there were FreeBSD versions too, and most continue
to only develop for Linux. So what is a FreeBSD user to do? This
is where the Linux binary compatibility of FreeBSD comes into
play.In a nutshell, the compatibility allows FreeBSD users to run
about 90% of all Linux applications without modification. This
includes applications such as Star Office,
the Linux version of Netscape,
Adobe Acrobat,
RealPlayer
5 and 7, VMWare,
Oracle,
WordPerfect, Doom,
Quake, and more. It is also reported
that in some situations, Linux binaries perform better on FreeBSD
than they do under Linux.Linux/proc filesystemThere are, however, some Linux-specific operating system
features that are not supported under FreeBSD. Linux binaries will
not work on FreeBSD if they overly use the Linux
/proc filesystem (which is different from
FreeBSD's /proc filesystem), or i386-specific
calls, such as enabling virtual 8086 mode.For information on installing the Linux binary compatibility
mode, see the next section.InstallationWith the advent of 3.0-RELEASE, it is no longer necessary to
specify options LINUX or
options COMPAT_LINUX in your kernel
configuration.KLD (kernel loadable object)The Linux binary compatibility is now done via a KLD object
(Kernel LoaDable object), so it can be installed
on-the-fly without having to reboot. You will,
however, need to have the following in
/etc/rc.conf:linux_enable=YESThis, in turn, triggers the following action in
/etc/rc.i386:# Start the Linux binary compatibility if requested.
#
case ${linux_enable} in
[Yy][Ee][Ss])
echo -n ' linux'; linux > /dev/null 2>&1
;;
esacIf you wish to verify that the KLD is loaded,
kldstat will do that:&prompt.user; kldstat
Id Refs Address Size Name
1 2 0xc0100000 16bdb8 kernel
7 1 0xc24db000 d000 linux.kokernel optionsLINUXIf for some reason you do not want to or cannot load the KLD,
then you may statically link the binary compatibility in the kernel
by adding options LINUX to your kernel
configuration file. Then install your new kernel as described in
the kernel configuration section
of this handbook.Installing Linux Runtime LibrariesLinuxinstalling Linux librariesThis can be done one of two ways, either by using the
linux_base port, or
by installing them manually.Installing using the linux_base portports collectionThis is by far the easiest method to use when installing the
runtime libraries. It is just like installing any other port
from the ports collection.
Simply do the following:&prompt.root; cd /usr/ports/emulators/linux_base
&prompt.root; make install distcleanYou should now have working Linux binary compatibility.
Some programs may complain about incorrect minor versions of the
system libraries. In general, however, this does not seem to be
a problem.Installing libraries manuallyIf you do not have the ports collection
installed, you can install the libraries by hand instead. You
will need the Linux shared libraries that the program depends on
and the runtime linker. Also, you will need to create a
shadow root directory,
/compat/linux, for Linux libraries on your
FreeBSD system. Any shared libraries opened by Linux programs
run under FreeBSD will look in this tree first. So, if a Linux
program loads, for example, /lib/libc.so,
FreeBSD will first try to open
/compat/linux/lib/libc.so, and if that does
not exist, it will then try /lib/libc.so.
Shared libraries should be installed in the shadow tree
/compat/linux/lib rather than the paths
that the Linux ld.so reports.Generally, you will need to look for the shared libraries
that Linux binaries depend on only the first few times that you
install a Linux program on your FreeBSD system. After a while,
you will have a sufficient set of Linux shared libraries on your
system to be able to run newly imported Linux binaries without
any extra work.How to install additional shared librariesshared librariesWhat if you install the linux_base port
and your application still complains about missing shared
libraries? How do you know which shared libraries Linux
binaries need, and where to get them? Basically, there are 2
possibilities (when following these instructions you will need
to be root on your FreeBSD system).If you have access to a Linux system, see what shared
libraries the application needs, and copy them to your FreeBSD
system. Look at the following example:Let us assume you used FTP to get the Linux binary of
Doom, and put it on a Linux system you have access to. You
then can check which shared libraries it needs by running
ldd linuxdoom, like so:&prompt.user; ldd linuxdoom
libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0
libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0
libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29symbolic linksYou would need to get all the files from the last column,
and put them under /compat/linux, with
the names in the first column as symbolic links pointing to
them. This means you eventually have these files on your
FreeBSD system:/compat/linux/usr/X11/lib/libXt.so.3.1.0
/compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3.1.0
/compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0
/compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
Note that if you already have a Linux shared library
with a matching major revision number to the first column
of the ldd output, you will not need to
copy the file named in the last column to your system, the
one you already have should work. It is advisable to copy
the shared library anyway if it is a newer version,
though. You can remove the old one, as long as you make
the symbolic link point to the new one. So, if you have
these libraries on your system:/compat/linux/lib/libc.so.4.6.27
/compat/linux/lib/libc.so.4 -> libc.so.4.6.27and you find a new binary that claims to require a
later version according to the output of
ldd:libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29If it is only one or two versions out of date in the
in the trailing digit then do not worry about copying
/lib/libc.so.4.6.29 too, because the
program should work fine with the slightly older version.
However, if you like, you can decide to replace the
libc.so anyway, and that should leave
you with:/compat/linux/lib/libc.so.4.6.29
/compat/linux/lib/libc.so.4 -> libc.so.4.6.29
The symbolic link mechanism is
only needed for Linux binaries. The
FreeBSD runtime linker takes care of looking for matching
major revision numbers itself and you do not need to worry
about it.
Installing Linux ELF binariesLinuxELF binariesELF binaries sometimes require an extra step of
branding. If you attempt to run an unbranded ELF
binary, you will get an error message like the following;&prompt.user; ./my-linux-elf-binary
ELF binary type not known
AbortTo help the FreeBSD kernel distinguish between a FreeBSD ELF
binary from a Linux binary, use the &man.brandelf.1;
utility.&prompt.user; brandelf -t Linux my-linux-elf-binaryGNU toolchainThe GNU toolchain now places the appropriate branding
information into ELF binaries automatically, so you this step
should become increasingly more rare in the future.Configuring the host name resolverIf DNS does not work or you get this message:resolv+: "bind" is an invalid keyword resolv+:
"hosts" is an invalid keywordYou will need to configure a
/compat/linux/etc/host.conf file
containing:order hosts, bind
multi onThe order here specifies that /etc/hosts
is searched first and DNS is searched second. When
/compat/linux/etc/host.conf is not
installed, Linux applications find FreeBSD's
/etc/host.conf and complain about the
incompatible FreeBSD syntax. You should remove
bind if you have not configured a name server
using the /etc/resolv.conf file.Installing MathematicaUpdated for Mathematica
version 4.X by &a.murray
and merged with work by Bojan Bistrovic
bojanb@physics.odu.edu.applicationsMathematicaThis document describes the process of installing the Linux
version of Mathematica 4.X onto
a FreeBSD system.The Linux version of Mathematica
runs perfectly under FreeBSD
however the binaries shipped by Wolfram need to be branded so that
FreeBSD knows to use the Linux ABI to execute them.The Linux version of Mathematica
or Mathematica for Students can
be ordered directly from Wolfram at http://www.wolfram.com/.Branding the Linux binariesThe Linux binaries are located in the Unix
directory of the Mathematica CDROM
distributed by Wolfram. You
need to copy this directory tree to your local hard drive so that
you can brand the Linux binaries with &man.brandelf.1; before
running the installer:&prompt.root; mount /cdrom
&prompt.root; cp -rp /cdrom/Unix/ /localdir/
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/*
&prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm
&prompt.root; cd /localdir/Installers/Linux/
&prompt.root; ./MathInstallerAlternatively, you can simply set the default ELF brand
to Linux for all unbranded binaries with the command:&prompt.root; sysctl -w kern.fallback_elf_brand=3This will make FreeBSD assume that unbranded ELF binaries
use the Linux ABI and so you should be able to run the
installer straight from the CDROM.Obtaining your Mathematica PasswordBefore you can run Mathematica
you will have to obtain a
password from Wolfram that corresponds to your machine
ID.EthernetMAC addressOnce you have installed the Linux compatibility runtime
libraries and unpacked Mathematica
you can obtain the
machine ID by running the program
mathinfo in the Install directory. This
machine ID is based solely on the MAC address of your first
Ethernet card.&prompt.root; cd /localdir/Files/SystemFiles/Installation/Binaries/Linux
&prompt.root; mathinfo
disco.example.com 7115-70839-20412When you register with Wolfram, either by email, phone or fax,
you will give them the machine ID and they will
respond with a corresponding password consisting of groups of
numbers. You can then enter this information when you attempt to
run Mathematica for the first time
exactly as you would for any other
Mathematica platform.Running the Mathematica front end over a networkMathematica uses some special
fonts to display characters not
present in any of the standard font sets (integrals, sums, Greek
letters, etc.). The X protocol requires these fonts to be install
locally. This means you will have to copy
these fonts from the CDROM or from a host with
Mathematica
installed to your local machine. These fonts are normally stored
in /cdrom/Unix/Files/SystemFiles/Fonts on the
CDROM, or
/usr/local/mathematica/SystemFiles/Fonts on
your hard drive. The actual fonts are in the subdirectories
Type1 and X. There are
several ways to use them, as described below.The first way is to copy them into one of the existing font
directories in /usr/X11R6/lib/X11/fonts.
This will require editing the fonts.dir file,
adding the font names to it, and changing the number of fonts on
the first line. Alternatively, you should also just be able to
run mkfontdir in the directory you have copied
them to.The second way to do this is to copy the directories to
/usr/X11R6/lib/X11/fonts:&prompt.root; cd /usr/X11R6/lib/X11/fonts
&prompt.root; mkdir X
&prompt.root; mkdir MathType1
&prompt.root; cd /cdrom/Unix/Files/SystemFiles/Fonts
&prompt.root; cp X/* /usr/X11R6/lib/X11/fonts/X
&prompt.root; cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1
&prompt.root; cd /usr/X11R6/lib/X11/fonts/X
&prompt.root; mkfontdir
&prompt.root; cd ../MathType1
&prompt.root; mkfontdirNow add the new font directories to your font path:&prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/X
&prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/MathType1
&prompt.root; xset fp rehashIf you are using the XFree86 server, you can have these font
directories loaded automatically by adding them to your
XF86Config file.fontsIf you do not already have a directory
called /usr/X11R6/lib/X11/fonts/Type1, you
can change the name of the MathType1
directory in the example above to
Type1.
+
+
+
+ Marcel
+ Moolenaar
+ Contributed by
+
+
+
+ Installing Oracle
-
- Contributed by Marcel Moolenaar
- marcel@cup.hp.com
+
applicationsOraclePrefaceThis document describes the process of installing Oracle 8.0.5 and
Oracle 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD
machineInstalling the Linux environmentMake sure you have both linux_base and
linux_devtools from the ports collection
installed. These ports are added to the collection after the release
of FreeBSD 3.2. If you are using FreeBSD 3.2 or an older version for
that matter, update your ports collection. You may want to consider
updating your FreeBSD version too. If you run into difficulties with
linux_base-6.1 or
linux_devtools-6.1 you may have to use version
5.2 of these packages.If you want to run the intelligent agent, you'll
also need to install the Red Hat Tcl package:
tcl-8.0.3-20.i386.rpm. The general command
for installing packages with the official RPM port is :&prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm packageInstallation of the package should not generate any errors.Creating the Oracle environmentBefore you can install Oracle, you need to set up a proper
environment. This document only describes what to do
specially to run Oracle for Linux on FreeBSD, not
what has been described in the Oracle installation guide.Kernel Tuningkernel tuningAs described in the Oracle installation guide, you need to set
the maximum size of shared memory. Don't use
SHMMAX under FreeBSD. SHMMAX
is merely calculated out of SHMMAXPGS and
PGSIZE. Therefore define
SHMMAXPGS. All other options can be used as
described in the guide. For example:options SHMMAXPGS=10000
options SHMMNI=100
options SHMSEG=10
options SEMMNS=200
options SEMMNI=70
options SEMMSL=61Set these options to suit your intended use of Oracle.Also, make sure you have the following options in your kernel
config-file:options SYSVSHM #SysV shared memory
options SYSVSEM #SysV semaphores
options SYSVMSG #SysV interprocess communicationOracle accountCreate an Oracle account just as you would create any other
account. The Oracle account is special only that you need to give
it a Linux shell. Add /compat/linux/bin/bash to
/etc/shells and set the shell for the Oracle
account to /compat/linux/bin/bash.EnvironmentBesides the normal Oracle variables, such as
ORACLE_HOME and ORACLE_SID you must
set the following environment variables:VariableValueLD_LIBRARY_PATH$ORACLE_HOME/libCLASSPATH$ORACLE_HOME/jdbc/lib/classes111.zipPATH/compat/linux/bin
/compat/linux/sbin
/compat/linux/usr/bin
/compat/linux/usr/sbin
/bin
/sbin
/usr/bin
/usr/sbin
/usr/local/bin
$ORACLE_HOME/binIt is advised to set all the environment variables in
.profile. A complete example is:ORACLE_BASE=/oracle; export ORACLE_BASE
ORACLE_HOME=/oracle; export ORACLE_HOME
LD_LIBRARY_PATH=$ORACLE_HOME/lib
export LD_LIBRARY_PATH
ORACLE_SID=ORCL; export ORACLE_SID
ORACLE_TERM=386x; export ORACLE_TERM
CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip
export CLASSPATH
PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:$ORACLE_HOME/bin
export PATHInstalling OracleDue to a slight inconsistency in the Linux emulator, you need to
create a directory named .oracle in
/var/tmp before you start the installer. Either
make it world writable or let it be owner by the oracle user. You
should be able to install Oracle without any problems. If you have
problems, check your Oracle distribution and/or configuration first!
After you have installed Oracle, apply the patches described in the
next two subsections.A frequent problem is that the TCP protocol adapter is not
installed right. As a consequence, you cannot start any TCP listeners.
The following actions help solve this problem:&prompt.root; cd $ORACLE_HOME/network/lib
&prompt.root; make -f ins_network.mk ntcontab.o
&prompt.root; cd $ORACLE_HOME/lib
&prompt.root; ar r libnetwork.a ntcontab.o
&prompt.root; cd $ORACLE_HOME/network/lib
&prompt.root; make -f ins_network.mk installDon't forget to run root.sh again!Patching root.shWhen installing Oracle, some actions, which need to be performed
as root, are recorded in a shell script called
root.sh. root.sh is
written in the orainst directory. Apply the
following patch to root.sh, to have it use to proper location of
chown or alternatively run the script under a
Linux native shell.*** orainst/root.sh.orig Tue Oct 6 21:57:33 1998
--- orainst/root.sh Mon Dec 28 15:58:53 1998
***************
*** 31,37 ****
# This is the default value for CHOWN
# It will redefined later in this script for those ports
# which have it conditionally defined in ss_install.h
! CHOWN=/bin/chown
#
# Define variables to be used in this script
--- 31,37 ----
# This is the default value for CHOWN
# It will redefined later in this script for those ports
# which have it conditionally defined in ss_install.h
! CHOWN=/usr/sbin/chown
#
# Define variables to be used in this scriptWhen you don't install Oracle from CD, you can patch the source
for root.sh. It is called
rthd.sh and is located in the
orainst directory in the source tree.Patching genclntshThe script genclntsh is used to create
a single shared client
library. It is used when building the demos. Apply the following
patch to comment out the definition of PATH:*** bin/genclntsh.orig Wed Sep 30 07:37:19 1998
--- bin/genclntsh Tue Dec 22 15:36:49 1998
***************
*** 32,38 ****
#
# Explicit path to ensure that we're using the correct commands
#PATH=/usr/bin:/usr/ccs/bin export PATH
! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
#
# each product MUST provide a $PRODUCT/admin/shrept.lst
--- 32,38 ----
#
# Explicit path to ensure that we're using the correct commands
#PATH=/usr/bin:/usr/ccs/bin export PATH
! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH
#
# each product MUST provide a $PRODUCT/admin/shrept.lstRunning OracleWhen you have followed the instructions, you should be able to run
Oracle as if it was run on Linux
itself.
+
+
+
+ Holger
+ Kill
+ Contributed by
+
+
+
+
+
+ Valentino
+ Vaschetto
+ Converted to SGML by
+
+
+
+
Installing SAP R/3 (4.6B - IDES)
- Contributed by Holger Kippholger.kipp@alogis.com
- Converted to SGML by &a.logo;
+
applicationsSAP R/3PrefaceThis document describes a possible way of installing a
SAP R/3 4.6B IDES-System
with Oracle 8.0.5
for Linux onto a FreeBSD 4.3 machine, including the installation
of FreeBSD 4.3-STABLE and
Oracle 8.0.5.Even though this document tries to describe all important
steps in a greater detail, it is not intended as a replacement
for the Oracle and
SAP R/3 installation guides.Please see the documentation that comes with the
SAP R/3
Linux edition for SAP- and
Oracle-specific questions, as well
as resources from Oracle and
SAP OSS.SoftwareThe following CDROMs have been used for
SAP-installation:NameNumberDescriptionKERNEL51009113SAP Kernel Oracle /
Installation / AIX, Linux, SolarisRDBMS51007558Oracle / RDBMS 8.0.5.X /
LinuxEXPORT151010208IDES / DB-Export / Disc
1 of 6EXPORT251010209IDES / DB-Export / Disc
2 of 6EXPORT351010210IDES / DB-Export /
Disc3 of 6EXPORT451010211IDES / DB-Export /
Disc4 of 6EXPORT551010212IDES / DB-Export /
Disc5 of 6EXPORT651010213IDES / DB-Export /
Disc6 of 6Additionally, I used the Oracle 8
Server (Pre-production version 8.0.5 for Linux,
Kernel Version 2.0.33) CD which is not really necessary, and
of course FreeBSD 4.3 stable (it was only a few days past 4.3
RELEASE).SAP-NotesThe following notes should be read before installing
SAP R/3 or proved to be useful
during installation:NumberTitle0171356SAP Software auf Linux: grundlegenden
Anmerkungen0201147INST: 4.6C R/3 Inst. on UNIX -
Oracle0373203Update / Migration Oracle 8.0.5 -->
8.0.6/8.1.6 LINUX0072984Release of Digital UNIX 4.0B for
Oracle0130581R3SETUP step DIPGNTAB terminates0144978Your system has not been installed
correctly0162266Questions and tips for R3SETUP on Windows
NT / W2KHardware-RequirementsThe following equipment is sufficient for a
SAP R/3 System (4.6B):Component4.6B4.6CProcessor2 x 800MHz Pentium III2 x 800MHz Pentium IIIMemory1GB ECC2GB ECCHard Disc Space50-60GB (IDES)50-60GB (IDES)For use in production, Xeon-Processors with large cache,
high-speed disc access (SCSI, RAID hardware controller), USV
and ECC-RAM is recommended. The large amount of Hard disc
space is due to the preconfigured IDES System, which creates
27 GB of database files during installation. Usually after
installation it is then necessary to extend some
tablespaces.I used a dual processor board with 2 800MHz Pentium III
processors, Adaptec 29160 Ultra160 SCSI adapter (for accessing
a 40/80 GB DLT tape drive and CDROM), Mylex AcelleRAID (2
channels, firmware 6.00-1-00 with 32MB RAM). To the Mylex
Raid-controller are attached two 17GB hard discs (mirrored)
and four 36GB hard discs (RAID level 5).Installation of FreeBSD 4.3 stableFirst I installed FreeBSD 4.3 stable. I did the
default-installation via FTP.Installation via FTPGet the diskimages
kern.flp and mfsroot.flp and put them on floppy disks (I got
mine from ftp7.de.freebsd.org. Please choose the appropriate
mirror).&prompt.root; dd if=kern.flp of=/dev/fd0
&prompt.root; dd if=mfsroot.flp of=/dev/fd0Don't forget to use different disks for the two images,
then boot from the floppy with the kern.flp-image on it
and follow instructions. I used the following disk
layout:FilesystemSize (1k-blocks)Size (GB)Mounted on/dev/da0s1a1.016.3031//dev/da0s1b6<swap>/dev/da0s1e2.032.6232/var/dev/da0s1f8.205.3398/usr/dev/da1s1e45.734.36145/compat/linux/oracle/dev/da1s1f2.032.6232/compat/linux/sapmnt/dev/da1s1g2.032.6232/compat/linux/usr/sapI had to configure and initialize the two logical drives
with the Mylex software beforehand. It is located on the
board itself and can be started during the boot phase of the
PC. Please note that this disk layout differs slightly from
the SAP recommendations, as SAP suggests mounting the
oracle-subdirectories (and some others) separately - I
decided to just create them as real subdirectories for
simplicity.Get the latest stable-sourcesFor FreeBSD 4.3 stable onwards, it is quite easy to get
the latest stable sources. With the older versions of
FreeBSD, I had my own script located in /etc/cvsup. Setting
up CVSup for FreeBSD 4.3 is quite
easy. As user
root do the following:&prompt.root; cp /etc/defaults/make.conf /etc/make.conf
&prompt.root; vi /etc/make.confThe file /etc/make.conf requires the
following entries to be active:SUP_UPDATE= yes
SUP= /usr/local/bin/cvsup
SUPFLAGS= -g -L 2
SUPHOST= cvsup8.FreeBSD.org
SUPFILE= /usr/share/examples/cvsup/stable-supfile
PORTSSUPFILE= /usr/share/examples/cvsup/ports-supfile
DOCSUPFILE= /usr/share/examples/cvsup/doc-supfileChange the SUPHOST-value
appropriately. The supfiles in
/usr/share/examples/cvsup should be
fine. If you don't want to load all the docfiles, leave the
corresponding DOCSUPFILE-entry
inactive. Starting cvsup
to get the latest stable-sources is then very easy:&prompt.root; cd /usr/src
&prompt.root; make updateMake world and a new kernelThe first thing to do is to install the sources.
As user root, do the following:&prompt.root; cd /usr/src
&prompt.root; make worldIf this goes through, one can then continue creating and
configuring the new kernel. Usually this is where to
customize the kernel configuration file. As the computer is
named troubadix, the natural name for the
config file also is troubadix:&prompt.root; cd /usr/src/sys/i386/conf
&prompt.root; cp GENERIC TROUBADIX
&prompt.root; vi TROUBADIXAt this stage one can define the drivers to use and not
to use, etc. See the appropriate documentation or have a
look at file LINT for some additional
explanations.One can then also include the parameters as described
below Creating the new kernel then requires:&prompt.root; cd /usr/src/sys/i386/conf
&prompt.root; config TROUBADIX
&prompt.root; cd /usr/src/sys/compile/TROUBADIX
&prompt.root; make depend
&prompt.root; make
&prompt.root; make installAfter make install finished
successfully, one should reboot the computer to have the new
kernel available.Installing the Linux environmentI had some trouble downloading the required RPM-files (for
4.3 stable, 2nd May 2001), so you might try one of the
following locations (if all the others fail and the following
aren't out of date):ftp7.de.freebsd.org/pub/FreeBSD/distfiles/rpmftp.redhat.com/pub/redhat/linux/6.1/en/os/i386/RedHat/RPMSInstalling Linux base-systemFirst the Linux base-system needs to be installed (as root):
&prompt.root; cd /usr/ports/emulators/linux_base
&prompt.root; make packageInstalling Linux developmentNext, the Linux development is needed:&prompt.root; cd /usr/ports/devel/linux_devtools
&prompt.root; make packageInstalling necessary RPMsRPMsTo start the R3SETUP-Program, pam support is needed. As
this also requires some other packages, I ended up
installing several packages. After that, pam still
complained about a missing package, so I forced the
installation and it worked. I wonder if the other packages
are really needed or if it would have been sufficient to
install the pam-package.Anyway, here is the list of packages I installed:cracklib-2.7-5.i386.rpmcracklib-dicts-2.7-5.i386.rpmpwdb-0.60-1.i386.rpmpam-0.68-7.i386.rpmI installed these packages with the following
command:&prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <package_name>except for the pam package, which I forced with&prompt.root; rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm pam-0.68-7.i386.rpmFor Oracle to run the
intelligent agent, I also had to install the following
RedHat Tcl package (as is stated in the FreeBSD Handbook):
tcl-8.0.5-30.i386.rpm (otherwise the
relinking during Oracle install
won't work). There are some other issues regarding
relinking of Oracle, but that is
a Oracle-Linux issue, not FreeBSD specific as far as I
understand it.Creating the SAP/R3 environmentCreating the necessary filesystems and mountpointsFor a simple installation, it is sufficient to create the
following filesystems:mountpointsize in GB/compat/linux/oracle45 GB/compat/linux/sapmnt2 GB/compat/linux/usr/sap2 GBI also created some links, so FreeBSD will also find the
correct path:&prompt.root; ln -s /compat/linux/oracle /oracle
&prompt.root; ln -s /compat/linux/sapmnt /sapmnt
&prompt.root; ln -s /compat/linux/usr/sap /usr/sapCreating users and directoriesSAP R/3 needs two users and
three groups. The usernames depend on the
SAP system id (SID) which consists
of three letters. Some of these SIDs are reserved
by SAP (for example
SAP and NIX. For a
complete list please see the SAP documentation). For the IDES
installation I used IDS. We have
therefore the following groups (group ids might differ, these
are just the values I used with my installation):group idgroup namedescription100dbaData Base Administrator101sapsysSAP System102operData Base OperatorFor a default Oracle-Installation, only group
dba is used. As
oper-group, one also uses group
dba (see Oracle- and
SAP-documentation for further information).We also need the following users:user idusernamegeneric namegroupadditional groupsdescription1000idsadm<sid>admsapsysoperSAP Administrator1002oraidsora<sid>dbaoperDB AdministratorAdding the users with adduser
requires the following (please note shell and home
directory) entries for SAP-Administrator:Name: idsadm <sid>adm
Password: ******
Fullname: SAP IDES Administrator
Uid: 1000
Gid: 101 (sapsys)
Class:
Groups: sapsys dba
HOME: /home/idsadm /home/<sid>adm
Shell: /bin/shand for Database-Administrator:Name: oraids ora<sid>
Password: ******
Fullname: Oracle IDES Administrator
Uid: 1002
Gid: 100 (dba)
Class:
Groups: dba
HOME: /oracle/IDS /oracle/<sid>
Shell: /bin/shThis should also include group
oper in case you are using both
groups dba and
oper.Creating directoriesThese directories are usually created as separate
filesystems. This depends entirely on your requirements. I
choose to create them as simple directories, as they are all
located on the same RAID 5 anyway:First we'll set owners and right of some directories (as
user root):&prompt.root; chmod 775 /oracle
&prompt.root; chmod 777 /sapmnt
&prompt.root; chown root:dba /oracle
&prompt.root; chown idsadm:sapsys /compat/linux/usr/sap
&prompt.root; chmow 775 /compat/linux/usr/sapSecond we'll create directories as user ora<sid>. These
will all be subdirectories of /oracle/IDS:&prompt.root; su - oraids
&prompt.root; mkdir mirrlogA mirrlogB origlogA origlogB
&prompt.root; mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6
&prompt.root; mkdir saparch sapreorg
&prompt.root; exitIn the third step we create directories as user
idsadm (<sid>adm):&prompt.root; su - idsadm
&prompt.root; cd /usr/sap
&prompt.root; mkdir IDS
&prompt.root; mkdir trans
&prompt.root; exitEntries in /etc/servicesSAP R/3 requires some entries in file
/etc/services , which will not be set
correctly during installation under FreeBSD. Please add the
following entries (you need at least those entries
corresponding to the instance number - in this case,
00. It'll do no harm adding all
entries from 00 to
99 for dp,
gw, sp and
ms);sapdp00 3200/tcp # SAP Dispatcher. 3200 + Instance-Number
sapgw00 3300/tcp # SAP Gateway. 3300 + Instance-Number
sapsp00 3400/tcp # 3400 + Instance-Number
sapms00 3500/tcp # 3500 + Instance-Number
sapmsIDS 3600/tcp # SAP Message Server. 3600 + Instance-NumberNecessary localeslocaleSAP requires at least two locales that aren't part of
the default RedHat installation. SAP offers the required
RPMs as download from their FTP-server (which is only
accessible if you are a customer with OSS-access). See note
0171356 for a list of RPMs you need.It is also possible to just create appropriate links
(for example from de_DE and
en_US ), but I wouldn't recommend this
for a production system (so far it worked with the IDES
system without any problems, though). The following locales
are needed:de_DE.ISO-8859-1
en_US.ISO-8859-1If they are not present, there will be some problems
during the installation. If these are then subsequently
ignored (eg by setting the status of the offending steps to
OK in file CENTRDB.R3S), it will be impossible to log onto
the SAP-system without some additional effort.Kernel Tuningkernel tuningSAP R/3 Systems need a lot of resources. I therefore
added the following parameters to my kernel config-file:
# Set these for memory pigs (SAP and Oracle):
options MAXDSIZ="(1024*1024*1024)"
options DFLDSIZ="(1024*1024*1024)" # System V options needed.
options SYSVSHM #SYSV-style shared memory
options SHMMAXPGS=262144 #max amount of shared mem. pages
options SHMMNI=256 #max number of shared memory ident if.
options SHMSEG=100 #max shared mem.segs per process
options SYSVMSG #SYSV-style message queues
options MSGSEG=32767 #max num. of mes.segments in system
options MSGSSZ=32 #size of msg-seg. MUST be power of 2
options MSGMNB=65535 #max char. per message queue
options MSGTQL=2046 #max amount of msgs in system
options SYSVSEM #SYSV-style semaphores
options SEMMNU=256 #number of semaphore UNDO structures
options SEMMNS=1024 #number of semaphores in system
options SEMMNI=520 #number of semaphore indentifiers
options SEMUME=100 #number of UNDO keysThe minimum values are specified in the documentation that
comes from SAP. As there is no description for Linux, see the
HP-UX-section (32-bit) for further information.
Installing SAP R/3Preparing SAP CDROMsThere are lots of CDROMs to mount and unmount during
installation. Assuming you have enough CDROM-drives, you
can just mount them all. I decided to copy the CDROM
contents to corresponding directories:/oracle/IDS/sapreorg/<cd-name>where <cd-name> was one of KERNEL,
RDBMS, EXPORT1,
EXPORT2, EXPORT3,
EXPORT4, EXPORT5 and
EXPORT6. All the
filenames should be in capital letters, otherwise use the -g
option for mounting. So use the following commands:&prompt.root; mount_cd9660 -g /dev/cd0a /mnt
&prompt.root; cp -R /mnt/* /oracle/IDS/sapreorg/<cd-name>
&prompt.root; umount /mntRunning the install-scriptFirst we need to prepare an install-directory:&prompt.root; cd /oracle/IDS/sapreorg
&prompt.root; mkdir install
&prompt.root; cd installThen the install-script is started, which will copy nearly
all the relevant files into the install-directory:/oracle/IDS/sapreorg/KERNEL/UNIX/INSTTOOL.SHAs this is an IDES-Installation with a fully customized
SAP R/3 Demo-System, we have six instead of just three
EXPORT-CDs. At this point the installation template
CENTRDB.R3S is for installing a standard central instance
(R/3 and Database), not an IDES central instance, so copy
the corresponding CENTRDB.R3S from the EXPORT1 directory,
otherwise R3SETUP will only ask for three EXPORT-CDs.Start R3SETUPMake sure LD_LIBRARY_PATH is set correctly:&prompt.root; export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/libStart R3SETUP as user root from installation
directory:&prompt.root; cd /oracle/IDS/sapreorg/install
&prompt.root; ./R3SETUP -f CENTRDB.R3SThe script then asks some questions (defaults in brackets,
followed by actual input):QuestionDefaultInputEnter SAP System ID[C11]IDS<ret>Enter SAP Instance Number[00]<ret>Enter SAPMOUNT Directory[/sapmnt]<ret>Enter name of SAP central host[troubadix.domain.de]<ret>Enter name of SAP db host[troubadix]<ret>Select character set[1] (WE8DEC)<ret>Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.61<ret>Extract Oracle Client archive[1] (Yes, extract)<ret>Enter path to KERNEL CD[/sapcd]/oracle/IDS/sapreorg/KERNELEnter path to RDBMS CD[/sapcd]/oracle/IDS/sapreorg/RDBMSEnter path to EXPORT1 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT1Directory to copy EXPORT1 CD[/oracle/IDS/sapreorg/CD4_DIR]<ret>Enter path to EXPORT2 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT2Directory to copy EXPORT2 CD[/oracle/IDS/sapreorg/CD5_DIR]<ret>Enter path to EXPORT3 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT3Directory to copy EXPORT3 CD[/oracle/IDS/sapreorg/CD6_DIR]<ret>Enter path to EXPORT4 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT4Directory to copy EXPORT4 CD[/oracle/IDS/sapreorg/CD7_DIR]<ret>Enter path to EXPORT5 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT5Directory to copy EXPORT5 CD[/oracle/IDS/sapreorg/CD8_DIR]<ret>Enter path to EXPORT6 CD[/sapcd]/oracle/IDS/sapreorg/EXPORT6Directory to copy EXPORT6 CD[/oracle/IDS/sapreorg/CD9_DIR]<ret>Enter amount of RAM for SAP + DB850<ret> (in Megabytes)Service Entry Message Server[3600]<ret>Enter Group-ID of sapsys[101]<ret>Enter Group-ID of oper[102]<ret>Enter Group-ID of dba[100]<ret>Enter User-ID of <sid>adm[1000]<ret>Enter User-ID of ora<sid>[1002]<ret>Number of parallel procs[2]<ret>If I had not copied the CDs to the different locations,
then the SAP-Installer can't find the CD needed (identified
by the LABEL.ASC-File on CD) and would
then ask you to insert / mount the CD and confirm or enter
the mount path.The CENTRDB.R3S might not be
error-free. In my case, it requested EXPORT4 again (but
indicated the correct key (6_LOCATI ON, then 7_LOCATION
etc.), so one can just continue with entering the correct
values. Don't get irritated.Apart from some problems mentioned below, everything
should go straight through up to the point where the Oracle
database software needs to be installed.Installing Oracle 8.0.5Please see the corresponding SAP-Notes and Oracle Readmes
regarding Linux and Oracle DB for possible problems. Most if
not all problems stem from incompatible librariesFor more information on installing Oracle, refer to the Installing Oracle
chapter.Installing the Oracle 8.0.5 with orainstIf Oracle 8.0.5 is to be
used, some additional libraries are needed for successfully
relinking, as Oracle 8.0.5 was linked with an old glibc
(RedHat 6.0), but RedHat 6.1 already uses a new glibc. So
you have to install the following additional packages to
ensure that linking will work:compat-libs-5.2-2.i386.rpmcompat-glibc-5.2-2.0.7.2.i386.rpmcompat-egcs-5.2-1.0.3a.1.i386.rpmcompat-egcs-c++-5.2-1.0.3a.1.i386.rpmcompat-binutils-5.2-2.9.1.0.23.1.i386.rpmSee the corresponding SAP-Notes or Oracle Readmes for
further information. If this is no option (at the time of
installation I didn't have enough time to check this), one
could use the original binaries, or use the relinked
binaries from an original RedHat System.For compiling the intelligent agent, the RedHat Tcl
package must be installed. If you can't get
tcl-8.0.3-20.i386.rpm, a newer one like
tcl-8.0.5-30.i386.rpm for RedHat 6.1
should also do.Apart from relinking, the installation is
straightforward:&prompt.root; su - oraids
&prompt.root; export TERM=xterm
&prompt.root; export ORACLE_TERM=xterm
&prompt.root; export ORACLE_HOME=/oracle/IDS
&prompt.root; cd /ORACLE_HOME/orainst_sap
&prompt.root; ./orainstConfirm all Screens with Enter until the software is
installed, except that one has to deselect the
Oracle On-Line Text Viewer , as this is
not currently available for Linux. Oracle then wants to
relink with i386-glibc20-linux-gcc
instead of the available gcc,
egcs or i386-redhat-linux-gcc
.Due to time constrains I decided to use the binaries
from an Oracle 8.0.5 PreProduction
release, after the first
attempt at getting the version from the RDBMS-CD working,
failed, and finding / accessing the correct RPMs was a
nightmare at that time.Installing the Oracle 8.0.5 Pre-Production release for
Linux (Kernel 2.0.33)This installation is quite easy. Mount the CD, start the
installer. It will then ask for the location of the Oracle
home directory, and copy all binaries there. I did not
delete the remains of my previous RDBMS-installation tries,
though.Afterwards, Oracle Database could be started with no
problems.Continue with SAP R/3 installationFirst check the environment settings of users
idsamd
(<sid>adm) and
oraids (ora<sid>). They should now
both have the files .profile ,
.login and .cshrc
which are all using hostname. In case the
system's hostname is the fully qualified name, you need to
change hostname to hostname
-s within all three files.Database loadAfterwards, R3SETUP can either be restarted or continued
(depending on whether exit was chosen or not). R3SETUP then
creates the tablespaces and loads the data from EXPORT1 to
EXPORT6 (remember, it is an IDES system, otherwise it would
only be EXPORT1 to EXPORT3) with R3load into the
database.When the database load is finished (might take a few
hours), some passwords are requested. For test
installations, one can use the well known default passwords
(use different ones if security is an issue!):QuestionInputEnter Password for sapr3sap<ret>Confirum Password for sapr3sap<ret>Enter Password for syschange_on_install<ret>Confirm Password for syschange_on_install<ret>Enter Password for systemmanager<ret>Confirm Password for systemmanager<ret>At this point I had a few problems with
dipgntab.ListenerStart the Oracle-Listener as user
oraids (ora<sid>) as follows:umask 0; lsnrctl startOtherwise you might get ORA-12546 as the sockets won't
have the correct permissions. See SAP note 072984.Post-installation stepsRequest SAP R/3 license keyThis is needed, as the temporary license is only valid for
four weeks. Don't forget to enter the correct Operating System:
(X) Other: FreeBSD 4.3 Stable. First get
the hardware key. Log on as user idsadm and
call saplicense:&prompt.root; /sapmnt/IDS/exe/saplicense -getCalling saplicense without options
gives a list of options. Upon receiving the license key, it can
be installed using&prompt.root; /sapmnt/IDS/exe/saplicense -installYou are then required to enter the following
values:SAP SYSTEM ID = <SID, 3 chars>
CUSTOMER KEY = <hardware key, 11 chars>
INSTALLATION NO = <installation, 10 digits>
EXPIRATION DATE = <yyyymmdd, usually "99991231">
LICENSE KEY = <license key, 24 chars>Creating UsersCreate a user within client 000 (for some tasks required
to be done within client 000, but with a user different from
users sap* and
ddic). As a username, I usually choose
wartung (or
service in English). Profiles
required are sap_new and
sap_all. For additional safety the
passwords of default users within all clients should be
changed (this includes users sap* and
ddic).Configure Transport System, Profile, Operation Modes, etc.Within client 000, user different from ddic
and sap*, do at least the following:TaskTransactionConfigure Transport System, eg as Stand-Alone
Transport Domain EntitySTMSCreate / Edit Profile for SystemRZ10Maintain Operation Modes and InstancesRZ04These and all the other post-installation steps are
thoroughly described in SAP installation guides.Edit init<sid>.sap (initIDS.sap)The file
/oracle/IDS/dbs/initIDS.sap contains
the SAP backup profile. Here the size of the tape to be
used, type of compression and so on need to be defined. To
get this running with sapdba /
brbackup, I changed the following
values:compress = hardware
archive_function = copy_delete_save
cpio_flags = "-ov --format=newc --block-size=128 --quiet"
cpio_in_flags = "-iuv --block-size=128 --quiet"
tape_size = 38000M
tape_address = /dev/nsa0
tape_address_rew = /dev/sa0Explanations:compress The tape I use is a HP DLT1
which does hardware compression.archive_function This defines the
default behavior for saving Oracle archive logs: New logfiles
are saved to tape, already saved logfiles are saved again and
are then deleted. This prevents lots of trouble if one needs to
recover the database, and one of the archive-tapes has gone
bad.cpio_flags Default is to use -B which
sets blocksize to 5120 Bytes. For DLT-Tapes, HP recommends at
least 32K blocksize, so I used --block-size=128 for
64K. --format=newc is needed I have inode numbers greater than
65535. The last option --quiet is needed as otherwise
brbackup
complains as soon as cpio outputs the
numbers of blocks saved.cpio_in_flags Flags needed for
loading data back from tape. Format is recognized
automagically.tape_size This usually gives the raw
storage capability of the tape. For security reason (we use
hardware compression), thevalue is slightly lower than the
actual value.tape_address The non-rewindable
device to be used with cpio.tape_address_rew The rewindable device to be
used with cpio.Problems during installationOSUSERSIDADM_IND_ORA during R3SETUPIf R3SETUP complains at this stage, edit file
CENTRDB.R3S. Locate [OSUSERSIDADM_IND_ORA] and edit the
following values:HOME=/home/idsadm (was empty)
STATUS=OK (had status ERROR)
Then you can restart R3SETUP with:&prompt.root; ./R3SETUP -f CENTRDB.R3SOSUSERDBSID_IND_ORA during R3SETUPPossibly R3SETUP also complains at this stage. Just edit
CENTRDB.R3S. Locate [OSUSERDBSID_IND_ORA] and edit the
following value in that section:STATUS=OKThen just restart R3SETUP again:&prompt.root; ./R3SETUP -f CENTRDB.R3Soraview.vrf FILE NOT FOUND during Oracle installationYou haven't deselected Oracle On-Line Text Viewer
before starting the installation. This is marked for installation even
though this option is currently not available for Linux. Deselect this
product inside the Oracle installation menu and restart installation.TEXTENV_INVALID during R3SETUP, RFC or SAPGUI startIf this error is encountered, the correct locale is
missing. SAP note 0171356 lists the necessary RPMs that need
be installed (eg saplocales-1.0-3,
saposcheck-1.0-1 for RedHat 6.1). In case
you ignored all the related errors and set the corresponding
status from ERROR to OK (in CENTRDB.R3S) every time R3SETUP
complained and just restarted R3SETUP, the SAP-System will not
be properly configured and you will then not be able to
connect to the system with a
sapgui, even though the system
can be started. Trying to connect with the old Linux
sapgui gave the following
messages:Sat May 5 14:23:14 2001
*** ERROR => no valid userarea given [trgmsgo. 0401]
Sat May 5 14:23:22 2001
*** ERROR => ERROR NR 24 occured [trgmsgi. 0410]
*** ERROR => Error when generating text environment. [trgmsgi. 0435]
*** ERROR => function failed [trgmsgi. 0447]
*** ERROR => no socket operation allowed [trxio.c 3363]
SpeicherzugriffsfehlerThis behavior is due to SAP R/3 being unable to
correctly assign a locale and also not being properly
configured itself (missing entries in some database
tables). To be able to connect to SAP, add the following
entries to file DEFAULT.PFL (see note 0043288):abap/set_etct_env_at_new_mode =0
install/collate/active =0
rscp/TCP0B =TCP0B
Restart the SAP system. Now one can connect to the
system, even though country-specific language settings might
not work as expected. After correcting country-settings
(and providing the correct locales), these entries can be
removed from DEFAULT.PFL and the SAP system can be
restarted.ORA-12546. Start Listener with correct permissionsStart the Oracle Listener as user
oraids with the following commands:&prompt.root; umask 0; lsnrctl startOtherwise one might get ORA-12546 as the sockets won't
have the correct permissions. See SAP note 0072984.[DIPGNTAB_IND_IND] during R3SETUPIn general, see SAP note 0130581 (R3SETUP step
DIPGNTAB
terminates). During this specific installation, for some
reasons the installation process was not using the proper
SAP system name "IDS", but the empty string "" instead. This
lead to some minor problems with accessing directories, as
the paths are generated dynamically using <sid> (in
this case IDS). So instead of accessing:/usr/sap/IDS/SYS/...
/usr/sap/IDS/DVMGS00the following path were used:/usr/sap//SYS/...
/usr/sap/D00iTo continue with the installation, I created a link and an
additional directory:&prompt.root; pwd
/compat/linux/usr/sap
&prompt.root; ls -l
total 4
drwxr-xr-x 3 idsadm sapsys 512 May 5 11:20 D00
drwxr-x--x 5 idsadm sapsys 512 May 5 11:35 IDS
lrwxr-xr-x 1 root sapsys 7 May 5 11:35 SYS -> IDS/SYS
drwxrwxr-x 2 idsadm sapsys 512 May 5 13:00 tmp
drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans I also found SAP notes (0029227 and 0008401) describing
this behavior.[RFCRSWBOINI_IND_IND] during R3SETUPSet STATUS of the offending step from ERROR to OK (file
CENTRDB.R3S) and restart R3SETUP. After
installation, you have to execute the report
RSWBOINS from transaction SE38. See SAP
note 0162266 for additional information about phase
RFCRSWBOINI and
RFCRADDBDIF.[RFCRADDBDIF_IND_IND] during R3SETUPSet STATUS of the offending step from ERROR to OK (file
CENTRDB.R3S) and restart R3SETUP. After
installation, you have to execute the report
RADDBDIF from transaction SE38.
See SAP note 0162266 for further information.Advanced TopicsIf you are curious as to how the Linux binary compatibility
works, this is the section you want to read. Most of what follows
is based heavily on an email written to &a.chat; by Terry Lambert
tlambert@primenet.com (Message ID:
<199906020108.SAA07001@usr09.primenet.com>).How Does It Work?execution class loaderFreeBSD has an abstraction called an execution class
loader. This is a wedge into the &man.execve.2; system
call.What happens is that FreeBSD has a list of loaders, instead of
a single loader with a fallback to the #!
loader for running any shell interpreters or shell scripts.Historically, the only loader on the Unix platform examined
the magic number (generally the first 4 or 8 bytes of the file) to
see if it was a binary known to the system, and if so, invoked the
binary loader.If it was not the binary type for the system, the
&man.execve.2; call returned a failure, and the shell attempted to
start executing it as shell commands.The assumption was a default of whatever the current
shell is.Later, a hack was made for &man.sh.1; to examine the first two
characters, and if they were :\n, then it
invoked the &man.csh.1; shell instead (we believe SCO first made
this hack).What FreeBSD does now is go through a list of loaders, with a
generic #! loader that knows about interpreters
as the characters which follow to the next whitespace next to
last, followed by a fallback to
/bin/sh.ELFFor the Linux ABI support, FreeBSD sees the magic number as an
ELF binary (it makes no distinction between FreeBSD, Solaris,
Linux, or any other OS which has an ELF image type, at this
point).SolarisThe ELF loader looks for a specialized
brand, which is a comment section in the ELF
image, and which is not present on SVR4/Solaris ELF
binaries.For Linux binaries to function, they must be
branded as type Linux;
from &man.brandelf.1;:&prompt.root; brandelf -t Linux fileWhen this is done, the ELF loader will see the
Linux brand on the file.ELFbrandingWhen the ELF loader sees the Linux brand,
the loader replaces a pointer in the proc
structure. All system calls are indexed through this pointer (in
a traditional Unix system, this would be the
sysent[] structure array, containing the system
calls). In addition, the process flagged for special handling of
the trap vector for the signal trampoline code, and sever other
(minor) fix-ups that are handled by the Linux kernel
module.The Linux system call vector contains, among other things, a
list of sysent[] entries whose addresses reside
in the kernel module.When a system call is called by the Linux binary, the trap
code dereferences the system call function pointer off the
proc structure, and gets the Linux, not the
FreeBSD, system call entry points.In addition, the Linux mode dynamically
reroots lookups; this is, in effect, what the
union option to FS mounts
(not the unionfs!) does. First, an attempt
is made to lookup the file in the
/compat/linux/original-path
directory, then only if that fails, the
lookup is done in the
/original-path
directory. This makes sure that binaries that require other
binaries can run (e.g., the Linux toolchain can all run under
Linux ABI support). It also means that the Linux binaries can
load and exec FreeBSD binaries, if there are no corresponding
Linux binaries present, and that you could place a &man.uname.1;
command in the /compat/linux directory tree
to ensure that the Linux binaries could not tell they were not
running on Linux.In effect, there is a Linux kernel in the FreeBSD kernel; the
various underlying functions that implement all of the services
provided by the kernel are identical to both the FreeBSD system
call table entries, and the Linux system call table entries: file
system operations, virtual memory operations, signal delivery,
System V IPC, etc… The only difference is that FreeBSD
binaries get the FreeBSD glue functions, and
Linux binaries get the Linux glue functions
(most older OS's only had their own glue
functions: addresses of functions in a static global
sysent[] structure array, instead of addresses
of functions dereferenced off a dynamically initialized pointer in
the proc structure of the process making the
call).Which one is the native FreeBSD ABI? It does not matter.
Basically the only difference is that (currently; this could
easily be changed in a future release, and probably will be after
this) the FreeBSD glue functions are
statically linked into the kernel, and the Linux glue functions
can be statically linked, or they can be accessed via a kernel
module.Yeah, but is this really emulation? No. It is an ABI
implementation, not an emulation. There is no emulator (or
simulator, to cut off the next question) involved.So why is it sometimes called Linux emulation?
To make it hard to sell FreeBSD! Really, it
is because the historical implementation was done at a time when
there was really no word other than that to describe what was
going on; saying that FreeBSD ran Linux binaries was not true, if
you did not compile the code in or load a module, and there needed
to be a word to describe what was being loaded—hence
the Linux emulator.
diff --git a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml
index 55eb5369e3..c7b80f6751 100644
--- a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml
@@ -1,528 +1,543 @@
+
+
+
+ Bill
+ Lloyd
+ Original work by
+
+
+
+
+ Jim
+ Mock
+ Rewritten by
+
+
+
+
+
Electronic Mail
- Rewritten by &a.jim;, 02 December 1999. Original work
- done by &a.wlloyd;.
-
Synopsisemailelectronic mailElectronic Mail, better known as email, is one of the most
widely used forms of communication today. Millions of people use
email every day, and chances are if you are reading this online,
you fall into that category and probably even have more than one
email address.Electronic Mail configuration is the subject of many System Administration books. If you
plan on doing anything beyond setting up one mailhost for your
network, you need industrial strength help.DNSSome parts of email configuration are controlled in the Domain
Name System (DNS). If you are going to run your own DNS server, be
sure to read through the files in /etc/namedb
and man -k named.Using Electronic MailPOPIMAPThere are five major parts involved in an email exchange. They
are: the user program, the server daemon, DNS, a pop or
IMAP daemon, and of course, the
mailhost itself.The User ProgramThis includes command line programs such as
mutt, pine,
elm, and
mail, and GUI programs such as
balsa,
xfmail to name a few, and something
more sophisticated like a WWW browser. These
programs simply pass off the email transactions to the local mailhost, either by
calling one of the server daemons
available or delivering it over TCP.Mailhost Server Daemonmail server daemonssendmailmail server daemonspostfixmail server daemonsqmailmail server daemonseximThis is usually sendmail (by
default with FreeBSD) or one of the other mail server daemons such
as qmail,
postfix, or
exim. There are others, but those are
the most widely used.The server daemon usually has two functions—it looks
after receiving incoming mail and delivers outgoing mail. It does
not allow you to connect to it via POP or IMAP to read your mail.
You need an additional daemon
for that.Be aware that some older versions of
sendmail have some serious security
problems, however as long as you run a current version of it you
should not have any problems. As always, it is a good idea to
stay up-to-date with any software you run.Email and DNSThe Domain Name System (DNS) and its daemon
named play a large role in the delivery of
email. In order to deliver mail from your site to another, the
server daemon will look up the site in the DNS to determine the
host that will receive mail for the destination.It works the same way when you have mail sent to you. The DNS
contains the database mapping hostname to an IP address, and a
hostname to mailhost. The IP address is specified in an A record.
The MX (Mail eXchanger) record specifies the mailhost that will
receive mail for you. If you do not have an MX record for your
hostname, the mail will be delivered directly to your host.Receiving MailemailreceivingReceiving mail for your domain is done by the mail host. It
will collect mail sent to you and store it for reading or pickup.
In order to pick the stored mail up, you will need to connect to
the mail host. This is done by either using POP or IMAP. If you
want to read mail directly on the mail host, then a POP or IMAP
server is not needed.POPIMAPIf you want to run a POP or IMAP server, there are two things
you need to do:Get a POP or IMAP daemon from the ports collection and install
it on your system.Modify /etc/inetd.conf to load the
POP or IMAP server.The Mail Hostmail hostThe mail host is the name given to a server that is
responsible for delivering and receiving mail for your host, and
possibly your network.TroubleshootingemailtroubleshootingHere are some frequently asked questions and answers. These
have been migrated from the FAQ.Why do I have to use the FQDN for hosts on my site?You will probably find that the host is actually in a
different domain; for example, if you are in
foo.bar.edu and you wish to reach
a host called mumble in the bar.edu domain, you will have to
refer to it by the fully-qualified domain name, mumble.bar.edu, instead of just
mumble.BINDTraditionally, this was allowed by BSD BIND resolvers.
However the current version of BIND
that ships with FreeBSD no longer provides default abbreviations
for non-fully qualified domain names other than the domain you
are in. So an unqualified host mumble must
either be found as mumble.foo.bar.edu, or it will be searched
for in the root domain.This is different from the previous behavior, where the
search continued across mumble.bar.edu, and mumble.edu. Have a look at RFC 1535
for why this was considered bad practice, or even a security
hole.As a good workaround, you can place the line:
search foo.bar.edu bar.edu
instead of the previous:
domain foo.bar.edu
into your /etc/resolv.conf. However, make
sure that the search order does not go beyond the
boundary between local and public administration,
as RFC 1535 calls it.Sendmail says mail loops back to
myselfThis is answered in the sendmail FAQ as follows:* I am getting Local configuration error messages, such as:
553 relay.domain.net config error: mail loops back to myself
554 <user@domain.net>... Local configuration error
How can I solve this problem?
You have asked mail to the domain (e.g., domain.net) to be
forwarded to a specific host (in this case, relay.domain.net)
by using an MX record, but the relay machine does not recognize
itself as domain.net. Add domain.net to /etc/sendmail.cw
(if you are using FEATURE(use_cw_file)) or add Cw domain.net
to /etc/sendmail.cf.The sendmail FAQ is in
/usr/src/usr.sbin/sendmail and is
recommended reading if you want to do any
tweaking of your mail setup.PPPHow can I do email with a dial-up PPP host?You want to connect a FreeBSD box on a lan, to the
Internet. The FreeBSD box will be a mail gateway for the lan.
The PPP connection is non-dedicated.There are at least two ways to do this.UUCPThe other is to use UUCP.The key is to get a Internet site to provide secondary MX
service for your domain. For example:bigco.com. MX 10 bigco.com.
MX 20 smalliap.com.Only one host should be specified as the final recipient
(add Cw bigco.com in
/etc/sendmail.cf on bigco.com).When the senders' sendmail is trying to
deliver the mail it will try to connect to you over the modem
link. It will most likely time out because you are not online.
sendmail will automatically deliver it to the
secondary MX site, i.e., your Internet provider. The secondary MX
site will try every
(sendmail_flags = -bd -q15m in
/etc/rc.conf) 15 minutes to connect to
your host to deliver the mail to the primary MX site.You might want to use something like this as a login
script.#!/bin/sh
# Put me in /usr/local/bin/pppbigco
( sleep 60 ; /usr/sbin/sendmail -q ) &
/usr/sbin/ppp -direct pppbigcoIf you are going to create a separate login script for a
user you could use sendmail -qRbigco.com
instead in the script above. This will force all mail in your
queue for bigco.com to be processed immediately.A further refinement of the situation is as follows.Message stolen from the &a.isp;.> we provide the secondary MX for a customer. The customer connects to
> our services several times a day automatically to get the mails to
> his primary MX (We do not call his site when a mail for his domains
> arrived). Our sendmail sends the mailqueue every 30 minutes. At the
> moment he has to stay 30 minutes online to be sure that all mail is
> gone to the primary MX.
>
> Is there a command that would initiate sendmail to send all the mails
> now? The user has not root-privileges on our machine of course.
In the privacy flags section of sendmail.cf, there is a
definition Opgoaway,restrictqrun
Remove restrictqrun to allow non-root users to start the queue processing.
You might also like to rearrange the MXs. We are the 1st MX for our
customers like this, and we have defined:
# If we are the best MX for a host, try directly instead of generating
# local config error.
OwTrue
That way a remote site will deliver straight to you, without trying
the customer connection. You then send to your customer. Only works for
hosts, so you need to get your customer to name their mail
machine customer.com as well as
hostname.customer.com in the DNS. Just put an A record in
the DNS for customer.com.Advanced TopicsThe following section covers more involved topics such as mail
configuration and setting up mail for your entire domain.Basic ConfigurationemailconfigurationOut of the box, you should be able to send email to external
hosts as long as you have set up
/etc/resolv.conf or are running your own
name server. If you would like to have mail for your host
delivered to that specific host, there are two methods:Run your own name server and have your own domain. For
example, FreeBSD.orgGet mail delivered directly to your host. This is done by
delivering mail directly to the current DNS name for your
machine. For example, example.FreeBSD.org.SMTPRegardless of which of the above you choose, in order to have
mail delivered directly to your host, you must have a permanent
(static) IP address (no dynamic PPP dial-up). If you are behind a
firewall, it must pass SMTP traffic on to you. If you want to
receive mail at your host itself, you need to be sure of one of two
things:MX recordMake sure that the MX record in your DNS points to your
host's IP address.Make sure there is no MX entry in your DNS for your
host.Either of the above will allow you to receive mail directly at
your host.Try this:&prompt.root; hostname
example.FreeBSD.org
&prompt.root; host example.FreeBSD.org
example.FreeBSD.org has address 204.216.27.XXIf that is what you see, mail directly to
yourlogin@example.FreeBSD.org should work without
problems.If instead you see something like this:&prompt.root; host example.FreeBSD.org
example.FreeBSD.org has address 204.216.27.XX
example.FreeBSD.org mail is handled (pri=10) by hub.FreeBSD.orgAll mail sent to your host (example.FreeBSD.org) will end up being
collected on hub under the same username instead
of being sent directly to your host.The above information is handled by your DNS server. The DNS
record that carries mail routing information is the
Mail eXchange entry. If
no MX record exists, mail will be delivered directly to the host by
way of its IP address.The MX entry for freefall.FreeBSD.org at one time looked like
this:freefall MX 30 mail.crl.net
freefall MX 40 agora.rdrop.com
freefall MX 10 freefall.FreeBSD.org
freefall MX 20 who.cdrom.comAs you can see, freefall had many MX entries.
The lowest MX number is the host that ends up receiving the mail in
the end while the others will queue mail temporarily if
freefall is busy or down.Alternate MX sites should have separate Internet connections
from your own in order to be the most useful. Your ISP or other
friendly site should have no problem providing this service for
you.Mail for your DomainIn order to set up a mailhost (a.k.a., mail
server) you need to have any mail sent to various workstations
directed to it. Basically, you want to hijack any
mail for your domain (in this case *.FreeBSD.org) and divert it to your mail
server so your users can check their mail via POP or directly on
the server.DNSTo make life easiest, a user account with the same
username should exist on both machines. Use
adduser to do this.The mailhost you will be using must be the designated mail
exchange for each workstation on the network. This is done in
your DNS configuration like so:example.FreeBSD.org A 204.216.27.XX ; Workstation
MX 10 hub.FreeBSD.org ; MailhostThis will redirect mail for the workstation to the mailhost no
matter where the A record points. The mail is sent to the MX
host.You cannot do this yourself unless you are running a DNS
server. If you are not, or cannot, run your own DNS server, talk
to your ISP or whoever does your DNS for you.If you're doing virtual email hosting, the following
information will come in handy. For the sake of an example, we
will assume you have a customer with their own domain, in this
case customer1.org and you want
all the mail for customer1.org
sent to your mailhost, which is named mail.myhost.com. The entry in your DNS
should look like this:customer1.org MX 10 mail.myhost.comYou do not need an A record if you only
want to handle email for the domain.Be aware that this means pinging customer1.org will not work unless
an A record exists for it.The last thing that you must do is tell
sendmail on your mailhost what domains
and/or hostnames it should be accepting mail for. There are a few
different ways this can be done. Either of the following will
work:Add the hosts to your
/etc/sendmail.cw file if you are using the
FEATURE(use_cw_file). If you are using
sendmail 8.10 or higher, the file is
/etc/mail/local-host-names.Add a Cwyour.host.com line to your
/etc/sendmail.cf or
/etc/mail/sendmail.cf if you are using
sendmail 8.10 or higher.
diff --git a/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml b/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml
index e242a377f7..1675e6e19e 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 @@
MosesMoore
- Contributed
+ Contributed by SoundSynopsisFreeBSD 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: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/policies/chapter.sgml b/en_US.ISO8859-1/books/handbook/policies/chapter.sgml
index 8731f45abe..f9fcbba896 100644
--- a/en_US.ISO8859-1/books/handbook/policies/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/policies/chapter.sgml
@@ -1,403 +1,437 @@
+
+
+ Poul-Henning
+ Kamp
+ Contributed by
+
+
+
Source Tree Guidelines and Policies
- Contributed by &a.phk;.
-
This chapter documents various guidelines and policies in force for
the FreeBSD source tree.MAINTAINER on Makefilesports maintainerJune 1996.If a particular portion of the FreeBSD distribution is being
maintained by a person or group of persons, they can communicate this
fact to the world by adding a
MAINTAINER= email-addresses
line to the Makefiles covering this portion of the
source tree.The semantics of this are as follows:The maintainer owns and is responsible for that code. This means
that he is responsible for fixing bugs and answer problem reports
pertaining to that piece of the code, and in the case of contributed
software, for tracking new versions, as appropriate.Changes to directories which have a maintainer defined shall be sent
to the maintainer for review before being committed. Only if the
maintainer does not respond for an unacceptable period of time, to
several emails, will it be acceptable to commit changes without review
by the maintainer. However, it is suggested that you try and have the
changes reviewed by someone else if at all possible.It is of course not acceptable to add a person or group as
maintainer unless they agree to assume this duty. On the other hand it
doesn't have to be a committer and it can easily be a group of
people.
+
+
+
+ Poul-Henning
+ Kamp
+ Contributed by
+
+
+ David
+ O'Brien
+
+
+
+
+
Contributed Softwarecontributed software
- Contributed by &a.phk; and &a.obrien;.
-
- June 1996.
-
+
Some parts of the FreeBSD distribution consist of software that is
actively being maintained outside the FreeBSD project. For historical
reasons, we call this contributed software. Some
examples are perl, gcc and
patch.Over the last couple of years, various methods have been used in
dealing with this type of software and all have some number of
advantages and drawbacks. No clear winner has emerged.Since this is the case, after some debate one of these methods has
been selected as the official method and will be required
for future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on this
model over time, as it has significant advantages over the old method,
including the ability to easily obtain diffs relative to the
official versions of the source by everyone (even without
cvs access). This will make it significantly easier to return changes
to the primary developers of the contributed software.Ultimately, however, it comes down to the people actually doing the
work. If using this model is particularly unsuited to the package being
dealt with, exceptions to these rules may be granted only with the
approval of the core team and with the general consensus of the other
developers. The ability to maintain the package in the future will be a
key issue in the decisions.Because of some unfortunate design limitations with the RCS file
format and CVS's use of vendor branches, minor, trivial and/or
cosmetic changes are strongly discouraged on
files that are still tracking the vendor branch. Spelling
fixes are explicitly included here under the
cosmetic category and are to be avoided for files with
revision 1.1.x.x. The repository bloat impact from a single character
change can be rather dramatic.The Tcl embedded programming
language will be used as example of how this model works:src/contrib/tcl contains the source as
distributed by the maintainers of this package. Parts that are entirely
not applicable for FreeBSD can be removed. In the case of Tcl, the
mac, win and
compat subdirectories were eliminated before the
importsrc/lib/libtcl contains only a "bmake style"
Makefile that uses the standard
bsd.lib.mk makefile rules to produce the library
and install the documentation.src/usr.bin/tclsh contains only a
bmake style
Makefile which will produce and install the
tclsh program and its associated man-pages using the
standard bsd.prog.mk rules.src/tools/tools/tcl_bmake contains a couple of
shell-scripts that can be of help when the Tcl software needs updating.
These are not part of the built or installed software.The important thing here is that the
src/contrib/tcl directory is created according to
the rules: It is supposed to contain the sources as distributed (on a
proper CVS vendor-branch and without RCS keyword expansion) with as few
FreeBSD-specific changes as possible. The 'easy-import' tool on
freefall will assist in doing the import, but if there
are any doubts on
how to go about it, it is imperative that you ask first and not blunder
ahead and hope it works out. CVS is not forgiving of
import accidents and a fair amount of effort is required to back out
major mistakes.Because of the previously mentioned design limitations with CVS's
vendor branches, it is required that official patches from
the vendor be applied to the original distributed sources and the result
re-imported onto the vendor branch again. Official patches should never
be patched into the FreeBSD checked out version and "committed", as this
destroys the vendor branch coherency and makes importing future versions
rather difficult as there will be conflicts.Since many packages contain files that are meant for compatibility
with other architectures and environments that FreeBSD, it is
permissible to remove parts of the distribution tree that are of no
interest to FreeBSD in order to save space. Files containing copyright
notices and release-note kind of information applicable to the remaining
files shall not be removed.If it seems easier, the bmakeMakefiles can be produced from the dist tree
automatically by some utility, something which would hopefully make it
even easier to upgrade to a new version. If this is done, be sure to
check in such utilities (as necessary) in the
src/tools directory along with the port itself so
that it is available to future maintainers.In the src/contrib/tcl level directory, a file
called FREEBSD-upgrade should be added and it
should states things like:Which files have been left outWhere the original distribution was obtained from and/or the
official master site.Where to send patches back to the original authorsPerhaps an overview of the FreeBSD-specific changes that have
been made.However, please do not import FREEBSD-upgrade
with the contributed source. Rather you should cvs add
FREEBSD-upgrade ; cvs ci after the initial import. Example
wording from src/contrib/cpio is below:This directory contains virgin sources of the original distribution files
on a "vendor" branch. Do not, under any circumstances, attempt to upgrade
the files in this directory via patches and a cvs commit. New versions or
official-patch versions must be imported. Please remember to import with
"-ko" to prevent CVS from corrupting any vendor RCS Ids.
For the import of GNU cpio 2.4.2, the following files were removed:
INSTALL cpio.info mkdir.c
Makefile.in cpio.texi mkinstalldirs
To upgrade to a newer version of cpio, when it is available:
1. Unpack the new version into an empty directory.
[Do not make ANY changes to the files.]
2. Remove the files listed above and any others that don't apply to
FreeBSD.
3. Use the command:
cvs import -ko -m 'Virgin import of GNU cpio v<version>' \
src/contrib/cpio GNU cpio_<version>
For example, to do the import of version 2.4.2, I typed:
cvs import -ko -m 'Virgin import of GNU v2.4.2' \
src/contrib/cpio GNU cpio_2_4_2
4. Follow the instructions printed out in step 3 to resolve any
conflicts between local FreeBSD changes and the newer version.
Do not, under any circumstances, deviate from this procedure.
To make local changes to cpio, simply patch and commit to the main
branch (aka HEAD). Never make local changes on the GNU branch.
All local changes should be submitted to "cpio@gnu.ai.mit.edu" for
inclusion in the next vendor release.
obrien@FreeBSD.org - 30 March 1997Encumbered FilesIt might occasionally be necessary to include an encumbered file in
the FreeBSD source tree. For example, if a device requires a small
piece of binary code to be loaded to it before the device will operate,
and we do not have the source to that code, then the binary file is said
to be encumbered. The following policies apply to including encumbered
files in the FreeBSD source tree.Any file which is interpreted or executed by the system CPU(s)
and not in source format is encumbered.Any file with a license more restrictive than BSD or GNU is
encumbered.A file which contains downloadable binary data for use by the
hardware is not encumbered, unless (1) or (2) apply to it. It must
be stored in an architecture neutral ASCII format (file2c or
uuencoding is recommended).Any encumbered file requires specific approval from the Core team before it is added to the
CVS repository.Encumbered files go in src/contrib or
src/sys/contrib.The entire module should be kept together. There is no point in
splitting it, unless there is code-sharing with non-encumbered
code.Object files are named
arch/filename.o.uu>.Kernel files;Should always be referenced in
conf/files.* (for build simplicity).Should always be in LINT, but the Core team decides per case if it
should be commented out or not. The Core team can, of course, change
their minds later on.The Release Engineer
decides whether or not it goes in to the release.User-land files;core teamThe Core team decides if
the code should be part of make world.release engineerThe Release Engineer
decides if it goes in to the release.
+
+
+
+ Satoshi
+ Asami
+ Contributed by
+
+
+ Peter
+ Wemm
+
+
+ David
+ O'Brien
+
+
+
+
+
Shared Libraries
-
- Contributed by &a.asami;, &a.peter;, and &a.obrien; 9
- December 1996.If you are adding shared library support to a port or other piece of
software that doesn't have one, the version numbers should follow these
rules. Generally, the resulting numbers will have nothing to do with
the release version of the software.The three principles of shared library building are:Start from 1.0If there is a change that is backwards compatible, bump minor
number (note that ELF systems ignore the minor number)If there is an incompatible change, bump major numberFor instance, added functions and bugfixes result in the minor
version number being bumped, while deleted functions, changed function
call syntax etc. will force the major version number to change.Stick to version numbers of the form major.minor
(x.y). Our a.out
dynamic linker does not handle version numbers of the form
x.y.z
well. Any version number after the y
(ie. the third digit) is totally ignored when comparing shared lib
version numbers to decide which library to link with. Given two shared
libraries that differ only in the micro revision,
ld.so will link with the higher one. Ie: if you link
with libfoo.so.3.3.3, the linker only records
3.3 in the headers, and will link with anything
starting with
libfoo.so.3.(anything >=
3).(highest
available).ld.so will always use the highest
minor revision. Ie: it will use
libc.so.2.2 in preference to
libc.so.2.0, even if the program was initially
linked with libc.so.2.0.In addition, our ELF dynamic linker does not handle minor version
numbers at all. However, one should still specify a major and minor
version number as our Makefiles "do the right thing"
based on the type of system.For non-port libraries, it is also our policy to change the shared
library version number only once between releases. In addition, it is
our policy to change the major shared library version number only once
between major OS releases. Ie: X.0 to (X+1).0. When you make a
change to a system library that requires the version number to be
bumped, check the Makefile's commit logs. It is the
responsibility of the committer to ensure that the first such change
since the release will result in the shared library version number in
the Makefile to be updated, and any subsequent
changes will not.
diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
index 594b4ca50d..c413036709 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml
@@ -1,1314 +1,1314 @@
Installing Applications: Packages and PortsSynopsisportspackagesThere is only so much you can do with FreeBSD. If you are an
operating systems developer then the base system likely contains
everything you need. If that is not what you are planning to do with
FreeBSD then you will probably want to install additional
software—perhaps a web server, or a mail reader, or a graphical
environment such as KDE or
GNOME.If you have used a Unix system before you will know that the typical
procedure for installing third party software goes something like
this:Download the software, which might be distributed in source code
format, or as a binary.Unpack the software from its distribution format (typically a
tarball compressed with either &man.compress.1; or &man.gzip.1;).Locate the documentation (perhaps a README
file, or some files in a doc/ subdirectory) and
read up on how to install the software.If the software was distributed in source format, compile it.
This may involve editing a Makefile, or
running a configure script, and other work.Test and install the software.And that is only if everything goes well. If you are installing a
software package that was not deliberately ported to FreeBSD you may
even have to go in and edit the code to make it work properly.Should you want to, you can continue to install software the
traditional way with FreeBSD. However, FreeBSD
provides two technologies which can save you a lot of effort;
packages and ports. At the time of writing, over &os.numports;
third party applications have been made available in this
way.For any given application, the FreeBSD package for that application
is a single file which you must download. The package contains
pre-compiled copies of all the commands for the application, as well as
any configuration files or documentation. A downloaded package file can
be manipulated with FreeBSD package management commands, such as
&man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so on.Installing a new application can be carried out with a single
command.A FreeBSD port for an application is a collection of files designed
to automate the process of compiling an application from source
code.Remember that there are a number of steps you would normally carry
out if you compiled a program yourself (unpacking, patching, compiling,
installing). The files that make up a port contain all the necessary
information to allow the system to do this for you. You run a handful
of simple commands and the source code for the application is
automatically downloaded, extracted, patched, compiled, and installed
for you.In fact, the ports system can also be used to generate packages
which can later be manipulated with the pkg_add
and friends commands.Both packages and ports understand
dependencies. Suppose you want to install an
application that depends on a specific library being installed. Both
the application and the library have been made available as FreeBSD
ports and packages. If you use the pkg_add command
or the ports system to add the application, both will notice that the
library has not been installed, and the commands will install the
library first.Given that the two technologies are quite similar, you might be
wondering why FreeBSD bothers with both. Packages and ports both have
their own strengths, and which one you use will depend on your own
preference.Package benefitsA compressed package tarball is typically smaller than the
compressed tarball containing the source code for the application.Packages do not require any additional compilation. For large
applications, such as Mozilla,
KDE, or GNOME
this can be important, particularly if you are on a slow system.Packages do not require you to understand the process
involved in compiling software on FreeBSD.Ports benefitsPackages are normally compiled with conservative options,
because they have to run on the maximum number of systems. By
installing from the port, you can tweak the compilation options to
(for example) generate code that is specific to a 686 processor.Some packages have compile time options relating to what they
can and can't do. For example, Apache
can be configured with a wide variety of different builtin options.
By building from the port you do not have to accept the default
options, and can set them yourself.In some cases, multiple packages will exist for the same
application to specify certain settings. For example,
Ghostscript is available as a
ghostscript package and a
ghostscript-nox11 package, depending on whether
or not you have installed an X11 server. This sort of rough
tweaking is possible with packages, but rapidly becomes impossible
if an application has more than one or two different compile time
options.The licensing conditions of some software distributions forbid
binary distribution. They must be distributed as source
code.Some people do not trust binary distributions. At least with
source code, you can (in theory) read through it and look for
potential problems yourself.If you have local patches, you will need the source in order to
apply them.Some people like having code around, so they can read it if they
get bored, hack it, borrow from it (license permitting, of course),
and so on.To keep track of updated ports, subscribe to the
freebsd-ports@freebsd.org mailing list.The remainder of this chapter will explain how to use packages and
ports to install and manage third party software on FreeBSD.Finding your applicationBefore you can install any applications you need to know what you
want, and what the application is called.FreeBSD's list of available applications is growing all the
time. Currently there are over &os.numports; applications
available as packages or ports. There are a number of ways to
find what you want.The FreeBSD web site maintains an up-to-date searchable list of
all the available applications, at
http://www.FreeBSD.org/ports/.
The name space is divided in to categories, and you may either
search for an application by name (if you know it), or you can list
all the applications available in a category.FreshPortsDan Langille maintains FreshPorts, at
http://www.freshports.org/.
FreshPorts tracks changes to the applications in the ports tree as
they happen, and allows you to watch one or more
ports, and will send you an email when they are updated.FreshMeatIf you do not know the name of the application you want, try
using a site like FreshMeat
(http://www.freshmeat.net/)
or AppWatch
(http://www.appwatch.com/)
to find an application, then check back at the FreeBSD site to see
if the application has been ported yet.ChernLee
- Contributed
+ Contributed by Using the Packages SystemInstalling a Packagepackagesinstallingpkg_addYou can use the &man.pkg.add.1; utility to install a
FreeBSD software package from a local file or from a server on
the network.Downloading a package and then installing it locally&prompt.root; ftp -a ftp2.freebsd.org
Connected to ftp2.freebsd.org.
220 ftp2.freebsd.org FTP server (Version 6.00LS) ready.
331 Guest login ok, send your email address as password.
230-
230- This machine is in Vienna, VA, USA, hosted by Verio.
230- Questions? E-mail freebsd@vienna.verio.net.
230-
230-
230 Guest login ok, access restrictions apply.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp>cd /pub/FreeBSD/ports/packages/sysutils/
250 CWD command successful.
ftp>get lsof-4.56.4.tgz
local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz
200 PORT command successful.
150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes).
100% |**************************************************| 92375 00:00 ETA
226 Transfer complete.
92375 bytes received in 5.60 seconds (16.11 KB/s)
ftp>exit
&prompt.root; pkg_add lsof-4.56.4.tgzIf you don't have a source of local packages (such as a
FreeBSD CDROM set) then it will probably be easier to use the
-r option to &man.pkg.add.1;. This will cause the utility to
automatically determine the correct object format and release
and then to fetch and install the package from an FTP site.
pkg_add&prompt.root; pkg_add -r lsof-4.56.4This would download the correct package and add it without
any further user intervention.Package files are distributed in .tgz format. You can
find them at
ftp://ftp.freebsd.org/pub/FreeBSD/ports/packages/,
or on the FreeBSD CDROM distribution. Every CD on the
FreeBSD 4-CD set (and PowerPak, etc) contains packages in
the /packages directory. The layout of
the packages is similar to that of the
/usr/ports tree. Each category has its
own directory, and every package can be found within the
All directory.
The directory structure of the package system is homologous
to that of the ports; they work with each other to form the entire
package/port system.
Deleting a Packagepkg_deletepackagesdeletingTo remove a previously installed software package, use the
&man.pkg.delete.1; utility.
&prompt.root pkg_delete xchat-1.7.1Managing packagespackagesmanaging&man.pkg.info.1; a utility that lists and describes
the various packages installed.
pkg_info&prompt.root pkg_info
cvsup-16.1 A general network file distribution system optimized for CV
docbook-1.2 Meta-port for the different versions of the DocBook DTD
...&man.pkg.version.1; a utility that summarizes the
versions of all installed packages. It compares the package
version to the current version found in the ports tree.
&prompt.root pkg_version
cvsup =
docbook =
...The symbols in the second column indicate the relative age
of the installed version and the version available in the local
ports tree.SymbolMeaning=The version of the
installed package matches that of the one found in the
local ports tree.<The installed version is older then the one available
in the ports tree.>The installed version is newer
than the one found in the local ports tree. (local ports
tree is probably out of date)?The installed package cannot be
found in the ports index.*There are multiple versions of the
package.MiscellaneousAll package information is stored within the
/var/db/pkg directory. The listing
of contents and descriptions of each package can be found within
files in this directory.
Using the Ports CollectionThe following sections provide basic instructions on using the
ports collection to install or remove programs from your
system.Installing PortsportsinstallingThe first thing that should be explained
when it comes to the ports collection is what is actually meant
by a skeleton. In a nutshell, a port skeleton is a
minimal set of files that are needed for a program to compile and
install cleanly on FreeBSD. Each port skeleton includes:A Makefile. The
Makefile contains various statements that
specify how the application should be compiled and where it
should be installed on your systemA distinfo file. This file contains
information about the files that must be downloaded to build the
port, and checksums, to ensure that those files have not been
corrupted during the download.A files directory. This directory
contains patches to make the program compile and install on
your FreeBSD system. Patches are basically small files that
specify changes to particular files. They are in plain text
format, and basically say Remove line 10 or
Change line 26 to this .... Patches are also
known as diffs because they are generated by the
diff program.This directory may also contain other files used in building
the port.A pkg-comment file. This is a one-line
description of the program.A pkg-descr file. This is a more
detailed, often multiple-line, description of the program.A pkg-plist file. This is a list of all
the files that will be installed by the port. It also tells the
ports system what files to remove upon deinstallation.Now that you have enough background information to know what
the ports collection is used for, you are ready to install your
first port. There are two ways this can be done, and each is
explained below.Before we get into that however, you will need to choose a
port to install. There are a few ways to do this, with the
easiest method being the ports listing on the FreeBSD
web site. You can browse through the ports listed there
or use the search function on the site. Each port also includes
a description so you can read a bit about each port before
deciding to install it.Another method is to use the whereis
command. To use whereis, simply type
whereis <program you want to
install> at the prompt, and if it is found on
your system, you will be told where it is, like so:&prompt.root; whereis lsof
lsof: /usr/ports/sysutils/lsofThis tells us that lsof (a system utility)
can be found in the
/usr/ports/sysutils/lsof directory.Yet another way of finding a particular port is by using the
ports collection's built-in search mechanism. To use the search
feature, you will need to be in the
/usr/ports directory. Once in that
directory, run make search key=program-name
where program-name is the name of the program you
want to find. For example, if you were looking for
lsof:&prompt.root; cd /usr/ports
&prompt.root; make search key=lsof
Port: lsof-4.56.4
Path: /usr/ports/sysutils/lsof
Info: Lists information about open files (similar to fstat(1))
Maint: obrien@FreeBSD.org
Index: sysutils
B-deps:
R-deps: The part of the output you want to pay particular attention
to is the Path: line, since that tells you where to
find it. The other information provided is not needed in order
to install the port directly, so it will not be covered
here.You must be the root user to install
ports.Now that you have found a port you would like to install, you
are ready to do the actual installation.Installing ports from a CDROMportsinstalling from CDROMAs you may have guessed from the title, everything
described in this section assumes you have a FreeBSD CDROM set.
If you do not, you can order one from the FreeBSD Mall.Assuming that your FreeBSD CDROM is in the drive and is
mounted on /cdrom (and the mount point
must be /cdrom),
you are ready to install the port. To begin, change
to the directory where the port you want to install lives:&prompt.root; cd /usr/ports/sysutils/lsofOnce inside the lsof directory,
you will see the port
skeleton. The next step is to compile (also called build) the
port. This is done by simply typing make at
the prompt. Once you have done so, you should see something
like this:&prompt.root; make
>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
>> Attempting to fetch from file:/cdrom/ports/distfiles/.
===> Extracting for lsof-4.57
...
[extraction output snipped]
...
>> Checksum OK for lsof_4.57D.freebsd.tar.gz.
===> Patching for lsof-4.57
===> Applying FreeBSD patches for lsof-4.57
===> Configuring for lsof-4.57
...
[configure output snipped]
...
===> Building for lsof-4.57
...
[compilation snipped]
...
&prompt.root;Take notice that once the compile is complete you are
returned to your prompt. The next step is to install the
port. In order to install it, you simply need to tack one word
onto the make command, and that word is
install:&prompt.root; make install
===> Installing for lsof-4.57
...
[install routines snipped]
...
===> Generating temporary packing list
===> Compressing manual pages for lsof-4.57
===> Registering installation for lsof-4.57
===> SECURITY NOTE:
This port has installed the following binaries which execute with
increased privileges.
&prompt.root;Once you are returned to your prompt, you should be able to
run the application you just installed. Since
lsof is a
program that runs with increased privileges, a security
warning is shown. During the building and installation of
ports, you should take heed of any other warnings that
may appear.You can save an extra step by just running make
install instead of make and
make install as two separate steps.Please be aware that the licenses of a few ports do not
allow for inclusion on the CDROM. This could be for various
reasons, including things such as registration form needs
to be filled out before downloading, if redistribution is not
allowed, and so on. If you wish to install a port not
included on the CDROM, you will need to be online in order to
do so (see the next
section).Installing ports from the InternetAs with the last section, this section makes an assumption
that you have a working Internet connection. If you do not,
you will need to do the CDROM
installation.Installing a port from the Internet is done exactly the same
way as it would be if you were installing from a CDROM. The
only difference between the two is that the program's source
code is downloaded from the Internet instead of pulled from the
CDROM.The steps involved are identical:&prompt.root; make install
>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
>> Attempting to fetch from ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/.
Receiving lsof_4.57D.freebsd.tar.gz (439860 bytes): 100%
439860 bytes transferred in 18.0 seconds (23.90 kBps)
===> Extracting for lsof-4.57
...
[extraction output snipped]
...
>> Checksum OK for lsof_4.57D.freebsd.tar.gz.
===> Patching for lsof-4.57
===> Applying FreeBSD patches for lsof-4.57
===> Configuring for lsof-4.57
...
[configure output snipped]
...
===> Building for lsof-4.57
...
[compilation snipped]
...
===> Installing for lsof-4.57
...
[install routines snipped]
...
===> Generating temporary packing list
===> Compressing manual pages for lsof-4.57
===> Registering installation for lsof-4.57
===> SECURITY NOTE:
This port has installed the following binaries which execute with
increased privileges.
&prompt.root;As you can see, the only difference is the line that tells
you where the system is fetching the port from.That about does it for installing ports onto your
system. In the next section you will learn how to remove a
port from your system.Removing Installed PortsportsremovingNow that you know how to install ports, you are probably
wondering how to remove them, just in case you install one and
later on you decide that you installed the wrong port. The next
few paragraphs will cover just that.Now we will remove our previous example (which was
lsof for
those of you not paying attention). As with installing ports,
the first thing you must do is change to the port directory,
which if you remember was
/usr/ports/irc/lsof. After you change
directories, you are ready to uninstall lsof.
This is done with
the make deinstall command:&prompt.root; cd /usr/ports/irc/lsof
&prompt.root; make deinstall
===> Deinstalling for lsof-4.57That was easy enough. You have now managed to remove
lsof
from your system. If you would like to reinstall it, you can do
so by running make reinstall from the
/usr/ports/irc/lsof directory.TroubleshootingThe following sections cover some of the more frequently asked
questions about the ports collection and some basic troubleshooting
techniques, and what do to if a port is broken.Some Questions and AnswersI thought this was going to be a discussion about
modems??!Ah, you must be thinking of the serial ports on the back
of your computer. We are using port here to
mean the result of porting a program from one
version of Unix to another.What is a patch?A patch is a small file that specifies how to go from
one version of a file to another. It contains plain text,
and basically says things like delete line 23,
add these two lines after line 468, or
change line 197 to this. They are also known
as diffs because they are generated by the
diff program.tarballWhat is all this about
tarballs?It is a file ending in .tar, or
with variations such as .tar.gz,
.tar.Z, .tar.bz2,
and even .tgz.Basically, it is a directory tree that has been archived
into a single file (.tar) and
optionally compressed (.gz). This
technique was originally used for Tape
ARchives (hence the name
tar), but it is a widely used way of
distributing program source code around the Internet.You can see what files are in them, or even extract
them yourself by using the standard Unix
tar program, which comes with the base
FreeBSD system, like this:&prompt.user; tar tvzf foobar.tar.gz
&prompt.user; tar xzvf foobar.tar.gz
&prompt.user; tar tvf foobar.tar
&prompt.user; tar xvf foobar.tarchecksumAnd a checksum?It is a number generated by adding up all the data in
the file you want to check. If any of the characters
change, the checksum will no longer be equal to the total,
so a simple comparison will allow you to spot the
difference.I did what you said for compiling ports from a CDROM and
it worked great until I tried to install the kermit
port.&prompt.root; make install
>> cku190.tar.gz doesn't seem to exist on this system.
>> Attempting to fetch from ftp://kermit.columbia.edu/kermit/archives/.Why can it not be found? Have I got a dud CDROM?As was explained in the compiling ports from CDROM
section, some ports cannot be put on the CDROM set
due to licensing restrictions. Kermit is an example of
that. The licensing terms for kermit do not allow us to put
the tarball for it on the CDROM, so you will have to fetch
it by hand—sorry!The reason why you got all those error messages was
because you were not connected to the Internet at the time.
Once you have downloaded it from any of the MASTER_SITES
(listed in the Makefile), you can restart the install
process.I did that, but when I tried to put it into
/usr/ports/distfiles I got some error
about not having permission.The ports mechanism looks for the tarball in
/usr/ports/distfiles, but you will not
be able to copy anything there because it is symlinked to
the CDROM, which is read-only. You can tell it to look
somewhere else by doing:&prompt.root; make DISTDIR=/where/you/put/it installDoes the ports scheme only work if you have everything
in /usr/ports? My system administrator
says I must put everything under
/u/people/guests/wurzburger, but it
does not seem to work.You can use the PORTSDIR and
PREFIX variables to tell the ports
mechanism to use different directories. For
instance,&prompt.root; make PORTSDIR=/u/people/guests/wurzburger/ports installwill compile the port in
/u/people/guests/wurzburger/ports and
install everything under
/usr/local.&prompt.root; make PREFIX=/u/people/guests/wurzburger/local installwill compile it in /usr/ports and
install it in
/u/people/guests/wurzburger/local.And of course,&prompt.root; make PORTSDIR=../ports PREFIX=../local installwill combine the two (it is too long to write fully on
the page, but it should give you the general idea).imakeSome ports that use &man.imake.1; (a part of the X Windows
System) don't work well with PREFIX, and will insist on
installing under /usr/X11R6. Similarly, some Perl ports
ignore PREFIX and install in the Perl tree. Making these
ports respect PREFIX is a difficult or impossible
job.If you do not fancy typing all that in every time you
install a port, it is a good idea to put these variables
into your environment. Read the man page for your shell for
instructions on doing so.I do not have a FreeBSD CDROM, but I would like to have
all the tarballs handy on my system so I do not have to wait
for a download every time I install a port. Is there any
way to get them all at once?To get every single tarball for the ports collection,
do:&prompt.root; cd /usr/ports
&prompt.root; make fetchFor all the tarballs for a single ports directory,
do:&prompt.root; cd /usr/ports/directory
&prompt.root; make fetchand for just one port—well, you have probably
guessed already.I know it is probably faster to fetch the tarballs from
one of the FreeBSD mirror sites close by. Is there any way
to tell the port to fetch them from servers other than the
ones listed in the MASTER_SITES?Yes. If you know, for example, that ftp.FreeBSD.org is much closer to you
than the sites listed in MASTER_SITES,
do as follows:&prompt.root; cd /usr/ports/directory
&prompt.root; make MASTER_SITE_OVERRIDE= \
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetchI want to know what files make is
going to need before it tries to pull them down.make fetch-list will display a list
of the files needed for a port.Is there any way to stop the port from compiling? I
want to do some hacking on the source before I install it,
but it is a bit tiresome to watch it and hit control-C every
time.Doing make extract will stop it
after it has fetched and extracted the source code.I am trying to make my own port and I want to be able
to stop it compiling until I have had a chance to see if my
patches worked properly. Is there something like
make extract, but for patches?Yep, make patch is what you want.
You will probably find the PATCH_DEBUG
option useful as well. And by the way, thank you for your
efforts!I have heard that some compiler options can cause bugs.
Is this true? How can I make sure that I compile ports
with the right settings?Yes, with version 2.6.3 of gcc (the
version shipped with FreeBSD 2.1.0 and 2.1.5), the
option could result in buggy code
unless you used the
option as well. (Most of the ports do not use
). You should be
able to specify the compiler options used by something
like:&prompt.root; make CFLAGS='-O2 -fno-strength-reduce' installor by editing /etc/make.conf, but
unfortunately not all ports respect this. The surest way
is to do make configure, then go into
the source directory and inspect the Makefiles by hand, but
this can get tedious if the source has lots of
sub-directories, each with their own Makefiles.The default FreeBSD compiler options are quite conservative,
so if you have not changed them you should not have any
problems.There are so many ports it is hard to find the one I
want. Is there a list anywhere of what ports are
available?Look in the INDEX file in
/usr/ports. If you would like to
search the ports collection for a keyword, you can do that
too. For example, you can find ports relevant to the LISP
programming language using:&prompt.user; cd /usr/ports
&prompt.user; make search key=lispI went to install the foo port but
the system suddenly stopped compiling it and starting
compiling the bar port. What is going
on?The foo port needs something that is
supplied with bar — for instance,
if foo uses graphics,
bar might have a library with useful
graphics processing routines. Or bar
might be a tool that is needed to compile the
foo port. I installed the
grizzle program from the ports and
frankly it is a complete waste of disk space. I want to
delete it but I do not know where it put all the files.
Any clues?No problem, just type:&prompt.root; pkg_delete grizzle-6.5Alternatively, you can type:&prompt.root; cd /usr/ports/somewhere/grizzle
&prompt.root; make deinstallHang on a minute, you have to know the version number
to use that command. You do not seriously expect me to
remember that, do you?Not at all, you can find it out by doing:&prompt.root; pkg_info -I 'grizzle*'
Information for grizzle-6.5:
grizzle-6.5 - the combined piano tutorial, LOGO interpreter and shoot 'em up
arcade game.The version number can also be found using the
pkg_info or by typing:
ls /var/db/pkgTalking of disk space, the ports directory seems to be
taking up an awful lot of room. Is it safe to go in there
and delete things?Yes, if you have installed the program and are fairly
certain you will not need the source again, there is no
point in keeping it hanging around. The best way to do
this is:&prompt.root; cd /usr/ports
&prompt.root; make cleanwhich will go through all the ports subdirectories and
delete everything except the skeletons for each
port.I tried that and it still left all those tarballs or
whatever you called them in the
distfiles directory. Can I delete
those as well?Yes, if you are sure you have finished with them,
those can go as well. They can be removed manually, or by
using make distclean.I like having lots and lots of programs to play with.
Is there any way of installing all the ports in one
go?Just do:&prompt.root; cd /usr/ports
&prompt.root; make installBe careful, as some ports may install files with the same
name. If you install two graphics ports and they both install
/usr/local/bin/plot then you will obviously
have problems.OK, I tried that, but I thought it would take a very
long time so I went to bed and left it to get on with it.
When I looked at the computer this morning, it had only
done three and a half ports. Did something go
wrong?No, the problem is that some of the ports need to ask
you questions that we cannot answer for you (e.g., Do
you want to print on A4 or US letter sized paper?)
and they need to have someone on hand to answer
them.I really do not want to spend all day staring at the
monitor. Any better ideas?OK, do this before you go to bed/work/the local
park:&prompt.root cd /usr/ports
&prompt.root; make -DBATCH installThis will install every port that does
not require user input. Then, when
you come back, do:&prompt.root; cd /usr/ports
&prompt.root; make -DINTERACTIVE installto finish the job.At work, we are using frobble, which
is in your ports collection, but we have altered it quite a
bit to get it to do what we need. Is there any way of making
our own packages, so we can distribute it more easily around
our sites?No problem, assuming you know how to make patches for
your changes:&prompt.root; cd /usr/ports/somewhere/frobble
&prompt.root; make extract
&prompt.root; cd work/frobble-2.8
[Apply your patches]
&prompt.root; cd ../..
&prompt.root; make packageThis ports stuff is really clever. I am desperate to
find out how you did it. What is the secret?Nothing secret about it at all, just look at the
bsd.port.mk and
bsd.port.subdir.mk files in your
makefiles
directory.(Readers with an aversion to intricate shell-scripts are
advised not to look at the files in this directory.)Help! This port is broken!If you come across a port that doesn't work for you, there are
a few things you can do, including:Fix it! The Porter's
Handbook should help you do this.Gripe—by email only! Send
email to the maintainer of the port first. Type make
maintainer or read the Makefile
to find the maintainer's email address. Remember to include
the name and version of the port (send the
$FreeBSD: line from the
Makefile) and the output leading up to the
error when you email the maintainer. If you do not get a
response from the maintainer, you can use
send-pr to submit a bug report.Grab the package from an ftp site near you. The
master package collection is on ftp.FreeBSD.org in the packages
directory, but be sure to check your local mirror
first! These are more likely to work
than trying to compile from source and are a lot faster as
well. Use the &man.pkg.add.1; program to install the package
on your system.Advanced TopicsThe documentation that was here has been moved to its own Porter's Handbook for ease of
reference. Please go there if you wish to create and submit your own
ports.
diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
index 6984bf7997..05ccabea86 100644
--- a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml
@@ -1,2901 +1,2976 @@
- PPP and SLIP
+
+
+
+ Jim
+ Mock
+ Restructured, reorganized, and updated by
+
+
+
+
- Restructured, reorganized, and updated by &a.jim;,
- 1 March 2000.
+ PPP and SLIPSynopsisPPPSLIPIf you are connecting to the Internet via modem, or wish to
provide dial-up connections to the Internet for others using FreeBSD,
you have the option of using PPP or SLIP.PPPuser PPPPPPkernel PPPPPPover EthernetThis chapter covers three varieties of PPP;
user, kernel, and
PPPoE (PPP over Ethernet). It also covers
setting up a SLIP client and server.The first variety of PPP that will be covered is User PPP. User
PPP was introduced into FreeBSD in 2.0.5-RELEASE as an addition to
the already existing kernel implementation of PPP.You may be wondering what the main difference is between User
PPP and kernel PPP. The answer is simple; user PPP does not run as
a daemon, and can run as and when desired. No PPP interface needs
to be compiled into their kernel; it runs as a user process, and uses
the tunnel device driver (tun) to get data
into and out of the kernel.From here on out in this chapter, user ppp will simply be
referred to as ppp unless a distinction needs to be made between it
and any other PPP software such as pppd.
Unless otherwise stated, all of the commands explained in this
section should be executed as root.
- Using User PPP
+
+
+
+ Brian
+ Somers
+ Originally contributed by
+
+
+
+
+ Nik
+ Clayton
+ With input from
+
+
+ Dirk
+ Frömberg
+
+
+ Peter
+ Childs
+
+
+
- Originally contributed by &a.brian;, with input
- from &a.nik;, &a.dirkvangulik;, and &a.pjc;.
+ Using User PPPUser PPPAssumptionsThis document assumes you have the following:ISPPPPAn account with an Internet Service Provider (ISP) which
you connect to using PPP. Further, you have a modem or
other device connected to your system and configured
correctly, which allows you to connect to your ISP.The dial-up number(s) of your ISP.PAPCHAPUnixlogin namepasswordYour login name and password. This can be either a
regular Unix-style login and password pair, or a PAP or CHAP
login and password pair.nameserverThe IP address(es) of one or more name servers.
Normally, you will be given two IP addresses by your ISP to
use for this. If they have not given you at least one, then
you can use the enable dns command in
your ppp.conf file to tell
ppp to set the name servers for
you.The following information may be supplied by your ISP, but
is not completely necessary:The IP address of your ISP's gateway. The gateway is
the machine to which you will connect and will be set up as
your default route. If you do not have
this information, we can make one up and your ISP's PPP
server will tell us the correct value when we connect.This IP number is referred to as
HISADDR by
ppp.The netmask you should use. If your ISP has not
provided you with one, you can safely use 255.255.255.0.static IP addressIf your ISP provides you with a static IP address and
hostname, you can enter it. Otherwise, we simply let the
peer assign whatever IP address it sees fit.If you do not have any of the required information, contact
your ISP and make sure they provide it to you.Preparing the KernelAs previously mentioned, ppp
uses the tun device, and whichever kernel
you are using must have tun configured.
The tun device is preconfigured
for the default GENERIC kernel that ships
with FreeBSD. However, if you have installed a custom kernel,
you must make sure your kernel is configured for ppp.kernelcompilingTo check, go to your kernel compile directory
(/sys/i386/conf or
/sys/pc98/conf) and examine your
configuration file. It should have the following line somewhere
in it:pseudo-device tun 1If this line is not present, you will need to add it to the
configuration file and recompile your kernel. The stock
GENERIC kernel has this included, so if you
have not installed a custom kernel or do not have a
/sys directory, you do not have to change
anything. If you do need to recompile your kernel, please refer
to the kernel configuration
section for more information.You can check how many tunnel devices your current kernel
has by typing the following:&prompt.root; ifconfig -a
tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
inet 200.10.100.1 --> 203.10.100.24 netmask 0xffffffff
tun1: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mtu 576
tun2: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
inet 203.10.100.1 --> 203.10.100.20 netmask 0xffffffff
tun3: flags=8010<POINTOPOINT,MULTICAST> mtu 1500In FreeBSD 4.0 and later releases, you will only see any
tun devices which have already been
used. This means you might not see anytun devices. If this is the case, do
not worry; the device should be created dynamically when
ppp attempts to use it.This case shows four tunnel devices, two of which are
currently configured and being used. It should be noted that
the RUNNING flag above indicates that the
interface has been used at some point—it is not an error
if your interface does not show up as
RUNNING.If for some reason you have a kernel that does not have the
tun device in it and cannot recompile
the kernel, all is not lost. You should be able to dynamically
load the code. Please refer to the appropriate
&man.modload.8; and &man.lkm.4; man pages for further
details.Check the tun deviceUnder normal circumstances, most users will only require one
tun device
(/dev/tun0). If you have specified more
than one on the pseudo-device line for
tun in your kernel configuration file,
then alter all references to tun0 below
to reflect whichever device number you are using (e.g.,
tun2).The easiest way to make sure that the
tun0 device is configured correctly,
is to remake the device. This process is quite easy. To remake
the device, do the following:&prompt.root; cd /dev
&prompt.root; ./MAKEDEV tun0If you need 16 tunnel devices in your kernel, you will need
to create them. This can be done by executing the following
commands:&prompt.root; cd /dev
&prompt.root; ./MAKEDEV tun15To confirm that the kernel is configured correctly, issue
the follow command and compare the results:&prompt.root; ifconfig tun0
tun0: flags=8050<POINTOPOINT,RUNNING,MULTICAST> mut 1500The RUNNING flag may not yet be set, in
which case you will see:&prompt.root; ifconfig tun0
tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500Remember from earlier that you might not see the device if it
has not been used yet, as tun devices are
created on demand in FreeBSD 4.0 and later releases.Name Resolution ConfigurationresolverhostnamehostsThe resolver is the part of the system that turns IP
addresses into hostnames and vice versa. It can be configured
to look for maps that describe IP to hostname mappings in one of
two places. The first is a file called
/etc/hosts. Read &man.hosts.5; for more
information. The second is the Internet Domain Name Service
(DNS), a distributed data base, the discussion of which is
beyond the scope of this document.The resolver is a set of system calls that do the name
mappings, but you have to tell them where to find their
information. You do this by first editing the file
/etc/host.conf. Do not
call this file /etc/hosts.conf (note the
extra s) as the results can be
confusing.Edit /etc/host.confThis file should contain the following two lines (in this
order):hosts
bindThese instruct the resolver to first look in the file
/etc/hosts, and then to consult the DNS
if the name was not found.Edit /etc/hostsThis file should contain the IP addresses and names of
machines on your network. At a bare minimum it should contain
entries for the machine which will be running ppp. Assuming
that your machine is called foo.bar.com with the IP address 10.0.0.1,
/etc/hosts should contain:127.0.0.1 localhost.bar.com localhost
127.0.0.1 localhost.bar.com.
10.0.0.1 foo.bar.com foo
10.0.0.1 foo.bar.com.The first two lines define the alias
localhost as a synonym for the current
machine. Regardless of your own IP address, the IP address
for this line should always be 127.0.0.1. The second two lines map
the name foo.bar.com (and the
shorthand foo) to the IP address 10.0.0.1.If your provider allocates you a static IP address and
name, use them in place of the 10.0.0.1 entry.Edit /etc/resolv.confThe /etc/resolv.conf file tells the
resolver how to behave. If you are running your own DNS, you
may leave this file empty. Normally, you will need to enter
the following line(s):domain bar.com
nameserver x.x.x.x
nameserver y.y.y.yThe x.x.x.x and
y.y.y.y
addresses are those given to you by your ISP. Add as many
nameserver lines as your ISP provides. The
domain line defaults to your hostname's
domain, and is probably unnecessary. Refer to the
&man.resolv.conf.5; manual page for details of other possible
entries in this file.PPPISPIf you are running PPP version 2 or greater, the
enable dns command will tell PPP to request
that your ISP confirms the nameserver values. If your ISP
supplies different addresses (or if there are no nameserver
lines in /etc/resolv.conf), PPP will
rewrite the file with the ISP-supplied values.PPP ConfigurationPPPconfigurationBoth ppp and pppd
(the kernel level implementation of PPP) use the configuration
files located in the /usr/share/examples/ppp directory.
The sample configuration files provided are a good reference,
so do not delete them.Configuring ppp requires that you edit a
number of files, depending on your requirements. What you put
in them depends to some extent on whether your ISP allocates IP
addresses statically (i.e., you get given one IP address, and
always use that one) or dynamically (i.e., your IP address
changes each time you connect to your ISP).PPP and Static IP AddressesPPPwith static IP addressesYou will need to create a configuration file called
/etc/ppp/ppp.conf. It should look
similar to the example below.Lines that end in a : start in the
first column, all other lines should be indented as shown
using spaces or tabs.1 default:
2 set device /dev/cuaa0
3 set speed 115200
4 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0 OK-AT-OK \\dATDT\\TTIMEOUT 40 CONNECT"
5 provider:
6 set phone "(123) 456 7890"
7 set login "TIMEOUT 10 \"\" \"\" gin:--gin: foo word: bar col: ppp"
8 set timeout 300
9 set ifaddr x.x.x.xy.y.y.y 255.255.255.0 0.0.0.0
10 add default HISADDR
11 enable dnsDo not include the line numbers, they are just for
reference in this discussion.Line 1:Identifies the default entry. Commands in this
entry are executed automatically when ppp is run.Line 2:Identifies the device to which the modem is
connected. COM1 is
/dev/cuaa0 and
COM2 is
/dev/cuaa1.Line 3:Sets the speed you want to connect at. If 115200
does not work (it should with any reasonably new modem),
try 38400 instead.Line 4:PPPuser PPPThe dial string. User PPP uses an expect-send
syntax similar to the &man.chat.8; program. Refer to
the manual page for information on the features of this
language.Line 5:Identifies an entry for a provider called
provider.Line 6:Sets the phone number for this provider. Multiple
phone numbers may be specified using the colon
(:) or pipe character
(|)as a separator. The difference
between the two separators is described in &man.ppp.8;.
To summarize, if you want to rotate through the numbers,
use a colon. If you want to always attempt to dial the
first number first and only use the other numbers if the
first number fails, use the pipe character. Always
quote the entire set of phone numbers as shown.Line 7:The login string is of the same chat-like syntax as
the dial string. In this example, the string works for
a service whose login session looks like this:J. Random Provider
login: foo
password: bar
protocol: pppYou will need to alter this script to suit your own
needs. When you write this script for the first time,
you should enable chat logging to ensure
that the conversation is going as expected.PAPCHAPIf you are using PAP or CHAP, there will be no login
at this point, so your login string can be left blank.
See PAP and CHAP
authentication for further details.Line 8:timeoutSets the default timeout (in seconds) for the
connection. Here, the connection will be closed
automatically after 300 seconds of inactivity. If you
never want to timeout, set this value to zero.Line 9:ISPSets the interface addresses. The string
x.x.x.x should be replaced by
the IP address that your provider has allocated to you.
The string y.y.y.y should be
replaced by the IP address that your ISP indicated for
their gateway (the machine to which you connect). If
your ISP hasn't given you a gateway address, use 10.0.0.2/0. If you need to use
a guessed address, make sure that you
create an entry in
/etc/ppp/ppp.linkup as per the
instructions for PPP
and Dynamic IP addresses. If this line is
omitted, ppp cannot run in
or
mode.Line 10:Adds a default route to your ISP's gateway. The
special word HISADDR is replaced with
the gateway address specified on line 9. It is
important that this line appears after line 9,
otherwise HISADDR will not yet be
initialized.Line 11:nameserverThis line tells PPP to ask your ISP to confirm that
your nameserver addresses are correct. If your ISP
supports this facility, PPP can then update
/etc/resolv.conf with the correct
nameserver entries.It is not necessary to add an entry to
ppp.linkup when you have a static IP
address as your routing table entries are already correct
before you connect. You may however wish to create an entry
to invoke programs after connection. This is explained later
with the sendmail example.Example configuration files can be found in the
/usr/share/examples/ppp directory.PPP and Dynamic IP AddressesPPPwith dynamic IP addressesIPCPIf your service provider does not assign static IP
addresses, ppp can be configured to
negotiate the local and remote addresses. This is done by
guessing an IP address and allowing
ppp to set it up correctly using the IP
Configuration Protocol (IPCP) after connecting. The
ppp.conf configuration is the same as
PPP and Static IP
Addresses, with the following change:9 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0Again, do not include the line numbers, they are just for
reference. Indentation of at least one space is
required.Line 9:The number after the / character
is the number of bits of the address that ppp will
insist on. You may wish to use IP numbers more
appropriate to your circumstances, but the above example
will always work.The last argument (0.0.0.0) tells
PPP to negotiate using address 0.0.0.0 rather than 10.0.0.1. Do not use
0.0.0.0 as the first argument to
set ifaddr as it prevents PPP from
setting up an initial route in
mode.If you are running version 1.x of PPP, you will also need
to create an entry in /etc/ppp/ppp.linkup.
ppp.linkup is used after a connection has
been established. At this point, ppp will
know what IP addresses should really be
used. The following entry will delete the existing bogus
routes, and create correct ones:1 provider:
2 delete ALL
3 add 0 0 HISADDRLine 1:On establishing a connection, ppp
will look for an entry in ppp.linkup
according to the following rules: First, try to match
the same label as we used in
ppp.conf. If that fails, look for
an entry for the IP address of our gateway. This entry
is a four-octet IP style label. If we still have not
found an entry, look for the MYADDR
entry.Line 2:This line tells ppp to delete all
of the existing routes for the acquired
tun interface (except the
direct route entry).Line 3:This line tells ppp to add a
default route that points to HISADDR.
HISADDR will be replaced with the IP
number of the gateway as negotiated in the IPCP.See the pmdemand entry in the files
/usr/share/examples/ppp/ppp.conf.sample and
/usr/share/examples/ppp/ppp.linkup.sample for a
detailed example.Version 2 of PPP introduces sticky routes.
Any add or delete lines
that contain MYADDR or
HISADDR will be remembered, and any time
the actual values of MYADDR or
HISADDR change, the routes will be
reapplied. This removes the necessity of repeating these
lines in ppp.linkup.Receiving Incoming CallsPPPreceiving
incoming callsWhen you configure ppp to
receive incoming calls on a machine connected to a LAN, you
must decide if you wish to forward packets to the LAN. If you
do, you should allocate the peer an IP number from your LAN's
subnet, and use the command enable proxy in
your /etc/ppp/ppp.conf file. You should
also confirm that the /etc/rc.conf file
contains the following:gateway="YES"Which getty?Configuring FreeBSD for Dial-up
Services provides a good description on enabling
dial-up services using &man.getty.8;.An alternative to getty is mgetty,
a smarter version of getty designed with
dial-up lines in mind.The advantages of using mgetty is
that it actively talks to modems,
meaning if port is turned off in
/etc/ttys then your modem will not answer
the phone.Later versions of mgetty (from
0.99beta onwards) also support the automatic detection of
PPP streams, allowing your clients script-less access to
your server.Refer to Mgetty and
AutoPPP for more information on
mgetty.PPP PermissionsThe ppp command must normally be run
as user id 0. If however, you wish to allow
ppp to run in server mode as a normal
user by executing ppp as described below,
that user must be given permission to run
ppp by adding them to the
network group in
/etc/group.You will also need to give them access to one or more
sections of the configuration file using the
allow command:allow users fred maryIf this command is used in the default
section, it gives the specified users access to
everything.PPP Shells for Dynamic-IP UsersPPP shellsCreate a file called
/etc/ppp/ppp-shell containing the
following:#!/bin/sh
IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'`
CALLEDAS="$IDENT"
TTY=`tty`
if [ x$IDENT = xdialup ]; then
IDENT=`basename $TTY`
fi
echo "PPP for $CALLEDAS on $TTY"
echo "Starting PPP for $IDENT"
exec /usr/sbin/ppp -direct $IDENTThis script should be executable. Now make a symbolic
link called ppp-dialup to this script
using the following commands:&prompt.root; ln -s ppp-shell /etc/ppp/ppp-dialupYou should use this script as the
shell for all of your dialup users.
This is an example from /etc/password
for a dialup PPP user with username
pchilds (remember don't directly edit
the password file, use vipw).pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialupCreate a /home/ppp directory that
is world readable containing the following 0 byte
files:-r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin
-r--r--r-- 1 root wheel 0 May 27 02:22 .rhostswhich prevents /etc/motd from being
displayed.PPP shells for Static-IP UsersPPP shellsCreate the ppp-shell file as above
and for each account with statically assigned IPs create a
symbolic link to ppp-shell.For example, if you have three dialup customers
fred, sam, and
mary, that you route class C networks
for, you would type the following:&prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred
&prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam
&prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-maryEach of these users dialup accounts should have their
shell set to the symbolic link created above (i.e.,
mary's shell should be
/etc/ppp/ppp-mary).Setting up ppp.conf for dynamic-IP usersThe /etc/ppp/ppp.conf file should
contain something along the lines of:default:
set debug phase lcp chat
set timeout 0
ttyd0:
set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255
enable proxy
ttyd1:
set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255
enable proxyThe indenting is important.The default: section is loaded for
each session. For each dialup line enabled in
/etc/ttys create an entry similar to
the one for ttyd0: above. Each line
should get a unique IP address from your pool of IP
addresses for dynamic users.Setting up ppp.conf for static-IP
usersAlong with the contents of the sample
/usr/share/examples/ppp/ppp.conf above you should add
a section for each of the statically assigned dialup users.
We will continue with our fred,
sam, and mary
example.fred:
set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255
sam:
set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255
mary:
set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255The file /etc/ppp/ppp.linkup should
also contain routing information for each static IP user if
required. The line below would add a route for the 203.14.101.0 class C via the
client's ppp link.fred:
add 203.14.101.0 netmask 255.255.255.0 HISADDR
sam:
add 203.14.102.0 netmask 255.255.255.0 HISADDR
mary:
add 203.14.103.0 netmask 255.255.255.0 HISADDRMore on mgetty, AutoPPP, and MS
extensionsmgetty and AutoPPPmgettyAutoPPPLCPConfiguring and compiling mgetty with
the AUTO_PPP option enabled allows
mgetty to detect the LCP phase of PPP
connections and automatically spawn off a ppp shell.
However, since the default login/password sequence does not
occur it is necessary to authenticate users using either PAP
or CHAP.This section assumes the user has successfully
configured, compiled, and installed a version of
mgetty with the
AUTO_PPP option (v0.99beta or
later).Make sure your
/usr/local/etc/mgetty+sendfax/login.config
file has the following in it:/AutoPPP/ - - /etc/ppp/ppp-pap-dialupThis will tell mgetty to run the
ppp-pap-dialup script for detected PPP
connections.Create a file called
/etc/ppp/ppp-pap-dialup containing the
following (the file should be executable):#!/bin/sh
exec /usr/sbin/ppp -direct pap$IDENTFor each dialup line enabled in
/etc/ttys, create a corresponding entry
in /etc/ppp/ppp.conf. This will
happily co-exist with the definitions we created
above.pap:
enable pap
set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40
enable proxyEach user logging in with this method will need to have
a username/password in
/etc/ppp/ppp.secret file, or
alternatively add the following option to authenticate users
via PAP from /etc/password file.enable passwdauthIf you wish to assign some users a static IP number, you
can specify the number as the third argument in
/etc/ppp/ppp.secret. See
/usr/share/examples/ppp/ppp.secret.sample for
examples.MS extensionsDNSNetBIOSPPPMicrosoft extensionsIt is possible to configure PPP to supply DNS and
NetBIOS nameserver addresses on demand.To enable these extensions with PPP version 1.x, the
following lines might be added to the relevant section of
/etc/ppp/ppp.conf.enable msext
set ns 203.14.100.1 203.14.100.2
set nbns 203.14.100.5And for PPP version 2 and above:accept dns
set dns 203.14.100.1 203.14.100.2
set nbns 203.14.100.5This will tell the clients the primary and secondary
name server addresses, and a netbios nameserver host.In version 2 and above, if the
set dns line is omitted, PPP will use the
values found in /etc/resolv.conf.PAP and CHAP authenticationPAPCHAPSome ISPs set their system up so that the authentication
part of your connection is done using either of the PAP or
CHAP authentication mechanisms. If this is the case, your ISP
will not give a login: prompt when you
connect, but will start talking PPP immediately.PAP is less secure than CHAP, but security is not normally
an issue here as passwords, although being sent as plain text
with PAP, are being transmitted down a serial line only.
There's not much room for crackers to
eavesdrop.Referring back to the PPP
and Static IP addresses or PPP and Dynamic IP addresses
sections, the following alterations must be made:7 set login
…
12 set authname MyUserName
13 set authkey MyPasswordAs always, do not include the line numbers, they are just
for reference in this discussion. Indentation of at least one
space is required.Line 7:Your ISP will not normally require that you log into
the server if you're using PAP or CHAP. You must
therefore disable your set login
string.Line 12:This line specifies your PAP/CHAP user name. You
will need to insert the correct value for
MyUserName.Line 13:passwordThis line specifies your PAP/CHAP password. You
will need to insert the correct value for
MyPassword. You may want to
add an additional line, such as:15 accept PAPor15 accept CHAPto make it obvious that this is the intention, but
PAP and CHAP are both accepted by default.Changing your ppp configuration on the
flyIt is possible to talk to the ppp
program while it is running in the background, but only if a
suitable diagnostic port has been set up. To do this, add the
following line to your configuration:set server /var/run/ppp-tun%d DiagnosticPassword 0177This will tell PPP to listen to the specified unix-domain
socket, asking clients for the specified password before
allowing access. The %d in the name is
replaced with the tun device number
that is in use.Once a socket has been set up, the &man.pppctl.8; program
may be used in scripts that wish to manipulate the running
program.Final system configurationPPPconfigurationYou now have ppp configured, but there
are a few more things to do before it is ready to work. They
all involve editing the /etc/rc.conf
file.Working from the top down in this file, make sure the
hostname= line is set, e.g.:hostname="foo.bar.com"If your ISP has supplied you with a static IP address and
name, it's probably best that you use this name as your host
name.Look for the network_interfaces variable.
If you want to configure your system to dial your ISP on demand,
make sure the tun0 device is added to
the list, otherwise remove it.network_interfaces="lo0 tun0" ifconfig_tun0=The ifconfig_tun0 variable should be
empty, and a file called
/etc/start_if.tun0 should be created.
This file should contain the line:ppp -auto mysystemThis script is executed at network configuration time,
starting your ppp daemon in automatic mode. If you have a LAN
for which this machine is a gateway, you may also wish to use
the switch. Refer to the manual page
for further details.Set the router program to NO with
following line in your
/etc/rc.conf:router_enable="NO"routedIt is important that the routed daemon is
not started (it is started by default), as it
routed tends to delete the default routing
table entries created by ppp.It is probably worth your while ensuring that the
sendmail_flags line does not include the
option, otherwise
sendmail will attempt to do a network lookup
every now and then, possibly causing your machine to dial out.
You may try:sendmail_flags="-bd"sendmailThe downside of this is that you must force
sendmail to re-examine the mail queue
whenever the ppp link is up by typing:&prompt.root; /usr/sbin/sendmail -qYou may wish to use the !bg command in
ppp.linkup to do this automatically:1 provider:
2 delete ALL
3 add 0 0 HISADDR
4 !bg sendmail -bd -q30mSMTPIf you don't like this, it is possible to set up a
dfilter to block SMTP traffic. Refer to the
sample files for further details.Now the only thing left to do is reboot the machine.All that is left is to reboot the machine. After rebooting,
you can now either type:&prompt.root; pppand then dial provider to start the PPP
session, or, if you want ppp to establish
sessions automatically when there is outbound traffic (and
you have not created the start_if.tun0
script), type:&prompt.root; ppp -auto providerSummaryTo recap, the following steps are necessary when setting up
ppp for the first time:Client side:Ensure that the tun device is
built into your kernel.Ensure that the
tunX device
file is available in the /dev
directory.Create an entry in
/etc/ppp/ppp.conf. The
pmdemand example should suffice for
most ISPs.If you have a dynamic IP address, create an entry in
/etc/ppp/ppp.linkup.Update your /etc/rc.conf
file.Create a start_if.tun0 script if
you require demand dialing.Server side:Ensure that the tun device is
built into your kernel.Ensure that the
tunX device
file is available in the /dev
directory.Create an entry in /etc/passwd
(using the &man.vipw.8; program).Create a profile in this users home directory that runs
ppp -direct direct-server or
similar.Create an entry in
/etc/ppp/ppp.conf. The
direct-server example should
suffice.Create an entry in
/etc/ppp/ppp.linkup.Update your /etc/rc.conf
file.
- Using Kernel PPP
+
+
+
+ Gennady B.
+ Sorokopud
+ Parts originally contributed by
+
+
+ Robert
+ Huff
+
+
+
- Parts originally contributed by &a.gena; and
- &a.rhuff;.
+ Using Kernel PPPSetting up Kernel PPPPPPkernel PPPBefore you start setting up PPP on your machine make sure
that pppd is located in
/usr/sbin and the directory
/etc/ppp exists.pppd can work in two modes:As a client, i.e., you want to connect your
machine to the outside world via a PPP serial connection or
modem line.PPPserveras a server, i.e. your machine is located on
the network and used to connect other computers using
PPP.In both cases you will need to set up an options file
(/etc/ppp/options or
~/.ppprc if you have more than one user on
your machine that uses PPP).You also will need some modem/serial software (preferably
kermit) so you can dial and establish a connection with the
remote host.Using pppd as a clientPPPclientCiscoThe following /etc/ppp/options might be
used to connect to a CISCO terminal server PPP line.crtscts # enable hardware flow control
modem # modem control line
noipdefault # remote PPP server must supply your IP address.
# if the remote host doesn't send your IP during IPCP
# negotiation , remove this option
passive # wait for LCP packets
domain ppp.foo.com # put your domain name here
:<remote_ip> # put the IP of remote PPP host here
# it will be used to route packets via PPP link
# if you didn't specified the noipdefault option
# change this line to <local_ip>:<remote_ip>
defaultroute # put this if you want that PPP server will be your
# default routerTo connect:kermitmodemDial to the remote host using kermit (or some other modem
program), and enter your user name and password (or whatever
is needed to enable PPP on the remote host).Exit kermit (without hanging up the line).Enter the following:&prompt.root; /usr/src/usr.sbin/pppd.new/pppd /dev/tty0119200Be sure to use the appropriate speed and device name.Now your computer is connected with PPP. If the connection
fails, you can add the option to the
/etc/ppp/options file and check messages on
the console to track the problem.Following /etc/ppp/pppup script will make
all 3 stages automatically:#!/bin/sh
ps ax |grep pppd |grep -v grep
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing kermit, PID=' ${pid}
kill -9 ${pid}
fi
ifconfig ppp0 down
ifconfig ppp0 delete
kermit -y /etc/ppp/kermit.dial
pppd /dev/tty01 19200kermit/etc/ppp/kermit.dial is a kermit script
that dials and makes all necessary authorization on the remote
host (an example of such a script is attached to the end of this
document).Use the following /etc/ppp/pppdown script
to disconnect the PPP line:#!/bin/sh
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ X${pid} != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill -TERM ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing kermit, PID=' ${pid}
kill -9 ${pid}
fi
/sbin/ifconfig ppp0 down
/sbin/ifconfig ppp0 delete
kermit -y /etc/ppp/kermit.hup
/etc/ppp/ppptestCheck to see if PPP is still running by executing
/usr/etc/ppp/ppptest, which should look like
this:#!/bin/sh
pid=`ps ax| grep pppd |grep -v grep|awk '{print $1;}'`
if [ X${pid} != "X" ] ; then
echo 'pppd running: PID=' ${pid-NONE}
else
echo 'No pppd running.'
fi
set -x
netstat -n -I ppp0
ifconfig ppp0To hang up the modem, execute
/etc/ppp/kermit.hup, which should
contain:set line /dev/tty01 ; put your modem device here
set speed 19200
set file type binary
set file names literal
set win 8
set rec pack 1024
set send pack 1024
set block 3
set term bytesize 8
set command bytesize 8
set flow none
pau 1
out +++
inp 5 OK
out ATH0\13
echo \13
exitHere is an alternate method using chat
instead of kermit.The following two files are sufficient to accomplish a
pppd connection./etc/ppp/options:/dev/cuaa1 115200
crtscts # enable hardware flow control
modem # modem control line
connect "/usr/bin/chat -f /etc/ppp/login.chat.script"
noipdefault # remote PPP serve must supply your IP address.
# if the remote host doesn't send your IP during
# IPCP negotiation, remove this option
passive # wait for LCP packets
domain <your.domain> # put your domain name here
: # put the IP of remote PPP host here
# it will be used to route packets via PPP link
# if you didn't specified the noipdefault option
# change this line to <local_ip>:<remote_ip>
defaultroute # put this if you want that PPP server will be
# your default router/etc/ppp/login.chat.script:The following should go on a single line.ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<phone.number>
CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <login-id>
TIMEOUT 5 sword: <password>Once these are installed and modified correctly, all you need
to do is run pppd, like so:&prompt.root; pppdThis sample is based primarily on information provided by:
Trev Roydhouse <Trev.Roydhouse@f401.n711.z3.fidonet.org>
and used with permission.Using pppd as a server/etc/ppp/options should contain something
similar to the following:crtscts # Hardware flow control
netmask 255.255.255.0 # netmask ( not required )
192.114.208.20:192.114.208.165 # ip's of local and remote hosts
# local ip must be different from one
# you assigned to the ethernet ( or other )
# interface on your machine.
# remote IP is ip address that will be
# assigned to the remote machine
domain ppp.foo.com # your domain
passive # wait for LCP
modem # modem lineThe following /etc/ppp/pppserv script
will enable tell pppd to behave as a
server:#!/bin/sh
ps ax |grep pppd |grep -v grep
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing kermit, PID=' ${pid}
kill -9 ${pid}
fi
# reset ppp interface
ifconfig ppp0 down
ifconfig ppp0 delete
# enable autoanswer mode
kermit -y /etc/ppp/kermit.ans
# run ppp
pppd /dev/tty01 19200Use this /etc/ppp/pppservdown script to
stop the server:#!/bin/sh
ps ax |grep pppd |grep -v grep
pid=`ps ax |grep pppd |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing pppd, PID=' ${pid}
kill ${pid}
fi
ps ax |grep kermit |grep -v grep
pid=`ps ax |grep kermit |grep -v grep|awk '{print $1;}'`
if [ "X${pid}" != "X" ] ; then
echo 'killing kermit, PID=' ${pid}
kill -9 ${pid}
fi
ifconfig ppp0 down
ifconfig ppp0 delete
kermit -y /etc/ppp/kermit.noansThe following kermit script
(/etc/ppp/kermit.ans) will enable/disable
autoanswer mode on your modem. It should look like this:set line /dev/tty01
set speed 19200
set file type binary
set file names literal
set win 8
set rec pack 1024
set send pack 1024
set block 3
set term bytesize 8
set command bytesize 8
set flow none
pau 1
out +++
inp 5 OK
out ATH0\13
inp 5 OK
echo \13
out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable
; autoanswer mod
inp 5 OK
echo \13
exitA script named /etc/ppp/kermit.dial is
used for dialing and authenticating on the remote host. You will
need to customize it for your needs. Put your login and password
in this script; you will also need to change the input statement
depending on responses from your modem and remote host.;
; put the com line attached to the modem here:
;
set line /dev/tty01
;
; put the modem speed here:
;
set speed 19200
set file type binary ; full 8 bit file xfer
set file names literal
set win 8
set rec pack 1024
set send pack 1024
set block 3
set term bytesize 8
set command bytesize 8
set flow none
set modem hayes
set dial hangup off
set carrier auto ; Then SET CARRIER if necessary,
set dial display on ; Then SET DIAL if necessary,
set input echo on
set input timeout proceed
set input case ignore
def \%x 0 ; login prompt counter
goto slhup
:slcmd ; put the modem in command mode
echo Put the modem in command mode.
clear ; Clear unread characters from input buffer
pause 1
output +++ ; hayes escape sequence
input 1 OK\13\10 ; wait for OK
if success goto slhup
output \13
pause 1
output at\13
input 1 OK\13\10
if fail goto slcmd ; if modem doesn't answer OK, try again
:slhup ; hang up the phone
clear ; Clear unread characters from input buffer
pause 1
echo Hanging up the phone.
output ath0\13 ; hayes command for on hook
input 2 OK\13\10
if fail goto slcmd ; if no OK answer, put modem in command mode
:sldial ; dial the number
pause 1
echo Dialing.
output atdt9,550311\13\10 ; put phone number here
assign \%x 0 ; zero the time counter
:look
clear ; Clear unread characters from input buffer
increment \%x ; Count the seconds
input 1 {CONNECT }
if success goto sllogin
reinput 1 {NO CARRIER\13\10}
if success goto sldial
reinput 1 {NO DIALTONE\13\10}
if success goto slnodial
reinput 1 {\255}
if success goto slhup
reinput 1 {\127}
if success goto slhup
if < \%x 60 goto look
else goto slhup
:sllogin ; login
assign \%x 0 ; zero the time counter
pause 1
echo Looking for login prompt.
:slloop
increment \%x ; Count the seconds
clear ; Clear unread characters from input buffer
output \13
;
; put your expected login prompt here:
;
input 1 {Username: }
if success goto sluid
reinput 1 {\255}
if success goto slhup
reinput 1 {\127}
if success goto slhup
if < \%x 10 goto slloop ; try 10 times to get a login prompt
else goto slhup ; hang up and start again if 10 failures
:sluid
;
; put your userid here:
;
output ppp-login\13
input 1 {Password: }
;
; put your password here:
;
output ppp-password\13
input 1 {Entering SLIP mode.}
echo
quit
:slnodial
echo \7No dialtone. Check the telephone line!\7
exit 1
; local variables:
; mode: csh
; comment-start: "; "
; comment-start-skip: "; "
; end:
+
+
+
+ Jim
+ Mock
+ Contributed (from http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html) by
+
+
+
+
+
Using PPP over Ethernet (PPPoE)PPPover EthernetPPPoEPPP, over Ethernet
- Contributed by &a.jim; (from node.to) 10 Jan 2000.
-
The following describes how to set up PPP over Ethernet, a.k.a,
PPPoE.PrerequisitesThere are a few requirements that your system will need to meet
in order for PPPoE to function properly. They are:Kernel source for FreeBSD 3.4 or laterppp from FreeBSD 3.4 or laterKernel ConfigurationkernelconfigurationYou will need to set the following options in your kernel
configuration file and then compile a new
kernel.Optionally, you can add
although if this functionality is not available at runtime,
ppp will load the relevant modules
on demand
Setting up ppp.confHere is an example of a working
ppp.conf:default: # or name_of_service_provider
set device PPPoE:xl1 # replace xl1 with your ethernet device
set mru 1492
set mtu 1492
set authname YOURLOGINNAME
set authkey YOURPASSWORD
set log Phase tun command # you can add more detailed logging if you wish
set dial
set login
set ifaddr 10.0.0.1/0 10.0.0.2/0
add default HISADDR
nat enable yes # if you want to enable nat for your local net
papchap:
set authname YOURLOGINNAME
set authkey YOURPASSWORD
Care should be taken when running PPPoE with the
option.
Running PPPAs root, you can run:&prompt.root; ppp -ddial name_of_service_providerStarting PPP at BootAdd the following to your /etc/rc.conf
file:ppp_enable="YES"
ppp_mode="ddial"
ppp_nat="YES"
ppp_profile="default" # or your provider
- PPPoE with a 3Com HomeConnect ADSL Modem Dual Link
+
+
+
+ Mário Sérgio Fujikawa
+ Ferreira
+ Contributed by
+
+
+
+
- Contributed by &a.lioux;, 07 Apr
- 2001.
+ PPPoE with a 3Com HomeConnect ADSL Modem Dual LinkIn short, it does not work. It should, but unfortunately,
that is not the case. For whatever reason, this modem does not
follow RFC
2516 (A Method for transmitting PPP over
Ethernet (PPPoE), written by L. Mamakos, K. Lidl,
J. Evarts, D. Carrel, D. Simone, and R. Wheeler).Since it does not follow the specification, FreeBSD's PPPoE
implementation will not talk to it. It is very likely that it will
not work under other Unix systems for that same reason.
Complain to 3Com if you think it should
comply with the PPPoE specification.ADSLIf you absolutely want to use your ADSL connection with
FreeBSD and are stuck with this modem, you can either:DSLTry replacing the modem with a different brand or model
if your DSL provider permits you to do so. If you are not
sure which brand(s) will work, the &a.questions; is a good
place to ask.Try to get it working. Keep in mind that there is no
guarantee it will work, your mileage may vary.If you want to try to make it work, you can do the
following, but please keep in mind that you do this at
your own risk! Just because it worked for me does
not mean it will work for you.There are three steps to the process. They are:Make sure you already have ppp.conf
set up. See the beginning of this chapter for more details
on doing so.Since the modem does not speak the correct protocol, we
need to learn how to speak its variant of the protocol.
This information was obtained from a DSLreports
forum message.The modem speaks 0x3c12 for
DISCOVERY, and 0x3c13
for PAYLOAD identifiers instead of
0x8863 and 0x8864
respectively, as mandated by the PPPoE specification.CodeRFC's CodeDual Link Modem's CodePAYLOAD0x88630x3c12PAYLOAD0x88640x3c13So, now what? You need to recompile the
NETGRAPH_PPPOE code with the modem's
codes. For this, you should have installed the full kernel
sources.Find the
/usr/src/sys/netgraph/ng_pppoe.h file.
Be careful while editing this file. You have to modify both
the little and the big endian entries.For big endian, find the line with
0x8863 in it, and replace the number
with 0x3c12. Do the same with
0x8864, replacing it with
0x3c13.For little endian, find the line with
0x6388in it, and replace the number
with 0x123c. Do the same with
0x6488, replacing it with
0x133c.Here is a diff of how the new file
should look:&prompt.user; diff -u ng_pppoe.h.orig ng_pppoe.h
--- ng_pppoe.h.orig Thu Apr 12 13:42:46 2001
+++ ng_pppoe.h Thu Apr 12 13:44:47 2001
@@ -148,8 +148,8 @@
#define PTT_SYS_ERR (0x0202)
#define PTT_GEN_ERR (0x0203)
-#define ETHERTYPE_PPPOE_DISC 0x8863 /* pppoe discovery packets */
-#define ETHERTYPE_PPPOE_SESS 0x8864 /* pppoe session packets */
+#define ETHERTYPE_PPPOE_DISC 0x3c12 /* pppoe discovery packets */
+#define ETHERTYPE_PPPOE_SESS 0x3c13 /* pppoe session packets */
#else
#define PTT_EOL (0x0000)
#define PTT_SRV_NAME (0x0101)
@@ -162,8 +162,8 @@
#define PTT_SYS_ERR (0x0202)
#define PTT_GEN_ERR (0x0302)
-#define ETHERTYPE_PPPOE_DISC 0x6388 /* pppoe discovery packets */
-#define ETHERTYPE_PPPOE_SESS 0x6488 /* pppoe session packets */
+#define ETHERTYPE_PPPOE_DISC 0x123c /* pppoe discovery packets */
+#define ETHERTYPE_PPPOE_SESS 0x133c /* pppoe session packets */
#endif
struct pppoe_tag {Then do the following as
root:&prompt.root; cd /usr/src/sys/modules/netgraph/pppoe
&prompt.root; make clean depend all install
&prompt.root; make cleanNow you can speak the modem's variant of the PPPoE
specification.The third step is to figure out the name of the profile
your ISP assigned to the modem. The information for this
step was obtained from the Roaring Penguin
PPPoE program which can be found in the ports collection. If you still are
not able to find it, ask your ISP's tech support.If they do not know it either, and you are feeling bold
(this may de-program your modem and render it useless, so
think twice about doing it).Install the program shipped with the modem by your
provider. Then, access the System menu
from the program. The name of your profile should be
listed there. It is usually ISP.The profile name will be used in the PPPoE configuration
inside ppp.conf as the provider
parameter. See the &man.ppp.8; manual page for more
information.The PPPoE line in your ppp.conf
should look like this:set device PPPoE:xl1:ISPDo not forget to change xl1
to the proper device for your Ethernet card.Do not forget to change ISP
to the profile you have just found above.For additional information, you can try:Cheaper
Broadband with FreeBSD on DSL by Renaud
Waldura in Daemon
News.Another PPPoE tutorial by Sympatico
Users Group.
+
+
+
+ Satoshi
+ Asami
+ Originally contributed by
+
+
+
+
+ Guy
+ Helmer
+ With input from
+
+
+ Piero
+ Serini
+
+
+
+
Using SLIPSLIP
- Originally contributed by &a.asami; and
- &a.ghelmer;, with input from &a.wilko; and
- &a.piero;.Setting up a SLIP ClientSLIPclientThe following is one way to set up a FreeBSD machine for SLIP
on a static host network. For dynamic hostname assignments (i.e.,
your address changes each time you dial up), you probably need to
do something much fancier.First, determine which serial port your modem is connected to.
I have a symbolic link to /dev/modem from
/dev/cuaa1, and only use the modem name in
my configuration files. It can become quite cumbersome when you
need to fix a bunch of files in /etc and
.kermrc's all over the system!/dev/cuaa0 is
COM1, cuaa1 is
COM2, etc.Make sure you have the following in your kernel configuration
file:pseudo-device sl 1It is included in the GENERIC kernel, so
this should not be a problem unless you have deleted it.Things you have to do only onceAdd your home machine, the gateway and nameservers to
your /etc/hosts file. Mine looks like
this:127.0.0.1 localhost loghost
136.152.64.181 silvia.HIP.Berkeley.EDU silvia.HIP silvia
136.152.64.1 inr-3.Berkeley.EDU inr-3 slip-gateway
128.32.136.9 ns1.Berkeley.edu ns1
128.32.136.12 ns2.Berkeley.edu ns2Make sure you have before
in your
/etc/host.conf. Otherwise, funny
things may happen.Edit the /etc/rc.conf file.Set your hostname by editing the line that
says:hostname=myname.my.domainYou should give it your full Internet
hostname.Add sl0 to the list of network interfaces by
changing the line that says:network_interfaces="lo0"to:network_interfaces=lo0 sl0Set the startup flags of sl0 by adding a
line:ifconfig_sl0="inet ${hostname} slip-gateway netmask 0xffffff00 up"default routeDesignate the default router by changing the
line:defaultrouter=NOto:defaultrouter=slip-gatewayMake a file /etc/resolv.conf which
contains:domain HIP.Berkeley.EDU
nameserver 128.32.136.9
nameserver 128.32.136.12nameserverdomain nameAs you can see, these set up the nameserver hosts. Of
course, the actual domain names and addresses depend on your
environment.Set the password for root and
toor (and any other
accounts that do not have a password). Use passwd or
&man.vipw.8;, do not edit the
/etc/passwd or
/etc/master.passwd files!Reboot your machine and make sure it comes up with the
correct hostname.Making a SLIP connectionSLIPconnecting withDial up, type slip at the prompt,
enter your machine name and password. The things you need
to enter depends on your environment. If you use kermit, you
can try a script like this:# kermit setup
set modem hayes
set line /dev/modem
set speed 115200
set parity none
set flow rts/cts
set terminal bytesize 8
set file type binary
# The next macro will dial up and login
define slip dial 643-9600, input 10 =>, if failure stop, -
output slip\x0d, input 10 Username:, if failure stop, -
output silvia\x0d, input 10 Password:, if failure stop, -
output ***\x0d, echo \x0aCONNECTED\x0aOf course, you have to change the hostname and password
to fit yours. After doing so, you can just type
slip from the kermit prompt to get
connected.Leaving your password in plain text anywhere in the
filesystem is generally a BAD idea. Do it at your own
risk.Leave the kermit there (you can suspend it by
z) and as root, type:&prompt.root; slattach -h -c -s 115200 /dev/modemIf you are able to ping hosts on the
other side of the router, you are connected! If it does not
work, you might want to try instead of
as an argument to
slattach.How to shutdown the connectionDo the following:&prompt.root; kill -INT `cat /var/run/slattach.modem.pid`to kill slattach. Keep in mind you must be
root to do the above. Then go back to
kermit (fg if you suspended it) and exit from
it (q).The slattach man page says you have
to use ifconfig sl0 down
to mark the interface down, but this does not
seem to make any difference for me.
(ifconfig sl0 reports the same thing.)Some times, your modem might refuse to drop the carrier
(mine often does). In that case, simply start kermit and quit
it again. It usually goes out on the second try.TroubleshootingIf it does not work, feel free to ask me. The things that
people tripped over so far:Not using or in
slattach (I have no idea why this
can be fatal, but adding
this flag solved the problem for at least one
person).Using instead of
(might be hard to see the difference on
some fonts).Try ifconfig sl0 to see your
interface status. For example, you might get:&prompt.root; ifconfig sl0
sl0: flags=10<POINTOPOINT>
inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00Also, netstat -r will give the
routing table, in case you get the no route to
host messages from ping. Mine looks like:&prompt.root; netstat -r
Routing tables
Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks:
(root node)
(root node)
Route Tree for Protocol Family inet:
(root node) =>
default inr-3.Berkeley.EDU UG 8 224515 sl0 - -
localhost.Berkel localhost.Berkeley UH 5 42127 lo0 - 0.438
inr-3.Berkeley.E silvia.HIP.Berkele UH 1 0 sl0 - -
silvia.HIP.Berke localhost.Berkeley UGH 34 47641234 lo0 - 0.438
(root node)This is after transferring a bunch of files, your
numbers should be smaller).Setting up a SLIP ServerSLIPserverThis document provides suggestions for setting up SLIP Server
services on a FreeBSD system, which typically means configuring
your system to automatically startup connections upon login for
remote SLIP clients. The author has written this document based
on his experience; however, as your system and needs may be
different, this document may not answer all of your questions, and
the author cannot be responsible if you damage your system or lose
data due to attempting to follow the suggestions here.PrerequisitesTCP/IP networkingThis document is very technical in nature, so background
knowledge is required. It is assumed that you are familiar with
the TCP/IP network protocol, and in particular, network and node
addressing, network address masks, subnetting, routing, and
routing protocols, such as RIP. Configuring SLIP services on a
dial-up server requires a knowledge of these concepts, and if
you are not familiar with them, please read a copy of either
Craig Hunt's TCP/IP Network Administration
published by O'Reilly & Associates, Inc. (ISBN Number
0-937175-82-X), or Douglas Comer's books on the TCP/IP
protocol.modemIt is further assumed that you have already setup your
modem(s) and configured the appropriate system files to allow
logins through your modems. If you have not prepared your
system for this yet, please see the tutorial for configuring
dialup services; if you have a World-Wide Web browser available,
browse the list of tutorials at http://www.FreeBSD.org/.
You may also want to check the manual pages for &man.sio.4; for
information on the serial port device driver and &man.ttys.5;,
&man.gettytab.5;, &man.getty.8;, & &man.init.8; for
information relevant to configuring the system to accept logins
on modems, and perhaps &man.stty.1; for information on setting
serial port parameters (such as clocal for
directly-connected serial interfaces).Quick OverviewIn its typical configuration, using FreeBSD as a SLIP server
works as follows: a SLIP user dials up your FreeBSD SLIP Server
system and logs in with a special SLIP login ID that uses
/usr/sbin/sliplogin as the special user's
shell. The sliplogin program browses the
file /etc/sliphome/slip.hosts to find a
matching line for the special user, and if it finds a match,
connects the serial line to an available SLIP interface and then
runs the shell script
/etc/sliphome/slip.login to configure the
SLIP interface.An Example of a SLIP Server LoginFor example, if a SLIP user ID were
Shelmerg, Shelmerg's
entry in /etc/master.passwd would look
something like this (except it would be all on one
line):Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliploginWhen Shelmerg logs in,
sliplogin will search
/etc/sliphome/slip.hosts for a line that
had a matching user ID; for example, there may be a line in
/etc/sliphome/slip.hosts that
reads:Shelmerg dc-slip sl-helmer 0xfffffc00 autocompsliplogin will find that matching line,
hook the serial line into the next available SLIP interface,
and then execute /etc/sliphome/slip.login
like this:/etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocompIf all goes well,
/etc/sliphome/slip.login will issue an
ifconfig for the SLIP interface to which
sliplogin attached itself (slip interface
0,in the above example, which was the first parameter in the
list given to slip.login) to set the
local IP address (dc-slip), remote IP address
(sl-helmer), network mask for the SLIP
interface (0xfffffc00), and
any additional flags (autocomp). If
something goes wrong, sliplogin usually
logs good informational messages via the
daemon syslog facility, which usually goes
into /var/log/messages (see the manual
pages for &man.syslogd.8; and &man.syslog.conf.5; and perhaps
check /etc/syslog.conf to see to which
files syslogd is logging).OK, enough of the examples — let us dive into
setting up the system.Kernel ConfigurationkernelconfigurationFreeBSD's default kernels usually come with two SLIP
interfaces defined (sl0 and
sl1); you can use netstat
-i to see whether these interfaces are defined in your
kernel.Sample output from netstat -i:Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll
ed0 1500 <Link>0.0.c0.2c.5f.4a 291311 0 174209 0 133
ed0 1500 138.247.224 ivory 291311 0 174209 0 133
lo0 65535 <Link> 79 0 79 0 0
lo0 65535 loop localhost 79 0 79 0 0
sl0* 296 <Link> 0 0 0 0 0
sl1* 296 <Link> 0 0 0 0 0The sl0 and
sl1 interfaces shown in
netstat -i's output indicate that there are
two SLIP interfaces built into the kernel. (The asterisks after
the sl0 and sl1 indicate
that the interfaces are down.)However, FreeBSD's default kernels do not come configured
to forward packets (ie, your FreeBSD machine will not act as a
router) due to Internet RFC requirements for Internet hosts (see
RFCs 1009 [Requirements for Internet Gateways], 1122
[Requirements for Internet Hosts — Communication Layers],
and perhaps 1127 [A Perspective on the Host Requirements RFCs]),
so if you want your FreeBSD SLIP Server to act as a router, you
will have to edit the /etc/rc.conf file and
change the setting of the gateway_enable variable to
.You will then need to reboot for the new settings to take
effect.You will notice that near the end of the default kernel
configuration file (/sys/i386/conf/GENERIC)
is a line that reads:pseudo-device sl 2SLIPThis is the line that defines the number of SLIP devices
available in the kernel; the number at the end of the line is
the maximum number of SLIP connections that may be operating
simultaneously.Please refer to Configuring the
FreeBSD Kernel for help in reconfiguring your
kernel.Sliplogin ConfigurationAs mentioned earlier, there are three files in the
/etc/sliphome directory that are part of
the configuration for /usr/sbin/sliplogin
(see &man.sliplogin.8; for the actual manual page for
sliplogin): slip.hosts,
which defines the SLIP users & their associated IP
addresses; slip.login, which usually just
configures the SLIP interface; and (optionally)
slip.logout, which undoes
slip.login's effects when the serial
connection is terminated.slip.hosts Configuration/etc/sliphome/slip.hosts contains
lines which have at least four items, separated by
whitespace:SLIP user's login IDLocal address (local to the SLIP server) of the SLIP
linkRemote address of the SLIP linkNetwork maskThe local and remote addresses may be host names (resolved
to IP addresses by /etc/hosts or by the
domain name service, depending on your specifications in
/etc/host.conf), and the
network mask may be a name that can be resolved by a lookup
into /etc/networks. On a sample system,
/etc/sliphome/slip.hosts looks like
this:#
# login local-addr remote-addr mask opt1 opt2
# (normal,compress,noicmp)
#
Shelmerg dc-slip sl-helmerg 0xfffffc00 autocompAt the end of the line is one or more of the
options. — no header
compression — compress
headers — compress headers if
the remote end allows it — disable ICMP packets
(so any ping packets will be dropped instead
of using up your bandwidth)Note that sliplogin under early releases
of FreeBSD 2 ignored the options that FreeBSD 1.x recognized,
so the options ,
, , and
had no effect until support was added
in FreeBSD 2.2 (unless your slip.login
script included code to make use of the flags).SLIPTCP/IP networkingYour choice of local and remote addresses for your SLIP
links depends on whether you are going to dedicate a TCP/IP
subnet or if you are going to use proxy ARP on
your SLIP server (it is not true proxy ARP, but
that is the terminology used in this document to describe it).
If you are not sure which method to select or how to assign IP
addresses, please refer to the TCP/IP books referenced in the
slips-prereqs section
and/or consult your IP network manager.gatedIf you are going to use a separate subnet for your SLIP
clients, you will need to allocate the subnet number out of
your assigned IP network number and assign each of your SLIP
client's IP numbers out of that subnet. Then, you will
probably either need to configure a static route to the SLIP
subnet via your SLIP server on your nearest IP router, or
install gated on your FreeBSD SLIP server
and configure it to talk the appropriate routing protocols to
your other routers to inform them about your SLIP server's
route to the SLIP subnet.EthernetOtherwise, if you will use the proxy ARP
method, you will need to assign your SLIP client's IP
addresses out of your SLIP server's Ethernet subnet, and you
will also need to adjust your
/etc/sliphome/slip.login and
/etc/sliphome/slip.logout scripts to use
&man.arp.8; to manage the proxy-ARP entries in the SLIP
server's ARP table.slip.login ConfigurationThe typical /etc/sliphome/slip.login
file looks like this:#!/bin/sh -
#
# @(#)slip.login 5.1 (Berkeley) 7/1/90
#
# generic login file for a slip line. sliplogin invokes this with
# the parameters:
# 1 2 3 4 5 6 7-n
# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 inet $4 $5 netmask $6This slip.login file merely
ifconfig's the appropriate SLIP interface
with the local and remote addresses and network mask of the
SLIP interface.If you have decided to use the proxy ARP
method (instead of using a separate subnet for your SLIP
clients), your /etc/sliphome/slip.login
file will need to look something like this:#!/bin/sh -
#
# @(#)slip.login 5.1 (Berkeley) 7/1/90
#
# generic login file for a slip line. sliplogin invokes this with
# the parameters:
# 1 2 3 4 5 6 7-n
# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 inet $4 $5 netmask $6
# Answer ARP requests for the SLIP client with our Ethernet addr
/usr/sbin/arp -s $5 00:11:22:33:44:55 pubThe additional line in this
slip.login, arp -s
$5 00:11:22:33:44:55 pub, creates an ARP entry
in the SLIP server's ARP table. This ARP entry causes the
SLIP server to respond with the SLIP server's Ethernet MAC
address whenever a another IP node on the Ethernet asks to
speak to the SLIP client's IP address.EthernetMAC addressWhen using the example above, be sure to replace the
Ethernet MAC address (00:11:22:33:44:55) with the MAC address of
your system's Ethernet card, or your proxy ARP
will definitely not work! You can discover your SLIP server's
Ethernet MAC address by looking at the results of running
netstat -i; the second line of the output
should look something like:ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116This indicates that this particular system's Ethernet MAC
address is 00:02:c1:28:5f:4a
— the periods in the Ethernet MAC address given by
netstat -i must be changed to colons and
leading zeros should be added to each single-digit hexadecimal
number to convert the address into the form that &man.arp.8;
desires; see the manual page on &man.arp.8; for complete
information on usage.When you create
/etc/sliphome/slip.login and
/etc/sliphome/slip.logout, the
execute bit (ie, chmod 755
/etc/sliphome/slip.login /etc/sliphome/slip.logout)
must be set, or sliplogin will be unable
to execute it.slip.logout Configuration/etc/sliphome/slip.logout is not
strictly needed (unless you are implementing proxy
ARP), but if you decide to create it, this is an
example of a basic
slip.logout script:#!/bin/sh -
#
# slip.logout
#
# logout file for a slip line. sliplogin invokes this with
# the parameters:
# 1 2 3 4 5 6 7-n
# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 downIf you are using proxy ARP, you will want to
have /etc/sliphome/slip.logout remove the
ARP entry for the SLIP client:#!/bin/sh -
#
# @(#)slip.logout
#
# logout file for a slip line. sliplogin invokes this with
# the parameters:
# 1 2 3 4 5 6 7-n
# slipunit ttyspeed loginname local-addr remote-addr mask opt-args
#
/sbin/ifconfig sl$1 down
# Quit answering ARP requests for the SLIP client
/usr/sbin/arp -d $5The arp -d $5 removes the ARP entry
that the proxy ARPslip.login added when the SLIP client
logged in.It bears repeating: make sure
/etc/sliphome/slip.logout has the execute
bit set for after you create it (ie, chmod 755
/etc/sliphome/slip.logout).Routing ConsiderationsSLIProutingIf you are not using the proxy ARP method for
routing packets between your SLIP clients and the rest of your
network (and perhaps the Internet), you will probably either
have to add static routes to your closest default router(s) to
route your SLIP client subnet via your SLIP server, or you will
probably need to install and configure gated
on your FreeBSD SLIP server so that it will tell your routers
via appropriate routing protocols about your SLIP subnet.Static Routesstatic routesAdding static routes to your nearest default routers can
be troublesome (or impossible, if you do not have authority to
do so...). If you have a multiple-router network in your
organization, some routers, such as Cisco and Proteon, may
not only need to be configured with the static route to the
SLIP subnet, but also need to be told which static routes to
tell other routers about, so some expertise and
troubleshooting/tweaking may be necessary to get
static-route-based routing to work.Running gatedgatedAn alternative to the headaches of static routes is to
install gated on your FreeBSD SLIP server
and configure it to use the appropriate routing protocols
(RIP/OSPF/BGP/EGP) to tell other routers about your SLIP
subnet. You can use gated from the ports collection or retrieve and build
it yourself from the
GateD anonymous FTP site; the current version
as of this writing is
gated-R3_5Alpha_8.tar.Z, which includes
support for FreeBSD out-of-the-box. Complete
information and documentation on gated is
available on the Web starting at the Merit GateD
Consortium. Compile and install it, and then write a
/etc/gated.conf file to configure your
gated; here is a sample, similar to what the author used on a
FreeBSD SLIP server:#
# gated configuration file for dc.dsu.edu; for gated version 3.5alpha5
# Only broadcast RIP information for xxx.xxx.yy out the ed Ethernet interface
#
#
# tracing options
#
traceoptions "/var/tmp/gated.output" replace size 100k files 2 general ;
rip yes {
interface sl noripout noripin ;
interface ed ripin ripout version 1 ;
traceoptions route ;
} ;
#
# Turn on a bunch of tracing info for the interface to the kernel:
kernel {
traceoptions remnants request routes info interface ;
} ;
#
# Propagate the route to xxx.xxx.yy out the Ethernet interface via RIP
#
export proto rip interface ed {
proto direct {
xxx.xxx.yy mask 255.255.252.0 metric 1; # SLIP connections
} ;
} ;
#
# Accept routes from RIP via ed Ethernet interfaces
import proto rip interface ed {
all ;
} ;RIPThe above sample gated.conf file
broadcasts routing information regarding the SLIP subnet
xxx.xxx.yy via RIP onto the
Ethernet; if you are using a different Ethernet driver than
the ed driver, you will need to
change the references to the ed
interface appropriately. This sample file also sets up
tracing to /var/tmp/gated.output for
debugging gated's activity; you can
certainly turn off the tracing options if
gated works OK for you. You will need to
change the xxx.xxx.yy's into the
network address of your own SLIP subnet (be sure to change the
net mask in the proto direct clause as
well).When you get gated built and installed
and create a configuration file for it, you will need to run
gated in place of routed
on your FreeBSD system; change the
routed/gated startup parameters in
/etc/netstart as appropriate for your
system. Please see the manual page for
gated for information on
gated's command-line parameters.
diff --git a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
index 1563e6a2b4..9ddd060d1f 100644
--- a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml
@@ -1,4752 +1,4768 @@
- Printing
+
+
+
+ Sean
+ Kelly
+ Contributed by
+
+
+
+
+
+ Jim
+ Mock
+ Restructured and updated by
+
+
+
+
- Contributed by &a.kelly;, 30 September 1995.
- Restructured and updated by &a.jim;, March 2000.
+ PrintingSynopsisLPD spooling systemprintingFreeBSD can be used to print to a wide variety of printers, from the
oldest impact printer to the latest laser printers, and everything in
between, allowing you to produce high quality printed output from the
applications you run.FreeBSD can also be configured to act as a print server on a
network; in this capacity FreeBSD can receive print jobs from a variety
of other computers, including other FreeBSD computers, Windows and MacOS
hosts. FreeBSD will ensure that one job at a time is printed, and can
keep statistics on which users and machines are doing the most printing,
produce banner pages showing who's printout is who's, and
more.After reading this chapter you will know:How to configure the FreeBSD print spoolerHow to install print filters, to handle special print jobs
differently, including converting incoming documents to print
formats that your printers understandHow to enable header, or banner pages on your printoutHow to print to printers connected to other computersHow to print to printers connected directly to the
networkHow to control printer restrictions, including limiting the size
of print jobs, and preventing certain users from printingHow to keep printer statistics, and account for printer
usageHow to troubleshoot printing problemsBefore reading this chapter you should:Know how to configure and install a new kernel
()IntroductionIn order to use printers with FreeBSD, you will need to set them
up to work with the Berkeley line printer spooling system, also
known as the LPD spooling system. It is the standard printer
control system in FreeBSD. This chapter introduces the LPD spooling
system, often simply called LPD, and will guide you through its
configuration.If you are already familiar with LPD or another printer spooling
system, you may wish to skip to section Setting up the spooling
system.LPD controls everything about a host's printers. It is
responsible for a number of things:It controls access to attached printers and printers
attached to other hosts on the network.print jobsIt enables users to submit files to be printed; these
submissions are known as jobs.It prevents multiple users from accessing a printer at the
same time by maintaining a queue for each
printer.It can print header pages (also known
as banner or burst
pages) so users can easily find jobs they have printed in a
stack of printouts.It takes care of communications parameters for printers
connected on serial ports.It can send jobs over the network to a LPD spooler on
another host.It can run special filters to format jobs to be printed for
various printer languages or printer capabilities.It can account for printer usage.Through a configuration file
(/etc/printcap), and by providing the special
filter programs, you can enable the LPD system to do all or some
subset of the above for a great variety of printer hardware.Why You Should Use the SpoolerIf you are the sole user of your system, you may be wondering
why you should bother with the spooler when you do not need access
control, header pages, or printer accounting. While it is
possible to enable direct access to a printer, you should use the
spooler anyway since:LPD prints jobs in the background; you do not have to wait
for data to be copied to the printer.TeXLPD can conveniently run a job to be printed through
filters to add date/time headers or convert a special file
format (such as a TeX DVI file) into a format the printer will
understand. You will not have to do these steps
manually.Many free and commercial programs that provide a print
feature usually expect to talk to the spooler on your system.
By setting up the spooling system, you will more easily
support other software you may later add or already
have.Basic SetupTo use printers with the LPD spooling system, you will need to
set up both your printer hardware and the LPD software. This
document describes two levels of setup:See section Simple Printer
Setup to learn how to connect a printer, tell LPD how to
communicate with it, and print plain text files to the
printer.See section Advanced
Printer Setup to find out how to print a variety of
special file formats, to print header pages, to print across a
network, to control access to printers, and to do printer
accounting.Simple Printer SetupThis section tells how to configure printer hardware and the
LPD software to use the printer. It teaches the basics:Section Hardware
Setup gives some hints on connecting the printer to a
port on your computer.Section Software
Setup shows how to setup the LPD spooler configuration
file (/etc/printcap).If you are setting up a printer that uses a network protocol
to accept data to print instead of a serial or parallel interface,
see Printers With
Networked Data Stream Interfaces.Although this section is called Simple Printer
Setup, it is actually fairly complex. Getting the printer
to work with your computer and the LPD spooler is the hardest
part. The advanced options like header pages and accounting are
fairly easy once you get the printer working.Hardware SetupThis section tells about the various ways you can connect a
printer to your PC. It talks about the kinds of ports and
cables, and also the kernel configuration you may need to enable
FreeBSD to speak to the printer.If you have already connected your printer and have
successfully printed with it under another operating system, you
can probably skip to section Software Setup.Ports and CablesNearly all printers you can get for a PC today support one
or both of the following interfaces:printerserialSerial interfaces use a serial
port on your computer to send data to the printer. Serial
interfaces are common in the computer industry and cables
are readily available and also easy to construct. Serial
interfaces sometimes need special cables and might require
you to configure somewhat complex communications
options.printerparallelParallel interfaces use a
parallel port on your computer to send data to the
printer. Parallel interfaces are common in the PC market.
Cables are readily available but more difficult to
construct by hand. There are usually no communications
options with parallel interfaces, making their
configuration exceedingly simple.centronicsparallel printersParallel interfaces are sometimes known as
Centronics interfaces, named after the
connector type on the printer.In general, serial interfaces are slower than parallel
interfaces. Parallel interfaces usually offer just
one-way communication (computer to printer) while serial
gives you two-way. Many newer parallel ports and printers
can communicate in both directions under FreeBSD when a
IEEE1284 compliant cable is used.PostScriptUsually, the only time you need two-way communication with
the printer is if the printer speaks PostScript. PostScript
printers can be very verbose. In fact, PostScript jobs are
actually programs sent to the printer; they need not produce
paper at all and may return results directly to the computer.
PostScript also uses two-way communication to tell the
computer about problems, such as errors in the PostScript
program or paper jams. Your users may be appreciative of such
information. Furthermore, the best way to do effective
accounting with a PostScript printer requires two-way
communication: you ask the printer for its page count (how
many pages it has printed in its lifetime), then send the
user's job, then ask again for its page count. Subtract the
two values and you know how much paper to charge the
user.Parallel PortsTo hook up a printer using a parallel interface, connect
the Centronics cable between the printer and the computer.
The instructions that came with the printer, the computer, or
both should give you complete guidance.Remember which parallel port you used on the computer.
The first parallel port is /dev/lpt0 to
FreeBSD; the second is /dev/lpt1, and so
on.Serial PortsTo hook up a printer using a serial interface, connect the
proper serial cable between the printer and the computer. The
instructions that came with the printer, the computer, or both
should give you complete guidance.If you are unsure what the proper serial
cable is, you may wish to try one of the following
alternatives:A modem cable connects each pin
of the connector on one end of the cable straight through
to its corresponding pin of the connector on the other
end. This type of cable is also known as a
DTE-to-DCE cable.null-modem cableA null-modem cable connects some
pins straight through, swaps others (send data to receive
data, for example), and shorts some internally in each
connector hood. This type of cable is also known as a
DTE-to-DTE cable.A serial printer cable, required
for some unusual printers, is like the null-modem cable,
but sends some signals to their counterparts instead of
being internally shorted.baud rateparityflow control protocolYou should also set up the communications parameters for
the printer, usually through front-panel controls or DIP
switches on the printer. Choose the highest
bps (bits per second, sometimes
baud rate) rate that both your computer
and the printer can support. Choose 7 or 8 data bits; none,
even, or odd parity; and 1 or 2 stop bits. Also choose a flow
control protocol: either none, or XON/XOFF (also known as
in-band or software) flow control.
Remember these settings for the software configuration that
follows.Software SetupThis section describes the software setup necessary to print
with the LPD spooling system in FreeBSD.Here is an outline of the steps involved:Configure your kernel, if necessary, for the port you
are using for the printer; section Kernel Configuration tells
you what you need to do.Set the communications mode for the parallel port, if
you are using a parallel port; section Setting the
Communication Mode for the Parallel Port gives
details.Test if the operating system can send data to the printer.
Section Checking Printer
Communications gives some suggestions on how to do
this.Set up LPD for the printer by modifying the file
/etc/printcap. You will find out how
to do this later in this chapter.Kernel ConfigurationThe operating system kernel is compiled to work with a
specific set of devices. The serial or parallel interface for
your printer is a part of that set. Therefore, it might be
necessary to add support for an additional serial or parallel
port if your kernel is not already configured for one.To find out if the kernel you are currently using supports
a serial interface, type:&prompt.root; dmesg | grep sioNWhere N is the number of the
serial port, starting from zero. If you see output similar to
the following:sio2 at 0x3e8-0x3ef irq 5 on isa
sio2: type 16550Athen the kernel supports the port.To find out if the kernel supports a parallel interface,
type:&prompt.root; dmesg | grep lptNWhere N is the number of the
parallel port, starting from zero. If you see output similar
to the following lpt0 at 0x378-0x37f on isa
then the kernel supports the port.You might have to reconfigure your kernel in order for the
operating system to recognize and use the parallel or serial
port you are using for the printer.To add support for a serial port, see the section on
kernel configuration. To add support for a parallel port, see
that section and the section that
follows.Adding /dev Entries for the
PortsEven though the kernel may support communication along a
serial or parallel port, you will still need a software
interface through which programs running on the system can
send and receive data. That is what entries in the
/dev directory are for.To add a /dev entry for a
port:Become root with the &man.su.1; command. Enter the
root password when prompted.Change to the /dev
directory:&prompt.root; cd /devType:&prompt.root; ./MAKEDEV portWhere port is the device
entry for the port you want to make. Use
lpt0 for the first parallel port,
lpt1 for the second, and so on; use
ttyd0 for the first serial port,
ttyd1 for the second, and so on.Type:&prompt.root; ls -l portto make sure the device entry got created.Setting the Communication Mode for the Parallel
PortWhen you are using the parallel interface, you can choose
whether FreeBSD should use interrupt-driven or polled
communication with the printer.The interrupt-driven method is
the default with the GENERIC kernel. With this method,
the operating system uses an IRQ line to determine when
the printer is ready for data.The polled method directs the
operating system to repeatedly ask the printer if it is
ready for more data. When it responds ready, the kernel
sends more data.The interrupt-driven method is somewhat faster but uses up
a precious IRQ line. You should use whichever one
works.You can set the communications mode in two ways: by
configuring the kernel or by using the &man.lptcontrol.8;
program.To set the communications mode by configuring
the kernel:Edit your kernel configuration file. Look for or add
an lpt0 entry. If you are setting up
the second parallel port, use lpt1
instead. Use lpt2 for the third port,
and so on.If you want interrupt-driven mode, add the
irq specifier:device lpt0 at isa? port? tty irq N vector lptintrWhere N is the IRQ
number for your computer's parallel port.If you want polled mode, do not add the
irq specifier:device lpt0 at isa? port? tty vector lptintrSave the file. Then configure, build, and install the
kernel, then reboot. See kernel configuration for
more details.To set the communications mode with
&man.lptcontrol.8;:Type:&prompt.root; lptcontrol -i -u Nto set interrupt-driven mode for
lptN.Type:&prompt.root; lptcontrol -p -u Nto set polled-mode for
lptN.You could put these commands in your
/etc/rc.local file to set the mode each
time your system boots. See &man.lptcontrol.8; for more
information.Checking Printer CommunicationsBefore proceeding to configure the spooling system, you
should make sure the operating system can successfully send
data to your printer. It is a lot easier to debug printer
communication and the spooling system separately.To test the printer, we will send some text to it. For
printers that can immediately print characters sent to them,
the program &man.lptest.1; is perfect: it generates all 96
printable ASCII characters in 96 lines.PostScriptFor a PostScript (or other language-based) printer, we
will need a more sophisticated test. A small PostScript
program, such as the following, will suffice:%!PS
100 100 moveto 300 300 lineto stroke
310 310 moveto /Helvetica findfont 12 scalefont setfont
(Is this thing working?) show
showpageThe above PostScript code can be placed into a file and
used as shown in the examples appearing in the following
sections.PCLWhen this document refers to a printer language, it is
assuming a language like PostScript, and not Hewlett
Packard's PCL. Although PCL has great functionality, you
can intermingle plain text with its escape sequences.
PostScript cannot directly print plain text, and that is the
kind of printer language for which we must make special
accommodations.Checking a Parallel PrinterprinterparallelThis section tells you how to check if FreeBSD can
communicate with a printer connected to a parallel
port.To test a printer on a parallel
port:Become root with &man.su.1;.Send data to the printer.If the printer can print plain text, then use
&man.lptest.1;. Type:&prompt.root; lptest > /dev/lptNWhere N is the number
of the parallel port, starting from zero.If the printer understands PostScript or other
printer language, then send a small program to the
printer. Type:&prompt.root; cat > /dev/lptNThen, line by line, type the program
carefully as you cannot edit a
line once you have pressed RETURN
or ENTER. When you have finished
entering the program, press
CONTROL+D, or whatever your end
of file key is.Alternatively, you can put the program in a file
and type:&prompt.root; cat file > /dev/lptNWhere file is the
name of the file containing the program you want to
send to the printer.You should see something print. Do not worry if the
text does not look right; we will fix such things
later.Checking a Serial PrinterprinterserialThis section tells you how to check if FreeBSD can
communicate with a printer on a serial port.To test a printer on a serial
port:Become root with &man.su.1;.Edit the file /etc/remote. Add
the following entry:printer:dv=/dev/port:br#bps-rate:pa=paritybits-per-secondserial portparityWhere port is the device
entry for the serial port (ttyd0,
ttyd1, etc.),
bps-rate is the
bits-per-second rate at which the printer communicates,
and parity is the parity
required by the printer (either even,
odd, none, or
zero).Here is a sample entry for a printer connected via
a serial line to the third serial port at 19200 bps with
no parity:printer:dv=/dev/ttyd2:br#19200:pa=noneConnect to the printer with &man.tip.1;.
Type:&prompt.root; tip printerIf this step does not work, edit the file
/etc/remote again and try using
/dev/cuaaN
instead of
/dev/ttydN.Send data to the printer.If the printer can print plain text, then use
&man.lptest.1;. Type:~$lptestIf the printer understands PostScript or other
printer language, then send a small program to the
printer. Type the program, line by line,
very carefully as backspacing
or other editing keys may be significant to the
printer. You may also need to type a special
end-of-file key for the printer so it knows it
received the whole program. For PostScript
printers, press CONTROL+D.Alternatively, you can put the program in a file
and type:~>fileWhere file is the
name of the file containing the program. After
&man.tip.1; sends the file, press any required
end-of-file key.You should see something print. Do not worry if the
text does not look right; we will fix that later.Enabling the Spooler: The /etc/printcap
FileAt this point, your printer should be hooked up, your kernel
configured to communicate with it (if necessary), and you have
been able to send some simple data to the printer. Now, we are
ready to configure LPD to control access to your printer.You configure LPD by editing the file
/etc/printcap. The LPD spooling system
reads this file each time the spooler is used, so updates to the
file take immediate effect.printercapabilitiesThe format of the &man.printcap.5; file is straightforward.
Use your favorite text editor to make changes to
/etc/printcap. The format is identical to
other capability files like
/usr/share/misc/termcap and
/etc/remote. For complete information
about the format, see the &man.cgetent.3;.The simple spooler configuration consists of the following
steps:Pick a name (and a few convenient aliases) for the
printer, and put them in the
/etc/printcap file; see the
Naming the Printer
section for more information on naming.header pagesTurn off header pages (which are on by default) by
inserting the sh capability; see the
Suppressing Header
Pages section for more information.Make a spooling directory, and specify its location with
the sd capability; see the Making the Spooling
Directory section for more information.Set the /dev entry to use for the
printer, and note it in /etc/printcap
with the lp capability; see the Identifying the Printer
Device for more information. Also, if the printer is
on a serial port, set up the communication parameters with
the fs, fc,
xs, and xc
capabilities; which is discussed in the Configuring Spooler
Communications Parameters section.Install a plain text input filter; see the Installing the Text
Filter section for details.Test the setup by printing something with the
&man.lpr.1; command. More details are available in the
Trying It Out and
Troubleshooting
sections.Language-based printers, such as PostScript printers,
cannot directly print plain text. The simple setup outlined
above and described in the following sections assumes that if
you are installing such a printer you will print only files
that the printer can understand.Users often expect that they can print plain text to any of
the printers installed on your system. Programs that interface
to LPD to do their printing usually make the same assumption.
If you are installing such a printer and want to be able to
print jobs in the printer language and
print plain text jobs, you are strongly urged to add an
additional step to the simple setup outlined above: install an
automatic plain-text-to-PostScript (or other printer language)
conversion program. The section entitled Accommodating Plain
Text Jobs on PostScript Printers tells how to do
this.Naming the PrinterThe first (easy) step is to pick a name for your printer
It really does not matter whether you choose functional or
whimsical names since you can also provide a number of aliases
for the printer.At least one of the printers specified in the
/etc/printcap should have the alias
lp. This is the default printer's name.
If users do not have the PRINTER environment
variable nor specify a printer name on the command line of any
of the LPD commands, then lp will be the
default printer they get to use.Also, it is common practice to make the last alias for a
printer be a full description of the printer, including make
and model.Once you have picked a name and some common aliases, put
them in the /etc/printcap file. The name
of the printer should start in the leftmost column. Separate
each alias with a vertical bar and put a colon after the last
alias.In the following example, we start with a skeletal
/etc/printcap that defines two printers
(a Diablo 630 line printer and a Panasonic KX-P4455 PostScript
laser printer):#
# /etc/printcap for host rose
#
rattan|line|diablo|lp|Diablo 630 Line Printer:
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:In this example, the first printer is named
rattan and has as aliases
line, diablo,
lp, and Diablo 630 Line
Printer. Since it has the alias
lp, it is also the default printer. The
second is named bamboo, and has as aliases
ps, PS,
S, panasonic, and
Panasonic KX-P4455 PostScript v51.4.Suppressing Header Pagesprintingheader pagesThe LPD spooling system will by default print a
header page for each job. The header
page contains the user name who requested the job, the host
from which the job came, and the name of the job, in nice
large letters. Unfortunately, all this extra text gets in the
way of debugging the simple printer setup, so we will suppress
header pages.To suppress header pages, add the sh
capability to the entry for the printer in
/etc/printcap. Here is an example
/etc/printcap with sh
added:#
# /etc/printcap for host rose - no header pages anywhere
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:sh:
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:Note how we used the correct format: the first line starts
in the leftmost column, and subsequent lines are indented with
a single TAB. Every line in an entry except the last ends in
a backslash character.Making the Spooling Directoryprinter spoolprint jobsThe next step in the simple spooler setup is to make a
spooling directory, a directory where
print jobs reside until they are printed, and where a number
of other spooler support files live.Because of the variable nature of spooling directories, it
is customary to put these directories under
/var/spool. It is not necessary to
backup the contents of spooling directories, either.
Recreating them is as simple as running &man.mkdir.1;.It is also customary to make the directory with a name
that is identical to the name of the printer, as shown
below:&prompt.root; mkdir /var/spool/printer-nameHowever, if you have a lot of printers on your network,
you might want to put the spooling directories under a single
directory that you reserve just for printing with LPD. We
will do this for our two example printers
rattan and
bamboo:&prompt.root; mkdir /var/spool/lpd
&prompt.root; mkdir /var/spool/lpd/rattan
&prompt.root; mkdir /var/spool/lpd/bambooIf you are concerned about the privacy of jobs that
users print, you might want to protect the spooling
directory so it is not publicly accessible. Spooling
directories should be owned and be readable, writable, and
searchable by user daemon and group daemon, and no one else.
We will do this for our example printers:&prompt.root; chown daemon:daemon /var/spool/lpd/rattan
&prompt.root; chown daemon:daemon /var/spool/lpd/bamboo
&prompt.root; chmod 770 /var/spool/lpd/rattan
&prompt.root; chmod 770 /var/spool/lpd/bambooFinally, you need to tell LPD about these directories
using the /etc/printcap file. You
specify the pathname of the spooling directory with the
sd capability:#
# /etc/printcap for host rose - added spooling directories
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:sh:sd=/var/spool/lpd/rattan:
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:sd=/var/spool/lpd/bamboo:Note that the name of the printer starts in the first
column but all other entries describing the printer should be
indented with a tab and each line escaped with a
backslash.If you do not specify a spooling directory with
sd, the spooling system will use
/var/spool/lpd as a default.Identifying the Printer DeviceIn the Adding
/dev Entries for the Ports
section, we identified which entry in the
/dev directory FreeBSD will use to
communicate with the printer. Now, we tell LPD that
information. When the spooling system has a job to print, it
will open the specified device on behalf of the filter program
(which is responsible for passing data to the printer).List the /dev entry pathname in the
/etc/printcap file using the
lp capability.In our running example, let us assume that
rattan is on the first parallel port, and
bamboo is on a sixth serial port; here are
the additions to /etc/printcap:#
# /etc/printcap for host rose - identified what devices to use
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:sh:sd=/var/spool/lpd/rattan:\
:lp=/dev/lpt0:
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:sd=/var/spool/lpd/bamboo:\
:lp=/dev/ttyd5:If you do not specify the lp capability
for a printer in your /etc/printcap file,
LPD uses /dev/lp as a default.
/dev/lp currently does not exist in
FreeBSD.If the printer you are installing is connected to a
parallel port, skip to the section entitled, Installing the Text
Filter. Otherwise, be sure to follow the instructions
in the next section.Configuring Spooler Communication ParametersprinterserialFor printers on serial ports, LPD can set up the bps rate,
parity, and other serial communication parameters on behalf of
the filter program that sends data to the printer. This is
advantageous since:It lets you try different communication parameters by
simply editing the /etc/printcap
file; you do not have to recompile the filter
program.It enables the spooling system to use the same filter
program for multiple printers which may have different
serial communication settings.The following /etc/printcap
capabilities control serial communication parameters of the
device listed in the lp capability:br#bps-rateSets the communications speed of the device to
bps-rate, where
bps-rate can be 50, 75, 110,
134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600,
19200, or 38400 bits-per-second.fc#clear-bitsClears the flag bits
clear-bits in the
sgttyb structure after
opening the device.fs#set-bitsSets the flag bits
set-bits in the
sgttyb structure.xc#clear-bitsClears local mode bits
clear-bits after opening the
device.xs#set-bitsSets local mode bits
set-bits.For more information on the bits for the
fc, fs,
xc, and xs capabilities,
see the file
/usr/include/sys/ioctl_compat.h.When LPD opens the device specified by the
lp capability, it reads the flag bits in
the sgttyb structure; it clears any bits in
the fc capability, then sets bits in the
fs capability, then applies the resultant
setting. It does the same for the local mode bits as
well.Let us add to our example printer on the sixth serial
port. We will set the bps rate to 38400. For the flag bits,
we will set the TANDEM,
ANYP, LITOUT,
FLUSHO, and PASS8 flags.
For the local mode bits, we will set the
LITOUT and PASS8
flags:bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:sd=/var/spool/lpd/bamboo:\
:lp=/dev/ttyd5:fs#0x82000c1:xs#0x820:Installing the Text Filterprint filtersWe are now ready to tell LPD what text filter to use to
send jobs to the printer. A text filter,
also known as an input filter, is a
program that LPD runs when it has a job to print. When LPD
runs the text filter for a printer, it sets the filter's
standard input to the job to print, and its standard output to
the printer device specified with the lp
capability. The filter is expected to read the job from
standard input, perform any necessary translation for the
printer, and write the results to standard output, which will
get printed. For more information on the text filter, see
the Filters
section.For our simple printer setup, the text filter can be a
small shell script that just executes
/bin/cat to send the job to the printer.
FreeBSD comes with another filter called
lpf that handles backspacing and
underlining for printers that might not deal with such
character streams well. And, of course, you can use any other
filter program you want. The filter lpf is
described in detail in section entitled lpf: a Text
Filter.First, let us make the shell script
/usr/local/libexec/if-simple be a simple
text filter. Put the following text into that file with your
favorite text editor:#!/bin/sh
#
# if-simple - Simple text input filter for lpd
# Installed in /usr/local/libexec/if-simple
#
# Simply copies stdin to stdout. Ignores all filter arguments.
/bin/cat && exit 0
exit 2Make the file executable:&prompt.root; chmod 555 /usr/local/libexec/if-simpleAnd then tell LPD to use it by specifying it with the
if capability in
/etc/printcap. We will add it to the two
printers we have so far in the example
/etc/printcap:#
# /etc/printcap for host rose - added text filter
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\
:if=/usr/local/libexec/if-simple:
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:sd=/var/spool/lpd/bamboo:\
:lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:\
:if=/usr/local/libexec/if-simple:Turn on LPD&man.lpd.8; is run from /etc/rc,
controlled by the lpd_enable variable. This
variable defaults to NO. If you have not done
so already, add the line:lpd_enable="YES"to /etc/rc.conf, and then either restart
your machine, or just run &man.lpd.8;.&prompt.root; lpdTrying It OutYou have reached the end of the simple LPD setup.
Unfortunately, congratulations are not quite yet in order,
since we still have to test the setup and correct any
problems. To test the setup, try printing something. To
print with the LPD system, you use the command &man.lpr.1;,
which submits a job for printing.You can combine &man.lpr.1; with the &man.lptest.1;
program, introduced in section Checking Printer
Communications to generate some test text.To test the simple LPD setup:Type:&prompt.root; lptest 20 5 | lpr -Pprinter-nameWhere printer-name is a the
name of a printer (or an alias) specified in
/etc/printcap. To test the default
printer, type &man.lpr.1; without any
argument. Again, if you are testing a printer that expects
PostScript, send a PostScript program in that language instead
of using &man.lptest.1;. You can do so by putting the program
in a file and typing lpr
file.For a PostScript printer, you should get the results of
the program. If you are using &man.lptest.1;, then your
results should look like the following:!"#$%&'()*+,-./01234
"#$%&'()*+,-./012345
#$%&'()*+,-./0123456
$%&'()*+,-./01234567
%&'()*+,-./012345678To further test the printer, try downloading larger
programs (for language-based printers) or running
&man.lptest.1; with different arguments. For example,
lptest 80 60 will produce 60 lines of 80
characters each.If the printer did not work, see the Troubleshooting
section.Advanced Printer SetupThis section describes filters for printing specially formatted
files, header pages, printing across networks, and restricting and
accounting for printer usage.Filtersprint filtersAlthough LPD handles network protocols, queuing, access control,
and other aspects of printing, most of the real
work happens in the filters. Filters are
programs that communicate with the printer and handle its device
dependencies and special requirements. In the simple printer setup,
we installed a plain text filter—an extremely simple one that
should work with most printers (section Installing the Text
Filter).However, in order to take advantage of format conversion, printer
accounting, specific printer quirks, and so on, you should understand
how filters work. It will ultimately be the filter's responsibility
to handle these aspects. And the bad news is that most of the time
you have to provide filters yourself. The good
news is that many are generally available; when they are not, they are
usually easy to write.Also, FreeBSD comes with one,
/usr/libexec/lpr/lpf, that works with many
printers that can print plain text. (It handles backspacing and tabs
in the file, and does accounting, but that is about all it does.)
There are also several filters and filter components in the FreeBSD
Ports Collection.Here is what you will find in this section:Section How Filters
Work, tries to give an overview of a filter's role in the
printing process. You should read this section to get an
understanding of what is happening under the hood
when LPD uses filters. This knowledge could help you anticipate
and debug problems you might encounter as you install more and
more filters on each of your printers.LPD expects every printer to be able to print plain text by
default. This presents a problem for PostScript (or other
language-based printers) which cannot directly print plain text.
Section Accommodating
Plain Text Jobs on PostScript Printers tells you what you
should do to overcome this problem. You should read this
section if you have a PostScript printer.PostScript is a popular output format for many programs. Even
some people (myself included) write PostScript code directly. But
PostScript printers are expensive. Section Simulating PostScript on
Non-PostScript Printers tells how you can further modify
a printer's text filter to accept and print PostScript data on a
non-PostScript printer. You should read
this section if you do not have a PostScript printer.Section Conversion
Filters tells about a way you can automate the conversion
of specific file formats, such as graphic or typesetting data,
into formats your printer can understand. After reading this
section, you should be able to set up your printers such that
users can type lpr -t to print troff data, or
lpr -d to print TeX DVI data, or lpr
-v to print raster image data, and so forth. I
recommend reading this section.Section Output
Filters tells all about a not often used feature of LPD:
output filters. Unless you are printing header pages (see Header Pages),
you can probably skip that section altogether.Section lpf: a Text
Filter describes lpf, a fairly
complete if simple text filter for line printers (and laser
printers that act like line printers) that comes with FreeBSD. If
you need a quick way to get printer accounting working for plain
text, or if you have a printer which emits smoke when it sees
backspace characters, you should definitely consider
lpf.How Filters WorkAs mentioned before, a filter is an executable program started
by LPD to handle the device-dependent part of communicating with the
printer.When LPD wants to print a file in a job, it starts a filter
program. It sets the filter's standard input to the file to print,
its standard output to the printer, and its standard error to the
error logging file (specified in the lf
capability in /etc/printcap, or
/dev/console by default).troffWhich filter LPD starts and the filter's arguments depend on
what is listed in the /etc/printcap file and
what arguments the user specified for the job on the
&man.lpr.1; command line. For example, if the user typed
lpr -t, LPD would start the troff filter, listed
in the tf capability for the destination printer.
If the user wanted to print plain text, it would start the
if filter (this is mostly true: see Output Filters for
details).There are three kinds of filters you can specify in
/etc/printcap:The text filter, confusingly called the
input filter in LPD documentation, handles
regular text printing. Think of it as the default filter. LPD
expects every printer to be able to print plain text by default,
and it is the text filter's job to make sure backspaces, tabs,
or other special characters do not confuse the printer. If you
are in an environment where you have to account for printer
usage, the text filter must also account for pages printed,
usually by counting the number of lines printed and comparing
that to the number of lines per page the printer supports. The
text filter is started with the following argument list:
filter-name-c-wwidth-llength-iindent-n login-h hostacct-file
where
appears if the job's submitted with lpr
-lwidthis the value from the pw (page
width) capability specified in
/etc/printcap, default 132lengthis the value from the pl (page
length) capability, default 66indentis the amount of the indentation from lpr
-i, default 0loginis the account name of the user printing the
filehostis the host name from which the job was
submittedacct-fileis the name of the accounting file from the
af capability.printerfiltersA conversion filter converts a specific
file format into one the printer can render onto paper. For
example, ditroff typesetting data cannot be directly printed,
but you can install a conversion filter for ditroff files to
convert the ditroff data into a form the printer can digest and
print. Section Conversion
Filters tells all about them. Conversion filters also
need to do accounting, if you need printer accounting.
Conversion filters are started with the following arguments:
filter-name-xpixel-width-ypixel-height-n login-h hostacct-file
where pixel-width is the value
from the px capability (default 0) and
pixel-height is the value from the
py capability (default 0).The output filter is used only if there
is no text filter, or if header pages are enabled. In my
experience, output filters are rarely used. Section Output Filters describe
them. There are only two arguments to an output filter:
filter-name-wwidth-llength
which are identical to the text filters and
arguments.Filters should also exit with the
following exit status:exit 0If the filter printed the file successfully.exit 1If the filter failed to print the file but wants LPD to
try to print the file again. LPD will restart a filter if it
exits with this status.exit 2If the filter failed to print the file and does not want
LPD to try again. LPD will throw out the file.The text filter that comes with the FreeBSD release,
/usr/libexec/lpr/lpf, takes advantage of the
page width and length arguments to determine when to send a form
feed and how to account for printer usage. It uses the login, host,
and accounting file arguments to make the accounting entries.If you are shopping for filters, see if they are LPD-compatible.
If they are, they must support the argument lists described above.
If you plan on writing filters for general use, then have them
support the same argument lists and exit codes.Accommodating Plain Text Jobs on PostScript Printersprint jobsIf you are the only user of your computer and PostScript (or
other language-based) printer, and you promise to never send plain
text to your printer and to never use features of various programs
that will want to send plain text to your printer, then you do not
need to worry about this section at all.But, if you would like to send both PostScript and plain text
jobs to the printer, then you are urged to augment your printer
setup. To do so, we have the text filter detect if the arriving job
is plain text or PostScript. All PostScript jobs must start with
%! (for other printer languages, see your printer
documentation). If those are the first two characters in the job,
we have PostScript, and can pass the rest of the job directly. If
those are not the first two characters in the file, then the filter
will convert the text into PostScript and print the result.How do we do this?printerserialIf you have got a serial printer, a great way to do it is to
install lprps. lprps is a
PostScript printer filter which performs two-way communication with
the printer. It updates the printer's status file with verbose
information from the printer, so users and administrators can see
exactly what the state of the printer is (such as toner
low or paper jam). But more
importantly, it includes a program called psif
which detects whether the incoming job is plain text and calls
textps (another program that comes with
lprps) to convert it to PostScript. It then uses
lprps to send the job to the printer.lprps is part of the FreeBSD Ports Collection
(see The Ports Collection). You can
fetch, build and install it yourself, of course. After installing
lprps, just specify the pathname to the
psif program that is part of
lprps. If you installed lprps
from the ports collection, use the following in the serial
PostScript printer's entry in
/etc/printcap::if=/usr/local/libexec/psif:You should also specify the rw capability;
that tells LPD to open the printer in read-write mode.If you have a parallel PostScript printer (and therefore cannot
use two-way communication with the printer, which
lprps needs), you can use the following shell
script as the text filter:#!/bin/sh
#
# psif - Print PostScript or plain text on a PostScript printer
# Script version; NOT the version that comes with lprps
# Installed in /usr/local/libexec/psif
#
read first_line
first_two_chars=`expr "$first_line" : '\(..\)'`
if [ "$first_two_chars" = "%!" ]; then
#
# PostScript job, print it.
#
echo "$first_line" && cat && printf "\004" && exit 0
exit 2
else
#
# Plain text, convert it, then print it.
#
( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0
exit 2
fiIn the above script, textps is a program we
installed separately to convert plain text to PostScript. You can
use any text-to-PostScript program you wish. The FreeBSD Ports
Collection (see The Ports Collection)
includes a full featured text-to-PostScript program called
a2ps that you might want to investigate.Simulating PostScript on Non-PostScript PrintersPostScriptemulatingGhostscriptPostScript is the de facto standard for
high quality typesetting and printing. PostScript is, however, an
expensive standard. Thankfully, Alladin
Enterprises has a free PostScript work-alike called
Ghostscript that runs with FreeBSD.
Ghostscript can read most PostScript files and can render their
pages onto a variety of devices, including many brands of
non-PostScript printers. By installing Ghostscript and using a
special text filter for your printer, you can make your
non-PostScript printer act like a real PostScript printer.Ghostscript is in the FreeBSD Ports Collection, if you
would like to install it from there. You can fetch, build, and
install it quite easily yourself, as well.To simulate PostScript, we have the text filter detect if it is
printing a PostScript file. If it is not, then the filter will pass
the file directly to the printer; otherwise, it will use Ghostscript
to first convert the file into a format the printer will
understand.Here is an example: the following script is a text filter
for Hewlett Packard DeskJet 500 printers. For other printers,
substitute the argument to the
gs (Ghostscript) command. (Type gs
-h to get a list of devices the current installation of
Ghostscript supports.)#!/bin/sh
#
# ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500
# Installed in /usr/local/libexec/hpif
#
# Treat LF as CR+LF:
#
printf "\033&k2G" || exit 2
#
# Read first two characters of the file
#
read first_line
first_two_chars=`expr "$first_line" : '\(..\)'`
if [ "$first_two_chars" = "%!" ]; then
#
# It is PostScript; use Ghostscript to scan-convert and print it.
#
# Note that PostScript files are actually interpreted programs,
# and those programs are allowed to write to stdout, which will
# mess up the printed output. So, we redirect stdout to stderr
# and then make descriptor 3 go to stdout, and have Ghostscript
# write its output there. Exercise for the clever reader:
# capture the stderr output from Ghostscript and mail it back to
# the user originating the print job.
#
exec 3>&1 1>&2
/usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \
-sOutputFile=/dev/fd/3 - && exit 0
#
/usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 -sOutputFile=- - \
&& exit 0
else
#
# Plain text or HP/PCL, so just print it directly; print a form
# at the end to eject the last page.
#
echo $first_line && cat && printf "\033&l0H" &&
exit 0
fi
exit 2Finally, you need to notify LPD of the filter via the
if capability::if=/usr/local/libexec/hpif:That is it. You can type lpr plain.text and
lpr whatever.ps and both should print
successfully.Conversion FiltersAfter completing the simple setup described in Simple Printer Setup, the first
thing you will probably want to do is install conversion filters for
your favorite file formats (besides plain ASCII text).Why Install Conversion Filters?TeXprinting dvi filesConversion filters make printing various kinds of files easy.
As an example, suppose we do a lot of work with the TeX
typesetting system, and we have a PostScript printer. Every time
we generate a DVI file from TeX, we cannot print it directly until
we convert the DVI file into PostScript. The command sequence
goes like this:&prompt.user; dvips seaweed-analysis.dvi
&prompt.user; lpr seaweed-analysis.psBy installing a conversion filter for DVI files, we can skip
the hand conversion step each time by having LPD do it for us.
Now, each time we get a DVI file, we are just one step away from
printing it:&prompt.user; lpr -d seaweed-analysis.dviWe got LPD to do the DVI file conversion for us by specifying
the option. Section Formatting and Conversion
Options lists the conversion options.For each of the conversion options you want a printer to
support, install a conversion filter and
specify its pathname in /etc/printcap. A
conversion filter is like the text filter for the simple printer
setup (see section Installing
the Text Filter) except that instead of printing plain
text, the filter converts the file into a format the printer can
understand.Which Conversions Filters Should I Install?You should install the conversion filters you expect to use.
If you print a lot of DVI data, then a DVI conversion filter is in
order. If you have got plenty of troff to print out, then you
probably want a troff filter.The following table summarizes the filters that LPD works
with, their capability entries for the
/etc/printcap file, and how to invoke them
with the lpr command:File type/etc/printcap capabilitylpr optioncifplotcfDVIdfplotgfditroffnfFORTRAN textrftroffrfrastervfplain textifnone, , or
In our example, using lpr -d means the
printer needs a df capability in its entry in
/etc/printcap.fortranDespite what others might contend, formats like FORTRAN text
and plot are probably obsolete. At your site, you can give new
meanings to these or any of the formatting options just by
installing custom filters. For example, suppose you would like to
directly print Printerleaf files (files from the Interleaf desktop
publishing program), but will never print plot files. You could
install a Printerleaf conversion filter under the
gf capability and then educate your users that
lpr -g mean print Printerleaf
files.Installing Conversion FiltersSince conversion filters are programs you install outside of
the base FreeBSD installation, they should probably go under
/usr/local. The directory
/usr/local/libexec is a popular location,
since they are specialized programs that only LPD will run;
regular users should not ever need to run them.To enable a conversion filter, specify its pathname under the
appropriate capability for the destination printer in
/etc/printcap.In our example, we will add the DVI conversion filter to the
entry for the printer named bamboo. Here is
the example /etc/printcap file again, with
the new df capability for the printer
bamboo.#
# /etc/printcap for host rose - added df filter for bamboo
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:sh:sd=/var/spool/lpd/rattan:\
:lp=/dev/lpt0:\
:if=/usr/local/libexec/if-simple:
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:sd=/var/spool/lpd/bamboo:\
:lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
:if=/usr/local/libexec/psif:\
:df=/usr/local/libexec/psdf:The DVI filter is a shell script named
/usr/local/libexec/psdf. Here is that
script:#!bin/sh
#
# psdf - DVI to PostScript printer filter
# Installed in /usr/local/libexec/psdf
#
# Invoked by lpd when user runs lpr -d
#
exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@"This script runs dvips in filter mode (the
argument) on standard input, which is the job
to print. It then starts the PostScript printer filter
lprps (see section Accommodating Plain
Text Jobs on PostScript Printers) with the arguments LPD
passed to this script. lprps will use those
arguments to account for the pages printed.More Conversion Filter ExamplesSince there is no fixed set of steps to install conversion
filters, let me instead provide more examples. Use these as
guidance to making your own filters. Use them directly, if
appropriate.This example script is a raster (well, GIF file, actually)
conversion filter for a Hewlett Packard LaserJet III-Si
printer:#!/bin/sh
#
# hpvf - Convert GIF files into HP/PCL, then print
# Installed in /usr/local/libexec/hpvf
PATH=/usr/X11R6/bin:$PATH; export PATH
giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \
&& exit 0 \
|| exit 2It works by converting the GIF file into a portable anymap,
converting that into a portable graymap, converting that into a
portable bitmap, and converting that into LaserJet/PCL-compatible
data.Here is the /etc/printcap file with an
entry for a printer using the above filter:#
# /etc/printcap for host orchid
#
teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
:lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\
:if=/usr/local/libexec/hpif:\
:vf=/usr/local/libexec/hpvf:The following script is a conversion filter for troff data
from the groff typesetting system for the PostScript printer named
bamboo:#!/bin/sh
#
# pstf - Convert groff's troff data into PS, then print.
# Installed in /usr/local/libexec/pstf
#
exec grops | /usr/local/libexec/lprps "$@"The above script makes use of lprps again
to handle the communication with the printer. If the printer were
on a parallel port, we would use this script instead:#!/bin/sh
#
# pstf - Convert groff's troff data into PS, then print.
# Installed in /usr/local/libexec/pstf
#
exec gropsThat is it. Here is the entry we need to add to
/etc/printcap to enable the filter::tf=/usr/local/libexec/pstf:Here is an example that might make old hands at FORTRAN blush.
It is a FORTRAN-text filter for any printer that can directly
print plain text. We will install it for the printer
teak:#!/bin/sh
#
# hprf - FORTRAN text filter for LaserJet 3si:
# Installed in /usr/local/libexec/hprf
#
printf "\033&k2G" && fpr && printf "\033&l0H" &&
exit 0
exit 2And we will add this line to the
/etc/printcap for the printer
teak to enable this filter::rf=/usr/local/libexec/hprf:Here is one final, somewhat complex example. We will add a
DVI filter to the LaserJet printer teak
introduced earlier. First, the easy part: updating
/etc/printcap with the location of the DVI
filter::df=/usr/local/libexec/hpdf:Now, for the hard part: making the filter. For that, we need
a DVI-to-LaserJet/PCL conversion program. The FreeBSD Ports
Collection (see The Ports Collection)
has one: dvi2xx is the name of the package.
Installing this package gives us the program we need,
dvilj2p, which converts DVI into LaserJet IIp,
LaserJet III, and LaserJet 2000 compatible codes.dvilj2p makes the filter
hpdf quite complex since
dvilj2p cannot read from standard input. It
wants to work with a filename. What is worse, the filename has to
end in .dvi so using
/dev/fd/0 for standard input is problematic.
We can get around that problem by linking (symbolically) a
temporary file name (one that ends in .dvi)
to /dev/fd/0, thereby forcing
dvilj2p to read from standard input.The only other fly in the ointment is the fact that we cannot
use /tmp for the temporary link. Symbolic
links are owned by user and group bin. The
filter runs as user daemon. And the
/tmp directory has the sticky bit set. The
filter can create the link, but it will not be able clean up when
done and remove it since the link will belong to a different
user.Instead, the filter will make the symbolic link in the current
working directory, which is the spooling directory (specified by
the sd capability in
/etc/printcap). This is a perfect place for
filters to do their work, especially since there is (sometimes)
more free disk space in the spooling directory than under
/tmp.Here, finally, is the filter:#!/bin/sh
#
# hpdf - Print DVI data on HP/PCL printer
# Installed in /usr/local/libexec/hpdf
PATH=/usr/local/bin:$PATH; export PATH
#
# Define a function to clean up our temporary files. These exist
# in the current directory, which will be the spooling directory
# for the printer.
#
cleanup() {
rm -f hpdf$$.dvi
}
#
# Define a function to handle fatal errors: print the given message
# and exit 2. Exiting with 2 tells LPD to do not try to reprint the
# job.
#
fatal() {
echo "$@" 1>&2
cleanup
exit 2
}
#
# If user removes the job, LPD will send SIGINT, so trap SIGINT
# (and a few other signals) to clean up after ourselves.
#
trap cleanup 1 2 15
#
# Make sure we are not colliding with any existing files.
#
cleanup
#
# Link the DVI input file to standard input (the file to print).
#
ln -s /dev/fd/0 hpdf$$.dvi || fatal "Cannot symlink /dev/fd/0"
#
# Make LF = CR+LF
#
printf "\033&k2G" || fatal "Cannot initialize printer"
#
# Convert and print. Return value from dvilj2p does not seem to be
# reliable, so we ignore it.
#
dvilj2p -M1 -q -e- dfhp$$.dvi
#
# Clean up and exit
#
cleanup
exit 0Automated Conversion: An Alternative To Conversion
FiltersAll these conversion filters accomplish a lot for your
printing environment, but at the cost forcing the user to specify
(on the &man.lpr.1; command line) which one to use.
If your users are not particularly computer literate, having to
specify a filter option will become annoying. What is worse,
though, is that an incorrectly specified filter option may run a
filter on the wrong type of file and cause your printer to spew
out hundreds of sheets of paper.Rather than install conversion filters at all, you might want
to try having the text filter (since it is the default filter)
detect the type of file it has been asked to print and then
automatically run the right conversion filter. Tools such as
file can be of help here. Of course, it will
be hard to determine the differences between
some file types—and, of course, you can
still provide conversion filters just for them.apsfilterprinterfiltersapsfilterThe FreeBSD Ports Collection has a text filter that performs
automatic conversion called apsfilter. It can
detect plain text, PostScript, and DVI files, run the proper
conversions, and print.Output FiltersThe LPD spooling system supports one other type of filter that
we have not yet explored: an output filter. An output filter is
intended for printing plain text only, like the text filter, but
with many simplifications. If you are using an output filter but no
text filter, then:LPD starts an output filter once for the entire job instead
of once for each file in the job.LPD does not make any provision to identify the start or the
end of files within the job for the output filter.LPD does not pass the user's login or host to the filter, so
it is not intended to do accounting. In fact, it gets only two
arguments:filter-name-wwidth-llengthWhere width is from the
pw capability and
length is from the
pl capability for the printer in
question.Do not be seduced by an output filter's simplicity. If you
would like each file in a job to start on a different page an output
filter will not work. Use a text filter (also
known as an input filter); see section Installing the Text Filter.
Furthermore, an output filter is actually more
complex in that it has to examine the byte stream being
sent to it for special flag characters and must send signals to
itself on behalf of LPD.However, an output filter is necessary if
you want header pages and need to send escape sequences or other
initialization strings to be able to print the header page. (But it
is also futile if you want to charge header
pages to the requesting user's account, since LPD does not give any
user or host information to the output filter.)On a single printer, LPD allows both an output filter and text
or other filters. In such cases, LPD will start the output filter
to print the header page (see section Header Pages)
only. LPD then expects the output filter to stop
itself by sending two bytes to the filter: ASCII 031
followed by ASCII 001. When an output filter sees these two bytes
(031, 001), it should stop by sending SIGSTOP to itself. When LPD's
done running other filters, it will restart the output filter by
sending SIGCONT to it.If there is an output filter but no text
filter and LPD is working on a plain text job, LPD uses the output
filter to do the job. As stated before, the output filter will
print each file of the job in sequence with no intervening form
feeds or other paper advancement, and this is probably
not what you want. In almost all cases, you
need a text filter.The program lpf, which we introduced earlier
as a text filter, can also run as an output filter. If you need a
quick-and-dirty output filter but do not want to write the byte
detection and signal sending code, try lpf. You
can also wrap lpf in a shell script to handle any
initialization codes the printer might require.lpf: a Text FilterThe program /usr/libexec/lpr/lpf that comes
with FreeBSD binary distribution is a text filter (input filter)
that can indent output (job submitted with lpr
-i), allow literal characters to pass (job submitted
with lpr -l), adjust the printing position for
backspaces and tabs in the job, and account for pages printed. It
can also act like an output filter.lpf is suitable for many printing
environments. And although it has no capability to send
initialization sequences to a printer, it is easy to write a shell
script to do the needed initialization and then execute
lpf.page accountingaccountingprinterIn order for lpf to do page accounting
correctly, it needs correct values filled in for the
pw and pl capabilities in the
/etc/printcap file. It uses these values to
determine how much text can fit on a page and how many pages were in
a user's job. For more information on printer accounting, see Accounting for Printer
Usage.Header PagesIf you have lots of users, all of them using
various printers, then you probably want to consider header
pages as a necessary evil.banner pagesheader pagesheader pagesHeader pages, also known as banner or
burst pages identify to whom jobs belong after
they are printed. They are usually printed in large, bold letters,
perhaps with decorative borders, so that in a stack of printouts they
stand out from the real documents that comprise users' jobs. They
enable users to locate their jobs quickly. The obvious drawback to a
header page is that it is yet one more sheet that has to be printed
for every job, their ephemeral usefulness lasting not more than a few
minutes, ultimately finding themselves in a recycling bin or rubbish
heap. (Note that header pages go with each job, not each file in a
job, so the paper waste might not be that bad.)The LPD system can provide header pages automatically for your
printouts if your printer can directly print
plain text. If you have a PostScript printer, you will need an
external program to generate the header page; see Header Pages on
PostScript Printers.Enabling Header PagesIn the Simple Printer
Setup, we turned off header pages by specifying
sh (meaning suppress header) in the
/etc/printcap file. To enable header pages for
a printer, just remove the sh capability.Sounds too easy, right?You are right. You might have to provide
an output filter to send initialization strings to the printer.
Here is an example output filter for Hewlett Packard PCL-compatible
printers:#!/bin/sh
#
# hpof - Output filter for Hewlett Packard PCL-compatible printers
# Installed in /usr/local/libexec/hpof
printf "\033&k2G" || exit 2
exec /usr/libexec/lpr/lpfSpecify the path to the output filter in the
of capability. See Output Filters for more
information.Here is an example /etc/printcap file for
the printer teak that we introduced earlier; we
enabled header pages and added the above output filter:#
# /etc/printcap for host orchid
#
teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
:lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
:if=/usr/local/libexec/hpif:\
:vf=/usr/local/libexec/hpvf:\
:of=/usr/local/libexec/hpof:Now, when users print jobs to teak, they get
a header page with each job. If users want to spend time searching
for their printouts, they can suppress header pages by submitting
the job with lpr -h; see Header Page Options for
more &man.lpr.1; options.LPD prints a form feed character after the header page. If
your printer uses a different character or sequence of characters
to eject a page, specify them with the ff
capability in /etc/printcap.Controlling Header PagesBy enabling header pages, LPD will produce a long
header, a full page of large letters identifying the
user, host, and job. Here is an example (kelly printed the job
named outline from host rose): k ll ll
k l l
k l l
k k eeee l l y y
k k e e l l y y
k k eeeeee l l y y
kk k e l l y y
k k e e l l y yy
k k eeee lll lll yyy y
y
y y
yyyy
ll
t l i
t l
oooo u u ttttt l ii n nnn eeee
o o u u t l i nn n e e
o o u u t l i n n eeeeee
o o u u t l i n n e
o o u uu t t l i n n e e
oooo uuu u tt lll iii n n eeee
r rrr oooo ssss eeee
rr r o o s s e e
r o o ss eeeeee
r o o ss e
r o o s s e e
r oooo ssss eeee
Job: outline
Date: Sun Sep 17 11:04:58 1995LPD appends a form feed after this text so the job starts on a
new page (unless you have sf (suppress form
feeds) in the destination printer's entry in
/etc/printcap).If you prefer, LPD can make a short header;
specify sb (short banner) in the
/etc/printcap file. The header page will look
like this:rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995Also by default, LPD prints the header page first, then the job.
To reverse that, specify hl (header last) in
/etc/printcap.Accounting for Header PagesUsing LPD's built-in header pages enforces a particular paradigm
when it comes to printer accounting: header pages must be
free of charge.Why?Because the output filter is the only external program that will
have control when the header page is printed that could do
accounting, and it is not provided with any user or
host information or an accounting file, so it has no
idea whom to charge for printer use. It is also not enough to just
add one page to the text filter or any of the
conversion filters (which do have user and host information) since
users can suppress header pages with lpr -h.
They could still be charged for header pages they did not print.
Basically, lpr -h will be the preferred option of
environmentally-minded users, but you cannot offer any incentive to
use it.It is still not enough to have each of the
filters generate their own header pages (thereby being able to
charge for them). If users wanted the option of suppressing the
header pages with lpr -h, they will still get
them and be charged for them since LPD does not pass any knowledge
of the option to any of the filters.So, what are your options?You can:Accept LPD's paradigm and make header pages free.Install an alternative to LPD, such as LPRng. Section
Alternatives to the
Standard Spooler tells more about other spooling
software you can substitute for LPD.Write a smart output filter. Normally,
an output filter is not meant to do anything more than
initialize a printer or do some simple character conversion. It
is suited for header pages and plain text jobs (when there is no
text (input) filter). But, if there is a text filter for the
plain text jobs, then LPD will start the output filter only for
the header pages. And the output filter can parse the header
page text that LPD generates to determine what user and host to
charge for the header page. The only other problem with this
method is that the output filter still does not know what
accounting file to use (it is not passed the name of the file
from the af capability), but if you have a
well-known accounting file, you can hard-code that into the
output filter. To facilitate the parsing step, use the
sh (short header) capability in
/etc/printcap. Then again, all that might
be too much trouble, and users will certainly appreciate the
more generous system administrator who makes header pages
free.Header Pages on PostScript PrintersAs described above, LPD can generate a plain text header page
suitable for many printers. Of course, PostScript cannot directly
print plain text, so the header page feature of LPD is
useless—or mostly so.One obvious way to get header pages is to have every conversion
filter and the text filter generate the header page. The filters
should use the user and host arguments to generate a suitable
header page. The drawback of this method is that users will always
get a header page, even if they submit jobs with lpr
-h.Let us explore this method. The following script takes three
arguments (user login name, host name, and job name) and makes a
simple PostScript header page:#!/bin/sh
#
# make-ps-header - make a PostScript header page on stdout
# Installed in /usr/local/libexec/make-ps-header
#
#
# These are PostScript units (72 to the inch). Modify for A4 or
# whatever size paper you are using:
#
page_width=612
page_height=792
border=72
#
# Check arguments
#
if [ $# -ne 3 ]; then
echo "Usage: `basename $0` <user> <host> <job>" 1>&2
exit 1
fi
#
# Save these, mostly for readability in the PostScript, below.
#
user=$1
host=$2
job=$3
date=`date`
#
# Send the PostScript code to stdout.
#
exec cat <<EOF
%!PS
%
% Make sure we do not interfere with user's job that will follow
%
save
%
% Make a thick, unpleasant border around the edge of the paper.
%
$border $border moveto
$page_width $border 2 mul sub 0 rlineto
0 $page_height $border 2 mul sub rlineto
currentscreen 3 -1 roll pop 100 3 1 roll setscreen
$border 2 mul $page_width sub 0 rlineto closepath
0.8 setgray 10 setlinewidth stroke 0 setgray
%
% Display user's login name, nice and large and prominent
%
/Helvetica-Bold findfont 64 scalefont setfont
$page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto
($user) show
%
% Now show the boring particulars
%
/Helvetica findfont 14 scalefont setfont
/y 200 def
[ (Job:) (Host:) (Date:) ] {
200 y moveto show /y y 18 sub def }
forall
/Helvetica-Bold findfont 14 scalefont setfont
/y 200 def
[ ($job) ($host) ($date) ] {
270 y moveto show /y y 18 sub def
} forall
%
% That is it
%
restore
showpage
EOFNow, each of the conversion filters and the text filter can call
this script to first generate the header page, and then print the
user's job. Here is the DVI conversion filter from earlier in this
document, modified to make a header page:#!/bin/sh
#
# psdf - DVI to PostScript printer filter
# Installed in /usr/local/libexec/psdf
#
# Invoked by lpd when user runs lpr -d
#
orig_args="$@"
fail() {
echo "$@" 1>&2
exit 2
}
while getopts "x:y:n:h:" option; do
case $option in
x|y) ;; # Ignore
n) login=$OPTARG ;;
h) host=$OPTARG ;;
*) echo "LPD started `basename $0` wrong." 1>&2
exit 2
;;
esac
done
[ "$login" ] || fail "No login name"
[ "$host" ] || fail "No host name"
( /usr/local/libexec/make-ps-header $login $host "DVI File"
/usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_argsNotice how the filter has to parse the argument list in order to
determine the user and host name. The parsing for the other
conversion filters is identical. The text filter takes a slightly
different set of arguments, though (see section How Filters
Work).As we have mentioned before, the above scheme, though fairly
simple, disables the suppress header page option (the
option) to lpr. If users
wanted to save a tree (or a few pennies, if you charge for header
pages), they would not be able to do so, since every filter's going
to print a header page with every job.To allow users to shut off header pages on a per-job basis, you
will need to use the trick introduced in section Accounting for
Header Pages: write an output filter that parses the
LPD-generated header page and produces a PostScript version. If the
user submits the job with lpr -h, then LPD will
not generate a header page, and neither will your output filter.
Otherwise, your output filter will read the text from LPD and send
the appropriate header page PostScript code to the printer.If you have a PostScript printer on a serial line, you can make
use of lprps, which comes with an output filter,
psof, which does the above. Note that
psof does not charge for header pages.Networked Printingprinternetworknetwork printingFreeBSD supports networked printing: sending jobs to remote
printers. Networked printing generally refers to two different
things:Accessing a printer attached to a remote host. You install a
printer that has a conventional serial or parallel interface on
one host. Then, you set up LPD to enable access to the printer
from other hosts on the network. Section Printers Installed on
Remote Hosts tells how to do this.Accessing a printer attached directly to a network. The
printer has a network interface in addition (or in place of) a
more conventional serial or parallel interface. Such a printer
might work as follows:It might understand the LPD protocol and can even queue
jobs from remote hosts. In this case, it acts just like a
regular host running LPD. Follow the same procedure in
section Printers
Installed on Remote Hosts to set up such a
printer.It might support a data stream network connection. In this
case, you attach the printer to one host on the
network by making that host responsible for spooling jobs and
sending them to the printer. Section Printers with
Networked Data Stream Interfaces gives some
suggestions on installing such printers.Printers Installed on Remote HostsThe LPD spooling system has built-in support for sending jobs to
other hosts also running LPD (or are compatible with LPD). This
feature enables you to install a printer on one host and make it
accessible from other hosts. It also works with printers that have
network interfaces that understand the LPD protocol.To enable this kind of remote printing, first install a printer
on one host, the printer host, using the simple
printer setup described in Simple
Printer Setup. Do any advanced setup in Advanced Printer Setup that you
need. Make sure to test the printer and see if it works with the
features of LPD you have enabled. Also ensure that the
local host has authorization to use the LPD
service in the remote host (see Restricting Jobs
from Remote Printers).printernetworknetwork printingIf you are using a printer with a network interface that is
compatible with LPD, then the printer host in
the discussion below is the printer itself, and the
printer name is the name you configured for the
printer. See the documentation that accompanied your printer and/or
printer-network interface.If you are using a Hewlett Packard Laserjet then the printer
name text will automatically perform the LF to
CRLF conversion for you, so you will not require the
hpif script.Then, on the other hosts you want to have access to the printer,
make an entry in their /etc/printcap files with
the following:Name the entry anything you want. For simplicity, though,
you probably want to use the same name and aliases as on the
printer host.Leave the lp capability blank, explicitly
(:lp=:).Make a spooling directory and specify its location in the
sd capability. LPD will store jobs here
before they get sent to the printer host.Place the name of the printer host in the
rm capability.Place the printer name on the printer
host in the rp
capability.That is it. You do not need to list conversion filters, page
dimensions, or anything else in the
/etc/printcap file.Here is an example. The host rose has two
printers, bamboo and rattan.
We will enable users on the host orchid to print to those printers.
Here is the /etc/printcap file for
orchid (back from section Enabling Header
Pages). It already had the entry for the printer
teak; we have added entries for the two printers
on the host rose:#
# /etc/printcap for host orchid - added (remote) printers on rose
#
#
# teak is local; it is connected directly to orchid:
#
teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
:lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\
:if=/usr/local/libexec/ifhp:\
:vf=/usr/local/libexec/vfhp:\
:of=/usr/local/libexec/ofhp:
#
# rattan is connected to rose; send jobs for rattan to rose:
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
#
# bamboo is connected to rose as well:
#
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:Then, we just need to make spooling directories on
orchid:&prompt.root; mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo
&prompt.root; chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo
&prompt.root; chown daemon:daemon /var/spool/lpd/rattan /var/spool/lpd/bambooNow, users on orchid can print to
rattan and bamboo. If, for
example, a user on orchid typed
&prompt.user; lpr -P bamboo -d sushi-review.dvi
the LPD system on orchid would copy the job to the spooling
directory /var/spool/lpd/bamboo and note that
it was a DVI job. As soon as the host rose has room in its
bamboo spooling directory, the two LPDs would
transfer the file to rose. The file would wait in rose's queue
until it was finally printed. It would be converted from DVI to
PostScript (since bamboo is a PostScript printer) on rose.Printers with Networked Data Stream InterfacesOften, when you buy a network interface card for a printer, you
can get two versions: one which emulates a spooler (the more
expensive version), or one which just lets you send data to it as if
you were using a serial or parallel port (the cheaper version).
This section tells how to use the cheaper version. For the more
expensive one, see the previous section Printers Installed on
Remote Hosts.The format of the /etc/printcap file lets
you specify what serial or parallel interface to use, and (if you
are using a serial interface), what baud rate, whether to use flow
control, delays for tabs, conversion of newlines, and more. But
there is no way to specify a connection to a printer that is
listening on a TCP/IP or other network port.To send data to a networked printer, you need to develop a
communications program that can be called by the text and conversion
filters. Here is one such example: the script
netprint takes all data on standard input and
sends it to a network-attached printer. We specify the hostname of
the printer as the first argument and the port number to which to
connect as the second argument to netprint. Note
that this supports one-way communication only (FreeBSD to printer);
many network printers support two-way communication, and you might
want to take advantage of that (to get printer status, perform
accounting, etc.).#!/usr/bin/perl
#
# netprint - Text filter for printer attached to network
# Installed in /usr/local/libexec/netprint
#
$#ARGV eq 1 || die "Usage: $0 <printer-hostname> <port-number>";
$printer_host = $ARGV[0];
$printer_port = $ARGV[1];
require 'sys/socket.ph';
($ignore, $ignore, $protocol) = getprotobyname('tcp');
($ignore, $ignore, $ignore, $ignore, $address)
= gethostbyname($printer_host);
$sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address);
socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol)
|| die "Can't create TCP/IP stream socket: $!";
connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!";
while (<STDIN>) { print PRINTER; }
exit 0;We can then use this script in various filters. Suppose we had
a Diablo 750-N line printer connected to the network. The printer
accepts data to print on port number 5100. The host name of the
printer is scrivener. Here is the text filter for the
printer:#!/bin/sh
#
# diablo-if-net - Text filter for Diablo printer `scrivener' listening
# on port 5100. Installed in /usr/local/libexec/diablo-if-net
#
exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100Restricting Printer Usageprinterrestricting access toThis section gives information on restricting printer usage. The
LPD system lets you control who can access a printer, both locally or
remotely, whether they can print multiple copies, how large their jobs
can be, and how large the printer queues can get.Restricting Multiple CopiesThe LPD system makes it easy for users to print multiple copies
of a file. Users can print jobs with lpr -#5
(for example) and get five copies of each file in the job. Whether
this is a good thing is up to you.If you feel multiple copies cause unnecessary wear and tear on
your printers, you can disable the option to
&man.lpr.1; by adding the sc capability to the
/etc/printcap file. When users submit jobs
with the option, they will see:lpr: multiple copies are not allowedNote that if you have set up access to a printer remotely (see
section Printers
Installed on Remote Hosts), you need the
sc capability on the remote
/etc/printcap files as well, or else users will
still be able to submit multiple-copy jobs by using another
host.Here is an example. This is the
/etc/printcap file for the host
rose. The printer rattan is
quite hearty, so we will allow multiple copies, but the laser
printer bamboo's a bit more delicate, so we will
disable multiple copies by adding the sc
capability:#
# /etc/printcap for host rose - restrict multiple copies on bamboo
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:sh:sd=/var/spool/lpd/rattan:\
:lp=/dev/lpt0:\
:if=/usr/local/libexec/if-simple:
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:sd=/var/spool/lpd/bamboo:sc:\
:lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
:if=/usr/local/libexec/psif:\
:df=/usr/local/libexec/psdf:Now, we also need to add the sc capability on
the host orchid's
/etc/printcap (and while we are at it, let us
disable multiple copies for the printer
teak):#
# /etc/printcap for host orchid - no multiple copies for local
# printer teak or remote printer bamboo
teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
:lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:sc:\
:if=/usr/local/libexec/ifhp:\
:vf=/usr/local/libexec/vfhp:\
:of=/usr/local/libexec/ofhp:
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan:
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:sc:By using the sc capability, we prevent the
use of lpr -#, but that still does not prevent
users from running &man.lpr.1;
multiple times, or from submitting the same file multiple times in
one job like this:&prompt.user; lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.signThere are many ways to prevent this abuse (including ignoring
it) which you are free to explore.Restricting Access To PrintersYou can control who can print to what printers by using the Unix
group mechanism and the rg capability in
/etc/printcap. Just place the users you want
to have access to a printer in a certain group, and then name that
group in the rg capability.Users outside the group (including root) will be greeted with
lpr: Not a member of the restricted group
if they try to print to the controlled printer.As with the sc (suppress multiple copies)
capability, you need to specify rg on remote
hosts that also have access to your printers, if you feel it is
appropriate (see section Printers Installed on
Remote Hosts).For example, we will let anyone access the printer
rattan, but only those in group
artists can use bamboo. Here
is the familiar /etc/printcap for host
rose:#
# /etc/printcap for host rose - restricted group for bamboo
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:sh:sd=/var/spool/lpd/rattan:\
:lp=/dev/lpt0:\
:if=/usr/local/libexec/if-simple:
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:\
:lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
:if=/usr/local/libexec/psif:\
:df=/usr/local/libexec/psdf:Let us leave the other example
/etc/printcap file (for the host
orchid) alone. Of course, anyone on
orchid can print to bamboo. It
might be the case that we only allow certain logins on
orchid anyway, and want them to have access to the
printer. Or not.There can be only one restricted group per printer.Controlling Sizes of Jobs Submittedprint jobsIf you have many users accessing the printers, you probably need
to put an upper limit on the sizes of the files users can submit to
print. After all, there is only so much free space on the
filesystem that houses the spooling directories, and you also need
to make sure there is room for the jobs of other users.print jobscontrollingLPD enables you to limit the maximum byte size a file in a job
can be with the mx capability. The units are in
BUFSIZ blocks, which are 1024 bytes. If you put a zero for this
capability, there will be no limit on file size; however, if no
mx capability is specified, then a default limit
of 1000 blocks will be used.The limit applies to files in a job, and
not the total job size.LPD will not refuse a file that is larger than the limit you
place on a printer. Instead, it will queue as much of the file up
to the limit, which will then get printed. The rest will be
discarded. Whether this is correct behavior is up for
debate.Let us add limits to our example printers
rattan and bamboo. Since
those artists' PostScript files tend to be large, we will limit them
to five megabytes. We will put no limit on the plain text line
printer:#
# /etc/printcap for host rose
#
#
# No limit on job size:
#
rattan|line|diablo|lp|Diablo 630 Line Printer:\
:sh:mx#0:sd=/var/spool/lpd/rattan:\
:lp=/dev/lpt0:\
:if=/usr/local/libexec/if-simple:
#
# Limit of five megabytes:
#
bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\
:lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:\
:if=/usr/local/libexec/psif:\
:df=/usr/local/libexec/psdf:Again, the limits apply to the local users only. If you have
set up access to your printers remotely, remote users will not get
those limits. You will need to specify the mx
capability in the remote /etc/printcap files as
well. See section Printers Installed on
Remote Hosts for more information on remote
printing.There is another specialized way to limit job sizes from remote
printers; see section Restricting Jobs
from Remote Printers.Restricting Jobs from Remote PrintersThe LPD spooling system provides several ways to restrict print
jobs submitted from remote hosts:Host restrictionsYou can control from which remote hosts a local LPD
accepts requests with the files
/etc/hosts.equiv and
/etc/hosts.lpd. LPD checks to see if an
incoming request is from a host listed in either one of these
files. If not, LPD refuses the request.The format of these files is simple: one host name per
line. Note that the file
/etc/hosts.equiv is also used by the
&man.ruserok.3; protocol, and affects programs like
&man.rsh.1; and &man.rcp.1;, so be careful.For example, here is the
/etc/hosts.lpd file on the host
rose:orchid
violet
madrigal.fishbaum.deThis means rose will accept requests from
the hosts orchid, violet,
and madrigal.fishbaum.de. If any
other host tries to access rose's
LPD, the job will be refused.Size restrictionsYou can control how much free space there needs to remain
on the filesystem where a spooling directory resides. Make a
file called minfree in the spooling
directory for the local printer. Insert in that file a number
representing how many disk blocks (512 bytes) of free space
there has to be for a remote job to be accepted.This lets you insure that remote users will not fill your
filesystem. You can also use it to give a certain priority to
local users: they will be able to queue jobs long after the
free disk space has fallen below the amount specified in the
minfree file.For example, let us add a minfree
file for the printer bamboo. We examine
/etc/printcap to find the spooling
directory for this printer; here is bamboo's
entry:bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
:sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\
:lp=/dev/ttyd5:fs#0x82000e1:xs#0x820:rw:mx#5000:\
:if=/usr/local/libexec/psif:\
:df=/usr/local/libexec/psdf:The spooling directory is the given in the
sd capability. We will make three
megabytes (which is 6144 disk blocks) the amount of free disk
space that must exist on the filesystem for LPD to accept
remote jobs:&prompt.root; echo 6144 > /var/spool/lpd/bam
boo/minfreeUser restrictionsYou can control which remote users can print to local
printers by specifying the rs capability in
/etc/printcap. When
rs appears in the entry for a
locally-attached printer, LPD will accept jobs from remote
hosts if the user submitting the job also
has an account of the same login name on the local host.
Otherwise, LPD refuses the job.This capability is particularly useful in an environment
where there are (for example) different departments sharing a
network, and some users transcend departmental boundaries. By
giving them accounts on your systems, they can use your
printers from their own departmental systems. If you would
rather allow them to use only your
printers and not your compute resources, you can give them
token accounts, with no home directory and a
useless shell like /usr/bin/false.Accounting for Printer UsageaccountingprinterSo, you need to charge for printouts. And why not? Paper and ink
cost money. And then there are maintenance costs—printers are
loaded with moving parts and tend to break down. You have examined
your printers, usage patterns, and maintenance fees and have come up
with a per-page (or per-foot, per-meter, or per-whatever) cost. Now,
how do you actually start accounting for printouts?Well, the bad news is the LPD spooling system does not provide
much help in this department. Accounting is highly dependent on the
kind of printer in use, the formats being printed, and
your requirements in charging for printer
usage.To implement accounting, you have to modify a printer's text
filter (to charge for plain text jobs) and the conversion filters (to
charge for other file formats), to count pages or query the printer
for pages printed. You cannot get away with using the simple output
filter, since it cannot do accounting. See section Filters.Generally, there are two ways to do accounting:Periodic accounting is the more common
way, possibly because it is easier. Whenever someone prints a
job, the filter logs the user, host, and number of pages to an
accounting file. Every month, semester, year, or whatever time
period you prefer, you collect the accounting files for the
various printers, tally up the pages printed by users, and charge
for usage. Then you truncate all the logging files, starting with
a clean slate for the next period.Timely accounting is less common,
probably because it is more difficult. This method has the
filters charge users for printouts as soon as they use the
printers. Like disk quotas, the accounting is immediate. You can
prevent users from printing when their account goes in the red,
and might provide a way for users to check and adjust their
print quotas. But this method requires some database
code to track users and their quotas.The LPD spooling system supports both methods easily: since you
have to provide the filters (well, most of the time), you also have to
provide the accounting code. But there is a bright side: you have
enormous flexibility in your accounting methods. For example, you
choose whether to use periodic or timely accounting. You choose what
information to log: user names, host names, job types, pages printed,
square footage of paper used, how long the job took to print, and so
forth. And you do so by modifying the filters to save this
information.Quick and Dirty Printer AccountingFreeBSD comes with two programs that can get you set up with
simple periodic accounting right away. They are the text filter
lpf, described in section lpf: a Text Filter, and
&man.pac.8;, a program to gather and total
entries from printer accounting files.As mentioned in the section on filters (Filters), LPD starts
the text and the conversion filters with the name of the accounting
file to use on the filter command line. The filters can use this
argument to know where to write an accounting file entry. The name
of this file comes from the af capability in
/etc/printcap, and if not specified as an
absolute path, is relative to the spooling directory.LPD starts lpf with page width and length
arguments (from the pw and pl
capabilities). lpf uses these arguments to
determine how much paper will be used. After sending the file to
the printer, it then writes an accounting entry in the accounting
file. The entries look like this:2.00 rose:andy
3.00 rose:kelly
3.00 orchid:mary
5.00 orchid:mary
2.00 orchid:zhangYou should use a separate accounting file for each printer, as
lpf has no file locking logic built into it, and
two lpfs might corrupt each other's entries if
they were to write to the same file at the same time. A easy way to
insure a separate accounting file for each printer is to use
af=acct in /etc/printcap.
Then, each accounting file will be in the spooling directory for a
printer, in a file named acct.When you are ready to charge users for printouts, run the
&man.pac.8; program. Just change to the spooling directory for
the printer you want to collect on and type pac.
You will get a dollar-centric summary like the following: Login pages/feet runs price
orchid:kelly 5.00 1 $ 0.10
orchid:mary 31.00 3 $ 0.62
orchid:zhang 9.00 1 $ 0.18
rose:andy 2.00 1 $ 0.04
rose:kelly 177.00 104 $ 3.54
rose:mary 87.00 32 $ 1.74
rose:root 26.00 12 $ 0.52
total 337.00 154 $ 6.74These are the arguments &man.pac.8; expects:Which printer to summarize.
This option works only if there is an absolute path in the
af capability in
/etc/printcap.Sort the output by cost instead of alphabetically by user
name.Ignore host name in the accounting files. With this
option, user smith on host
alpha is the same user
smith on host gamma.
Without, they are different users.Compute charges with price
dollars per page or per foot instead of the price from the
pc capability in
/etc/printcap, or two cents (the
default). You can specify price as
a floating point number.Reverse the sort order.Make an accounting summary file and truncate the
accounting file.name…Print accounting information for the given user
names only.In the default summary that &man.pac.8; produces, you see the
number of pages printed by each user from various hosts. If, at
your site, host does not matter (because users can use any host),
run pac -m, to produce the following
summary: Login pages/feet runs price
andy 2.00 1 $ 0.04
kelly 182.00 105 $ 3.64
mary 118.00 35 $ 2.36
root 26.00 12 $ 0.52
zhang 9.00 1 $ 0.18
total 337.00 154 $ 6.74To compute the dollar amount due,
&man.pac.8; uses the pc capability in the
/etc/printcap file (default of 200, or 2 cents
per page). Specify, in hundredths of cents, the price per page or
per foot you want to charge for printouts in this capability. You
can override this value when you run &man.pac.8; with the
option. The units for the
option are in dollars, though, not hundredths of cents. For
example,
&prompt.root; pac -p1.50
makes each page cost one dollar and fifty cents. You can really
rake in the profits by using this option.Finally, running pac -s will save the summary
information in a summary accounting file, which is named the same as
the printer's accounting file, but with _sum
appended to the name. It then truncates the accounting file. When
you run &man.pac.8; again, it rereads the
summary file to get starting totals, then adds information from the
regular accounting file.How Can You Count Pages Printed?In order to perform even remotely accurate accounting, you need
to be able to determine how much paper a job uses. This is the
essential problem of printer accounting.For plain text jobs, the problem is not that hard to solve: you
count how many lines are in a job and compare it to how many lines
per page your printer supports. Do not forget to take into account
backspaces in the file which overprint lines, or long logical lines
that wrap onto one or more additional physical lines.The text filter lpf (introduced in lpf: a Text Filter) takes
into account these things when it does accounting. If you are
writing a text filter which needs to do accounting, you might want
to examine lpf's source code.How do you handle other file formats, though?Well, for DVI-to-LaserJet or DVI-to-PostScript conversion, you
can have your filter parse the diagnostic output of
dvilj or dvips and look to see
how many pages were converted. You might be able to do similar
things with other file formats and conversion programs.But these methods suffer from the fact that the printer may not
actually print all those pages. For example, it could jam, run out
of toner, or explode—and the user would still get
charged.So, what can you do?There is only one sure way to do
accurate accounting. Get a printer that can
tell you how much paper it uses, and attach it via a serial line or
a network connection. Nearly all PostScript printers support this
notion. Other makes and models do as well (networked Imagen laser
printers, for example). Modify the filters for these printers to
get the page usage after they print each job and have them log
accounting information based on that value
only. There is no line counting nor
error-prone file examination required.Of course, you can always be generous and make all printouts
free.Using PrintersprinterusageThis section tells you how to use printers you have setup with
FreeBSD. Here is an overview of the user-level commands:&man.lpr.1;Print jobs&man.lpq.1;Check printer queues&man.lprm.1;Remove jobs from a printer's queueThere is also an administrative command, &man.lpc.8;, described in
the section Administrating the LPD
Spooler, used to control printers and their queues.All three of the commands &man.lpr.1;, &man.lprm.1;, and &man.lpq.1;
accept an option to specify on which
printer/queue to operate, as listed in the
/etc/printcap file. This enables you to submit,
remove, and check on jobs for various printers. If you do not use the
option, then these commands use the printer
specified in the PRINTER environment variable. Finally,
if you do not have a PRINTER environment variable, these
commands default to the printer named lp.Hereafter, the terminology default printer
means the printer named in the PRINTER environment
variable, or the printer named lp when there is no
PRINTER environment variable.Printing JobsTo print files, type:&prompt.user; lpr filename...printingThis prints each of the listed files to the default printer. If
you list no files, &man.lpr.1; reads data to
print from standard input. For example, this command prints some
important system files:&prompt.user; lpr /etc/host.conf /etc/hosts.equivTo select a specific printer, type:&prompt.user; lpr -P printer-namefilename...This example prints a long listing of the current directory to the
printer named rattan:&prompt.user; ls -l | lpr -P rattanBecause no files were listed for the
&man.lpr.1; command, lpr read the data to print
from standard input, which was the output of the ls
-l command.The &man.lpr.1; command can also accept a wide variety of options
to control formatting, apply file conversions, generate multiple
copies, and so forth. For more information, see the section Printing Options.Checking Jobsprint jobsWhen you print with &man.lpr.1;, the data you wish to print is put
together in a package called a print job, which is sent
to the LPD spooling system. Each printer has a queue of jobs, and
your job waits in that queue along with other jobs from yourself and
from other users. The printer prints those jobs in a first-come,
first-served order.To display the queue for the default printer, type &man.lpq.1;.
For a specific printer, use the option. For
example, the command
&prompt.user; lpq -P bamboo
shows the queue for the printer named bamboo. Here
is an example of the output of the lpq
command:bamboo is ready and printing
Rank Owner Job Files Total Size
active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes
2nd kelly 10 (standard input) 1635 bytes
3rd mary 11 ... 78519 bytesThis shows three jobs in the queue for bamboo.
The first job, submitted by user kelly, got assigned job
number 9. Every job for a printer gets a unique job number.
Most of the time you can ignore the job number, but you will need it
if you want to cancel the job; see section Removing Jobs for details.Job number nine consists of two files; multiple files given on the
&man.lpr.1; command line are treated as part of a single job. It
is the currently active job (note the word active
under the Rank column), which means the printer should
be currently printing that job. The second job consists of data
passed as the standard input to the &man.lpr.1; command. The third
job came from user mary; it is a much larger
job. The pathname of the files she's trying to print is too long to
fit, so the &man.lpq.1; command just shows three dots.The very first line of the output from &man.lpq.1; is also useful:
it tells what the printer is currently doing (or at least what LPD
thinks the printer is doing).The &man.lpq.1; command also support a option
to generate a detailed long listing. Here is an example of
lpq -l:waiting for bamboo to become ready (offline ?)
kelly: 1st [job 009rose]
/etc/host.conf 73 bytes
/etc/hosts.equiv 15 bytes
kelly: 2nd [job 010rose]
(standard input) 1635 bytes
mary: 3rd [job 011rose]
/home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytesRemoving JobsIf you change your mind about printing a job, you can remove the
job from the queue with the &man.lprm.1; command. Often, you can
even use &man.lprm.1; to remove an active job, but some or all of the
job might still get printed.To remove a job from the default printer, first use
&man.lpq.1; to find the job number. Then type:&prompt.user; lprm job-numberTo remove the job from a specific printer, add the
option. The following command removes job number
10 from the queue for the printer bamboo:&prompt.user; lprm -P bamboo 10The &man.lprm.1; command has a few shortcuts:lprm -Removes all jobs (for the default printer) belonging to
you.lprm userRemoves all jobs (for the default printer) belonging to
user. The superuser can remove other
users' jobs; you can remove only your own jobs.lprmWith no job number, user name, or
appearing on the command line,
&man.lprm.1; removes the currently active job on the
default printer, if it belongs to you. The superuser can remove
any active job.Just use the option with the above shortcuts
to operate on a specific printer instead of the default. For example,
the following command removes all jobs for the current user in the
queue for the printer named rattan:&prompt.user; lprm -P rattan -If you are working in a networked environment, &man.lprm.1; will
let you remove jobs only from the
host from which the jobs were submitted, even if the same printer is
available from other hosts. The following command sequence
demonstrates this:&prompt.user; lpr -P rattan myfile
&prompt.user; rlogin orchid
&prompt.user; lpq -P rattan
Rank Owner Job Files Total Size
active seeyan 12 ... 49123 bytes
2nd kelly 13 myfile 12 bytes
&prompt.user; lprm -P rattan 13
rose: Permission denied
&prompt.user; logout
&prompt.user; lprm -P rattan 13
dfA013rose dequeued
cfA013rose dequeued
Beyond Plain Text: Printing OptionsThe &man.lpr.1; command supports a number of options that control
formatting text, converting graphic and other file formats, producing
multiple copies, handling of the job, and more. This section
describes the options.Formatting and Conversion OptionsThe following &man.lpr.1; options control formatting of the
files in the job. Use these options if the job does not contain
plain text or if you want plain text formatted through the
&man.pr.1; utility.TeXFor example, the following command prints a DVI file (from the
TeX typesetting system) named fish-report.dvi
to the printer named bamboo:&prompt.user; lpr -P bamboo -d fish-report.dviThese options apply to every file in the job, so you cannot mix
(say) DVI and ditroff files together in a job. Instead, submit the
files as separate jobs, using a different conversion option for each
job.All of these options except and
require conversion filters installed for the
destination printer. For example, the option
requires the DVI conversion filter. Section Conversion
Filters gives details.Print cifplot files.Print DVI files.Print FORTRAN text files.Print plot data.Indent the output by number
columns; if you omit number, indent
by 8 columns. This option works only with certain conversion
filters.Do not put any space between the and
the number.Print literal text data, including control
characters.Print ditroff (device independent troff) data.-pFormat plain text with &man.pr.1; before printing. See
&man.pr.1; for more information.Use title on the
&man.pr.1; header instead of the file name. This option has
effect only when used with the
option.Print troff data.Print raster data.Here is an example: this command prints a nicely formatted
version of the &man.ls.1; manual page on the default printer:&prompt.user; zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -tThe &man.zcat.1; command uncompresses the source of the
&man.ls.1; manual page and passes it to the &man.troff.1;
command, which formats that source and makes GNU troff
output and passes it to &man.lpr.1;, which submits the job
to the LPD spooler. Because we used the
option to &man.lpr.1;, the spooler will convert the GNU
troff output into a format the default printer can
understand when it prints the job.Job Handling OptionsThe following options to &man.lpr.1; tell LPD to handle the job
specially:-# copiesProduce a number of copies of
each file in the job instead of just one copy. An
administrator may disable this option to reduce printer
wear-and-tear and encourage photocopier usage. See section
Restricting
Multiple Copies.This example prints three copies of
parser.c followed by three copies of
parser.h to the default printer:&prompt.user; lpr -#3 parser.c parser.h-mSend mail after completing the print job. With this
option, the LPD system will send mail to your account when it
finishes handling your job. In its message, it will tell you
if the job completed successfully or if there was an error,
and (often) what the error was.-sDo not copy the files to the spooling directory, but make
symbolic links to them instead.If you are printing a large job, you probably want to use
this option. It saves space in the spooling directory (your
job might overflow the free space on the filesystem where the
spooling directory resides). It saves time as well since LPD
will not have to copy each and every byte of your job to the
spooling directory.There is a drawback, though: since LPD will refer to the
original files directly, you cannot modify or remove them
until they have been printed.If you are printing to a remote printer, LPD will
eventually have to copy files from the local host to the
remote host, so the option will save
space only on the local spooling directory, not the remote.
It is still useful, though.-rRemove the files in the job after copying them to the
spooling directory, or after printing them with the
option. Be careful with this
option!Header Page OptionsThese options to &man.lpr.1; adjust the text that normally
appears on a job's header page. If header pages are suppressed for
the destination printer, these options have no effect. See section
Header Pages
for information about setting up header pages.-C textReplace the hostname on the header page with
text. The hostname is normally the
name of the host from which the job was submitted.-J textReplace the job name on the header page with
text. The job name is normally the
name of the first file of the job, or
stdin if you are printing standard
input.-hDo not print any header page.At some sites, this option may have no effect due to the
way header pages are generated. See Header
Pages for details.Administrating PrintersAs an administrator for your printers, you have had to install,
set up, and test them. Using the &man.lpc.8; command, you
can interact with your printers in yet more ways. With &man.lpc.8;,
you canStart and stop the printersEnable and disable their queuesRearrange the order of the jobs in each queue.First, a note about terminology: if a printer is
stopped, it will not print anything in its queue.
Users can still submit jobs, which will wait in the queue until the
printer is started or the queue is
cleared.If a queue is disabled, no user (except root)
can submit jobs for the printer. An enabled
queue allows jobs to be submitted. A printer can be
started for a disabled queue, in which case it
will continue to print jobs in the queue until the queue is
empty.In general, you have to have root privileges to use the
&man.lpc.8; command. Ordinary users can use the &man.lpc.8; command
to get printer status and to restart a hung printer only.Here is a summary of the &man.lpc.8; commands. Most of the
commands takes a printer-name argument to
tell on which printer to operate. You can use all
for the printer-name to mean all printers
listed in /etc/printcap.abort
printer-nameCancel the current job and stop the printer. Users can
still submit jobs if the queue's enabled.clean
printer-nameRemove old files from the printer's spooling directory.
Occasionally, the files that make up a job are not properly
removed by LPD, particularly if there have been errors during
printing or a lot of administrative activity. This command
finds files that do not belong in the spooling directory and
removes them.disable
printer-nameDisable queuing of new jobs. If the printer's started, it
will continue to print any jobs remaining in the queue. The
superuser (root) can always submit jobs, even to a disabled
queue.This command is useful while you are testing a new printer
or filter installation: disable the queue and submit jobs as
root. Other users will not be able to submit jobs until you
complete your testing and re-enable the queue with the
enable command.down printer-namemessageTake a printer down. Equivalent to
disable followed by stop.
The message appears as the printer's
status whenever a user checks the printer's queue with
&man.lpq.1; or status with lpc
status.enable
printer-nameEnable the queue for a printer. Users can submit jobs but
the printer will not print anything until it is started.help
command-namePrint help on the command
command-name. With no
command-name, print a summary of the
commands available.restart
printer-nameStart the printer. Ordinary users can use this command if
some extraordinary circumstance hangs LPD, but they cannot start
a printer stopped with either the stop or
down commands. The
restart command is equivalent to
abort followed by
start.start
printer-nameStart the printer. The printer will print jobs in its
queue.stop
printer-nameStop the printer. The printer will finish the current job
and will not print anything else in its queue. Even though the
printer is stopped, users can still submit jobs to an enabled
queue.topq printer-namejob-or-usernameRearrange the queue for
printer-name by placing the jobs with
the listed job numbers or the jobs
belonging to username at the top of
the queue. For this command, you cannot use
all as the
printer-name.up
printer-nameBring a printer up; the opposite of the
down command. Equivalent to
start followed by
enable.&man.lpc.8; accepts the above commands on the command line. If
you do not enter any commands, &man.lpc.8; enters an interactive mode,
where you can enter commands until you type exit,
quit, or end-of-file.Alternatives to the Standard SpoolerIf you have been reading straight through this manual, by now you
have learned just about everything there is to know about the LPD
spooling system that comes with FreeBSD. You can probably appreciate
many of its shortcomings, which naturally leads to the question:
What other spooling systems are out there (and work with
FreeBSD)?LPRngLPRngLPRng, which purportedly means LPR: the Next
Generation is a complete rewrite of PLP. Patrick Powell
and Justin Mason (the principal maintainer of PLP) collaborated to
make LPRng. The main site for LPRng is http://www.astart.com/lprng/LPRng.html.TroubleshootingAfter performing the simple test with &man.lptest.1;, you might
have gotten one of the following results instead of the correct
printout:It worked, after awhile; or, it did not eject a full
sheet.The printer printed the above, but it sat for awhile and
did nothing. In fact, you might have needed to press a
PRINT REMAINING or FORM FEED button on the printer to get any
results to appear.If this is the case, the printer was probably waiting to
see if there was any more data for your job before it printed
anything. To fix this problem, you can have the text filter
send a FORM FEED character (or whatever is necessary) to the
printer. This is usually sufficient to have the printer
immediately print any text remaining in its internal buffer.
It is also useful to make sure each print job ends on a full
sheet, so the next job does not start somewhere on the middle
of the last page of the previous job.The following replacement for the shell script
/usr/local/libexec/if-simple prints a
form feed after it sends the job to the printer:#!/bin/sh
#
# if-simple - Simple text input filter for lpd
# Installed in /usr/local/libexec/if-simple
#
# Simply copies stdin to stdout. Ignores all filter arguments.
# Writes a form feed character (\f) after printing job.
/bin/cat && printf "\f" && exit 0
exit 2It produced the staircase effect.You got the following on paper:!"#$%&'()*+,-./01234
"#$%&'()*+,-./012345
#$%&'()*+,-./0123456MS-DOSOS/2ASCIIYou have become another victim of the staircase
effect, caused by conflicting interpretations of
what characters should indicate a new line. Unix-style
operating systems use a single character: ASCII code 10, the
line feed (LF). MS-DOS, OS/2, and others uses a pair of
characters, ASCII code 10 and ASCII code
13 (the carriage return or CR). Many printers use the MS-DOS
convention for representing new-lines.When you print with FreeBSD, your text used just the line
feed character. The printer, upon seeing a line feed
character, advanced the paper one line, but maintained the
same horizontal position on the page for the next character
to print. That is what the carriage return is for: to move
the location of the next character to print to the left edge
of the paper.Here is what FreeBSD wants your printer to do:Printer received CRPrinter prints CRPrinter received LFPrinter prints CR + LFHere are some ways to achieve this:Use the printer's configuration switches or control
panel to alter its interpretation of these characters.
Check your printer's manual to find out how to do
this.If you boot your system into other operating systems
besides FreeBSD, you may have to
reconfigure the printer to use a an
interpretation for CR and LF characters that those other
operating systems use. You might prefer one of the other
solutions, below.Have FreeBSD's serial line driver automatically
convert LF to CR+LF. Of course, this works with printers
on serial ports only. To enable this
feature, set the CRMOD bit in fs
capability in the /etc/printcap file
for the printer.Send an escape code to the
printer to have it temporarily treat LF characters
differently. Consult your printer's manual for escape
codes that your printer might support. When you find the
proper escape code, modify the text filter to send the
code first, then send the print job.PCLHere is an example text filter for printers that
understand the Hewlett-Packard PCL escape codes. This
filter makes the printer treat LF characters as a LF and
CR; then it sends the job; then it sends a form feed to
eject the last page of the job. It should work with
nearly all Hewlett Packard printers.#!/bin/sh
#
# hpif - Simple text input filter for lpd for HP-PCL based printers
# Installed in /usr/local/libexec/hpif
#
# Simply copies stdin to stdout. Ignores all filter arguments.
# Tells printer to treat LF as CR+LF. Ejects the page when done.
printf "\033&k2G" && cat && printf "\033&l0H" && exit 0
exit 2Here is an example /etc/printcap
from a host called orchid. It has a single printer
attached to its first parallel port, a Hewlett Packard
LaserJet 3Si named teak. It is using the
above script as its text filter:#
# /etc/printcap for host orchid
#
teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\
:lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\
:if=/usr/local/libexec/hpif:It overprinted each line.The printer never advanced a line. All of the lines of
text were printed on top of each other on one line.This problem is the opposite of the
staircase effect, described above, and is much rarer.
Somewhere, the LF characters that FreeBSD uses to end a line
are being treated as CR characters to return the print
location to the left edge of the paper, but not also down a
line.Use the printer's configuration switches or control panel
to enforce the following interpretation of LF and CR
characters:Printer receivesPrinter printsCRCRLFCR + LFThe printer lost characters.While printing, the printer did not print a few characters
in each line. The problem might have gotten worse as the
printer ran, losing more and more characters.The problem is that the printer cannot keep up with the
speed at which the computer sends data over a serial line
(this problem should not occur with printers on parallel
ports). There are two ways to overcome the problem:If the printer supports XON/XOFF flow control, have
FreeBSD use it by specifying the TANDEM bit in the
fs capability.If the printer supports carrier flow control, specify
the MDMBUF bit in the fs capability.
Make sure the cable connecting the printer to the computer
is correctly wired for carrier flow control.If the printer does not support any flow control, use
some combination of the NLDELAY, TBDELAY, CRDELAY, VTDELAY,
and BSDELAY bits in the fs capability
to add appropriate delays to the stream of data sent to
the printer.It printed garbage.The printer printed what appeared to be random garbage,
but not the desired text.This is usually another symptom of incorrect
communications parameters with a serial printer. Double-check
the bps rate in the br capability, and the
parity bits in the fs and
fc capabilities; make sure the printer is
using the same settings as specified in the
/etc/printcap file.Nothing happened.If nothing happened, the problem is probably within
FreeBSD and not the hardware. Add the log file
(lf) capability to the entry for the
printer you are debugging in the
/etc/printcap file. For example, here is
the entry for rattan, with the
lf capability:rattan|line|diablo|lp|Diablo 630 Line Printer:\
:sh:sd=/var/spool/lpd/rattan:\
:lp=/dev/lpt0:\
:if=/usr/local/libexec/if-simple:\
:lf=/var/log/rattan.logThen, try printing again. Check the log file (in our
example, /var/log/rattan.log) to see any
error messages that might appear. Based on the messages you
see, try to correct the problem.If you do not specify a lf capability,
LPD uses /dev/console as a
default.
diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
index 06b23e83e7..9ee1f9df24 100644
--- a/en_US.ISO8859-1/books/handbook/security/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/security/chapter.sgml
@@ -1,3043 +1,3099 @@
+
+
+
+ Matthew
+ Dillon
+ Much of this chapter has been taken from the
+ security(7) man page by
+
+
+
+
Securitysecurity
- Much of this chapter has been taken from the
- &man.security.7; man page, originally written by
- &a.dillon;.
-
SynopsisThe following chapter will provide a basic introduction to
system security concepts, some general good rules of thumb, and some
advanced topics such as S/Key, OpenSSL, Kerberos, and others.IntroductionSecurity is a function that begins and ends with the system
administrator. While all BSD Unix multi-user systems have some
inherent security, the job of building and maintaining additional
security mechanisms to keep those users honest is
probably one of the single largest undertakings of the sysadmin.
Machines are only as secure as you make them, and security concerns
are ever competing with the human necessity for convenience. Unix
systems, in general, are capable of running a huge number of
simultaneous processes and many of these processes operate as
servers – meaning that external entities can connect and talk
to them. As yesterday's mini-computers and mainframes become
today's desktops, and as computers become networked and
internetworked, security becomes an ever bigger issue.Security is best implemented through a layered
onion approach. In a nutshell, what you want to do is
to create as many layers of security as are convenient and then
carefully monitor the system for intrusions. You do not want to
overbuild your security or you will interfere with the detection
side, and detection is one of the single most important aspects of
any security mechanism. For example, it makes little sense to set
the schg flags (see &man.chflags.1;) on every system binary because
while this may temporarily protect the binaries, it prevents an
attacker who has broken in from making an easily detectable change
that may result in your security mechanisms not detecting the attacker
at all.System security also pertains to dealing with various forms of
attack, including attacks that attempt to crash or otherwise make a
system unusable but do not attempt to break root. Security concerns
can be split up into several categories:Denial of service attacks.User account compromises.Root compromise through accessible servers.Root compromise via user accounts.Backdoor creation.DoS attacksDenial of Service (DoS)securityDoS attacksDenial of Service (DoS)Denial of Service (DoS)A denial of service attack is an action that deprives the
machine of needed resources. Typically, D.O.S. attacks are
brute-force mechanisms that attempt to crash or otherwise make a
machine unusable by overwhelming its servers or network stack. Some
D.O.S. attacks try to take advantages of bugs in the networking
stack to crash a machine with a single packet. The latter can only
be fixed by applying a bug fix to the kernel. Attacks on servers
can often be fixed by properly specifying options to limit the load
the servers incur on the system under adverse conditions.
Brute-force network attacks are harder to deal with. A
spoofed-packet attack, for example, is nearly impossible to stop
short of cutting your system off from the Internet. It may not be
able to take your machine down, but it can saturate your
Internet connection.securityaccount compromisesA user account compromise is even more common than a D.O.S.
attack. Many sysadmins still run standard telnetd, rlogind, rshd,
and ftpd servers on their machines. These servers, by default, do
not operate over encrypted connections. The result is that if you
have any moderate-sized user base, one or more of your users logging
into your system from a remote location (which is the most common
and convenient way to login to a system) will have his or her
password sniffed. The attentive system admin will analyze his
remote access logs looking for suspicious source addresses even for
successful logins.One must always assume that once an attacker has access to a
user account, the attacker can break root. However, the reality is
that in a well secured and maintained system, access to a user
account does not necessarily give the attacker access to root. The
distinction is important because without access to root the attacker
cannot generally hide his tracks and may, at best, be able to do
nothing more than mess with the user's files or crash the machine.
User account compromises are very common because users tend not to
take the precautions that sysadmins take.securitybackdoorsSystem administrators must keep in mind that there are
potentially many ways to break root on a machine. The attacker
may know the root password, the attacker may find a bug in a
root-run server and be able to break root over a network
connection to that server, or the attacker may know of a bug in
an suid-root program that allows the attacker to break root once
he has broken into a user's account. If an attacker has found
a way to break root on a machine, the attacker may not have a need
to install a backdoor. Many of the root holes
found and closed to date involve a considerable amount of work
by the attacker to cleanup after himself, so most attackers install
backdoors. Backdoors provide the attacker with a way to easily
regain root access to the system, but it also gives the smart
system administrator a convenient way to detect the intrusion.
Making it impossible for an attacker to install a backdoor may
actually be detrimental to your security because it will not
close off the hole the attacker found to break in the first
place.Security remedies should always be implemented with a
multi-layered onion peel approach and can be
categorized as follows:Securing root and staff accounts.Securing root – root-run servers and suid/sgid
binaries.Securing user accounts.Securing the password file.Securing the kernel core, raw devices, and
filesystems.Quick detection of inappropriate changes made to the
system.Paranoia.The next section of this chapter will cover the above bullet
items in greater depth.securitysecuringSecuring FreeBSDThe sections that follow will cover the methods of securing your
FreeBSD system that were mentioned in the last section of this chapter.Securing the root account and staff accountssuFirst off, do not bother securing staff accounts if you have
not secured the root account. Most systems have a password
assigned to the root account. The first thing you do is assume
that the password is always compromised.
This does not mean that you should remove the password. The
password is almost always necessary for console access to the
machine. What it does mean is that you should not make it
possible to use the password outside of the console or possibly
even with the &man.su.1; command. For example, make sure that
your pty's are specified as being unsecure in the
/etc/ttys file so that direct root logins
via telnet or rlogin are
disallowed. If using other login services such as
sshd, make sure that direct root logins
are disabled there as well. Consider every access method –
services such as FTP often fall through the cracks. Direct root
logins should only be allowed via the system console.wheelOf course, as a sysadmin you have to be able to get to root,
so we open up a few holes. But we make sure these holes require
additional password verification to operate. One way to make root
accessible is to add appropriate staff accounts to the
wheel group (in
/etc/group). The staff members placed in the
wheel group are allowed to
su to root. You should never give staff
members native wheel access by putting them in the
wheel group in their password entry. Staff
accounts should be placed in a staff group, and
then added to the wheel group via the
/etc/group file. Only those staff members
who actually need to have root access should be placed in the
wheel group. It is also possible, when using
an authentication method such as kerberos, to use kerberos'
.k5login file in the root account to allow a
&man.ksu.1; to root without having to place anyone at all in the
wheel group. This may be the better solution
since the wheel mechanism still allows an
intruder to break root if the intruder has gotten hold of your
password file and can break into a staff account. While having
the wheel mechanism is better than having
nothing at all, it is not necessarily the safest option.An indirect way to secure staff accounts, and ultimately
root access is to use an alternative login access method and
do what is known as *'ing out the crypted
password for the staff accounts. Using the &man.vipw.8;
command, one can replace each instance of a crypted password
with a single * character. This command
will update the /etc/master.passwd file
and user/password database to disable password-authenticated
logins.A staff account entry such as:foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcshShould be changed to this :foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcshThis change will prevent normal logins from occurring,
since the encrypted password will never match
*. With this done, staff members must use
another mechanism to authenticate themselves such as
&man.kerberos.1; or &man.ssh.1; using a public/private key
pair. When using something like kerberos, one generally must
secure the machines which run the kerberos servers and your
desktop workstation. When using a public/private key pair
with ssh, one must generally secure
the machine used to login from (typically
one's workstation). An additional layer of protection can be
added to the key pair by password protecting the key pair when
creating it with &man.ssh-keygen.1;. Being able to
* out the passwords for staff accounts also
guarantees that staff members can only login through secure
access methods that you have setup. This forces all staff
members to use secure, encrypted connections for all of their
sessions which closes an important hole used by many
intruders: That of sniffing the network from an unrelated,
less secure machine.The more indirect security mechanisms also assume that you are
logging in from a more restrictive server to a less restrictive
server. For example, if your main box is running all sorts of
servers, your workstation should not be running any. In order for
your workstation to be reasonably secure you should run as few
servers as possible, up to and including no servers at all, and
you should run a password-protected screen blanker. Of course,
given physical access to a workstation an attacker can break any
sort of security you put on it. This is definitely a problem that
you should consider but you should also consider the fact that the
vast majority of break-ins occur remotely, over a network, from
people who do not have physical access to your workstation or
servers.KerberosUsing something like kerberos also gives you the ability to
disable or change the password for a staff account in one place
and have it immediately effect all the machine the staff member
may have an account on. If a staff member's account gets
compromised, the ability to instantly change his password on all
machines should not be underrated. With discrete passwords,
changing a password on N machines can be a mess. You can also
impose re-passwording restrictions with kerberos: not only can a
kerberos ticket be made to timeout after a while, but the kerberos
system can require that the user choose a new password after a
certain period of time (say, once a month).Securing Root-run Servers and SUID/SGID BinariesntalkcomsatfingersandboxessshdtelnetdrshdrlogindThe prudent sysadmin only runs the servers he needs to, no
more, no less. Be aware that third party servers are often the
most bug-prone. For example, running an old version of imapd or
popper is like giving a universal root ticket out to the entire
world. Never run a server that you have not checked out
carefully. Many servers do not need to be run as root. For
example, the ntalk,
comsat, and
finger daemons can be run in special
user sandboxes. A sandbox isn't perfect unless
you go to a large amount of trouble, but the onion approach to
security still stands: If someone is able to break in through
a server running in a sandbox, they still have to break out of the
sandbox. The more layers the attacker must break through, the
lower the likelihood of his success. Root holes have historically
been found in virtually every server ever run as root, including
basic system servers. If you are running a machine through which
people only login via sshd and never
login via telnetd or
rshd or
rlogind, then turn off those
services!FreeBSD now defaults to running
ntalkd,
comsat, and
finger in a sandbox. Another program
which may be a candidate for running in a sandbox is &man.named.8;.
/etc/defaults/rc.conf includes the arguments
necessary to run named in a sandbox in a
commented-out form. Depending on whether you are installing a new
system or upgrading an existing system, the special user accounts
used by these sandboxes may not be installed. The prudent
sysadmin would research and implement sandboxes for servers
whenever possible.sendmailThere are a number of other servers that typically do not run
in sandboxes: sendmail,
popper,
imapd, ftpd,
and others. There are alternatives to some of these, but
installing them may require more work than you are willing to
perform (the convenience factor strikes again). You may have to
run these servers as root and rely on other mechanisms to detect
break-ins that might occur through them.The other big potential root hole in a system are the
suid-root and sgid binaries installed on the system. Most of
these binaries, such as rlogin, reside
in /bin, /sbin,
/usr/bin, or /usr/sbin.
While nothing is 100% safe, the system-default suid and sgid
binaries can be considered reasonably safe. Still, root holes are
occasionally found in these binaries. A root hole was found in
Xlib in 1998 that made
xterm (which is typically suid)
vulnerable. It is better to be safe than sorry and the prudent
sysadmin will restrict suid binaries that only staff should run to
a special group that only staff can access, and get rid of
(chmod 000) any suid binaries that nobody uses.
A server with no display generally does not need an
xterm binary. Sgid binaries can be
almost as dangerous. If an intruder can break an sgid-kmem binary
the intruder might be able to read /dev/kmem
and thus read the crypted password file, potentially compromising
any passworded account. Alternatively an intruder who breaks
group kmem can monitor keystrokes sent through
pty's, including pty's used by users who login through secure
methods. An intruder that breaks the tty group can write to
almost any user's tty. If a user is running a terminal program or
emulator with a keyboard-simulation feature, the intruder can
potentially generate a data stream that causes the user's terminal
to echo a command, which is then run as that user.Securing User AccountsUser accounts are usually the most difficult to secure. While
you can impose Draconian access restrictions on your staff and
* out their passwords, you may not be able to
do so with any general user accounts you might have. If you do
have sufficient control then you may win out and be able to secure
the user accounts properly. If not, you simply have to be more
vigilant in your monitoring of those accounts. Use of
ssh and kerberos for user accounts is
more problematic due to the extra administration and technical
support required, but still a very good solution compared to a
crypted password file.Securing the Password FileThe only sure fire way is to * out as many
passwords as you can and use ssh or
kerberos for access to those accounts. Even though the crypted
password file (/etc/spwd.db) can only be read
by root, it may be possible for an intruder to obtain read access
to that file even if the attacker cannot obtain root-write
access.Your security scripts should always check for and report
changes to the password file (see Checking file integrity
below).Securing the Kernel Core, Raw Devices, and
FilesystemsIf an attacker breaks root he can do just about anything, but
there are certain conveniences. For example, most modern kernels
have a packet sniffing device driver built in. Under FreeBSD it
is called the bpf device. An intruder
will commonly attempt to run a packet sniffer on a compromised
machine. You do not need to give the intruder the capability and
most systems should not have the bpf device compiled in.sysctlBut even if you turn off the bpf device, you still have
/dev/mem and /dev/kmem
to worry about. For that matter, the intruder can still write to
raw disk devices. Also, there is another kernel feature called
the module loader, &man.kldload.8;. An enterprising intruder can
use a KLD module to install his own bpf device or other sniffing
device on a running kernel. To avoid these problems you have to
run the kernel at a higher secure level, at least securelevel 1.
The securelevel can be set with a sysctl on
the kern.securelevel variable. Once you have
set the securelevel to 1, write access to raw devices will be
denied and special chflags flags, such as schg,
will be enforced. You must also ensure that the
schg flag is set on critical startup binaries,
directories, and script files – everything that gets run up
to the point where the securelevel is set. This might be overdoing
it, and upgrading the system is much more difficult when you
operate at a higher secure level. You may compromise and run the
system at a higher secure level but not set the
schg flag for every system file and directory
under the sun. Another possibility is to simply mount
/ and /usr read-only.
It should be noted that being too Draconian in what you attempt to
protect may prevent the all-important detection of an
intrusion.Checking File Integrity: Binaries, Configuration Files,
Etc.When it comes right down to it, you can only protect your core
system configuration and control files so much before the
convenience factor rears its ugly head. For example, using
chflags to set the schg bit
on most of the files in / and
/usr is probably counterproductive because
while it may protect the files, it also closes a detection window.
The last layer of your security onion is perhaps the most
important – detection. The rest of your security is pretty
much useless (or, worse, presents you with a false sense of
safety) if you cannot detect potential incursions. Half the job
of the onion is to slow down the attacker rather than stop him in
order to give the detection side of the equation a chance to catch
him in the act.The best way to detect an incursion is to look for modified,
missing, or unexpected files. The best way to look for modified
files is from another (often centralized) limited-access system.
Writing your security scripts on the extra-secure limited-access
system makes them mostly invisible to potential attackers, and this
is important. In order to take maximum advantage you generally
have to give the limited-access box significant access to the
other machines in the business, usually either by doing a
read-only NFS export of the other machines to the limited-access
box, or by setting up ssh key-pairs to
allow the limit-access box to ssh to
the other machines. Except for its network traffic, NFS is the
least visible method – allowing you to monitor the
filesystems on each client box virtually undetected. If your
limited-access server is connected to the client boxes through a
switch, the NFS method is often the better choice. If your
limited-access server is connected to the client boxes through a
hub or through several layers of routing, the NFS method may be
too insecure (network-wise) and using
ssh may be the better choice even with
the audit-trail tracks that ssh
lays.Once you give a limit-access box at least read access to the
client systems it is supposed to monitor, you must write scripts
to do the actual monitoring. Given an NFS mount, you can write
scripts out of simple system utilities such as &man.find.1; and
&man.md5.1;. It is best to physically md5 the client-box files
boxes at least once a day, and to test control files such as those
found in /etc and
/usr/local/etc even more often. When
mismatches are found relative to the base md5 information the
limited-access machine knows is valid, it should scream at a
sysadmin to go check it out. A good security script will also
check for inappropriate suid binaries and for new or deleted files
on system partitions such as / and
/usr.When using ssh rather than NFS,
writing the security script is much more difficult. You
essentially have to scp the scripts to the client box in order to
run them, making them visible, and for safety you also need to
scp the binaries (such as find) that those
scripts use. The ssh daemon on the
client box may already be compromised. All in all, using
ssh may be necessary when running over
unsecure links, but it's also a lot harder to deal with.A good security script will also check for changes to user and
staff members access configuration files:
.rhosts, .shosts,
.ssh/authorized_keys and so forth…
files that might fall outside the purview of the
MD5 check.If you have a huge amount of user disk space it may take too
long to run through every file on those partitions. In this case,
setting mount flags to disallow suid binaries and devices on those
partitions is a good idea. The nodev and
nosuid options (see &man.mount.8;) are what you
want to look into. You should probably scan them anyway at least
once a week, since the object of this layer is to detect a break-in
whether or not the break-in is effective.Process accounting (see &man.accton.8;) is a relatively
low-overhead feature of the operating system which might help
as a post-break-in evaluation mechanism. It is especially
useful in tracking down how an intruder has actually broken into
a system, assuming the file is still intact after the break-in
occurs.Finally, security scripts should process the log files and the
logs themselves should be generated in as secure a manner as
possible – remote syslog can be very useful. An intruder
tries to cover his tracks, and log files are critical to the
sysadmin trying to track down the time and method of the initial
break-in. One way to keep a permanent record of the log files is
to run the system console to a serial port and collect the
information on a continuing basis through a secure machine
monitoring the consoles.ParanoiaA little paranoia never hurts. As a rule, a sysadmin can add
any number of security features as long as they do not effect
convenience, and can add security features that do effect
convenience with some added thought. Even more importantly, a
security administrator should mix it up a bit – if you use
recommendations such as those given by this document verbatim, you
give away your methodologies to the prospective attacker who also
has access to this document.Denial of Service AttacksDenial of Service (DoS)This section covers Denial of Service attacks. A DoS attack
is typically a packet attack. While there is not much you can do
about modern spoofed packet attacks that saturate your network,
you can generally limit the damage by ensuring that the attacks
cannot take down your servers.Limiting server forks.Limiting springboard attacks (ICMP response attacks, ping
broadcast, etc.).Kernel Route Cache.A common DoS attack is against a forking server that attempts
to cause the server to eat processes, file descriptors, and memory
until the machine dies. Inetd (see &man.inetd.8;) has several
options to limit this sort of attack. It should be noted that
while it is possible to prevent a machine from going down it is
not generally possible to prevent a service from being disrupted
by the attack. Read the inetd manual page carefully and pay
specific attention to the , ,
and options. Note that spoofed-IP attacks
will circumvent the option to inetd, so
typically a combination of options must be used. Some standalone
servers have self-fork-limitation parameters.Sendmail has its
option which tends to work
much better than trying to use sendmail's load limiting options
due to the load lag. You should specify a
MaxDaemonChildren parameter when you start
sendmail high enough to handle your
expected load but no so high that the computer cannot handle that
number of sendmails without falling on
its face. It is also prudent to run sendmail in queued mode
() and to run the daemon
(sendmail -bd) separate from the queue-runs
(sendmail -q15m). If you still want real-time
delivery you can run the queue at a much lower interval, such as
, but be sure to specify a reasonable
MaxDaemonChildren option for that sendmail to
prevent cascade failures.Syslogd can be attacked directly
and it is strongly recommended that you use the
option whenever possible, and the option
otherwise.You should also be fairly careful with connect-back services
such as tcpwrapper's reverse-identd,
which can be attacked directly. You generally do not want to use
the reverse-ident feature of
tcpwrappers for this reason.It is a very good idea to protect internal services from
external access by firewalling them off at your border routers.
The idea here is to prevent saturation attacks from outside your
LAN, not so much to protect internal services from network-based
root compromise. Always configure an exclusive firewall, i.e.,
firewall everything except ports A, B,
C, D, and M-Z. This way you can firewall off all of your
low ports except for certain specific services such as
named (if you are primary for a zone),
ntalkd,
sendmail, and other Internet-accessible
services. If you try to configure the firewall the other way
– as an inclusive or permissive firewall, there is a good
chance that you will forget to close a couple of
services or that you will add a new internal service and forget
to update the firewall. You can still open up the high-numbered
port range on the firewall to allow permissive-like operation
without compromising your low ports. Also take note that FreeBSD
allows you to control the range of port numbers used for dynamic
binding via the various net.inet.ip.portrangesysctl's (sysctl -a | fgrep
portrange), which can also ease the complexity of your
firewall's configuration. For example, you might use a normal
first/last range of 4000 to 5000, and a hiport range of 49152 to
65535, then block everything under 4000 off in your firewall
(except for certain specific Internet-accessible ports, of
course).ICMP_BANDLIMAnother common DoS attack is called a springboard attack
– to attack a server in a manner that causes the server to
generate responses which then overload the server, the local
network, or some other machine. The most common attack of this
nature is the ICMP ping broadcast attack.
The attacker spoofs ping packets sent to your LAN's broadcast
address with the source IP address set to the actual machine they
wish to attack. If your border routers are not configured to
stomp on ping's to broadcast addresses, your LAN winds up
generating sufficient responses to the spoofed source address to
saturate the victim, especially when the attacker uses the same
trick on several dozen broadcast addresses over several dozen
different networks at once. Broadcast attacks of over a hundred
and twenty megabits have been measured. A second common
springboard attack is against the ICMP error reporting system.
By constructing packets that generate ICMP error responses, an
attacker can saturate a server's incoming network and cause the
server to saturate its outgoing network with ICMP responses. This
type of attack can also crash the server by running it out of
mbuf's, especially if the server cannot drain the ICMP responses
it generates fast enough. The FreeBSD kernel has a new kernel
compile option called ICMP_BANDLIM which limits the effectiveness
of these sorts of attacks. The last major class of springboard
attacks is related to certain internal inetd services such as the
udp echo service. An attacker simply spoofs a UDP packet with the
source address being server A's echo port, and the destination
address being server B's echo port, where server A and B are both
on your LAN. The two servers then bounce this one packet back and
forth between each other. The attacker can overload both servers
and their LANs simply by injecting a few packets in this manner.
Similar problems exist with the internal chargen port. A
competent sysadmin will turn off all of these inetd-internal test
services.Spoofed packet attacks may also be used to overload the kernel
route cache. Refer to the net.inet.ip.rtexpire,
rtminexpire, and rtmaxcachesysctl parameters. A spoofed packet attack
that uses a random source IP will cause the kernel to generate a
temporary cached route in the route table, viewable with
netstat -rna | fgrep W3. These routes
typically timeout in 1600 seconds or so. If the kernel detects
that the cached route table has gotten too big it will dynamically
reduce the rtexpire but will never decrease it to less than
rtminexpire. There are two problems:The kernel does not react quickly enough when a lightly
loaded server is suddenly attacked.The rtminexpire is not low enough for
the kernel to survive a sustained attack.If your servers are connected to the Internet via a T3 or
better it may be prudent to manually override both
rtexpire and rtminexpire
via &man.sysctl.8;. Never set either parameter to zero (unless
you want to crash the machine. Setting both
parameters to 2 seconds should be sufficient to protect the route
table from attack.Access Issues with Kerberos and SSHsshKerberosThere are a few issues with both kerberos and
ssh that need to be addressed if
you intend to use them. Kerberos V is an excellent
authentication protocol but there are bugs in the kerberized
telnet and
rlogin applications that make them
unsuitable for dealing with binary streams. Also, by default
kerberos does not encrypt a session unless you use the
option. ssh
encrypts everything by default.ssh works quite well in every
respect except that it forwards encryption keys by default. What
this means is that if you have a secure workstation holding keys
that give you access to the rest of the system, and you
ssh to an unsecure machine, your keys
becomes exposed. The actual keys themselves are not exposed, but
ssh installs a forwarding port for the
duration of your login and if a attacker has broken root on the
unsecure machine he can utilize that port to use your keys to gain
access to any other machine that your keys unlock.We recommend that you use ssh in
combination with kerberos whenever possible for staff logins.
ssh can be compiled with kerberos
support. This reduces your reliance on potentially exposable
ssh keys while at the same time
protecting passwords via kerberos. ssh
keys should only be used for automated tasks from secure machines
(something that kerberos is unsuited to). We also recommend that
you either turn off key-forwarding in the
ssh configuration, or that you make use
of the from=IP/DOMAIN option that
ssh allows in its
authorized_keys file to make the key only
usable to entities logging in from specific machines.
+
+
+
+ Bill
+ Swingle
+ Parts rewritten and updated by
+
+
+
+
+
DES, MD5, and CryptsecuritycryptcryptDESMD5
-
- Parts rewritten and updated by &a.unfurl;, 21 March
- 2000.Every user on a Unix system has a password associated with
their account. It seems obvious that these passwords need to be
known only to the user and the actual operating system. In
order to keep these passwords secret, they are encrypted with
what is known as a one-way hash, that is, they can
only be easily encrypted but not decrypted. In other words, what
we told you a moment ago was obvious is not even true: the
operating system itself does not really know
the password. It only knows the encrypted
form of the password. The only way to get the
plain-text password is by a brute force search of the
space of possible passwords.Unfortunately the only secure way to encrypt passwords when
Unix came into being was based on DES, the Data Encryption
Standard. This is not such a problem for users that live in
the US, but since the source code for DES could not be exported
outside the US, FreeBSD had to find a way to both comply with
US law and retain compatibility with all the other Unix
variants that still use DES.The solution was to divide up the encryption libraries
so that US users could install the DES libraries and use
DES but international users still had an encryption method
that could be exported abroad. This is how FreeBSD came to
use MD5 as its default encryption method. MD5 is believed to
be more secure than DES, so installing DES is offered primarily
for compatibility reasons.Recognizing your crypt mechanismIt is pretty easy to identify which encryption method
FreeBSD is set up to use. Examining the encrypted passwords in
the /etc/master.passwd file is one way.
Passwords encrypted with the MD5 hash are longer than those with
encrypted with the DES hash and also begin with the characters
$1$. DES password strings do not
have any particular identifying characteristics, but they are
shorter than MD5 passwords, and are coded in a 64-character
alphabet which does not include the $
character, so a relatively short string which does not begin with
a dollar sign is very likely a DES password.The libraries can identify the passwords this way as well.
As a result, the DES libraries are able to identify MD5
passwords, and use MD5 to check passwords that were encrypted
that way, and DES for the rest. They are able to do this
because the DES libraries also contain MD5. Unfortunately, the
reverse is not true, so the MD5 libraries cannot authenticate
passwords that were encrypted with DES.Identifying which library is being used by the programs on
your system is easy as well. Any program that uses crypt is linked
against libcrypt which for each type of library is a symbolic link
to the appropriate implementation. For example, on a system using
the DES versions:&prompt.user; ls -l /usr/lib/libcrypt*
lrwxr-xr-x 1 root wheel 13 Mar 19 06:56 libcrypt.a -> libdescrypt.a
lrwxr-xr-x 1 root wheel 18 Mar 19 06:56 libcrypt.so.2.0 -> libdescrypt.so.2.0
lrwxr-xr-x 1 root wheel 15 Mar 19 06:56 libcrypt_p.a -> libdescrypt_p.aOn a system using the MD5-based libraries, the same links will
be present, but the target will be libscrypt
rather than libdescrypt.If you have installed the DES-capable crypt library
libdescrypt (e.g. by installing the
"crypto" distribution), then which password format will be used
for new passwords is controlled by the
passwd_format login capability in
/etc/login.conf, which takes values of
either des or md5. See the
&man.login.conf.5; manpage for more information about login
capabilities.S/KeyS/KeysecurityS/KeyS/Key is a one-time password scheme based on a one-way hash
function. FreeBSD uses the MD4 hash for compatibility but other
systems have used MD5 and DES-MAC. S/Key has been part of the
FreeBSD base system since version 1.1.5 and is also used on a
growing number of other operating systems. S/Key is a registered
trademark of Bell Communications Research, Inc.There are three different sorts of passwords which we will talk
about in the discussion below. The first is your usual Unix-style or
Kerberos password; we will call this a Unix password.
The second sort is the one-time password which is generated by the
S/Key key program and accepted by the
keyinit program and the login prompt; we will
call this a one-time password. The final sort of
password is the secret password which you give to the
key program (and sometimes the
keyinit program) which it uses to generate
one-time passwords; we will call it a secret password
or just unqualified password.The secret password does not have anything to do with your Unix
password; they can be the same but this is not recommended. S/Key
secret passwords are not limited to 8 characters like Unix passwords,
they can be as long as you like. Passwords of six or seven word
long phrases are fairly common. For the most part, the S/Key system
operates completely independently of the Unix password
system.Besides the password, there are two other pieces of data that
are important to S/Key. One is what is known as the
seed or key and consists of two letters
and five digits. The other is what is called the iteration
count and is a number between 1 and 100. S/Key creates the
one-time password by concatenating the seed and the secret password,
then applying the MD4 hash as many times as specified by the
iteration count and turning the result into six short English words.
These six English words are your one-time password. The
login and su programs keep
track of the last one-time password used, and the user is
authenticated if the hash of the user-provided password is equal to
the previous password. Because a one-way hash is used it is
impossible to generate future one-time passwords if a successfully
used password is captured; the iteration count is decremented after
each successful login to keep the user and the login program in
sync. When the iteration count gets down to 1 S/Key must be
reinitialized.There are four programs involved in the S/Key system which we
will discuss below. The key program accepts an
iteration count, a seed, and a secret password, and generates a
one-time password. The keyinit program is used
to initialized S/Key, and to change passwords, iteration counts, or
seeds; it takes either a secret password, or an iteration count,
seed, and one-time password. The keyinfo program
examines the /etc/skeykeys file and prints out
the invoking user's current iteration count and seed. Finally, the
login and su programs contain
the necessary logic to accept S/Key one-time passwords for
authentication. The login program is also
capable of disallowing the use of Unix passwords on connections
coming from specified addresses.There are four different sorts of operations we will cover. The
first is using the keyinit program over a secure
connection to set up S/Key for the first time, or to change your
password or seed. The second operation is using the
keyinit program over an insecure connection, in
conjunction with the key program over a secure
connection, to do the same. The third is using the
key program to log in over an insecure
connection. The fourth is using the key program
to generate a number of keys which can be written down or printed
out to carry with you when going to some location without secure
connections to anywhere.Secure connection initializationTo initialize S/Key for the first time, change your password,
or change your seed while logged in over a secure connection
(e.g., on the console of a machine or via ssh), use the
keyinit command without any parameters while
logged in as yourself:&prompt.user; keyinit
Adding unfurl:
Reminder - Only use this method if you are directly connected.
If you are using telnet or rlogin exit with no password and use keyinit -s.
Enter secret password:
Again secret password:
ID unfurl s/key is 99 to17757
DEFY CLUB PRO NASH LACE SOFTAt the Enter secret password: prompt you
should enter a password or phrase. Remember, this is not the
password that you will use to login with, this is used to generate
your one-time login keys. The ID line gives the
parameters of your particular S/Key instance; your login name, the
iteration count, and seed. When logging in with S/Key, the system
will remember these parameters and present them back to you so you
do not have to remember them. The last line gives the particular
one-time password which corresponds to those parameters and your
secret password; if you were to re-login immediately, this
one-time password is the one you would use.Insecure connection initializationTo initialize S/Key or change your secret password over an
insecure connection, you will need to already have a secure
connection to some place where you can run the
key program; this might be in the form of a
desk accessory on a Macintosh, or a shell prompt on a machine you
trust. You will also need to make up an iteration count (100 is
probably a good value), and you may make up your own seed or use a
randomly-generated one. Over on the insecure connection (to the
machine you are initializing), use the keyinit
-s command:&prompt.user; keyinit -s
Updating unfurl:
Old key: to17758
Reminder you need the 6 English words from the key command.
Enter sequence count from 1 to 9999: 100
Enter new key [default to17759]:
s/key 100 to 17759
s/key access password:To accept the default seed (which the
keyinit program confusingly calls a
key), press return. Then before entering an
access password, move over to your secure connection or S/Key desk
accessory, and give it the same parameters:&prompt.user; key 100 to17759
Reminder - Do not use this program while logged in via telnet or rlogin.
Enter secret password: <secret password>
CURE MIKE BANE HIM RACY GORENow switch back over to the insecure connection, and copy the
one-time password generated by key over to the
keyinit program:s/key access password:CURE MIKE BANE HIM RACY GORE
ID unfurl s/key is 100 to17759
CURE MIKE BANE HIM RACY GOREThe rest of the description from the previous section applies
here as well.Generating a single one-time passwordOnce you've initialized S/Key, when you login you will be
presented with a prompt like this:&prompt.user; telnet example.com
Trying 10.0.0.1...
Connected to example.com
Escape character is '^]'.
FreeBSD/i386 (example.com) (ttypa)
login: <username>
s/key 97 fw13894
Password: As a side note, the S/Key prompt has a useful feature
(not shown here): if you press return at the password prompt, the
login program will turn echo on, so you can see what you are
typing. This can be extremely useful if you are attempting to
type in an S/Key by hand, such as from a printout. Also, if this
machine were configured to disallow Unix passwords over a
connection from the source machine, the prompt would have also included
the annotation (s/key required), indicating
that only S/Key one-time passwords will be accepted.MS-DOSWindowsMacOSAt this point you need to generate your one-time password to
answer this login prompt. This must be done on a trusted system
that you can run the key command on. (There
are versions of the key program for MS-DOS,
Windows and MacOS as well.) The key program
needs both the iteration count and the seed as command line
options. You can cut-and-paste these right from the login prompt
on the machine that you are logging in to.On the trusted system:&prompt.user; key 97 fw13894
Reminder - Do not use this program while logged in via telnet or rlogin.
Enter secret password:
WELD LIP ACTS ENDS ME HAAGNow that you have your one-time password you can continue
logging in:login: <username>
s/key 97 fw13894
Password: <return to enable echo>
s/key 97 fw13894
Password [echo on]: WELD LIP ACTS ENDS ME HAAG
Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ... This is the easiest mechanism if you have
a trusted machine. There is a Java S/Key key
applet, The Java OTP
Calculator, that you can download and run locally on any
Java supporting browser.Generating multiple one-time passwordsSometimes you have to go places where you do not have
access to a trusted machine or secure connection. In this case,
it is possible to use the key command to
generate a number of one-time passwords before hand to be printed
out and taken with you. For example:&prompt.user; key -n 5 30 zz99999
Reminder - Do not use this program while logged in via telnet or rlogin.
Enter secret password: <secret password>
26: SODA RUDE LEA LIND BUDD SILT
27: JILT SPY DUTY GLOW COWL ROT
28: THEM OW COLA RUNT BONG SCOT
29: COT MASH BARR BRIM NAN FLAG
30: CAN KNEE CAST NAME FOLK BILKThe requests five keys in sequence, the
specifies what the last iteration number
should be. Note that these are printed out in
reverse order of eventual use. If you are
really paranoid, you might want to write the results down by hand;
otherwise you can cut-and-paste into lpr. Note
that each line shows both the iteration count and the one-time
password; you may still find it handy to scratch off passwords as
you use them.Restricting use of Unix passwordsRestrictions can be placed on the use of Unix passwords based
on the host name, user name, terminal port, or IP address of a
login session. These restrictions can be found in the
configuration file /etc/skey.access. The
&man.skey.access.5; manual page has more info on the complete
format of the file and also details some security cautions to be
aware of before depending on this file for security.If there is no /etc/skey.access file
(this is the FreeBSD default), then all users will be allowed to
use Unix passwords. If the file exists, however, then all users
will be required to use S/Key unless explicitly permitted to do
otherwise by configuration statements in the
skey.access file. In all cases, Unix
passwords are permitted on the console.Here is a sample configuration file which illustrates the
three most common sorts of configuration statements:permit internet 192.168.0.0 255.255.0.0
permit user fnord
permit port ttyd0The first line (permit internet) allows
users whose IP source address (which is vulnerable to spoofing)
matches the specified value and mask, to use Unix passwords. This
should not be considered a security mechanism, but rather, a means
to remind authorized users that they are using an insecure network
and need to use S/Key for authentication.The second line (permit user) allows the
specified username, in this case fnord, to use
Unix passwords at any time. Generally speaking, this should only
be used for people who are either unable to use the
key program, like those with dumb terminals, or
those who are uneducable.The third line (permit port) allows all
users logging in on the specified terminal line to use Unix
passwords; this would be used for dial-ups.
+
+
+
+ Mark
+ Murray
+ Contributed by
+
+
+
+
+ Mark
+ Dapoz
+ Based on a contribution by
+
+
+
+
KerberosKerberos
-
- Contributed by &a.markm; (based on contribution by
- &a.md;).Kerberos is a network add-on system/protocol that allows users to
authenticate themselves through the services of a secure server.
Services such as remote login, remote copy, secure inter-system file
copying and other high-risk tasks are made considerably safer and more
controllable.The following instructions can be used as a guide on how to set up
Kerberos as distributed for FreeBSD. However, you should refer to the
relevant manual pages for a complete description.4.4BSD-LiteIn FreeBSD, the Kerberos is not that from the original 4.4BSD-Lite,
distribution, but eBones, which had been previously ported to FreeBSD
1.1.5.1, and was sourced from outside the USA/Canada, and was thus
available to system owners outside those countries during the era
of restrictive export controls on cryptographic code from the USA.Creating the initial databaseThis is done on the Kerberos server only. First make sure that
you do not have any old Kerberos databases around. You should change
to the directory /etc/kerberosIV and check that
only the following files are present:&prompt.root; cd /etc/kerberosIV
&prompt.root; ls
README krb.conf krb.realmsIf any additional files (such as principal.*
or master_key) exist, then use the
kdb_destroy command to destroy the old Kerberos
database, of if Kerberos is not running, simply delete the extra
files.You should now edit the krb.conf and
krb.realms files to define your Kerberos realm.
In this case the realm will be GRONDAR.ZA and the
server is grunt.grondar.za. We edit or create
the krb.conf file:&prompt.root; cat krb.conf
GRONDAR.ZA
GRONDAR.ZA grunt.grondar.za admin server
CS.BERKELEY.EDU okeeffe.berkeley.edu
ATHENA.MIT.EDU kerberos.mit.edu
ATHENA.MIT.EDU kerberos-1.mit.edu
ATHENA.MIT.EDU kerberos-2.mit.edu
ATHENA.MIT.EDU kerberos-3.mit.edu
LCS.MIT.EDU kerberos.lcs.mit.edu
TELECOM.MIT.EDU bitsy.mit.edu
ARC.NASA.GOV trident.arc.nasa.govIn this case, the other realms do not need to be there. They are
here as an example of how a machine may be made aware of multiple
realms. You may wish to not include them for simplicity.The first line names the realm in which this system works. The
other lines contain realm/host entries. The first item on a line is a
realm, and the second is a host in that realm that is acting as a
key distribution center. The words admin
server following a hosts name means that host also
provides an administrative database server. For further explanation
of these terms, please consult the Kerberos man pages.Now we have to add grunt.grondar.za
to the GRONDAR.ZA realm and also add an entry to
put all hosts in the .grondar.za
domain in the GRONDAR.ZA realm. The
krb.realms file would be updated as
follows:&prompt.root; cat krb.realms
grunt.grondar.za GRONDAR.ZA
.grondar.za GRONDAR.ZA
.berkeley.edu CS.BERKELEY.EDU
.MIT.EDU ATHENA.MIT.EDU
.mit.edu ATHENA.MIT.EDUAgain, the other realms do not need to be there. They are here as
an example of how a machine may be made aware of multiple realms. You
may wish to remove them to simplify things.The first line puts the specific system into
the named realm. The rest of the lines show how to default systems of
a particular subdomain to a named realm.Now we are ready to create the database. This only needs to run
on the Kerberos server (or Key Distribution Center). Issue the
kdb_init command to do this:&prompt.root; kdb_initRealm name [default ATHENA.MIT.EDU ]:GRONDAR.ZA
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter Kerberos master key:Now we have to save the key so that servers on the local machine
can pick it up. Use the kstash command to do
this.&prompt.root; kstashEnter Kerberos master key:
Current Kerberos master key version is 1.
Master key entered. BEWARE!This saves the encrypted master password in
/etc/kerberosIV/master_key.Making it all runTwo principals need to be added to the database for
each system that will be secured with Kerberos.
Their names are kpasswd and rcmd
These two principals are made for each system, with the instance being
the name of the individual system.These daemons, kpasswd and
rcmd allow other systems to change Kerberos
passwords and run commands like rcp,
rlogin and rsh.Now let's add these entries:&prompt.root; kdb_edit
Opening database...
Enter Kerberos master key:
Current Kerberos master key version is 1.
Master key entered. BEWARE!
Previous or default values are in [brackets] ,
enter return to leave the same, or new value.
Principal name:passwdInstance:grunt
<Not found>, Create [y] ?y
Principal: passwd, Instance: grunt, kdc_key_ver: 1
New Password: <---- enter RANDOM here
Verifying password
New Password: <---- enter RANDOM here
Random password [y] ?y
Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?Max ticket lifetime (*5 minutes) [ 255 ] ?Attributes [ 0 ] ?
Edit O.K.
Principal name:rcmdInstance:grunt
<Not found>, Create [y] ?
Principal: rcmd, Instance: grunt, kdc_key_ver: 1
New Password: <---- enter RANDOM here
Verifying password
New Password: <---- enter RANDOM here
Random password [y] ?
Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?Max ticket lifetime (*5 minutes) [ 255 ] ?Attributes [ 0 ] ?
Edit O.K.
Principal name: <---- null entry here will cause an exitCreating the server fileWe now have to extract all the instances which define the services
on each machine. For this we use the ext_srvtab
command. This will create a file which must be copied or moved
by secure means to each Kerberos client's
/etc/kerberosIV directory. This file must be present on each server
and client, and is crucial to the operation of Kerberos.&prompt.root; ext_srvtab gruntEnter Kerberos master key:
Current Kerberos master key version is 1.
Master key entered. BEWARE!
Generating 'grunt-new-srvtab'....Now, this command only generates a temporary file which must be
renamed to srvtab so that all the server can pick
it up. Use the mv command to move it into place on
the original system:&prompt.root; mv grunt-new-srvtab srvtabIf the file is for a client system, and the network is not deemed
safe, then copy the
client-new-srvtab to
removable media and transport it by secure physical means. Be sure to
rename it to srvtab in the client's
/etc/kerberosIV directory, and make sure it is
mode 600:&prompt.root; mv grumble-new-srvtab srvtab
&prompt.root; chmod 600 srvtabPopulating the databaseWe now have to add some user entries into the database. First
let's create an entry for the user jane. Use the
kdb_edit command to do this:&prompt.root; kdb_edit
Opening database...
Enter Kerberos master key:
Current Kerberos master key version is 1.
Master key entered. BEWARE!
Previous or default values are in [brackets] ,
enter return to leave the same, or new value.
Principal name:janeInstance:
<Not found>, Create [y] ?y
Principal: jane, Instance: , kdc_key_ver: 1
New Password: <---- enter a secure password here
Verifying password
New Password: <---- re-enter the password here
Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?Max ticket lifetime (*5 minutes) [ 255 ] ?Attributes [ 0 ] ?
Edit O.K.
Principal name: <---- null entry here will cause an exitTesting it all outFirst we have to start the Kerberos daemons. NOTE that if you
have correctly edited your /etc/rc.conf then this
will happen automatically when you reboot. This is only necessary on
the Kerberos server. Kerberos clients will automagically get what
they need from the /etc/kerberosIV
directory.&prompt.root; kerberos &
Kerberos server starting
Sleep forever on error
Log file is /var/log/kerberos.log
Current Kerberos master key version is 1.
Master key entered. BEWARE!
Current Kerberos master key version is 1
Local realm: GRONDAR.ZA
&prompt.root; kadmind -n &
KADM Server KADM0.0A initializing
Please do not use 'kill -9' to kill this job, use a
regular kill instead
Current Kerberos master key version is 1.
Master key entered. BEWARE!Now we can try using the kinit command to get a
ticket for the id jane that we created
above:&prompt.user; kinit jane
MIT Project Athena (grunt.grondar.za)
Kerberos Initialization for "jane"
Password:Try listing the tokens using klist to see if we
really have them:&prompt.user; klist
Ticket file: /tmp/tkt245
Principal: jane@GRONDAR.ZA
Issued Expires Principal
Apr 30 11:23:22 Apr 30 19:23:22 krbtgt.GRONDAR.ZA@GRONDAR.ZANow try changing the password using passwd to
check if the kpasswd daemon can get authorization to the Kerberos
database:&prompt.user; passwd
realm GRONDAR.ZA
Old password for jane:New Password for jane:
Verifying password
New Password for jane:
Password changed.Adding su privilegesKerberos allows us to give each user who
needs root privileges their own separatesupassword. We could now add an id which is
authorized to su to root.
This is controlled by having an instance of root
associated with a principal. Using kdb_edit we can
create the entry jane.root in the Kerberos
database:&prompt.root; kdb_edit
Opening database...
Enter Kerberos master key:
Current Kerberos master key version is 1.
Master key entered. BEWARE!
Previous or default values are in [brackets] ,
enter return to leave the same, or new value.
Principal name:janeInstance:root
<Not found>, Create [y] ? y
Principal: jane, Instance: root, kdc_key_ver: 1
New Password: <---- enter a SECURE password here
Verifying password
New Password: <---- re-enter the password here
Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?Max ticket lifetime (*5 minutes) [ 255 ] ?12 <--- Keep this short!
Attributes [ 0 ] ?
Edit O.K.
Principal name: <---- null entry here will cause an exitNow try getting tokens for it to make sure it works:&prompt.root; kinit jane.root
MIT Project Athena (grunt.grondar.za)
Kerberos Initialization for "jane.root"
Password:Now we need to add the user to root's .klogin
file:&prompt.root; cat /root/.klogin
jane.root@GRONDAR.ZANow try doing the su:&prompt.user; suPassword:and take a look at what tokens we have:&prompt.root; klist
Ticket file: /tmp/tkt_root_245
Principal: jane.root@GRONDAR.ZA
Issued Expires Principal
May 2 20:43:12 May 3 04:43:12 krbtgt.GRONDAR.ZA@GRONDAR.ZAUsing other commandsIn an earlier example, we created a principal called
jane with an instance root.
This was based on a user with the same name as the principal, and this
is a Kerberos default; that a
<principal>.<instance> of the form
<username>.root will allow
that <username> to su to
root if the necessary entries are in the .klogin
file in root's home directory:&prompt.root; cat /root/.klogin
jane.root@GRONDAR.ZALikewise, if a user has in their own home directory lines of the
form:&prompt.user; cat ~/.klogin
jane@GRONDAR.ZA
jack@GRONDAR.ZAThis allows anyone in the GRONDAR.ZA realm
who has authenticated themselves to jane or
jack (via kinit, see above)
access to rlogin to jane's
account or files on this system (grunt) via
rlogin, rsh or
rcp.For example, Jane now logs into another system, using
Kerberos:&prompt.user; kinit
MIT Project Athena (grunt.grondar.za)
Password:
&prompt.user; rlogin grunt
Last login: Mon May 1 21:14:47 from grumble
Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
The Regents of the University of California. All rights reserved.
FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995Or Jack logs into Jane's account on the same machine (Jane having
set up the .klogin file as above, and the person
in charge of Kerberos having set up principal
jack with a null instance:&prompt.user; kinit
&prompt.user; rlogin grunt -l jane
MIT Project Athena (grunt.grondar.za)
Password:
Last login: Mon May 1 21:16:55 from grumble
Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
The Regents of the University of California. All rights reserved.
FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995
+
+
+
+ Gary
+ Palmer
+ Contributed by
+
+
+ Alex
+ Nash
+
+
+
+
Firewallsfirewallsecurityfirewalls
- Contributed by &a.gpalmer; and Alex Nash.
-
Firewalls are an area of increasing interest for people who are
connected to the Internet, and are even finding applications on private
networks to provide enhanced security. This section will hopefully
explain what firewalls are, how to use them, and how to use the
facilities provided in the FreeBSD kernel to implement them.People often think that having a firewall between your
internal network and the Big Bad Internet will solve all
your security problems. It may help, but a poorly setup firewall
system is more of a security risk than not having one at all. A
firewall can add another layer of security to your systems, but it
cannot stop a really determined cracker from penetrating your internal
network. If you let internal security lapse because you believe your
firewall to be impenetrable, you have just made the crackers job that
much easier.What is a firewall?There are currently two distinct types of firewalls in common use
on the Internet today. The first type is more properly called a
packet filtering router, where the kernel on a
multi-homed machine chooses whether to forward or block packets based
on a set of rules. The second type, known as a proxy
server, relies on daemons to provide authentication and to
forward packets, possibly on a multi-homed machine which has kernel
packet forwarding disabled.Sometimes sites combine the two types of firewalls, so that only a
certain machine (known as a bastion host) is
allowed to send packets through a packet filtering router onto an
internal network. Proxy services are run on the bastion host, which
are generally more secure than normal authentication
mechanisms.FreeBSD comes with a kernel packet filter (known as
IPFW), which is what the rest of this
section will concentrate on. Proxy servers can be built on FreeBSD
from third party software, but there is such a variety of proxy
servers available that it would be impossible to cover them in this
document.Packet filtering routersA router is a machine which forwards packets between two or more
networks. A packet filtering router has an extra piece of code in
its kernel which compares each packet to a list of rules before
deciding if it should be forwarded or not. Most modern IP routing
software has packet filtering code within it that defaults to
forwarding all packets. To enable the filters, you need to define a
set of rules for the filtering code so it can decide if the
packet should be allowed to pass or not.To decide whether a packet should be passed on, the code looks
through its set of rules for a rule which matches the contents of
this packets headers. Once a match is found, the rule action is
obeyed. The rule action could be to drop the packet, to forward the
packet, or even to send an ICMP message back to the originator.
Only the first match counts, as the rules are searched in order.
Hence, the list of rules can be referred to as a rule
chain.The packet matching criteria varies depending on the software
used, but typically you can specify rules which depend on the source
IP address of the packet, the destination IP address, the source
port number, the destination port number (for protocols which
support ports), or even the packet type (UDP, TCP, ICMP,
etc).Proxy serversProxy servers are machines which have had the normal system
daemons (telnetd, ftpd, etc) replaced with special servers. These
servers are called proxy servers as they
normally only allow onward connections to be made. This enables you
to run (for example) a proxy telnet server on your firewall host,
and people can telnet in to your firewall from the outside, go
through some authentication mechanism, and then gain access to the
internal network (alternatively, proxy servers can be used for
signals coming from the internal network and heading out).Proxy servers are normally more secure than normal servers, and
often have a wider variety of authentication mechanisms available,
including one-shot password systems so that even if
someone manages to discover what password you used, they will not be
able to use it to gain access to your systems as the password
instantly expires. As they do not actually give users access to the
host machine, it becomes a lot more difficult for someone to install
backdoors around your security system.Proxy servers often have ways of restricting access further, so
that only certain hosts can gain access to the servers, and often
they can be set up so that you can limit which users can talk to
which destination machine. Again, what facilities are available
depends largely on what proxy software you choose.What does IPFW allow me to do?ipfwIPFW, the software supplied with
FreeBSD, is a packet filtering and accounting system which resides in
the kernel, and has a user-land control utility,
&man.ipfw.8;. Together, they allow you to define and query the
rules currently used by the kernel in its routing decisions.There are two related parts to IPFW.
The firewall section allows you to perform packet filtering. There is
also an IP accounting section which allows you to track usage of your
router, based on similar rules to the firewall section. This allows
you to see (for example) how much traffic your router is getting from
a certain machine, or how much WWW (World Wide Web) traffic it is
forwarding.As a result of the way that IPFW is
designed, you can use IPFW on non-router
machines to perform packet filtering on incoming and outgoing
connections. This is a special case of the more general use of
IPFW, and the same commands and techniques
should be used in this situation.Enabling IPFW on FreeBSDipfwenablingAs the main part of the IPFW system
lives in the kernel, you will need to add one or more options to your
kernel configuration file, depending on what facilities you want, and
recompile your kernel. See reconfiguring
the kernel for more details on how to recompile your
kernel.There are currently three kernel configuration options relevant to
IPFW:options IPFIREWALLCompiles into the kernel the code for packet
filtering.options IPFIREWALL_VERBOSEEnables code to allow logging of packets through
&man.syslogd.8;. Without this option, even if you specify
that packets should be logged in the filter rules, nothing will
happen.options IPFIREWALL_VERBOSE_LIMIT=10Limits the number of packets logged through
&man.syslogd.8; on a per entry basis. You may wish to use
this option in hostile environments in which you want to log
firewall activity, but do not want to be open to a denial of
service attack via syslog flooding.When a chain entry reaches the packet limit specified,
logging is turned off for that particular entry. To resume
logging, you will need to reset the associated counter using the
&man.ipfw.8; utility:&prompt.root; ipfw zero 4500Where 4500 is the chain entry you wish to continue
logging.Previous versions of FreeBSD contained an
IPFIREWALL_ACCT option. This is now obsolete as
the firewall code automatically includes accounting
facilities.Configuring IPFWipfwconfiguringThe configuration of the IPFW software
is done through the &man.ipfw.8; utility. The syntax for this
command looks quite complicated, but it is relatively simple once you
understand its structure.There are currently four different command categories used by the
utility: addition/deletion, listing, flushing, and clearing.
Addition/deletion is used to build the rules that control how packets
are accepted, rejected, and logged. Listing is used to examine the
contents of your rule set (otherwise known as the chain) and packet
counters (accounting). Flushing is used to remove all entries from
the chain. Clearing is used to zero out one or more accounting
entries.Altering the IPFW rulesThe syntax for this form of the command is:
ipfw-NcommandindexactionlogprotocoladdressesoptionsThere is one valid flag when using this form of the
command:-NResolve addresses and service names in output.The command given can be shortened to the
shortest unique form. The valid commands
are:addAdd an entry to the firewall/accounting rule listdeleteDelete an entry from the firewall/accounting rule
listPrevious versions of IPFW used
separate firewall and accounting entries. The present version
provides packet accounting with each firewall entry.If an index value is supplied, it used to
place the entry at a specific point in the chain. Otherwise, the
entry is placed at the end of the chain at an index 100 greater than
the last chain entry (this does not include the default policy, rule
65535, deny).The log option causes matching rules to be
output to the system console if the kernel was compiled with
IPFIREWALL_VERBOSE.Valid actions are:rejectDrop the packet, and send an ICMP host or port unreachable
(as appropriate) packet to the source.allowPass the packet on as normal. (aliases:
pass and
accept)denyDrop the packet. The source is not notified via an
ICMP message (thus it appears that the packet never
arrived at the destination).countUpdate packet counters but do not allow/deny the packet
based on this rule. The search continues with the next chain
entry.Each action will be recognized by the
shortest unambiguous prefix.The protocols which can be specified
are:allMatches any IP packeticmpMatches ICMP packetstcpMatches TCP packetsudpMatches UDP packetsThe address specification is:fromaddress/maskporttoaddress/maskportvia interfaceYou can only specify port in
conjunction with protocols which support ports
(UDP and TCP).The is optional and may specify the IP
address or domain name of a local IP interface, or an interface name
(e.g. ed0) to match only packets coming
through this interface. Interface unit numbers can be specified
with an optional wildcard. For example, ppp*
would match all kernel PPP interfaces.The syntax used to specify an
address/mask is:
address
or
address/mask-bits
or
address:mask-patternA valid hostname may be specified in place of the IP address.
is a decimal
number representing how many bits in the address mask should be set.
e.g. specifying 192.216.222.1/24 will create a
mask which will allow any address in a class C subnet (in this case,
192.216.222) to be matched.
is an IP
address which will be logically AND'ed with the address given. The
keyword any may be used to specify any IP
address.The port numbers to be blocked are specified as:
port,port,port…
to specify either a single port or a list of ports, or
port-port
to specify a range of ports. You may also combine a single range
with a list, but the range must always be specified first.The options available are:fragMatches if the packet is not the first fragment of the
datagram.inMatches if the packet is on the way in.outMatches if the packet is on the way out.ipoptions specMatches if the IP header contains the comma separated list
of options specified in spec. The
supported list of IP options are: ssrr
(strict source route), lsrr (loose source
route), rr (record packet route), and
ts (time stamp). The absence of a
particular option may be denoted with a leading
!.establishedMatches if the packet is part of an already established
TCP connection (i.e. it has the RST or ACK bits set). You can
optimize the performance of the firewall by placing
established rules early in the
chain.setupMatches if the packet is an attempt to establish a TCP
connection (the SYN bit set is set but the ACK bit is
not).tcpflags flagsMatches if the TCP header contains the comma separated
list of flags. The supported flags
are fin, syn,
rst, psh,
ack, and urg. The
absence of a particular flag may be indicated by a leading
!.icmptypes typesMatches if the ICMP type is present in the list
types. The list may be specified
as any combination of ranges and/or individual types separated
by commas. Commonly used ICMP types are: 0
echo reply (ping reply), 3 destination
unreachable, 5 redirect,
8 echo request (ping request), and
11 time exceeded (used to indicate TTL
expiration as with &man.traceroute.8;).Listing the IPFW rulesThe syntax for this form of the command is:
ipfw-a-t-NlThere are three valid flags when using this form of the
command:-aWhile listing, show counter values. This option is the
only way to see accounting counters.-tDisplay the last match times for each chain entry. The
time listing is incompatible with the input syntax used by the
&man.ipfw.8; utility.-NAttempt to resolve given addresses and service
names.Flushing the IPFW rulesThe syntax for flushing the chain is:
ipfwflushThis causes all entries in the firewall chain to be removed
except the fixed default policy enforced by the kernel (index
65535). Use caution when flushing rules, the default deny policy
will leave your system cut off from the network until allow entries
are added to the chain.Clearing the IPFW packet countersThe syntax for clearing one or more packet counters is:
ipfwzeroindexWhen used without an index argument,
all packet counters are cleared. If an
index is supplied, the clearing operation
only affects a specific chain entry.Example commands for ipfwThis command will deny all packets from the host evil.crackers.org to the telnet port of the
host nice.people.org:&prompt.root ipfw add deny tcp from evil.crackers.org to nice.people.org 23The next example denies and logs any TCP traffic from the entire
crackers.org network (a class C) to
the nice.people.org machine (any
port).&prompt.root; ipfw add deny log tcp from evil.crackers.org/24 to nice.people.orgIf you do not want people sending X sessions to your internal
network (a subnet of a class C), the following command will do the
necessary filtering:&prompt.root; ipfw add deny tcp from any to my.org/28 6000 setupTo see the accounting records:
&prompt.root; ipfw -a list
or in the short form
&prompt.root; ipfw -a lYou can also see the last time a chain entry was matched
with:&prompt.root; ipfw -at lBuilding a packet filtering firewallThe following suggestions are just that: suggestions. The
requirements of each firewall are different and we cannot tell you
how to build a firewall to meet your particular requirements.When initially setting up your firewall, unless you have a test
bench setup where you can configure your firewall host in a controlled
environment, it is strongly recommend you use the logging version of the
commands and enable logging in the kernel. This will allow you to
quickly identify problem areas and cure them without too much
disruption. Even after the initial setup phase is complete, I
recommend using the logging for `deny' as it allows tracing of
possible attacks and also modification of the firewall rules if your
requirements alter.If you use the logging versions of the accept
command, it can generate large amounts of log
data as one log line will be generated for every packet that passes
through the firewall, so large FTP/http transfers, etc, will really
slow the system down. It also increases the latencies on those
packets as it requires more work to be done by the kernel before the
packet can be passed on. syslogd with also start using up a lot
more processor time as it logs all the extra data to disk, and it
could quite easily fill the partition /var/log
is located on.You should enable your firewall from
/etc/rc.conf.local or
/etc/rc.conf. The associated man page explains
which knobs to fiddle and lists some preset firewall configurations.
If you do not use a preset configuration, ipfw list
will output the current ruleset into a file that you can
pass to rc.conf. If you do not use
/etc/rc.conf.local or
/etc/rc.conf to enable your firewall,
it is important to make sure your firewall is enabled before
any IP interfaces are configured.
The next problem is what your firewall should actually
do! This is largely dependent on what access to
your network you want to allow from the outside, and how much access
to the outside world you want to allow from the inside. Some general
rules are:Block all incoming access to ports below 1024 for TCP. This is
where most of the security sensitive services are, like finger,
SMTP (mail) and telnet.Block all incoming UDP traffic. There
are very few useful services that travel over UDP, and what useful
traffic there is normally a security threat (e.g. Suns RPC and
NFS protocols). This has its disadvantages also, since UDP is a
connectionless protocol, denying incoming UDP traffic also blocks
the replies to outgoing UDP traffic. This can cause a problem for
people (on the inside) using external archie (prospero) servers.
If you want to allow access to archie, you'll have to allow
packets coming from ports 191 and 1525 to any internal UDP port
through the firewall. ntp is another service you may consider
allowing through, which comes from port 123.Block traffic to port 6000 from the outside. Port 6000 is the
port used for access to X11 servers, and can be a security threat
(especially if people are in the habit of doing xhost
+ on their workstations). X11 can actually use a
range of ports starting at 6000, the upper limit being how many X
displays you can run on the machine. The upper limit as defined
by RFC 1700 (Assigned Numbers) is 6063.Check what ports any internal servers use (e.g. SQL servers,
etc). It is probably a good idea to block those as well, as they
normally fall outside the 1-1024 range specified above.Another checklist for firewall configuration is available from
CERT at http://www.cert.org/tech_tips/packet_filtering.htmlAs stated above, these are only guidelines.
You will have to decide what filter rules you want to use on your
firewall yourself. We cannot accept ANY responsibility if someone
breaks into your network, even if you follow the advice given
above.OpenSSLsecurityOpenSSLOpenSSLAs of FreeBSD 4.0, the OpenSSL toolkit is a part of the base
system. OpenSSL
provides a general-purpose cryptography library, as well as the
Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer
Security v1 (TLSv1) network security protocols.However, one of the algorithms (specifically IDEA)
included in OpenSSL is protected by patents in the USA and
elsewhere, and is not available for unrestricted use.
IDEA is included in the OpenSSL sources in FreeBSD, but it is not
built by default. If you wish to use it, and you comply with the
license terms, enable the MAKE_IDEA switch in /etc/make.conf and
rebuild your sources using 'make world'.Today, the RSA algorithm is free for use in USA and other
countries. In the past it was protected by a patent.OpenSSLinstallSource Code InstallationsOpenSSL is part of the src-crypto and
src-secure cvsup collections. See the Obtaining FreeBSD section for more
information about obtaining and updating FreeBSD source
code.
+
+
+
+ Yoshinobu
+ Inoue
+ Contributed by
+
+
+
+
+
IPsecIPsecsecurityIPsec
- Contributed by &a.shin;, 5 March
- 2000.
-
The IPsec mechanism provides secure communication either for IP
layer and socket layer communication. This section should
explain how to use them. For implementation details, please
refer to The
Developers' Handbook.The current IPsec implementation supports both transport mode
and tunnel mode. However, tunnel mode comes with some restrictions.
http://www.kame.net/newsletter/
has more comprehensive examples.Please be aware that in order to use this functionality, you
must have the following options compiled into your kernel:options IPSEC #IP security
options IPSEC_ESP #IP security (crypto; define w/IPSEC)Transport mode example with IPv4Let's setup security association to deploy a secure channel
between HOST A (10.2.3.4) and HOST B (10.6.7.8). Here we show a little
complicated example. From HOST A to HOST B, only old AH is used.
From HOST B to HOST A, new AH and new ESP are combined.Now we should choose algorithm to be used corresponding to
"AH"/"new AH"/"ESP"/"new ESP". Please refer to the &man.setkey.8; man
page to know algorithm names. Our choice is MD5 for AH, new-HMAC-SHA1
for new AH, and new-DES-expIV with 8 byte IV for new ESP.Key length highly depends on each algorithm. For example, key
length must be equal to 16 bytes for MD5, 20 for new-HMAC-SHA1,
and 8 for new-DES-expIV. Now we choose "MYSECRETMYSECRET",
"KAMEKAMEKAMEKAMEKAME", "PASSWORD", respectively.OK, let's assign SPI (Security Parameter Index) for each protocol.
Please note that we need 3 SPIs for this secure channel since three
security headers are produced (one for from HOST A to HOST B, two for
from HOST B to HOST A). Please also note that SPI MUST be greater
than or equal to 256. We choose, 1000, 2000, and 3000, respectively.
(1)
HOST A ------> HOST B
(1)PROTO=AH
ALG=MD5(RFC1826)
KEY=MYSECRETMYSECRET
SPI=1000
(2.1)
HOST A <------ HOST B
<------
(2.2)
(2.1)
PROTO=AH
ALG=new-HMAC-SHA1(new AH)
KEY=KAMEKAMEKAMEKAMEKAME
SPI=2000
(2.2)
PROTO=ESP
ALG=new-DES-expIV(new ESP)
IV length = 8
KEY=PASSWORD
SPI=3000
Now, let's setup security association. Execute &man.setkey.8;
on both HOST A and B:
&prompt.root; setkey -c
add 10.2.3.4 10.6.7.8 ah-old 1000 -m transport -A keyed-md5 "MYSECRETMYSECRET" ;
add 10.6.7.8 10.2.3.4 ah 2000 -m transport -A hmac-sha1 "KAMEKAMEKAMEKAMEKAME" ;
add 10.6.7.8 10.2.3.4 esp 3000 -m transport -E des-cbc "PASSWORD" ;
^D
Actually, IPsec communication doesn't process until security policy
entries will be defined. In this case, you must setup each host.
At A:
&prompt.root; setkey -c
spdadd 10.2.3.4 10.6.7.8 any -P out ipsec
ah/transport/10.2.3.4-10.6.7.8/require ;
^D
At B:
&prompt.root; setkey -c
spdadd 10.6.7.8 10.2.3.4 any -P out ipsec
esp/transport/10.6.7.8-10.2.3.4/require ;
spdadd 10.6.7.8 10.2.3.4 any -P out ipsec
ah/transport/10.6.7.8-10.2.3.4/require ;
^D
HOST A --------------------------------------> HOST E
10.2.3.4 10.6.7.8
| |
========== old AH keyed-md5 ==========>
<========= new AH hmac-sha1 ===========
<========= new ESP des-cbc ============
Transport mode example with IPv6Another example using IPv6.ESP transport mode is recommended for TCP port number 110 between
Host-A and Host-B.
============ ESP ============
| |
Host-A Host-B
fec0::10 -------------------- fec0::11
Encryption algorithm is blowfish-cbc whose key is "kamekame", and
authentication algorithm is hmac-sha1 whose key is "this is the test
key". Configuration at Host-A:
&prompt.root; setkey -c <<EOF
spdadd fec0::10[any] fec0::11[110] tcp -P out ipsec
esp/transport/fec0::10-fec0::11/use ;
spdadd fec0::11[110] fec0::10[any] tcp -P in ipsec
esp/transport/fec0::11-fec0::10/use ;
add fec0::10 fec0::11 esp 0x10001
-m transport
-E blowfish-cbc "kamekame"
-A hmac-sha1 "this is the test key" ;
add fec0::11 fec0::10 esp 0x10002
-m transport
-E blowfish-cbc "kamekame"
-A hmac-sha1 "this is the test key" ;
EOF
and at Host-B:&prompt.root; setkey -c <<EOF
spdadd fec0::11[110] fec0::10[any] tcp -P out ipsec
esp/transport/fec0::11-fec0::10/use ;
spdadd fec0::10[any] fec0::11[110] tcp -P in ipsec
esp/transport/fec0::10-fec0::11/use ;
add fec0::10 fec0::11 esp 0x10001 -m transport
-E blowfish-cbc "kamekame"
-A hmac-sha1 "this is the test key" ;
add fec0::11 fec0::10 esp 0x10002 -m transport
-E blowfish-cbc "kamekame"
-A hmac-sha1 "this is the test key" ;
EOF
Note the direction of SP.Tunnel mode example with IPv4Tunnel mode between two security gatewaysSecurity protocol is old AH tunnel mode, i.e. specified by
RFC1826, with keyed-md5 whose key is "this is the test" as
authentication algorithm.
======= AH =======
| |
Network-A Gateway-A Gateway-B Network-B
10.0.1.0/24 ---- 172.16.0.1 ----- 172.16.0.2 ---- 10.0.2.0/24
Configuration at Gateway-A:
&prompt.root; setkey -c <<EOF
spdadd 10.0.1.0/24 10.0.2.0/24 any -P out ipsec
ah/tunnel/172.16.0.1-172.16.0.2/require ;
spdadd 10.0.2.0/24 10.0.1.0/24 any -P in ipsec
ah/tunnel/172.16.0.2-172.16.0.1/require ;
add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any
-A keyed-md5 "this is the test" ;
add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any
-A keyed-md5 "this is the test" ;
EOF
If port number field is omitted such above then "[any]" is
employed. `-m' specifies the mode of SA to be used. "-m any" means
wild-card of mode of security protocol. You can use this SA for both
tunnel and transport mode.and at Gateway-B:
&prompt.root; setkey -c <<EOF
spdadd 10.0.2.0/24 10.0.1.0/24 any -P out ipsec
ah/tunnel/172.16.0.2-172.16.0.1/require ;
spdadd 10.0.1.0/24 10.0.2.0/24 any -P in ipsec
ah/tunnel/172.16.0.1-172.16.0.2/require ;
add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any
-A keyed-md5 "this is the test" ;
add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any
-A keyed-md5 "this is the test" ;
EOF
Making SA bundle between two security gatewaysAH transport mode and ESP tunnel mode is required between
Gateway-A and Gateway-B. In this case, ESP tunnel mode is applied first,
and AH transport mode is next.
========== AH =========
| ======= ESP ===== |
| | | |
Network-A Gateway-A Gateway-B Network-B
fec0:0:0:1::/64 --- fec0:0:0:1::1 ---- fec0:0:0:2::1 --- fec0:0:0:2::/64
Tunnel mode example with IPv6Encryption algorithm is 3des-cbc, and authentication algorithm
for ESP is hmac-sha1. Authentication algorithm for AH is hmac-md5.
Configuration at Gateway-A:
&prompt.root; setkey -c <<EOF
spdadd fec0:0:0:1::/64 fec0:0:0:2::/64 any -P out ipsec
esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require
ah/transport/fec0:0:0:1::1-fec0:0:0:2::1/require ;
spdadd fec0:0:0:2::/64 fec0:0:0:1::/64 any -P in ipsec
esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require
ah/transport/fec0:0:0:2::1-fec0:0:0:1::1/require ;
add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10001 -m tunnel
-E 3des-cbc "kamekame12341234kame1234"
-A hmac-sha1 "this is the test key" ;
add fec0:0:0:1::1 fec0:0:0:2::1 ah 0x10001 -m transport
-A hmac-md5 "this is the test" ;
add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10001 -m tunnel
-E 3des-cbc "kamekame12341234kame1234"
-A hmac-sha1 "this is the test key" ;
add fec0:0:0:2::1 fec0:0:0:1::1 ah 0x10001 -m transport
-A hmac-md5 "this is the test" ;
EOF
Making SAs with the different endESP tunnel mode is required between Host-A and Gateway-A. Encryption
algorithm is cast128-cbc, and authentication algorithm for ESP is
hmac-sha1. ESP transport mode is recommended between Host-A and Host-B.
Encryption algorithm is rc5-cbc, and authentication algorithm for ESP is
hmac-md5.
================== ESP =================
| ======= ESP ======= |
| | | |
Host-A Gateway-A Host-B
fec0:0:0:1::1 ---- fec0:0:0:2::1 ---- fec0:0:0:2::2
Configuration at Host-A:
&prompt.root; setkey -c <<EOF
spdadd fec0:0:0:1::1[any] fec0:0:0:2::2[80] tcp -P out ipsec
esp/transport/fec0:0:0:1::1-fec0:0:0:2::2/use
esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ;
spdadd fec0:0:0:2::1[80] fec0:0:0:1::1[any] tcp -P in ipsec
esp/transport/fec0:0:0:2::2-fec0:0:0:l::1/use
esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ;
add fec0:0:0:1::1 fec0:0:0:2::2 esp 0x10001
-m transport
-E cast128-cbc "12341234"
-A hmac-sha1 "this is the test key" ;
add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10002
-E rc5-cbc "kamekame"
-A hmac-md5 "this is the test" ;
add fec0:0:0:2::2 fec0:0:0:1::1 esp 0x10003
-m transport
-E cast128-cbc "12341234"
-A hmac-sha1 "this is the test key" ;
add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10004
-E rc5-cbc "kamekame"
-A hmac-md5 "this is the test" ;
EOF
+
+
+
+ Chern
+ Lee
+ Contributed by
+
+
+
+
+
OpenSSHOpenSSHsecurityOpenSSH
- Contributed by &a.chern;, April 21,
- 2001.
-
-
Secure shell is a set of network connectivity tools used to
access remote machines securely. It can be used as a direct
replacement for rlogin,
rsh, rcp, and
telnet. Additionally, any other TCP/IP
connections can be tunneled/forwarded securely through ssh.
ssh encrypts all traffic to effectively eliminate eavesdropping,
connection hijacking, and other network-level attacks.OpenSSH is maintained by the OpenBSD project, and is based
upon SSH v1.2.12 with all the recent bug fixes and updates. It
is compatible with both SSH protocols 1 and 2. OpenSSH has been
in the base system since FreeBSD 4.0.Advantages of using OpenSSHNormally, when using &man.telnet.1; or &man.rlogin.1;,
data is sent over the network in an clear, un-encrypted form.
Network sniffers anywhere in between the client and server can
steal your user/password information or data transferred in
your session. OpenSSH offers a variety of authentication and
encryption methods to prevent this from happening.Enabling sshdOpenSSHenablingBe sure to make the following additions to your
rc.conf file:
sshd_enable="YES"This will load the ssh daemon the next time your system
initializes. Alternatively, you can simply run the
sshd daemon.SSH clientOpenSSHclientThe &man.ssh.1; utility works similarly to
&man.rlogin.1;.
&prompt.root ssh user@foobardomain.com
Host key not found from the list of known hosts.
Are you sure you want to continue connecting (yes/no)? yes
Host 'foobardomain.com' added to the list of known hosts.
user@foobardomain.com's password: *******The login will continue just as it would have if a session was
created using rlogin or telnet. SSH utilizes a key fingerprint
system for verifying the authenticity of the server when the
client connects. The user is prompted to enter 'yes' only during
the first time connecting. Future attempts to login are all
verified against the saved fingerprint key. The SSH client
will alert you if the saved fingerprint differs from the
received fingerprint on future login attempts. The fingerprints
are saved in ~/.ssh/known_hostsSecure copyOpenSSHsecure copyscpThe scp command works similarly to rcp;
it copies a file to or from a remote machine, except in a
secure fashion.&prompt.root scp user@foobardomain.com:/COPYRIGHT COPYRIGHT
user@foobardomain.com's password:
COPYRIGHT 100% |*****************************| 4735
00:00
&prompt.rootSince the fingerprint was already saved for this host in the
previous example, it is verified when using scp
here.
ConfigurationOpenSSHconfigurationThe system-wide configuration files for both the OpenSSH
daemon and client reside within the /etc/ssh
directory.
ssh_config configures the client
settings, while sshd_config configures the
daemon.
ssh-keygenInstead of using passwords, &man.ssh-keygen.1; can
be used to generate RSA keys to authenticate a user.
&prompt.user ssh-keygen
Initializing random number generator...
Generating p: .++ (distance 66)
Generating q: ..............................++ (distance 498)
Computing the keys...
Key generation complete.
Enter file in which to save the key (/home/user/.ssh/identity):
Enter passphrase:
Enter the same passphrase again:
Your identification has been saved in /home/user/.ssh/identity.
...&man.ssh-keygen.1; will create a public and private
key pair for use in authentication. The private key is stored in
~/.ssh/identity, whereas the public key is
stored in ~/.ssh/identity.pub. The public
key must be placed in ~/.ssh/authorized_keys
of the remote machine in order for the setup to work.
This will allow connection to the remote machine based upon
RSA authentication instead of passwords.If a passphrase is used in &man.ssh-keygen.1;, the user
will be prompted for a password each time in order to use the private
key.&man.ssh-agent.1; and &man.ssh-add.1; are
utilities used in managing multiple passworded private keys.
SSH TunnelingOpenSSHtunnelingOpenSSH has the ability to create a tunnel to encapsulate
another protocol in an encrypted session.The following command tells &man.ssh.1; to create a tunnel
for telnet.&prompt.user; ssh -2 -N -f -L 5023:localhost:23 user@foo.bar.com
&prompt.user;-2 this forces &man.ssh.1 to use version
2 of the protocol. (Do not use if you are working with older ssh
servers)-N indicates no command, or tunnel only.
If omitted, &man.ssh.1; would initiate a normal session.-f forces &man.ssh.1; to run
in the background.-L indicates a local tunnel in
localport:localhost:remoteport fashion.
foo.bar.com is the remote/target
SSH server.
An SSH tunnel works by creating a listen socket on the specified
local host and port. It then forwards any connection to the local
host/port via the SSH connection to the remote machine on the
specified remote port.
In the example, port 5023 on localhost
is being forwarded to port 23 on the remote
machine. Since 23 is telnet, this would
create a secure telnet session through an SSH tunnel.
This can be used to wrap any number of insecure TCP protocols
such as smtp, pop3, ftp, etc.
A typical SSH Tunnel&prompt.user; ssh -2 -N -f -L 5025:localhost:25 user@mailserver.foobar.com
user@mailserver.foobar.com's password: *****
&prompt.user; telnet localhost 5025
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 mailserver.foobar.com ESMTPThis can be used in conjunction with an &man.ssh-keygen.1;
and additional user accounts to create a more seamless/hassle-free
SSH tunneling environment. Keys can be used in place of typing
a password, and the tunnels can be run as a separate user.
Further ReadingOpenSSH&man.ssh.1; &man.scp.1; &man.ssh-keygen.1;
&man.ssh-agent.1; &man.ssh-add.1;&man.sshd.8; &man.sftp-server.8;
diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
index 39ed3aaae7..8aaaf6c721 100644
--- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
@@ -1,2586 +1,2590 @@
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.SeanKelly
- Contributed
+ Contributed by TerminalsterminalsTerminals 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.GuyHelmer
- Contributed
+ Contributed by
+
+ SeanKelly
- Additions
+ Additions by Dial-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.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.KazutakaYOKOTA
- Contributed
+ Contributed by
+
+ BillPaul
- Based on a document
+ Based on a document by Setting 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 e242a377f7..1675e6e19e 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 @@
MosesMoore
- Contributed
+ Contributed by SoundSynopsisFreeBSD 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: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/users/chapter.sgml b/en_US.ISO8859-1/books/handbook/users/chapter.sgml
index e42d02fed2..4387a025f3 100644
--- a/en_US.ISO8859-1/books/handbook/users/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/users/chapter.sgml
@@ -1,1027 +1,1027 @@
NeilBlakey-Milner
- Contributed
+ Contributed by Users and Basic Account ManagementSynopsisFreeBSD allows multiple users to use the computer at the same time.
Obviously, only one of those users can be sat in front of the screen and
keyboard at any one time, but any number of users can log in through the
network to get their work done. To use the system every user must have
an account.After reading this chapter you will know:The differences between the various user accounts on a FreeBSD
systemHow to add user accountsHow to remove user accountsHow to change account details, such as the user's full name, or
preferred shellHow to set limits on a per-account basis, to control the
resources such as memory and CPU time that accounts and groups of
accounts are allowed to accessHow to use groups to make account management easierBefore reading this chapter you should:Read IntroductionAll access to the system is achieved via accounts, and all
processes are run by users, so user and account management are
of integral importance on FreeBSD systems.Every account on a FreeBSD system has certain information associated
with it to identify the account.User nameThe user name as it would be typed at the
login: prompt. User names must be unique across
the computer; you may not have two users with the same
user name. There are a number of rules for creating valid user
names, documented in &man.passwd.5;; you would typically use user
names that consist of eight or fewer all lower case
characters.PasswordEach account has a password associated with it. The password
may be blank, in which case no password will be required to access
the system. This is normally a very bad idea; every account
should have a password.User ID (UID)The UID is a number from 0 to 65536 used to uniquely identify
the user to the system. Internally FreeBSD uses the UID to
identify users—any FreeBSD commands that allow you to
specify a user name will convert it to the UID before working with
it. This means that you can have several accounts with different
user names but the same UID. As far as FreeBSD is concerned these
accounts are one user. It is unlikely you will ever need to do
this.Group ID (GID)The GID is a number from 0 to 65536 used to uniquely identify
the primary group that the user belongs to. Groups are a
mechanism for controlling access to resources based on a user's
GID rather than their UID. This can significantly reduce the size
of some configuration files. A user may also be in more than one
group.Login classLogin classes are an extension to the group mechanism that
provide additional flexibility when tailoring the system to
different users.Password change timeBy default FreeBSD does not force users to change their
passwords periodically. You can enforce this on a per-user basis,
forcing some or all of your users to change their passwords after
a certain amount of time has elapsed.Account expiry timeBy default FreeBSD does not expire accounts. If you are
creating accounts that you know have a limited lifespan, for
example, in a school where you have accounts for the students,
then you can specify when the account expires. After the expiry
time has elapsed the account can not be used to log in to the
system, although the account's directories and files will
remain.User's full nameThe user name uniquely identifies the account to FreeBSD, but
does not necessarily reflect the user's real name. This
information can be associated with the account.Home directoryThe home directory is the full path to a directory on the
system in which the user will start when logging on to the
system. A common convention is to put all user home directories
under
/home/username.
The user would store their personal files in their home directory,
and any directories they may create in there.User shellThe shell provides the default environment users use to
interact with the system. There are many different kinds of
shells, and experienced users will have their own preferences,
which can be reflected in their account settings.There are three main types of accounts; the Superuser, system users, and user accounts. The Superuser
account, usually called root, is used to
manage the system with no limitations on privileges. System
users run services. Finally, user accounts are used by real
people, who log on, read mail, and so forth.The Superuser Accountaccountssuperuser (root)The superuser account, usually called
root, comes preconfigured to facilitate
system administration, and should not be used for day-to-day
tasks like sending and receiving mail, general exploration of
the system, or programming.This is because the superuser, unlike normal user accounts,
can operate without limits, and misuse of the superuser account
may result in spectacular disasters. User accounts are unable
to destroy the system by mistake, so it is generally best to use
normal user accounts whenever possible, unless you especially
need the extra privilege.You should always double and triple-check commands you issue
as the superuser, since an extra space or missing character can
mean irreparable data loss.So, the first thing you should do after reading this
chapter, is to create an unprivileged user account for yourself
for general usage, if you haven't already. This applies equally
whether you're running a multi-user or single-user machine.
Later in this chapter, we discuss how to create additional
accounts, and how to change between the normal user and
superuser.System AccountsaccountssystemSystem users are those used to run services such as DNS,
mail, web servers, and so forth. The reason for this is
security; if all services ran as the superuser, they could
act without restriction.accountsdaemonaccountsoperatorExamples of system users are daemon,
operator, bind (for
the Domain Name Service), and news. Often
sysadmins create httpd to run web servers
they install.accountsnobodynobody is the generic unprivileged
system user. However, it's important to keep in mind that the
more services that use nobody, the more
files and processes that user will become associated with, and
hence the more privileged that user becomes.User AccountsaccountsuserUser accounts are the primary means of access for real
people to the system, and these accounts insulate the user and
the environment, preventing the users from damaging the system
or other users, and allowing users to customize their
environment without affecting others.Every person accessing your system should have a unique user
account. This allows you to find out who is doing what, prevent
people from clobbering each others' settings or reading each
others' mail, and so forth.Each user can set up their own environment to accommodate
their use of the system, by using alternate shells, editors, key
bindings, and language.Modifying Accountsaccountsmodifyingpw is a powerful and flexible
tool to modify all aspects of user accounts. For most tasks
however, adduser and
rmuser are recommended to add and
remove accounts respectively.chpass allows both the system
administrator and normal users to adjust passwords, shells, and
personal information. If you are only interested in changing a
password then the passwd command is
usually quicker.adduseraccountsaddingadduser/usr/share/skelskeleton directoryadduser is a simple program for
adding new users. It creates entries in the system
passwd and group
files. It will also create a home directory for the new user,
copy in the default configuration files ("dotfiles") from
/usr/share/skel, and can optionally mail
the new user a welcome message.To create the initial configuration file, use
adduser -s -config_create.
The makes adduser
default to
quiet. We use later when we want to
change defaults.
Next, we configure adduser
defaults, and create our first user account, since using
root for normal usage is evil and
nasty.Configuring adduser&prompt.root; adduser -v
Use option ``-silent'' if you don't want to see all warnings and questions.
Check /etc/shells
Check /etc/master.passwd
Check /etc/group
Enter your default shell: csh date no sh tcsh zsh [sh]: zsh
Your default shell is: zsh -> /usr/local/bin/zsh
Enter your default HOME partition: [/home]:
Copy dotfiles from: /usr/share/skel no [/usr/share/skel]:
Send message from file: /etc/adduser.message no
[/etc/adduser.message]: no
Do not send message
Use passwords (y/n) [y]: y
Write your changes to /etc/adduser.conf? (y/n) [n]: y
Ok, let's go.
Don't worry about mistakes. I will give you the chance later to correct any input.
Enter username [a-z0-9_-]: jru
Enter full name []: J. Random User
Enter shell csh date no sh tcsh zsh [zsh]:
Enter home directory (full path) [/home/jru]:
Uid [1001]:
Enter login class: default []:
Login group jru [jru]:
Login group is ``jru''. Invite jru into other groups: guest no
[no]: wheel
Enter password []:
Enter password again []:
Name: jru
Password: ****
Fullname: J. Random User
Uid: 1001
Gid: 1001 (jru)
Class:
Groups: jru wheel
HOME: /home/jru
Shell: /usr/local/bin/zsh
OK? (y/n) [y]: y
Added user ``jru''
Copy files from /usr/share/skel to /home/jru
Add another user? (y/n) [y]: n
Goodbye!
&prompt.root;In summary, we changed the default shell to
zsh (an additional shell found in
packages), and turned off the sending of a welcome mail to
added users. We then saved the configuration, and then
created an account for jru, and we made
sure jru is in wheel
group (which we'll see is important later).The password you type in isn't echoed, nor are asterisks
displayed. Make sure you don't mistype the password twice.
Just use adduser without arguments
from now on, and you won't have to go through changing the
defaults. If the program asks you to change the defaults,
exit the program, and try the
option.rmuserrmuseraccountsremovingYou can use rmuser to
completely remove a user from the system.
rmuser performs the following
steps:Removes the user's &man.crontab.1; entry (if
any).Removes any &man.at.1; jobs belonging to the
user.Kills all processes owned by the user.Removes the user from the system's local password
file.Removes the user's home directory (if it is owned by
the user).Removes the incoming mail files belonging to the user
from /var/mail.Removes all files owned by the user from temporary
file storage areas such as /tmp.Finally, removes the username from all groups to which
it belongs in /etc/group.
If a group becomes empty and the group name is the
same as the username, the group is removed; this
complements the per-user unique groups created by
&man.adduser.8;.rmuser can't be used to remove
superuser accounts, since that is almost always an indication
of massive destruction.By default, an interactive mode is used, which attempts to
make sure you know what you're doing.rmuser interactive account removal&prompt.root; rmuser jru
Matching password entry:
jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/tcsh
Is this the entry you wish to remove? y
Remove user's home directory (/home/jru)? y
Updating password file, updating databases, done.
Updating group file: trusted (removing group jru -- personal group is empty) done.
Removing user's incoming mail file /var/mail/jru: done.
Removing files belonging to jru from /tmp: done.
Removing files belonging to jru from /var/tmp: done.
Removing files belonging to jru from /var/tmp/vi.recover: done.
&prompt.root;pwpwpw is a command line utility to
create, remove, modify, and display users and groups, and functions
as an editor of the system user and group files. This section
describes its use for users. The Groups section below describes its
use for groups.It is designed to be useful both as a directly executed
command and for use from shell scripts.For detailed information, please see &man.pw.8;.chpasschpasschpass changes user database
information such as passwords, shells, and personal
information.Only system administrators, as the superuser, may change
other users' information and passwords with
chpass.When passed no options, aside from an optional username,
chpass displays an editor
containing user information. When the user exists from the
editor, the user database is updated with the new
information.Interactive chpass by Superuser#Changing user database information for jru.
Login: jru
Password: *
Uid [#]: 1000
Gid [# or name]: 1000
Change [month day year]:
Expire [month day year]:
Class:
Home directory: /home/jru
Shell: /usr/local/bin/tcsh
Full Name: J. Random User
Office Location:
Office Phone:
Home Phone:
Other information:The normal user can change only a small subsection of this
information, and only for themselves.Interactive chpass by Normal User#Changing user database information for jru.
Shell: /usr/local/bin/tcsh
Full Name: J. Random User
Office Location:
Office Phone:
Home Phone:
Other information:chfn and chsh are
just links to chpass, as
are ypchpass,
ypchfn, and
ypchsh. NIS support is automatic, so
specifying the yp before the command is
not necessary.passwdpasswdaccountschanging passwordpasswd is the usual way to
change your own password as a user, or another user's password
as the superuser.Users must type in their original password before
changing their password, to prevent an unauthorized person
from changing their password when the user is away from
their console.Changing your password&prompt.user; passwd
Changing local password for jru.
Old password:
New password:
Retype new password:
passwd: updating the database...
passwd: doneChanging another user's password as the superuser&prompt.root; passwd jru
Changing local password for jru.
New password:
Retype new password:
passwd: updating the database...
passwd: doneyppasswd is just a link to
passwd. NIS support is automatic, so
specifying the yp before the command is
not necessary.Limiting Userslimiting usersaccountslimitingIf you run a multi-user system, chances are that you do not trust
all of your users not to damage your system. FreeBSD provides a
number of ways a system administrator can limit the amount of system
resources an individual user can use. These limits are generally
divided into two sections: disk quotas, and other resource
limits.quotaslimiting usersquotasdisk quotasDisk quotas are a way for the system administrator to tell the
filesystem the amount of disk space a user may use; moreover, they
provide a way to quickly check on the disk usage of a user without
having to calculate it every time. Quotas are discussed in .The other resource limits include ways to limit the amount of
CPU, memory, and other resources a user may consume. These are
defined using login classes and are discussed here./etc/login.confLogin classes are defined in
/etc/login.conf. The precise semantics are
beyond the scope of this section, but are described in detail in the
&man.login.conf.5; manual page. It is sufficient to say that each
user is assigned to a login class (default by
default), and that each login class has a set of login capabilities
associated with it. A login capability is a
name=value
pair, where name is a well-known
identifier and value is an arbitrary
string processed accordingly depending on the name. Setting up login
classes and capabilities is rather straight-forward, and is also
described in &man.login.conf.5;.Resource limits are different from plain vanilla login
capabilities in two ways. First, for every limit, there is a soft
(current) and hard limit. A soft limit may be adjusted by the user
or application, but may be no higher than the hard limit. The latter
may be lowered by the user, but never raised. Second, most resource
limits apply per process to a specific user, not the user as a whole.
Note, however, that these differences are mandated by the specific
handling of the limits, not by the implementation of the login
capability framework (i.e., they are not really
a special case of login capabilities).And so, without further ado, below are the most commonly used
resource limits (the rest, along with all the other login
capabilities, may be found in &man.login.conf.5;).coredumpsizecoredumpsizelimiting userscoredumpsizeThe limit on the size of a core file generated by a program
is, for obvious reasons, subordinate to other limits on disk
usage (e.g., filesize, or disk quotas).
Nevertheless, it is often used as a less-severe method of
controlling disk space consumption: since users do not generate
core files themselves, and often do not delete them, setting this
may save them from running out of disk space should a large
program (e.g., emacs) crash.cputimecputimelimiting userscputimeThis is the maximum amount of CPU time a user's process may
consume. Offending processes will be killed by the kernel.
This is a limit on CPU time
consumed, not percentage of the CPU as displayed in some
fields by &man.top.1; and &man.ps.1;. A limit on the
latter is, at the time of this writing, not possible, and
would be rather useless: a compiler—probably a
legitimate task—can easily use almost 100% of a CPU
for some time.filesizefilesizelimiting usersfilesizeThis is the maximum size of a file the user may possess.
Unlike disk quotas, this limit is
enforced on individual files, not the set of all files a user
owns.maxprocmaxproclimiting usersmaxprocThis is the maximum number of processes a user may be
running. This includes foreground and background processes
alike. For obvious reasons, this may not be larger than the
system limit specified by the kern.maxprocsysctl. Also note that setting this
too small may hinder a
user's productivity: it is often useful to be logged in
multiple times or execute pipelines. Some tasks, such as
compiling a large program, also spawn multiple processes (e.g.,
&man.make.1;, &man.cc.1;, and other intermediate
preprocessors).memorylockedmemorylockedlimiting usersmemorylockedThis is the maximum amount a memory a process may have
requested to be locked into main memory (e.g., see
&man.mlock.2;). Some system-critical programs, such as
&man.amd.8;, do this so that their getting swapped out does not
contribute to a system's thrashing in time of trouble.memoryusememoryuselimiting usersmemoryuseThis is the maximum amount of memory a process may consume
at any given time. It includes both core memory and swap
usage. This is not a catch-all limit for restricting memory
consumption, but it is a good start.openfilesopenfileslimiting usersopenfilesThis is the maximum amount of files a process may have
open. In FreeBSD, files are also used to represent sockets and
IPC channels; thus, be careful not to set this too low. The
system-wide limit for this is defined by the
kern.maxfilessysctl.sbsizesbsizelimiting userssbsizeThis is the limit on the amount of network memory, and thus
mbufs, a user may consume. This originated as a response to an
old DoS attack by creating a lot of sockets, but can be
generally used to limit network communications.stacksizestacksizelimiting usersstacksizeThis is the maximum size a process' stack may grow to.
This alone is not sufficient to limit the amount of memory a
program may use; consequently, it should be used in conjunction
with other limits.There are a few other things to remember when setting resource
limits. Following are some general tips, suggestions, and
miscellaneous comments.Processes started at system startup by
/etc/rc are assigned to the
daemon login class.Although the /etc/login.conf that comes
with the system is a good source of reasonable values for most
limits, only you, the administrator, can know what is appropriate
for your system. Setting a limit too high may open your system
up to abuse, while setting it too low may put a strain on
productivity.Users of the X Window System (X11) should probably be granted
more resources than other users. X11 by itself takes a lot of
resources, but it also encourages users to run more programs
simultaneously.Remember that many limits apply to individual processes, not
the user as a whole. For example, setting
openfiles to 50 means
that each process the user runs may open up to 50 files. Thus,
the gross amount of files a user may open is the value of
openfiles multiplied by the value of
maxproc. This also applies to memory
consumption.For further information on resource limits and login classes and
capabilities in general, please consult the relevant manual pages:
&man.cap.mkdb.1;, &man.getrlimit.2;, &man.login.conf.5;.Personalizing UsersLocalization is an environment set up by the system
administrator or user to accommodate different languages,
character sets, date and time standards, and so on. This is
discussed in the localization
chapter.Groupsgroups/etc/groupsaccountsgroupsA group is simply a list of users. Groups are identified by
their group name and gid (group ID). In FreeBSD (and most other Unix
systems), the two factors the kernel uses to decide whether a process
is allowed to do something is its user ID and list of groups it
belongs to. Unlike a user ID, a process has a list of groups
associated with it. You may hear some things refer to the "group ID"
of a user or process; most of the time, this just means the first
group in the list.The group name to group ID map is in
/etc/group. This is a plain text file with four
colon-delimited fields. The first field is the group name, the
second is the encrypted password, the third the group ID, and the
fourth the comma-delimited list of members. It can safely be edited
by hand (assuming, of course, that you don't make any syntax
errors!). For a more complete description of the syntax, see the
&man.group.5; manual page.If you don't want to edit /etc/group
manually, you can use the &man.pw.8; command to add and edit groups.
For example, to add a group called teamtwo and
then confirm that it exists you can use:Adding a group using &man.pw.8;&prompt.root; pw groupadd teamtwo
&prompt.root; pw groupshow teamtwo
teamtwo:*:1100:The number 1100 above is the group ID of the
group teamtwo. Right now,
teamtwo has no members, and is thus rather
useless. Let's change that by inviting jru to
the teamtwo group.Adding somebody to a group using &man.pw.8;&prompt.root; pw groupmod teamtwojru
&prompt.root; pw groupshow teamtwo
teamtwo:*:1100:jruThe argument to the option is a
comma-delimited list of users who are members of the group. From the
preceding sections, we know that the password file also contains a
group for each user. The latter (the user) is automatically added to
the group list by the system; the user will not show up as a member
when using the groupshow command to &man.pw.8;,
but will show up when the information is queried via &man.id.1; or
similar tool. In other words, &man.pw.8; only manipulates the
/etc/group file; it will never attempt to read
additionally data from /etc/passwd.Using &man.id.1; to determine group membership&prompt.user; idjru
uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)As you can see, jru is a member of the
groups jru and
teamtwo.For more information about &man.pw.8;, see its manual page, and
for more information on the format of
/etc/group, consult the &man.group.5; manual
page.
diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
index 069f1a356f..1372dd97a9 100644
--- a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml
@@ -1,1139 +1,1149 @@
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: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.MurrayStokely
- Section on fonts
+ Section on fonts by Using 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.SethKingsley
- Section on XDM
+ Section on XDM by The 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.
+
+
+
+ Valentino
+ Vaschetto
+ Contributed by
+
+
+
+
+
Desktop Environments
- Written 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.)