os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

The FreeBSD handbook finds a new home.

Browse source
This commit is contained in:
John Fieber 1995-04-28 16:19:59 +00:00
commit 4776451dac
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=2
21 changed files with 5167 additions and 0 deletions

20
handbook/authors.sgml Normal file
View file

@ -0,0 +1,20 @@
<!-- $Id: authors.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!--
Names and email address of contributing authors. Use these
entities when referencing people.
-->
<!ENTITY a.jkh "Jordan Hubbard <tt>&lt;jkh@FreeBSD.org&gt;</tt>">
<!ENTITY a.jfieber "John Fieber <tt>&lt;jfieber@FreeBSD.org&gt;</tt>">
<!ENTITY a.phk "Poul-Henning Kamp <tt>&lt;phk@FreeBSD.org&gt;</tt>">
<!ENTITY a.gclarkii "Gary Clark II <tt>&lt;gclarkii@FreeBSD.org&gt;</tt>">
<!ENTITY a.gena "Gennady B. Sorokopud <tt>&lt;gena@NetVision.net.il&gt;</tt>">
<!ENTITY a.ghelmer "Guy Helmer <tt>&lt;ghelmer@alpha.dsu.edu&gt;</tt>">
<!ENTITY a.md "Mark Dapoz <tt>&lt;md@bsc.no&gt;</tt>">
<!ENTITY a.martin "Martin Renters <tt>&lt;martin@innovus.com&gt;</tt>">
<!ENTITY a.gpalmer "Gary Palmer <tt>&lt;gpalmer@FreeBSD.org&gt;</tt>">
<!ENTITY a.john "John Lind <tt>&lt;john@starfire.MN.ORG&gt;</tt>">
<!ENTITY a.asami "Satoshi Asami <tt>&lt;asami@FreeBSD.org&gt;</tt>">
<!ENTITY a.wilko "Wilko Bulte <tt>&lt;wilko@yedi.iaf.nl&gt;</tt>">

73
handbook/basics.sgml Normal file
View file

@ -0,0 +1,73 @@
<!-- $Id: basics.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Unix Basics</heading>
<sect>
<heading>The online manual</heading>
<p>The most comprehensive documentation on FreeBSD is in
the form of <em>man pages</em>. Nearly every program
on the system comes with a short reference manual
explaining the basic operation and various argument.
These manuals can be view with the
<tt><bf>man</bf></tt> command. Use of the
<tt><bf>man</bf></tt> command is simple:
<tscreen>
<tt><bf>man</bf> <it>command</it></tt>
</tscreen>
where <it>command</it> is the name of the command
you wish to find. For example, to learn more about
<tt><bf>ls</bf></tt> command type:
<tscreen>
<tt><bf>man</bf> ls</tt>
</tscreen>
<p>The online manual is divided up into numbered
sections:
<enum>
<item>User commands</item>
<item>System calls and error numbers</item>
<item>Functions in the C libraries</item>
<item>Device drivers</item>
<item>File formats</item>
<item>Games and other diversions</item>
<item>Miscellaneous information</item>
<item>System maintenance and operation commands</item>
</enum>
in some cases, the same topic may appear in more than
one section of the on-line manual. For example, there
is a <tt><bf>chmod</bf></tt> user command and a
<tt><bf>chmod()</bf></tt> system call. In this case,
you can tell the <tt><bf>man</bf></tt> command which
you want by specifying the section:
<tscreen>
<tt><bf>man</bf> 1 chmod</tt>
</tscreen>
which will display the manual page for the user command
<tt><bf>chmod</bf></tt>.
<p>This is fine if you know the name of the command and
forgot how to use it, but what if you cannot recall the
command name? You can use <tt><bf>man</bf></tt> to
search through the command <em>descriptions</em> by
using the <tt><bf>-k</bf></tt> switch:
<tscreen>
<tt><bf>man</bf> -k mail</tt>
</tscreen>
With this command you will be presented with a list of
commands that have the keyword `mail' in their
descriptions.
<sect>
<heading>GNU Info files</heading>
<p>FreeBSD includes many applications and utilities
produced by the Free Software Foundation (FSF). In
addition to man pages, these programs come with more
extensive <em>info</em> files which can be viewed with
the <tt>info</tt> command or, if you installed
<tt>emacs</tt>, the info mode of <tt>emacs</tt>.
</sect>

110
handbook/bibliography.sgml Normal file
View file

@ -0,0 +1,110 @@
<!-- $Id: bibliography.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt>
<heading>Bibliography</heading>
<p>While the manual pages provide the definative reference
for individual pieces of the FreeBSD operating system,
they are notorious for not illustrating how to put the
pieces together to make the whole operating system run
smoothly. For this, there is no substitute for a good
book on Unix system administration, and a good users'
manual.
<sect>
<heading>Users' guides</heading>
<p><itemize>
<item>Gilley, Daniel. <sl>Unix in a Nutshell</sl>.
O'Reilly &amp; Associates, Inc. 1990</item>
</itemize>
<sect>
<heading>Administrators' guides</heading>
<p><itemize>
<item>Albitz, Paul; Liu, Cricket. <em>DNS and
BIND</em>. O'Reilley &amp; Associates. 1993. ISBN
1-56592-010-4 </item>
<item>Costales, Brian; Allman, Eric; Rickert,
Neil. <em>sendmail</em> O'Reilley &amp;
Associates. 1993. ISBN 1-56592-056-2 </item>
<item>Frisch, &AElig;leen. <em>Essential System
Administration</em>. O'Reilley &amp;
Associates. 1993. ISBN 0-937175-80-3 </item>
<item>Hunt, Craig. <em>TCP/IP Network Administration</em>
O'Reilley &amp; Associates. 1992. ISBN 0-937175-82-X</item>
<item>Nemeth, Evi. <em>Unix System Administration
Handbook</em>. Prentice Hall. 1989. ISBN
0-13-933441-6</item>
</itemize>
<sect>
<heading>Programmers' guides</heading>
<p><itemize>
<item>Asente, Paul. <em>X Window System
Toolkit</em>. Digital Press. ISBN
1-55558-051-3</item>
<item>Ellis, Margaret A. and Stroustrup,
Bjarne. <em>The Annotated C++ Reference
Manual</em>. Addison-Wesley. 1990. ISBN
0-201-51459-1</item>
<item>Harbison, Samuel P. and Steele, Guy
L. Jr. <em>C: A Reference Manual</em>. Prentice
Hall. 3rd Edition, 1991. ISBN
0-13-110933-2</item>
<item>Jolitz, William. "Porting UNIX to the
386". <em>Dr. Dobb's Journal</em>. January
1991-July 1992.</item>
<item>Leffler, Samuel J. <em>The Design and
implementation of the 4.3BSD UNIX operating
system</em>. Addison-Wesley. 1989.</item>
<item>Plauger, P. J. <em>The Standard C
Library</em>. Prentice Hall. 1992. ISBN
0-13-131509-9</item>
<item>Wells, Bill. "Writing Serial Drivers for UNIX".
<em>Dr. Dobb's Journal</em>. 19(15), December
1994. pp68-71, 97-99.</item>
</itemize>
<sect>
<heading>Hardware reference</heading>
<p><itemize>
<item>Stanley, Tom; Anderson, Don. <em>PCI System
Architechure</em>. Mindshare, Inc. ISBN
1-881609-08-1</item>
</itemize>
<sect>
<heading>Magazines and journals</heading>
<p><itemize>
<item><em>The C/C++ Users Journal</em>. R&amp;D Publications
Inc. ISSN 1075-2838</item>
</itemize>
</sect>

199
handbook/ctm.sgml Normal file
View file

@ -0,0 +1,199 @@
<!--
# This is the sgml version of the ctm.FAQ file.
#
# Converted by Ollivier RObert <roberto@FreeBSD.ORG>
#
# $Id: ctm.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $
#
# ----------------------------------------------------------------------------
# "THE BEER-WARE LICENSE" (Revision 42):
# <phk@login.dknet.dk> wrote this file. As long as you retain this notice you
# can do whatever you want with this stuff. If we meet some day, and you think
# this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp
# ----------------------------------------------------------------------------
#
-->
<sect><heading>CTM</heading>
<p><em>Contributed by &a.phk;. Updated 16-Mar-1995.</em>
<tt/CTM/ is a method for keeping a remote directory tree in sync with a
central one. It has been developed for usage with FreeBSD's source
trees, though other people may find it useful for other purposes as
time goes by. Little, if any, documentation currently exists at
this time on the process of creating deltas, so talk to &a.phk;
for more information should you wish to use <tt/CTM/ for other things.
<sect1>Why should I use <tt/CTM/ ?
<p><tt/CTM/ will give you a local copy of the ``FreeBSD-current''
sources. If you are an active developer on FreeBSD, but have lousy
or non-existent TCP/IP connectivity, <tt/CTM/ was made for you.
You will need to transfer up to four deltas per day (or you can
have them arrive in email automatically), the sizes for which are
always kept as small as possible. This is typically less than 5K,
with the occasional (one in ten) being 10-50K and every now and
then a biggie of 100K+ or more coming around.
You will also need to make yourself aware of the various caveats in
running ``current'' sources, and for this it is recommended that
you refer to the relevant FAQ which can be found in
<verb>
/usr/share/FAQ/Text/current-policy.FAQ
</verb>
<!-- XXX -->
<sect1>What do I need to use <tt/CTM/?
<p>You will need two things: The ``<tt/CTM/'' program and the initial
deltas to feed it (to get up to ``current'' levels).
The <tt/CTM/ program is in the <tt/FreeBSD-current/ tree from
version 2.0.0 and forward (<tt>/usr/src/usr.sbin/<tt/CTM/</tt>).
If you are running an older version of FreeBSD, you can fetch the
current <tt/CTM/ sources directly from:
<url
url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm">
The ``deltas'' you feed <tt/CTM/ can be had two ways, ftp or email.
If you have general ftp access to the Internet, then the following
ftp sites support access to <tt/CTM/:
<url url="ftp://freefall.cdrom.com/pub/CTM">
Ftp the the relevant directory and fetch the <tt/README/ file,
starting from there.
If you only have access to electronic mail or are otherwise blocked
from using ftp, then you may wish to your deltas via email:
Send email to <tt/&lt;majordomo@freebsd.org&gt;/ to subscribe to
the list ``ctm-src-cur''. (If you do not know how to subscribe
yourself using majordomo, send a message first containing the
word ``help'', it will send you back usage instructions.)
When you begin receiving your <tt/CTM/ updates in the mail, you may
use the <tt/ctm_rmail/ program to unpack and apply them with. You
can actually use the <tt/ctm_rmail/ program directly from a entry
in <tt>/etc/aliases</tt> if you want. Check the <tt/ctm_rmail/ man
page for more details.
<bf/NOTE/: No matter what method you use to get the <tt/CTM/
deltas, you should subscribe to the <tt/ctm-announce@freebsd.org/
mailing list. In the future this will be the only place where
announcements about the operation of the <tt/CTM/ system will be
posted. Send an email to <tt/majordomo@freebsd.org/ with a single
line of ``<tt/subscribe ctm-announce/'' to get added to the list.
<sect1>Starting off with <tt/CTM/ for the first time:
<p>Before you can start using <tt/CTM/ deltas, you will need to get a
special ``base'' delta that provides a starting point for all
deltas produced subsequently to it.
You can recognize a base delta by the ``<tt/A/'' appended to the
number (<tt/src-cur.0341A.gz/ for instance). As a rule a base
delta is produced every 100 deltas, the next one will be
<tt/src-cur.0400A.gz/. By the way, they are large! 25 to 30
Megabytes of <tt/gzip/'ed data is common for a base delta.
If you do have the 2.0-RELEASE <tt/srcdist/, you can instead
retreive the <tt/src-cur.0372R20.gz/ file, it's only 4Mb and it
will take you to current from the 2.0-RELEASE sources.
Once you've picked a base delta to start from, you will also need
all deltas with higher numbers following it.
<sect1>Using <tt/CTM/ in your daily life:
<p>To apply the deltas, simply say
<verb>
cd /where/ever/you/want/the/stuff
ctm -v -v /where/you/store/your/deltas/src-cur.*
</verb>
<tt/CTM/ understands deltas which have been put through <tt/gzip/,
so you don't need to gunzip them first, this saves diskspace.
Unless it feels very secure about the entire process, <tt/CTM/ will
not touch your tree. To check out a delta you can also use the
``<tt/-c/'' flag and <tt/CTM/ won't actually touch your tree, but
only check the integrity of the delta, and see if it would apply
cleanly to the tree.
There are other options to <tt/CTM/ as well, look in the sources.
I would also be very happy if somebody could help with the ``user
interface'' portions, as I have realized that I can't make up my
mind on what options should do what, how and when...
That's really all there is to it. Everytime you get a new delta,
you run it through <tt/CTM/.
Don't remove the deltas if they are hard to download again. You
just might want to keep them around in case something bad happens.
Even if you only have floppy disks, consider using <tt/fdwrite/ to
make a copy.
<sect1>Future plans for <tt/CTM/
<p>
Tons of them:
<itemize>
<item>
Make local modifications to the tree possible. One way to do
it could be this:<p> When <tt/CTM/ wants to edit the file
``<tt>foo/bar.c</tt>'', it would first check for the existence
of <tt>foo/bar.c&num;CTM</tt> If this file exists, the delta is
applied to it instead. This way the <tt>foo/bar.c</tt> file
can be edited to suit local needs.
<item>
Make a ``restore file(s)'' option to <tt/CTM/, something like:
<verb>
ctm -r src/sys/i386/wd.c /here/are/my/deltas/src-cur.*
</verb>
would restore <tt/wd.c/ to the current status from the files.
<item>
Clean up the options to <tt/CTM/, they became confusing and
counter intuitive.
</itemize>
The bad news is that I am very busy, so any help in doing this will
be most welcome. And don't forget to tell me what you want also...
<sect1>Miscellaneous stuff
<p>
All the ``DES infected'' (e.g. export controlled) source is not
included. You will get the ``international'' version only. If
sufficient interest appears, we will set up a ``<tt/sec-cur/''
sequence too.
If you are a frequent or valuable contributor to FreeBSD, I will be
willing to arrange special services, one option is delivery via
<tt/ftp/ or <tt/rcp/ to a machine closer to you. You need to have
earned this, since it takes time to do, but I'll be all the more
happy to do it for you then.
There is a sequence of deltas for the <tt/ports/ collection too,
but interest has not been all that high yet. Tell me if you want
an email list for that too and we'll consider setting it up.
If you have commit priviledges or are similary authorized by the
FreeBSD core team, you can also get access to the CVS repository
tree by the same means. Contact &a.phk;
for details.
<sect1>Thanks!
<p>
<descrip>
<tag/Bruce Evans/
for his pointed pen and invaluable comments.
<tag/Soren Schmidt/
for patience.
<tag/Stephen McKay/
wrote <tt/ctm_&lsqb;rs&rsqb;mail/, much appreciated.
<tag/Jordan Hubbard/
for being so stubborn that I had to make it better.
<tag/All the users/
I hope you like it...
</descrip>

179
handbook/current.sgml Normal file
View file

@ -0,0 +1,179 @@
<!-- $Id: current.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Staying current with FreeBSD</heading>
<p><em>Contributed by &a.jkh;.</em>
<!--
THE FREEBSD CURRENT POLICY
Last updated: $Date: 1995-04-28 16:19:59 $
This document attempts to explain the rationale behind FreeBSD-current,
what you should expect should you decide to run it, and states some
prerequisites for making sure the process goes as smoothly as possible.
-->
<sect><heading>What is FreeBSD-current?</heading>
<p>FreeBSD-current is, quite literally, nothing more than a daily snapshot of
the working sources for FreeBSD. These include work in progress, experimental
changes, and transitional mechanisms that may or may not be present in
the next official release of the software. While many of us compile
almost daily from FreeBSD-current sources, there are periods of time when
the sources are literally uncompilable. These problems are generally resolved
as expeditiously as possible, but whether or not FreeBSD-current sources bring
disaster or greatly desired functionality can literally be a matter of which
part of any given 24 hour period you grabbed them in!
Under certain circumstances we will sometimes make binaries for parts of
FreeBSD-current available, but only because we're interested in getting
something tested, not because we're in the business of providing binary
releases of current. If we don't offer, please don't ask! It takes far
too much time to do this as a general task.
<sect><heading>Who needs FreeBSD-current?</heading>
<p>FreeBSD-current is made generally available for 3 primary interest groups:
<enum>
<item> Members of the FreeBSD group who are actively working on one
part or another of the source tree and for whom keeping `current'
is an absolute requirement.
<item> Members of the FreeBSD group who are active ALPHA or BETA testers
and willing to spend time working through problems in order to
ensure that FreeBSD-current remains as sane as possible. These
are also people who wish to make topical suggestions on changes
and the general direction of FreeBSD.
<item> Peripheral members of the FreeBSD (or some other) group who merely
wish to keep an eye on things and use the current sources for
reference purposes (e.g. for <em>reading</em>, not running). These
people also make the occasional comment or contribute code.
</enum>
<sect><heading>What is FreeBSD-current <em>NOT</em>?</heading>
<p><enum>
<item> A fast-track to getting pre-release bits because there's something
you heard was pretty cool in there and you want to be the first on
your block to have it.
<item> A quick way of getting bug fixes.
<item> In any way ``officially supported'' by us.
We do our best to help people genuinely in one of the 3
``legitimate'' FreeBSD-current catagories, but we simply <em>do not
have the time</em> to help every person who jumps into FreeBSD-current
with more enthusiasm than knowledge of how to deal with
experimental system software. This is not because we're mean and
nasty people who don't like helping people out (we wouldn't even be
doing FreeBSD if we were), it's literally because we can't answer
400 messages a day <em>and</em> actually work on FreeBSD! I'm sure if
given the choice between having us answer lots of questions or
continue to improve FreeBSD, most of you would vote for us
improving it.
</enum>
<sect><heading>Using FreeBSD-current</heading>
<p><enum> <item> Join the freebsd-hackers and freebsd-commit
mailing lists. This is not just a good idea, it's
<em>essential</em>. If you aren't on freebsd-hackers, you
won't read the comments that people are making about the
current state of the system and thus will end up stumbling
over a lot of problems that others have already found and
solved. Even more importantly, you will miss out on
potentially critical information (e.g. ``Yo, Everybody!
Before you rebuild <tt>/usr/src</tt>, you <em>must</em>
rebuild the kernel or your system will crash horribly!").
The freebsd-commit list will allow you to see the commit log
entry for each change as its made. This can also contain
important information, and will let you know what parts of
the system are being actively changed.
To join these lists, send mail to `majordomo@FreeBSD.ORG'
and say:
<verb>
subscribe freebsd-hackers
subscribe freebsd-commit
</verb>
In the body of your message. Optionally, you can also say `help'
and MajorDomo will send you full help on how to subscribe and
unsubscribe to the various other mailing lists we support.
<item> Grab the sources from ftp.FreeBSD.ORG. You can do this in
three ways:
<enum>
<item> Using the CTM facility desribed below. Unless you
have a good TCP/IP connection at a flat rate, this is
the way to do it.
<item> Use the CMU `sup' program (Software Update
Protocol), also described below.
This is the second most recommended method, since it allows
you to grab the entire collection once and then only what's
changed from then on. Many people run sup from cron
and keep their sources up-to-date automatically.
The problem is that sup does not use the bandwidth efficient,
unless the round-trip is very fast. If the cost of connection
or the duration of the session is a concern, use CTM.
<item> Use ftp. The source tree for FreeBSD-current is always
"exported" on:
<verb>
ftp.FreeBSD.ORG:~ftp/pub/FreeBSD/FreeBSD-current
</verb>
We use `wu-ftpd' which allows compressed/tar'd grabbing
of whole trees. e.g. you see:
<verb>
usr.bin/lex
</verb>
You can do:
<verb>
ftp> cd usr.bin
ftp> get lex.tar.Z
</verb>
And it will get the whole directory for you as a compressed
tar file.
</enum>
<item> If you're grabbing the sources to run, and not just look at,
then grab <em>all</em> of current, not just selected portions. The
reason for this is that various parts of the source depend on
updates elsewhere and trying to compile just a subset is almost
guaranteed to get you into trouble.
<item> Before compiling current, read the Makefile in /usr/src
carefully. You'll see one-time targets like `bootstrapld'
which <em><bf>must</bf></em> be run as part of the upgrading process. Reading
freebsd-hackers will keep you up-to-date on other bootstrapping
procedures that sometimes become necessary as we move towards
the next release.
<item> Be active! If you're running FreeBSD-current, we want to know
what you have to say about it, especially if you have suggestions
for enhancements or bug fixes. Suggestions with accompanying code
are received most enthusiastically!
</enum>
<!--
Thank you for taking the time to read this all the way through. We're
always very keen to remain "open" and share the fruits of our labor
with the widest possible audience, but sharing development sources has
always had certain pitfalls associated with it (which is why most
commercial organizations won't even consider it) and I want to make
sure that people at least come into this with their eyes open, and
don't make the leap unless they're good at working without a net!
-->

809
handbook/dialup.sgml Normal file
View file

@ -0,0 +1,809 @@
<!-- This is an SGML document in the linuxdoc DTD of the Tutorial for
Configuring a FreeBSD for Dialup Services by Guy Helmer.
$Id: dialup.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $
<!DOCTYPE linuxdoc PUBLIC "-//Linux//DTD linuxdoc//EN">
<article>
<title>
Configuring FreeBSD for Dialup Services
<author>Guy Helmer, <tt/ghelmer@alpha.dsu.edu/
<date>v0.1, 28 March 1995
<abstract>
-->
<sect><heading>Dialup access</heading>
<p><em>Contributed by &a.ghelmer;.</em>
This document provides suggestions for configuring a FreeBSD system to
handle dialup modems. This document is written based on the author's
experience with FreeBSD versions 1.0, 1.1, and 1.1.5.1 (and experience
with dialup modems on other UNIX-like operating systems); however,
this document may not answer all of your questions or provide examples
specific enough to your environment. The author cannot be responsible
if you damage your system or lose data due to attempting to follow the
suggestions here.
<sect1><heading>Prerequisites<label id="dialup:prereqs"></>
<p>
To begin with, the author assumes you have some basic knowledge of
FreeBSD. You need to have FreeBSD installed, know how to edit files
in a UNIX-like environment, and how to look up manual pages on the
system. As discussed below, you'll need certain versions of FreeBSD,
and knowledge of some terminology &amp; modem and cabling.
<sect2>FreeBSD Version
<p>
First, it is assumed that you are using FreeBSD version 1.1 or higher
(including versions 2.x). FreeBSD version 1.0 included two different
serial drivers, which complicates the situation. Also, the serial
device driver (<tt/sio/) has improved in every release of FreeBSD, so
more recent versions of FreeBSD are assumed to have better and more
efficient drivers than earlier versions.
<sect2>Terminology
<p>
A quick rundown of terminology:
<descrip>
<tag/bps/ Bits per Second - the rate at which data is transmitted
<tag/DTE/ Data Terminal Equipment - for example, your computer
<tag/DCE/ Data Communications Equipment - your modem
<tag/RS-232/ EIA standard for serial communications via hardware
</descrip>
If you need more information about these terms and data communications
in general, the author remembers reading that <em/The RS-232 Bible/
(anybody have an ISBN?) is a good reference.
When talking about communications data rates, the author doesn't use
the term <bf/baud/. Baud refers to the number of electrical state
transitions that may be made in a period of time, while <bf/bps/ (bits
per second) is the ``correct'' term to use (at least it doesn't seem
to bother the curmudgeons quite a much).
<sect2>External vs. Internal Modems
<p>
External modems seem to be more convenient for dialup, 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.
<sect2>Modems and Cables
<p>
A background knowledge of these items is assumed
<itemize>
<item> You know how to connect your modem to your computer so that the
two can communicate (unless you have an internal modem, which doesn't
need such a cable)
<item> You are familiar with your modem's command set, or know where
to look up needed commands
<item> You know how to configure your modem (probably via a terminal
communications program) so you can set the non-volatile RAM
parameters
</itemize>
The first, connecting your modem, is usually simple - most
straight-through serial cables work without any problems. You need to
have a cable with appropriate connectors (DB-25 or DB-9, male or
female) on each end, and the cable must be a DCE-to-DTE cable with
these signals wired:
<itemize>
<item> Transmitted Data (<tt/SD/)
<item> Received Data (<tt/RD/)
<item> Request to Send (<tt/RTS/)
<item> Clear to Send (<tt/CTS/)
<item> Data Set Ready (<tt/DSR/)
<item> Data Terminal Ready (<tt/DTR/)
<item> Carrier Detect (<tt/CD/)
<item> Signal Ground (<tt/SG/)
</itemize>
FreeBSD needs the <tt/RTS/ and <tt/CTS/ signals for flow-control at
speeds above 2400bps, the <tt/CD/ signal to detect when a call has
been answered or the line has been hung up, and the <tt/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.
The second prerequisite depends on the modem(s) you use. If you don't
know your modem's command set by heart, you will need to have the
modem's reference book or user's guide handy. Sample commands for USR
Sportster 14,400 external modems will be given, which you may be able
to use as a reference for your own modem's commands.
Lastly, you'll need to know how to setup your modem so that it will
work well with FreeBSD. 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.
<sect2>Serial Interface Considerations
<p>
FreeBSD 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 prefered. If
the system has many active serial ports or will have a heavy load,
16550A-based cards are better for low-error-rate communications.
<sect1>Quick Overview
<p>
Here is the process that FreeBSD follows to accept dialup logins. A
<tt/getty/ process, spawned by <tt/init/, patiently waits to open the
assigned serial port (<tt>/dev/ttyd0</tt>, for our example). The
command <tt/ps ax/ might show this:
<tscreen><verb>
4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyd0
</verb></tscreen>
When a user dials the modem's line and the modems connect, the <tt/CD/
line is asserted by the modem. The kernel notices that carrier has
been detected and completes <tt/getty/'s open of the port. <tt/getty/
sends a <tt/login:/ prompt at the specified initial line speed.
<tt/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 <tt/getty/'s speed),
<tt/getty/ tries adjusting the line speeds until it receives
reasonable characters.
We hope <tt/getty/ finds the correct speed and the user sees a
<tt/login:/ prompt. After the user enters his/her login name,
<tt/getty/ executes <tt>/usr/bin/login</tt>, which completes the login
by asking for the user's password and then starting the user's shell.
Let's dive into the configuration...
<sect1>Kernel Configuration
<p>
FreeBSD kernels typically come prepared to search for four serial
ports, known in the PC-DOS world as <tt/COM1:/, <tt/COM2:/,
<tt/COM3:/, and <tt/COM4:/. FreeBSD can presently also handle
``dumb'' multiport serial interface cards, such as the Boca Board
1008 and 2016 (please see the manual page <tt/sio(4)/ for kernel
configuration information if you have a multiport serial card). 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
<tt>/sbin/dmesg</tt> command to replay the kernel's boot messages. In
particular, look for messages that start with the characters <tt/sio/.
Hint: to view just the messages that have the word <tt/sio/, use the
command
<tscreen><verb>
/usr/sbin/dmesg | grep 'sio'
</verb></tscreen>
For example, on a system with four serial ports, these are the
serial-port specific kernel boot messages:
<tscreen><verb>
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 16550A
</verb></tscreen>
If your kernel doesn't recognize all of your serial ports, you'll
probably need to configure a custom FreeBSD kernel for your system.
Please see the BSD System Manager's Manual chapter on ``Building
Berkeley Kernels with Config'' &lsqb;the source for which is in
<tt>/usr/src/share/doc/smm</tt>&rsqb; and ``FreeBSD Configuration
Options'' &lsqb;in <tt>/sys/doc/options.doc</tt>&rsqb; for more
information on configuring and building kernels. You may have to
unpack the kernel source distribution if haven't installed the system
sources already (<tt>srcdist/srcsys.??</tt> in FreeBSD 1.1,
<tt>srcdist/sys.??</tt> in FreeBSD 1.1.5.1, or the entire source
distribution in FreeBSD 2.0) to be able to configure and build
kernels.
Create a kernel configuration file for your system (if you haven't
already) by <tt/cd/ing to <tt>/sys/i386/conf</tt>. Then, if you are
creating a new custom configuration file, copy the file GENERICAH (or
GENERICBT, if you have a BusTek SCSI controller on FreeBSD 1.x) to
<em/YOURSYS/, where <em/YOURSYS/ is the name of your system, but in
upper-case letters. Edit the file, and change the device lines
<tscreen><verb>
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 siointr
</verb></tscreen>
You can comment-out or completely remove lines for devices you don't
have. If you have a multiport serial board, such as the Boca Board
BB2016, please see the <tt/sio(4)/ man 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.
Note that <tt/port "IO_COM1"/ is a substitution for <tt/port 0x3f8/,
<tt/IO_COM2/ is <tt/0x2f8/, <tt/IO_COM3/ is <tt/0x3e8/, and
<tt/IO_COM4/ is <tt/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
<bf>can't</bf> 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).
When you are finished adjusting the kernel configuration file, use the
program <tt/config/ as documented in ``Building Berkeley Kernels with
Config'' and the <tt/config(8)/ manual page to prepare a kernel
building directory, then build, install, and test the new kernel.
<sect1>Device Special Files
<p>
Most devices in the kernel are accessed through ``device special
files'', which are located in the <tt>/dev</tt> directory. The
<tt/sio/ devices are accessed through the <tt>/dev/ttyd?</tt>
(dial-in) and <tt>/dev/cua0?</tt> (call-out) devices. On FreeBSD
version 1.1.5 and higher, there are also initialization devices
(<tt>/dev/ttyid?</tt> and <tt>/dev/cuai0?</tt>) and locking devices
(<tt>/dev/ttyld?</tt> and <tt>/dev/cual0?</tt>). The initialization
devices are used to initialize communications port parameters each
time a port is opened, such as <tt>crtscts</tt> for modems which use
<tt>CTS/RTS</tt> signalling 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 <tt/termios(4)/, <tt/sio(4)/,
and <tt/stty(1)/ for information on the terminal settings, locking
&amp; initializing devices, and setting terminal options,
respectively.
<sect2>Making Device Special Files
<p>
A shell script called <tt/MAKEDEV/ in the <tt>/dev</tt> directory
manages the device special files. (The manual page for
<tt/MAKEDEV(8)/ on FreeBSD 1.1.5 is fairly bogus in its discussion of
<tt/COM/ ports, so ignore it.) To use <tt/MAKEDEV/ to make dialup
device special files for <tt/COM1:/ (port 0), <tt/cd/ to <tt>/dev</tt>
and issue the command <tt/MAKEDEV ttyd0/. Likewise, to make dialup
device special files for <tt/COM2:/ (port 1), use <tt/MAKEDEV ttyd1/.
<tt/MAKDEV/ not only creates the <tt>/dev/ttyd?</tt> device special
files, but also creates the <tt>/dev/cua0?</tt> (and all of the
initializing and locking special files under FreeBSD 1.1.5 and up) and
removes the hardwired terminal special file <tt>/dev/tty0?</tt>, if it
exists.
After making new device special files, be sure to check the
permissions on the files (especially the <tt>/dev/cua*</tt> files) to
make sure that only users who should have access to those device
special files can read &amp; write on them - you probably don't want
to allow your average user to use your modems to dialout. The default
permissions on the <tt>/dev/cua*</tt> files should be sufficient:
<tscreen><verb>
crw-rw---- 1 uucp dialer 28, 129 Feb 15 14:38 /dev/cua01
crw-rw---- 1 uucp dialer 28, 161 Feb 15 14:38 /dev/cuai01
crw-rw---- 1 uucp dialer 28, 193 Feb 15 14:38 /dev/cual01
</verb></tscreen>
These permissions allow the user <tt/uucp/ and users in the group
<tt/dialer/ to use the call-out devices.
<sect1>Configuration Files
<p>
There are three system configuration files in the <tt>/etc</tt>
directory that you'll probably need to edit to allow dialup access to
your FreeBSD system. The first, <tt>/etc/gettytab</tt>, contains
configuration information for the <tt>/usr/libexec/getty</tt> daemon.
Second, <tt>/etc/ttys</tt> holds information that tells
<tt>/sbin/init</tt> what <tt/tty/ devices should have <tt/getty/
processes running on them. Lastly, you can place port initialization
commands in the <tt>/etc/rc.serial</tt> script if you have FreeBSD
1.1.5.1 or higher; otherwise, you can initialize ports in the
<tt>/etc/rc.local</tt> script.
There are two schools of thought regarding dialup modems on UNIX. One
group likes to configure their modems and system 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 doesn't know what a user's true data
rate is, so full-screen programs like Emacs won't 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 <tt/getty/ doesn't
understand any particular modem's connection speed reporting,
<tt/getty/ gives a <tt/login:/ message at an initial speed and watches
the characters that come back in response. If the user sees junk,
it's assumed that they know they should press the
<tt>&lt;Enter&gt;</tt> key until they see a recognizable prompt. If
the data rates don't match, <tt/getty/ sees anything the user types as
``junk'', tries going to the next speed and gives the <tt/login:/
prompt again. This procedure can continue ad nauseum, but normally
only takes a keystroke or two before the user sees a good prompt.
Obviously, this login sequence doesn't 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 author will try to give balanced configuration information, but is
biased towards having the modem's data rate follow the connection
rate.
<sect2>/etc/gettytab
<p>
<tt>/etc/gettytab</tt> is a <tt/termcap(5)/-style file of
configuration information for <tt/getty(8)/. Please see the
<tt/gettytab(4)/ manual page for complete information on the format of
the file and the list of capabilities.
<sect3>Locked-Speed Config
<p>
If you are locking your modem's data communications rate at a
particular speed, you probably won't need to make any changes to
<tt>/etc/gettytab</tt>.
<sect3>Matching-Speed Config
<p>
You'll need to setup an entry in <tt>/etc/gettytab</tt> to give
<tt/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 <tt/D2400/ entry. This entry already exists in the FreeBSD
1.1.5.1 <tt/gettytab/ file, so you don't need to add it unless it is
missing under your version of FreeBSD:
<tscreen><verb>
#
# 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:
</verb></tscreen>
If you have a higher speed modem, you'll probably need to add an entry
in <tt>/etc/gettytab</tt>; here's an entry you could use for a 14.4
Kbps modem with a top interface speed of 19.2 Kpbs:
<tscreen><verb>
#
# 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:
</verb></tscreen>
On FreeBSD 1.1.5 and later, this will result in 8-bit, no parity
connections. Under FreeBSD 1.1, add <tt/:np:/ parameters to the
<tt>std.<em/xxx/</tt> entries at the top of the file for 8 bits, no
parity; otherwise, the default is 7 bits, even parity.
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. Communcations rate
cycling is implemented with the <tt/nx=/ (<bf/next table/) capability.
Each of the lines uses a <tt/tc=/ (<bf/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's an example of a
<tt/gettytab/ entry starting a 57.6 Kpbs:
<tscreen><verb>
#
# Additions for a V.32bis or V.34 Modem
# Starting at 57.6 Kpbs
#
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:
</verb></tscreen>
If you have a slow CPU or a heavily loaded system and you don't have
16550A-based serial ports, you may receive sio ``silo'' errors at 57.6
Kbps.
<sect2>/etc/ttys
<p>
<tt>/etc/ttys</tt> is the list of <tt/ttys/ for <tt/init/ to monitor.
<tt>/etc/ttys</tt> also provides security information to <tt/login/
(user <tt/root/ may only login on ttys marked <tt/secure/). See the
manual page for <tt/ttys(5)/ for more information.
You'll need to either modify existing lines in <tt>/etc/ttys</tt> or
add new lines to make <tt/init/ run <tt/getty/ processes automatically
on your new dialup ports. The general format of the line will be the
same, whether you are using a locked-speed or matching-speed
configuration:
<tscreen><verb>
ttyd0 "/usr/libexec/getty xxx" dialup on
</verb></tscreen>
The first item in the above line is the device special file for this
entry - <tt/ttyd0/ means <tt>/dev/ttyd0</tt> is the file that this
<tt/getty/ will be watching. The second item, <tt>"/usr/libexec/getty
<em/xxx/"</tt> (<em/xxx/ will be replaced by the initial <tt/gettytab/
capability) is the process <tt/init/ will run on the device. The
third item, <tt/dialup/, is the default terminal type. The fourth
parameter, <tt/on/, indicates to <tt/init/ that the line is
operational. There can be a fifth parameter, <tt>secure</tt>, but it
should only be used for terminals which are physically secure (such as
the system console).
The default terminal type (<tt/dialup/ in the example above) may
depend on local preferences. <tt/dialup/ is the traditional default
terminal type on dialup lines so that users may customize their login
scripts to notice when the terminal is <tt/dialup/ and automatically
adjust their terminal type. However, the author finds it easier at
his site to specify <tt/vt102/ as the default terminal type, since the
users just use VT102 emulation on their remote systems.
After you have made changes to <tt>/etc/ttys</tt>, you may send the
<tt/init/ process a <tt/HUP/ signal to re-read the file. You can use
the command
<tscreen><verb>
kill -1 1
</verb></tscreen>
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 signalling <tt/init/.
<sect3>Locked-Speed Config
<p>
For a locked-speed configuration, your <tt/ttys/ entry needs to
have a fixed-speed entry provided to <tt/getty/. For a modem whose
port speed is locked at 19.2 Kbps, the <tt/ttys/ entry might look like
this:
<tscreen><verb>
ttyd0 "/usr/libexec/getty std.19200" dialup on
</verb></tscreen>
If your modem is locked at a different data rate, substitute the
appropriate name for the <tt>std.<em/speed/</tt> entry for
<tt/std.19200/ from <tt>/etc/gettytab</tt> for your modem's data rate.
<sect3>Matching-Speed Config
<p>
In a matching-speed configuration, your <tt/ttys/ entry needs to
reference the appropriate beginning ``auto-baud'' (sic) entry in
<tt>/etc/gettytab</tt>. For example, if you added the above suggested
entry for a matching-speed modem that starts at 19.2 Kbps (the
<tt/gettytab/ entry containing the <tt/V19200/ starting point), your
<tt/ttys/ entry might look like this:
<tscreen><verb>
ttyd0 "/usr/libexec/getty V19200" dialup on
</verb></tscreen>
<sect2>/etc/rc.serial or /etc/rc.local
<p>
High-speed modems, like V.32, V.32bis, and V.34 modems, need to use
hardware (<tt>RTS/CTS</tt>) flow control. You can add <tt/stty/
commands to <tt>/etc/rc.serial</tt> on FreeBSD 1.1.5.1 and up, or
<tt>/etc/rc.local</tt> on FreeBSD 1.1, to set the hardware flow
control flag in the FreeBSD kernel for the modem ports.
For example, on a sample FreeBSD 1.1.5.1 system,
<tt>/etc/rc.serial</tt> reads:
<tscreen><verb>
#!/bin/sh
#
# Serial port initial configuration
stty -f /dev/ttyid1 crtscts
stty -f /dev/cuai01 crtscts
</verb></tscreen>
which sets the <tt/termios/ flag <tt/crtscts/ on serial port &num;1's
(<tt/COM2:/) dialin and dialout initialization devices.
On an old FreeBSD 1.1 system, these entries were added to
/etc/rc.local to set the <tt/crtscts/ flag on the devices:
<tscreen><verb>
# Set serial ports to use RTS/CTS flow control
stty -f /dev/ttyd0 crtscts
stty -f /dev/ttyd1 crtscts
stty -f /dev/ttyd2 crtscts
stty -f /dev/ttyd3 crtscts
</verb></tscreen>
Since there isn't an initialization device special file on FreeBSD
1.1, one has to just set the flags on the sole device special file and
hope the flags aren't cleared by a miscreant.
<sect1>Modem Settings
<p>
If you have a modem whose parameters may be permanently set in
non-volatile RAM, you'll need to use a terminal program (such as Telix
under PC-DOS or <tt/tip/ under FreeBSD) to set the parameters.
Connect to the modem using the same communications speed as the
initial speed <tt/getty/ will use and configure the modem's
non-volatile RAM to match these requirements:
<itemize>
<item> <tt/CD/ asserted when connected
<item> <tt/DTR/ asserted for operation; dropping DTR hangs up line
&amp; resets modem
<item> <tt/CTS/ transmitted data flow control
<item> Disable <tt>XON/XOFF</tt> flow control
<item> <tt/RTS/ received data flow control
<item> Quiet mode (no result codes)
<item> No command echo
</itemize>
Please 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:
<tscreen><verb>
ATZ
AT&amp;C1&amp;D2&amp;H1&amp;I0&amp;R2&amp;W
</verb></tscreen>
You 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:
<itemize>
<item> Switch 1: UP - DTR Normal
<item> Switch 2: Don't care (Verbal Result Codes/Numeric Result Codes)
<item> Switch 3: UP - Suppress Result Codes
<item> Switch 4: DOWN - No echo, offline commands
<item> Switch 5: UP - Auto Answer
<item> Switch 6: UP - Carrier Detect Normal
<item> Switch 7: UP - Load NVRAM Defaults
<item> Switch 8: Don't care (Smart Mode/Dumb Mode)
</itemize>
Result codes should be disabled/suppressed for dialup modems to avoid
problems that can occur if <tt/getty/ mistakenly gives a <tt/login:/
prompt to a modem that is in command mode and the modem echoes the
command or returns a result code. I've heard this sequence can result
in a extended, silly conversation between <tt/getty/ and the modem.
<sect2>Locked-speed Config
<p>
For a locked-speed configuration, you'll 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:
<tscreen><verb>
ATZ
AT&amp;B1&amp;W
</verb></tscreen>
<sect2>Matching-speed Config
<p>
For a variable-speed configuration, you'll 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:
<tscreen><verb>
ATZ
AT&amp;B2&amp;W
</verb></tscreen>
<sect2>Checking the Modem's Configuration
<p>
Most 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 <tt/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 <tt/ATZ/ and then <tt/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.
<sect1>Troubleshooting
<p>
Here are a few steps you can follow to check out the dialup modem on
your system.
<sect2>Checking out the FreeBSD system
<p>
Hook 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 <tt/DTR/ indicator lights when the <tt/login:/ prompt appears
on the system's console - if it lights up, that should mean that
FreeBSD has started a <tt/getty/ process on the appropriate
communications port and is waiting for the modem to accept a call.
If the <tt/DTR/ indicator doesn't light, login to the FreeBSD system
through the console and issue a <tt/ps ax/ to see if FreeBSD is trying
to run a <tt/getty/ process on the correct port. You should see a
lines like this among the processes displayed:
<tscreen><verb>
114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd0
115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyd1
</verb></tscreen>
If you see something different, like this:
<tscreen><verb>
114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyd0
^^
</verb></tscreen>
and the modem hasn't accepted a call yet, this means that <tt/getty/
has completed its open on the communications port. This could
indicate a problem with the cabling or a mis-configured modem, because
<tt/getty/ should not be able to open the communications port until
<tt/CD/ (carrier detect) has been asserted by the modem.
If you don't see any <tt/getty/ processes waiting to open the desired
<tt/ttyd?/ port, double-check your entries in <tt>/etc/ttys</tt> to
see if there are any mistakes there. Also, check the log file
<tt>/var/log/messages</tt> to see if there are any log messages from
<tt/init/ or <tt/getty/ regarding any problems. If there are any
messages, triple-check the configuration files <tt>/etc/ttys</tt> and
<tt>/etc/gettytab</tt>, as well as the appropriate device special
files <tt>/dev/ttyd?</tt>, for any mistakes, missing entries, or
missing device special files.
<sect2>Try Dialing In
<p>
Try dialing into the system; be sure to use 8 bits, no parity, 1 stop
bit on the remote system. If you don't get a prompt right away, or
get garbage, try pressing <tt>&lt;Enter&gt;</tt> about once per
second. If you still don't see a <tt/login:/ prompt after a while,
try sending a <tt>BREAK</tt>. If you are using a high-speed modem to
do the dialing, try dialing again after locking the dialing modem's
interface speed (via <tt>AT&amp;B1</tt> on a USR Sportster, for
example).
If you still can't get a <tt/login:/ prompt, check
<tt>/etc/gettytab</tt> again and double-check that
<itemize>
<item> The initial capability name specified in <tt>/etc/ttys</tt> for
the line matches a name of a capability in <tt>/etc/gettytab</tt>
<item> Each <tt/nx=/ entry matches another <tt/gettytab/ capabilty
name
<item> Each <tt/tc=/ entry matches another <tt/gettytab/ capability
name
</itemize>
If you dial but the modem on the FreeBSD system won't answer, make
sure that the modem is configured to answer the phone when <tt/DTR/ is
asserted. If the modem seems to be configured correctly, verify that
the <tt/DTR/ line is asserted by checking the modem's indicator lights
(if it has any).
If you've gone over everything several times and it still doesn't work,
take a break and come back to it later. If it still doesn't work,
perhaps you can send an electronic mail message to
<tt>FreeBSD-Questions@freebsd.org</tt> describing your modem and your
problem, and the good folks on the list will try to help.
<sect1>Acknowledgements
<p>
Thanks to these people for comments and advice:
<descrip>
<tag/Sean Kelly/ &lt;kelly@fsl.noaa.gov&gt; for a number of good
suggestions
</descrip>

153
handbook/diskless.sgml Normal file
View file

@ -0,0 +1,153 @@
<!-- $Id: diskless.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>Diskless operation</heading>
<p><em>Contributed by &a.martin;.</em>
<tt>netboot.com/netboot.rom</tt> 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)
<sect1>
<heading>Setup Instructions</heading>
<p><enum>
<item> Find 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:
<itemize>
<item>HP9000/8xx running HP-UX 9.04 or later (pre
9.04 doesn't work)</item>
<item>Sun/Solaries 2.3. (you may need to get
bootp)</item>
</itemize>
<item>Set up a bootp server to provide the client with
IP, gateway, netmask.
<tscreen><verb>
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:
</verb></tscreen></item>
<item>Set up a TFTP server (on same machine as bootp
server) to provide booting information to client.
The name of this file is <tt>cfg.X.X.X.X</tt> (or
<tt>/tftpboot/cfg.X.X.X.X</tt>, it will try both)
where <tt>X.X.X.X</tt> 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:
<tscreen><verb>
help - print help list
ip <X.X.X.X> - print/set client's IP address
server <X.X.X.X> - print/set bootp/tftp server address
netmask <X.X.X.X> - print/set netmask
hostname <name> - print/set hostname
kernel <name> - print/set kernel name
rootfs <ip:/fs> - print/set rootfilesystem
swapfs <ip:/fs> - print/set swapfilesystem
swapsize <size> - set diskless swapsize in Kbytes
diskboot - boot from disk
autoboot - continue boot process
</verb></tscreen>
A typical completely diskless cfg file might contain:
<tscreen><verb>
rootfs 192.1.2.3:/rootfs/myclient
swapfs 192.1.2.3:/swapfs
swapsize 20000
hostname myclient.mydomain
</verb></tscreen>
A cfg file for a machine with local swap might contain:
<tscreen><verb>
rootfs 192.1.2.3:/rootfs/myclient
hostname myclient.mydomain
</verb></tscreen>
<item>Ensure 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 <tt>/etc/exports</tt> file on FreeBSD might
look like:
<tscreen><verb>
/rootfs/myclient -maproot=0:0 myclient.mydomain
/swapfs -maproot=0:0 myclient.mydomain
</verb></tscreen>
And on HP-UX:
<tscreen><verb>
/rootfs/myclient -root=myclient.mydomain
/swapfs -root=myclient.mydomain
</verb></tscreen>
<item>If you are swapping over NFS (completely diskless
configuration) create a swap file for your client
using touch. If your <tt>swapfs</tt> command has the
argument <tt>/swapfs</tt> as in the example above,
the swapfile for myclient will be called
<tt>/swapfs/swap.X.X.X.X</tt> where <tt>X.X.X.X</tt>
is the client's IP addr, eg:
<tscreen><verb>
# touch /swapfs/swap.192.1.2.4
</verb></tscreen>
<item> Unpack the root filesystem in the directory the
client will use for its root filesystem
(<tt>/rootfs/myclient</tt> in the example above).
<itemize>
<item> On HP-UX systems: The server should be
running HP-UX 9.04 or later for HP9000/800 series
machines. Prior versions don't allow the
creation of device files over NFS.
<item> When extracting <tt>/dev</tt> in
<tt>/rootfs/myclient</tt>, 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
<tt>/dev</tt> and do a "<tt>sh ./MAKEDEV
all</tt>" from the client to fix this.
</itemize>
<item>Run <tt>netboot.com</tt> on the client or make an EPROM
from the <tt>netboot.rom</tt> file
</enum>
<sect1>
<heading>Using Shared <tt>/</tt> and <tt>/usr</tt> filesystems</heading>
<p>At present there isn't an officially sanctioned way of
doing this, although I have been using a shared <tt>/usr</tt>
filesystem and individual <tt>/</tt> filesystems for each client.
If anyone has any suggestions on how to do this cleanly,
please let me and/or the core group know.
<sect1>
<heading>Compiling netboot for specific setups</heading>
<p>Netboot can be compiled to support NE1000/2000 cards by
changing the configuration in
<tt>/sys/i386/boot/netboot/Makefile</tt>. See the
comments at the top of this file.

118
handbook/eresources.sgml Normal file
View file

@ -0,0 +1,118 @@
<!-- $Id: eresources.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt>
<heading>Additional resources on the Internet</heading>
<sect>
<heading>Mailing lists</heading>
<p>The FreeBSD Project runs a number of Internet mailing
lists dedicated to the discussion of FreeBSD and
related topics. Users with access to Internet mail are
encouraged to subscribe to the lists that interest them
and ask questions. The procedure is quite simple, just
send a mail message to:
<tscreen>
<tt>majordomo@freebsd.org</tt>
</tscreen>
with a message body of:
<tscreen>
<tt><bf>subscribe <it>listname</it></bf></tt>
</tscreen>
where <em>listname</em> is one of the lists described
below. You can subscribe to multiple lists with a
single message by having several <em>subscribe</em>
lines. For more detailed information, send a message
to:
<tscreen>
<tt>majordomo@freebsd.org</tt>
</tscreen>
with a message body of
<tscreen>
<tt><bf>help</bf></tt>
</tscreen>
<sect1>
<heading>General discussion lists</heading>
<p><descrip>
<tag>freebsd-announce</tag> Important announcements
about FreeBSD are posted here.
<tag>freebsd-questions</tag> General discussion of
problems people experience in setting up and using
FreeBSD.
<tag>freebsd-hackers</tag> Technical discussions
about the design and implementation of FreeBSD.
<tag>freebsd-bugs</tag> Bug reports and discussions
of reported bugs are posted here, although the
discussions are usually moved over to the
<em>freebsd-hackers</em> mailing list if the become involved.
</descrip>
<sect1>
<heading>CVS lists</heading>
<sect>
<heading>Usenet newsgroups</heading>
<p>While no newsgroups dedicated to FreeBSD exist, there
are many in which FreeBSD is discussed or are otherwise
relevant to FreeBSD users.
<sect1>
<heading>BSD specific newsgroups</heading>
<p><itemize>
<item> comp.unix.bsd.freebsd.announce
<item> comp.unix.bsd.freebsd.misc
</itemize>
<sect1>
<heading>Other Unix newsgroups of interest</heading>
<p><itemize>
<item> comp.unix
<item> comp.unix.questions
<item> comp.unix.admin
<item> comp.unix.programmer
<item> comp.unix.shell
<item> comp.unix.user-friendly
<item> comp.security.unix
<item> comp.sources.unix
<item> comp.unix.advocacy
<item> comp.unix.misc
<item> comp.os.386bsd.announce
<item> comp.os.386bsd.apps
<item> comp.os.386bsd.bugs
<item> comp.os.386bsd.development
<item> comp.os.386bsd.misc
<item> comp.os.386bsd.questions
<item> comp.bugs.4bsd
<item> comp.bugs.4bsd.ucb-fixes
<item> comp.unix.bsd
</itemize>
<sect1>
<heading>X-Window system</heading>
<p><itemize>
<item> comp.windows.x.i386unix
<item> comp.windows.x
<item> comp.windows.x.apps
<item> comp.windows.x.announce
<item> comp.windows.x.intrinsics
<item> comp.windows.x.motif
<item> comp.windows.x.pex
<item> comp.emulators.ms-windows.wine
</itemize>
<sect>
<heading>Word Wide Web servers</heading>
<p><itemize>
<item> <url url="http://www.freebsd.org/"></item>
</itemize>
</sect>

5
handbook/glossary.sgml Normal file
View file

@ -0,0 +1,5 @@
<!-- $Id: glossary.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Glossary</heading>

237
handbook/handbook.sgml Normal file
View file

@ -0,0 +1,237 @@
<!-- $Id: handbook.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!DOCTYPE linuxdoc PUBLIC "-//Linux//DTD linuxdoc//EN" [
<!ENTITY % authors SYSTEM "authors.sgml">
%authors;
<!ENTITY bibliography SYSTEM "bibliography.sgml">
<!ENTITY basics SYSTEM "basics.sgml">
<!ENTITY ctm SYSTEM "ctm.sgml">
<!ENTITY current SYSTEM "current.sgml">
<!ENTITY dialup SYSTEM "dialup.sgml">
<!ENTITY diskless SYSTEM "diskless.sgml">
<!ENTITY eresources SYSTEM "eresources.sgml">
<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY kerberos SYSTEM "kerberos.sgml">
<!ENTITY nfs SYSTEM "nfs.sgml">
<!ENTITY porting SYSTEM "porting.sgml">
<!ENTITY ports SYSTEM "ports.sgml">
<!ENTITY ppp SYSTEM "ppp.sgml">
<!ENTITY scsi SYSTEM "scsi.sgml">
<!ENTITY slipc SYSTEM "slipc.sgml">
<!ENTITY slips SYSTEM "slips.sgml">
<!ENTITY submitters SYSTEM "submitters.sgml">
<!ENTITY sup SYSTEM "sup.sgml">
<!ENTITY troubleshooting SYSTEM "troubleshooting.sgml">
]>
<!--
Potential target audience:
1. Potential users
a. new to unix
b. somewhat familiar with unix
c. veterans
2. Existing users
a. new to unix
b. somewhat familiar with unix
c. veterans
OUTLINE:
-->
<linuxdoc>
<book>
<title>FreeBSD Handbook
<author>
<name></name>
<!-- <date> -->
<abstract>Welcome to FreeBSD! This handbook covers the
installation and day to day use of FreeBSD.
This manual is a <bf>work in progress</bf> and is the
work of many individials. Many sections do not yet exist
and some of those that do exist need to be updated. If
you are interested in helping with this project, send
email to &a.jfieber; or to the FreeBSD Documentantion
Project mailing list <tt>&lt;doc@freebsd.org&gt;</tt>.
</abstract>
<toc>
<chapt><heading>Introduction</heading>
<sect><heading>FreeBSD In a nutshell</heading>
<sect><heading>History</heading>
<sect><heading>About this release</heading>
<sect><heading>FreeBSD now and in the future</heading>
<chapt><heading>Installing FreeBSD</heading>
<sect><heading>Preparing for the installation</heading>
<sect1><heading>Hardware checklist</heading>
<sect2><heading>minimal requirements</heading>
<sect2><heading>IRQs, IO Addresses, and DMA channels</heading>
<sect1><heading>Software checklist</heading>
<sect2><heading>Making the installation floppies</heading>
<sect2><heading>CD-ROM</heading>
<sect2><heading>Tape</heading>
<sect2><heading>Disk</heading>
<sect><heading>Installation</heading>
<sect><heading>Set up a user account</heading>
&basics;
<chapt><heading>Installing applications</heading>
<sect><heading>Installing packages</heading>
&ports;
&porting;
<chapt><heading>Reconfiguring the kernel</heading>
<p>Once you have your FreeBSD system installed and
operational it is a good idead to re-configure the
kernel. You may also need to re-configure the kernel if
you add, change, or remove hardware from your system.
<p>
<chapt><heading>Basic Networking</heading>
<sect><heading>Ethernet basics</heading>
<sect><heading>Serial basics</heading>
<sect><heading>Hardwired Terminals</heading>
&dialup;
<chapt><heading>PPP and SLIP</heading>
&ppp;
&slipc;
&slips;
<chapt><heading>Advanced networking</heading>
<sect><heading>Gateways and routing</heading>
&nfs;
<sect><heading>Yellow Pages/NIS</heading>
&diskless;
<sect><heading>ISDN</heading>
<chapt><heading>Mail</heading>
<chapt><heading>Printing</heading>
<chapt><heading>Users, groups and security</heading>
<sect><heading>DES, MD5 and Crypt</heading>
&kerberos;
<sect><heading>S/Key</heading>
<sect><heading>Firewalls</heading>
<chapt><heading>The X-Window System</heading>
<chapt><heading>Managing hardware</heading>
&scsi;
<sect><heading>adding/reconfiguring disks</heading>
<sect><heading>tapes and backups</heading>
<sect><heading>serial ports</heading>
<sect><heading>sound cards</heading>
<chapt><heading>PC Hardware compatibility</heading>
<sect><heading>CORE/PROCESSING</heading>
<sect1><heading>Motherboards</heading>
<sect2><heading>ISA</heading>
<sect2><heading>EISA</heading>
<sect2><heading>VLB</heading>
<sect2><heading>PCI</heading>
<sect1><heading>CPUs/FPUs</heading>
<sect1><heading>Memory</heading>
<sect1><heading>BIOS</heading>
<sect><heading>INPUT/OUTPUT</heading>
<sect1><heading>Video cards</heading>
<sect1><heading>Sound cards</heading>
<sect1><heading>Serial ports (including multiport cards)</heading>
<sect1><heading>Parallel ports</heading>
<sect1><heading>Modems</heading>
<sect1><heading>Etherenet cards</heading>
<sect1><heading>Keyboards</heading>
<sect1><heading>Mice</heading>
<sect1><heading>Other (joysticks? tablets?)</heading>
<sect><heading>STORAGE</heading>
<sect1><heading>Disk/tape controllers</heading>
<sect2><heading>SCSI</heading>
<sect2><heading>IDE</heading>
<sect2><heading>Floppy</heading>
<sect1><heading>Hard drives</heading>
<sect1><heading>Tape drives</heading>
<sect1><heading>CD-ROM drives</heading>
<sect1><heading>Other</heading>
<sect><heading>OTHER</heading>
<sect1><heading>PCMCIA</heading>
&current;
&ctm;
&sup;
&troubleshooting;
&submitters;
&bibliography;
&eresources;
&glossary;
</book>
</linuxdoc>

329
handbook/kerberos.sgml Normal file
View file

@ -0,0 +1,329 @@
<!-- $Id: kerberos.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>Kerberos</heading>
<p><em>Contributed by &a.md;.</em>
<p>The following instructions can be used as a quick
guide on how to set up kerberos as distributed in 4.4
BSD. However, you should refer to the original Athena
documentation for a complete description.
<sect1>
<heading>Creating the initial database</heading>
<p>First make sure that you don't have any old kerberos
databases around. You should change to the directory
<tt>/etc/kerberosIV</tt> and check that only the
following files are present:
<tscreen><verb>
mideon# cd /etc/kerberosIV
mideon# ls
README krb.conf krb.realms register_keys
</verb></tscreen>
If any additional files (such as <tt>principal.dir</tt>) exist,
then use the <tt>kdb_destroy</tt> command to destroy the
old kerberos database.
<p>You should now edit the <tt>krb.conf</tt> and
<tt>krb.realms</tt> files to define your kerberos realm.
In this case the realm will be <it>BSC.NO</it> and the
server is <it>mideon.bsc.no</it>. We would edit the
<tt>krb.conf</tt> file to be as follows:
<tscreen><verb>
mideon# cat krb.conf
BSC.NO
BSC.NO mideon.bsc.no 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.gov
</verb></tscreen>
<p>Now we have to add <it>mideon.bsc.no</it> to the
<it>BSC.NO</it> realm and also add an entry to put all
hosts in the <it>.bsc.no</it> domain in the
<it>BSC.NO</it> realm. The <tt>krb.realms</tt> file
would be updated as follows:
<tscreen><verb>
mideon# cat krb.realms
mideon.bsc.no BSC.NO
.bsc.no BSC.NO
.berkeley.edu CS.BERKELEY.EDU
.MIT.EDU ATHENA.MIT.EDU
.mit.edu ATHENA.MIT.EDU
</verb></tscreen>
<p>Now we're ready to create the database, issue the
<tt>kdb_init</tt> command to do this:
<tscreen><verb>
mideon# kdb_init
Realm name [default CS.BERKELEY.EDU ]: BSC.NO
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter Kerberos master key:
</verb></tscreen>
<p>Now we have to save the key so that servers on the local
machine can pick it up. Use the <tt>kstash</tt> command to
do this.
<tscreen><verb>
mideon# kstash
Enter Kerberos master key:
Current Kerberos master key version is 1.
Master key entered. BEWARE!
</verb></tscreen>
<sect1>
<heading>Populating the database</heading>
<p>We now have to add some entries into the database.
First lets create an entry for the user <it>md</it>. Use
the <tt>kdb_edit</tt> command to do this:
<tscreen><verb>
mideon# 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: md
Instance:
md. not found, Create [y] ?
Principal: md, Instance: , kdc_key_ver: 1
New Password:
New Password:
Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?
Max ticket lifetime (*5 minutes) [ 255 ] ? 100
Attributes [ 0 ] ?
Edit O.K.
</verb></tscreen>
<p>Now lets add an entry for the password changing daemon,
<tt>kpasswd</tt>. The principal name must be <it>kpasswd</it> and
the instance must be the name of the local machine,
<it>mideon</it> in this case. Similarily, we must also
add an entry for the principal <it>rcmd</it> with an
instance equal to the hostname of the local machine.
<tscreen><verb>
Principal name: kpasswd
Instance: mideon
kpasswd.mideon not found, Create [y] ?
Principal: kpasswd, Instance: mideon, kdc_key_ver: 1
New Password: <---- enter RANDOM here
New Password: <---- and 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: rcmd
Instance: mideon
rcmd.mideon not found, Create [y] ?
Principal: rcmd, Instance: mideon, kdc_key_ver: 1
New Password: <---- enter RANDOM here
New Password: <---- and 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 exit
</verb></tscreen>
<sect1>
<heading>Creating the server file</heading>
<p>We now have to extract all the instances which define
the services on this machine. For this we use the
<tt>ext_srvtab</tt> command.
<tscreen><verb>
mideon# ext_srvtab mideon
Enter Kerberos master key:
Current Kerberos master key version is 1.
Master key entered. BEWARE!
Generating 'mideon-new-srvtab'....
</verb></tscreen>
<p>Now, this command only generates a temporary file
which must be renamed to <tt>srvtab</tt> so that all the
server can pick it up. Use the <tt>mv</tt> command to move it
into place:
<tscreen><verb>
mideon# mv mideon-new-srvtab srvtab
</verb></tscreen>
<sect1>
<heading>Testing it all out</heading>
<p>First we have to start the kerberos daemon:
<tscreen><verb>
mideon# kerberos &
[1] 774
mideon# 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: BSC.NO
</verb></tscreen>
Now we can try using the <tt>kinit</tt> command to get
tokens for the id <it>md</it> that we created above:
<tscreen><verb>
mideon# kinit md
Kerberos Initialization for "md"
Kerberos Password:
</verb></tscreen>
Try listing the tokens using <tt>klist</tt> to see if we
really have them:
<tscreen><verb>
mideon# klist
Ticket file: /tmp/tkt0
Principal: md@BSC.NO
Issued Expires Principal
Mar 23 21:06:52 Mar 24 05:06:52 krbtgt.BSC.NO@BSC.NO
</verb></tscreen>
And now try changing the password using <tt>passwd</tt>
to check if the kpasswd daemon can get authorisation to
the kerberos database:
<tscreen><verb>
mideon# passwd md
Changing Kerberos password for md.@BSC.NO.
Old Kerberos password:
New Kerberos password:
Retype new Kerberos password:
Update complete.
</verb></tscreen>
<sect1>
<heading>Adding <tt>su</tt> priviledges</heading>
<p>We should now add an id which is authorised to <tt>su</tt> to
<it>root</it>. This is controlled by having an instance of
<it>root</it> associated with a principal. Using
<tt>kdb_edit</tt> we can create the entry
<it>md.root</it> in the kerberos database:
<tscreen><verb>
mideon# 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: md
Instance: root
md.admin not found, Create [y] ?
Principal: md, Instance: admin, kdc_key_ver: 1
New Password:
New Password:
Principal's new key version = 1
Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?
Max ticket lifetime (*5 minutes) [ 255 ] ? 12
Attributes [ 0 ] ?
Edit O.K.
Principal name:
</verb></tscreen>
Now try getting tokens for it to make sure it works:
<tscreen><verb>
mideon# kinit md.root
Kerberos Initialization for "md.root"
Kerberos Password:
</verb></tscreen>
And list them to check expiry times:
<tscreen><verb>
mideon# klist
Ticket file: /tmp/tkt0
Principal: md.root@BSC.NO
Issued Expires Principal
Mar 23 21:08:47 Mar 23 22:08:47 krbtgt.BSC.NO@BSC.NO
mideon#
</verb></tscreen>
Now we need to add the user to root's <tt>.klogin</tt> file:
<tscreen><verb>
mideon# cat /root/.klogin
md.root@BSC.NO
</verb></tscreen>
Now try doing the <tt>su</tt>:
<tscreen><verb>
[md@mideon.bsc.no 10407] su
Kerberos Password:
Warning: tgt not verified.
</verb></tscreen>
and take a look at what tokens we have:
<tscreen><verb>
mideon# klist
Ticket file: /tmp/tkt_root_1250
Principal: md.root@BSC.NO
Issued Expires Principal
Mar 23 22:09:59 Mar 23 22:19:59 krbtgt.BSC.NO@BSC.NO
mideon#
</verb></tscreen>
Notice that with this setup each user has their own entry
for <tt>su</tt>'ing to root (the <it>user</it>.root entry
in kerberos). This can allow you to give root access to
multiple users without the need to share a common root
password.

79
handbook/nfs.sgml Normal file
View file

@ -0,0 +1,79 @@
<!-- $Id: nfs.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>NFS</heading>
<p><em>Contributed by &a.john;.</em>
Certain Ethernet adapters for ISA PC systems have limitations which
can lead to serious network problems, particularly with NFS. This
difficulty is not specific to FreeBSD, but FreeBSD systems are affected
by it.
The problem nearly always occurs when (FreeBSD) PC systems are networked
with high-performance workstations, such as those made by Silicon Graphics,
Inc., and Sun Microsystems, Inc. The NFS mount will work fine, and some
operations may succeed, but suddenly the server will seem to become
unresponsive to the client, even though requests to and from other systems
continue to be processed. This happens to the client system, whether the
client is the FreeBSD system or the workstation. On many systems, there is
no way to shut down the client gracefully once this problem has manifested
itself. The only solution is often to reset the client, because the NFS
situation cannot be resolved.
Though the "correct" solution is to get a higher performance and capacity
Ethernet adapter for the FreeBSD system, there is a simple workaround that
will allow satisfactory operation. If the FreeBSD system is the SERVER,
include the option "wsize=1024" on the mount from the client. If the
FreeBSD system is the CLIENT, then mount the NFS file system with the
option "rsize=1024". These options may be specified using the fourth
field of the fstab entry on the client for automatic mounts, or by using
the "-o" parameter of the mount command for manual mounts.
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 "hard" or
"soft" and "bg" may be desireable in your application.
Examples for the FreeBSD system ("freebox") as the client:
in /etc/fstab on freebox:
fastws:/sharedfs /project nfs rw,rsize=1024 0 0
as a manual mount command on freebox:
mount -t nfs -o rsize=1024 fastws:/sharedfs /project
Examples for the FreeBSD system as the server:
in /etc/fstab on fastws:
freebox:/sharedfs /project nfs rw,wsize=1024 0 0
as a manual mount command on fastws:
mount -t nfs -o wsize=1024 freebox:/sharedfs /project
Nearly 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 guarranteed 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.

414
handbook/porting.sgml Normal file
View file

@ -0,0 +1,414 @@
<!-- $Id: porting.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>Porting applications</heading>
<p><em>Contributed by &a.jkh;.</em>
Here are the guidelines one should follow in
creating a new port for FreeBSD 2.x . This documentation will
change as this process is progressively refined, so watch
this space for details. The <tt>&dollar;{..}</tt>
variable names you see in this document all refer to
various user-overridable defaults used (and documented)
by <tt>/usr/share/mk/bsd.port.mk</tt>. Please refer to
that file for more details.
<sect1>
<heading>Before starting the port</heading>
<p> <em>Note: Only a fraction of the overridable variables
are mentioned in this document. Most (if not all) are
documented at the start of the <tt>bsd.port.mk</tt>
file which can be found in /usr/share/mk. This file
uses a non-standard tab setting. <tt>Emacs</tt> should
recognise the setting on loading the file. <tt>vi</tt>
or <tt>ex</tt> can be set to using the correct value by
typing "<tt>:set tabstop=4</tt>" once the file has been
loaded. - &a.gpalmer;</em>
You may come across code that needs modifications or
conditional compilation based upon what version of UNIX
it's running under. If you need to make such changes to
the code for conditional compilation, make sure you make
the changes as general as possible so that we can
back-port code to FreeBSD 1.x systems and cross-port to
other BSD systems such as 4.4bsd from CSRG, BSD/386,
386BSD and NetBSD.
The preferred way to tell 4.3BSD/Reno and newer versions
of the BSD code apart is by using the "<tt>BSD</tt>"
macro defined in <tt>&lt;sys/param.h&gt;</tt>. Hopefully
that file is already included; if not, add the code:
<tscreen><verb>
#ifdef _HAVE_PARAM_H
#include <sys/param.h>
#endif
</verb></tscreen>
to the proper place in the <tt>.c</tt> file and add
<tt>-D_HAVE_PARAM_H</tt> to the <tt>CFLAGS</tt> in the
Makefile.
Then, you may use:
<tscreen><verb>
#if (defined(BSD) && (BSD >= 199103))
</verb></tscreen>
to detect if the code is being compiled on a 4.3 Net2
code base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD
0.9, 386BSD, BSD/386 1.0).
Use:
<tscreen><verb>
#if (defined(BSD) && (BSD >= 199306))
</verb></tscreen>
to detect if the code is being compiled on a 4.4 code
base or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0,
BSD/386 1.1).
Use sparingly:
<itemize>
<item><tt>__FreeBSD__</tt> is defined in all
versions of FreeBSD. Use it if the change you
are making ONLY affects FreeBSD. Porting gotchas
like the use of <tt>sys_errlist[]</tt> vs
<tt>strerror()</tt> are Berkeleyisms, not FreeBSD
changes.
<item>In FreeBSD 2.x, <tt>__FreeBSD__</tt> is
defined to be <tt>2</tt>. In earlier versions,
it's <tt>1</tt>.
<item>If you need to tell the difference between a
FreeBSD 1.x system and a FreeBSD 2.x system,
usually the right answer is to use the
<tt>BSD</tt> macros described above. If there
actually is a FreeBSD specific change (such as
special shared library options when using
'<tt>ld</tt>') then it's OK to use
<tt>__FreeBSD__</tt> and "<tt>#if __FreeBSD_ &gt;
1</tt>" to detect a FreeBSD 2.x system.
</itemize>
In the dozens of ports that have been done, there have
only been one or two cases where <tt>__FreeBSD__</tt>
should have been used. Just because an earlier port
screwed up and used it in the wrong place doesn't mean
you should do so too.
<sect1>
<heading> Doing the port</heading>
<p>NOTE: If your sources work without change under FreeBSD,
skip to the next section.
<enum>
<item>Get the original sources (normally) as a
compressed tarball (<tt>&lt;foo&gt;.tar.gz</tt> or
<tt>&lt;foo&gt;.tar.Z</tt>) and copy it into
<tt>&dollar;{DISTDIR}</tt>. Always use
<em>mainstream</em> sources when and where you can,
and don't be tempted to patch a tarball 2 or 3
revisions ahead just to save yourself trouble. The
idea is that the ports collection should be usable
even with all of <tt>&dollar;{DISTDIR}</tt> blown
away, which is to say that it should be possible for
a user to repopulate all of
<tt>&dollar;{DISTDIR}</tt> with publically available
files.
<item>Unpack a copy of the tarball in a private
directory and make whatever changes are necessary to
get the port to compile properly under FreeBSD 2.0.
Keep <em>careful track</em> of everything you do, as
you will be automating the process shortly.
Everything, including the deletion, addition or
modification of files should be doable using an
automated script or patch file when your port is
finished. If your port requires significant user
interaction/customization to compile or install, you
should take a look at one of Larry Wall's classic
Configure scripts and perhaps do something similar
yourself. The goal of the new ports collection is to
make each port as `plug-and-play' as possible for the
end-user while using a minimum of disk space.
<item>Carefully consider the list of patches, shell
commands or user queries necessary for customizing
the port, then, making sure you understand the
following thoroughly, go for it. The sequence of
events you need to understand is that which occurs
when the user first types `<tt>make</tt>' in your
port's directory, and you may find that having
<tt>bsd.port.mk</tt> in another window while you read
this really helps to understand it:
Sequence of events:
<enum>
<item>The pre-fetch and fetch targets are run. The
fetch target is responsible for making sure that
the tarball exists locally in <tt>&dollar;{DISTDIR}</tt>.
The pre-fetch target hook is optional. If fetch
cannot find the required files in
<tt>&dollar;{DISTDIR}</tt> it will look up the URL
<tt>&dollar;{MASTER_SITES}</tt>, which can be set in the
Makefile or allowed to default to the Walnut
Creek CDROM archive site. It will then attempt
to fetch the named distribution file with
<tt>&dollar;{NCFTP}</tt>, assuming that the requesting
site has direct access to the Internet. If that
succeeds, it will save the file in
<tt>&dollar;{DISTDIR}</tt> for future use and proceed.
<item>The pre-extract target hook, if it exists, is
run.
<item>The extract target, if not disabled, is run.
It looks for your ports' distribution file in
<tt>&dollar;{DISTDIR}</tt> (typically a gzip'd
tarball) and unpacks it into a temporary
directory.
<item>The pre-configure target hook is run.
<item>The configure target is run. This can do any
one of many different things. First, if any
patches are found in the
<tt>&dollar;{PATCHDIR}</tt> subdirectory, they
are applied at this time in alphabetical order.
Next, a series of scripts, if detected, are run
in the following order:
<enum>
<item><tt>&dollar;{SCRIPTDIR}/pre-configure</tt>
<item><tt>&dollar;{SCRIPTDIR/configure</tt> or
<tt>&dollar;{WRKSRC}/configure</tt> if
<tt>&dollar;{HAS_CONFIGURE}</tt> is set.
<item>If <tt>&dollar;{USE_IMAKE}</tt> is set, an
xmkmf command is done.
<item><tt>&dollar;{SCRIPTDIR}/post-configure</tt>
</enum>
As you can see, it's possible to do just about anything to your
port, in a variety of stages!
<item>The pre-build target hook is run.
<item>The build target is run. This is responsible
for decending into the ports' private working
directory (<tt>&dollar;{WRKSRC}</tt>) and
building it. If <tt>&dollar;{USE_GMAKE}</tt> is
set, GNU <tt>make</tt> will be used, otherwise
the system <tt>&dollar;{MAKE}</tt>.
</enum>
<item>In the preparation of the port, files that have
been added or changed can be picked up with a
recursive diff for later feeding to patch. This is
the easiest kind of change to make as it doesn't
involve any mucking around with configuration files.
Each set of patches you wish to apply should be
collected into a file named
"<tt>patch-&lt;xx&gt;</tt>" where <tt>&lt;xx&gt;</tt>
denotes the sequence in which the patches will be
applied - these are done in <em>alphabetical
order</em>, thus "<tt>aa</tt>" first, "<tt>ab</tt>"
second and so on. These files should be stored in
<tt>&dollar;{PATCHDIR}</tt>, from where they will be
automatically applied. All patches should be
relative to <tt>&dollar;{WRKSRC}</tt> (generally the
directory your port's tarball unpacks itself into,
that being where the make is done).
<item>Include any additional customization commands to
your `<tt>configure</tt>' script and save it to
<tt>&dollar;{SCRIPTDIR}/configure</tt>. Add your
port to the Makefile one level above it so that it
will be made automatically.
<item>Always try to install relative to
<tt>&dollar;{PREFIX}</tt> in your Makefiles. This will
normally be set to <tt>/usr/local</tt>, though it can be can
be reassigned in your Makefile or in the users
environment. Not hardcoding <tt>/usr/local</tt> anywhere in
your installation will make the port much more
flexible and cater to the needs of other sites. Note
that this doesn't count for package `packing list'
files since they have their own scheme for relocating
themselves and can be left independant of
<tt>&dollar;{PREFIX}</tt> unless the package is one that
hardcodes itself to a compiled-in location.
<item>If your port requires user input to build,
configure or install, then set
<tt>IS_INTERACTIVE</tt> in your Makefile. This will
allow "overnight builds" to progress past your port
if the user sets the variable <tt>BATCH</tt> in his
environment (and if the user sets the variable
<tt>INTERACTIVE</tt>, then <em>only</em> those ports
requiring interaction are built).
For more details on any of this (since it may not be
clear at first reading), examine an existing port and
read the contents of <tt>/usr/share/mk/bsd.port.mk</tt>;
you'll see that it's not as difficult as it sounds!
</enum>
<sect1>
<heading>Configuring the Makefile</heading>
<p>Configuring the Makefile is pretty simple, and again I
suggest that you look at existing examples before
starting. Consider the following problems in sequence as
you design your new Makefile:
<enum>
<item>Does it live in <tt>&dollar;{DISTDIR}</tt> as a
standard gzip'd tarball? If so, you can go on to the
next step. If not, you should look at overriding any
of the <tt>&dollar;{EXTRACT_CMD}</tt>,
<tt>&dollar;{EXTRACT_ARGS}</tt>,
<tt>&dollar;{EXTRACT_SUFX}</tt>, or
<tt>&dollar;{DISTFILE}</tt> variables, depending on
how alien a format your port's distribution file is.
In the worst case, you can simply create your own
`<tt>extract</tt>' target to override the default,
though this should be rarely, if ever, necessary. If
you do find it necessary to do your own, your extract
target should take care to "leave tracks" for itself
so that files are not unnecessarily extracted
twice---see the default extract rule in
<tt>bsd.port.mk</tt> for an example of this.
<item>If your port is integrated into the ports
directory directly (original sources are already part
of FreeBSD), you may also consider simply setting
<tt>NO_EXTRACT</tt> and dispensing with the idea of a
distribution file altogether.
<item>You should set <tt>&dollar;{DISTNAME}</tt> to be the base
name of your port. The default rules expect the
distribution file list (<tt>&dollar;{DISTFILES}</tt>) to be
named
<tt>&dollar;{DISTDIR}/&dollar;{DISTFILE}&dollar;{EXTRACT_SUFX}</tt>
by default which, if it's a normal tarball, is going
to be something like:
<tscreen><verb>
foozolix-1.0.tar.gz
</verb></tscreen>
For a setting of "<tt>DISTNAME=foozolix-1.0</tt>"
The default rules also expect the tarball(s) to
extract into a subdirectory called
<tt>&dollar;{WRKDIR}/&dollar;{DISTNAME}</tt>, e.g.
<tscreen><verb>
"<blah>/foozolix-1.0/"
</verb></tscreen>
All this behavior can be overridden, of course, it
simply represents the most common time-saving
defaults. For a port requiring multiple distribution
files, simply set <tt>&dollar;{DISTFILES}</tt> explicitly. If
only a subset of <tt>&dollar;{DISTFILES}</tt> are actual
extractable archives, then set them up in
<tt>&dollar;{EXTRACT_ONLY}</tt>, which will override the
<tt>&dollar;{DISTFILES}</tt> list when it comes to extraction.
<item>If your package uses GNU <tt>make</tt>, set
"<tt>USE_GMAKE=yes</tt>". If your package uses GNU
<tt>configure</tt>, set "<tt>GNU_CONFIGURE=yes</tt>".
If you want to override the default GNU <tt>configure</tt>
arguments from `<tt>i386--freebsd</tt>' to something else,
set those arguments in <tt>&dollar;{GNU_CONFIGURE_ARGS}</tt>.
If your package uses <tt>imake</tt> (e.g. is an X
application that has an <tt>Imakefile</tt>), then set
"<tt>USE_IMAKE=yes</tt>". This will cause the
configure stage to automatically do an <tt>xmkmf</tt> and then
a `<tt>make Makefiles</tt>'.
<item>If you have a URL pointing at the the original
tarball, record the directory containing the tarball
in <tt>&dollar;{MASTER_SITES}</tt>. This will provide a
backup site, as well as a direct pointer to the
original source location.
The make macros will currently try to use this
specification for grabbing the distribution file with
<tt>&dollar;{NCFTP}</tt> if they can't find it
already on the system. See some of the other ports
for examples.
<item>Due to a problem in some of the ports, 2.0 was
distributed with a setting which meant ports that
have <tt>&dollar;{USE_IMAKE}</tt> set do not install their
manpages by default. Although -current has the logic
reversed, for compatability with 2.0 systems (at
least until 2.1 comes out) you should set
"<tt>INSTALL_MANPAGES=yes</tt>". For complete forward
compatability, if the port doesn't understand the
"<tt>install.man</tt>" target, "<tt>NO_INSTALL_MANPAGES=yes</tt>"
should be set (which conforms with the current logic
in <tt>bsd.port.mk</tt>)
<item>Don't forget to include
<tt>&lt;bsd.port.mk&gt;</tt> at the bottom. That
should do it!
</enum>
<sect1>
<heading>Do's and Dont's</heading>
<p><enum>
<item>Don't leave anything valuable lying around in
<tt>&dollar;{WRKDIR}</tt>, `<tt>make clean</tt>' will
<em>nuke</em> it completely! If you need auxilliary
files that aren't scripts or patches, put them in
<tt> &dollar;{FILESDIR}</tt>.
<item>Do install package information, if possible. It
would sure be nice if `<tt>make package</tt>' worked
for the whole ports tree this time.
<item>Do look at existing examples and the
<tt>bsd.port.mk</tt> file before asking me questions!
;-)
<item>Do ask me questions if you have any trouble!
Don't just beat your head against a wall! :-)
<item>Don't rely on custom utilities in your local
configure script---they may not be there on the
user's system! If you really need something else to
be installed before you can work, detect this from
your configure script, print a helpful message and
exit with a non-zero status! At least you'll have
given the user some idea of what's needed. If the
custom utility or package is actually part of the
ports tree, then set a pointer to it in your
<tt>DEPENDS</tt> variable---the port structure will
ensure that all <tt>DEPENDS</tt> targets are built
first.
<item>Do send applicable changes/patches to the
original author/maintainer for inclusion in next
release of the code. This will only make your job
that much easier for the next release.
</enum>

240
handbook/ports.sgml Normal file
View file

@ -0,0 +1,240 @@
<!-- $Id: ports.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>The Ports collection</heading>
<p><em>Contributed by &a.gpalmer; and &a.jkh;.</em>
Unfortunately, there are more variations of UN*X than most people
know of, and hence not all software for UN*X available on the Internet
will work on all versions of UN*X (in fact, I can guarantee it!).
Hence, some software needs modifications to work under some UN*Xs. The
process of making those modifications is known as ``porting'' and the
result known as a ``port'' (not to be confused with the sockets on the
back of your computer!).
<sect1><heading>What is the FreeBSD Ports Collection?</heading>
<p> People who (allegedly) know what they are doing have automated the
process of ``porting'' software to FreeBSD, and the result is the
Ports Collection. The general idea is that a combination of various
programming tools available in the base FreeBSD installation will
allow you to fetch the port from a FreeBSD mirror site, type ``make''
and get the fully working program.
The ports collection itself normally doesn't have any of the
original source code necessary for the compilation in the tree, just
those shell scripts, Makefiles and source code ``diffs'' that are
necessary to compile the program under FreeBSD. This is meant to keep
the entire system down to a manageable size, and the current system
has over 100 ports in the master source tree, and yet a compressed tar
file of that tree is about 2 megabytes (all the source code needed is
over 100Mb's!).
<sect1><heading>How does the system compile with no source code?</heading>
<p> A ports' Makefile automatically looks in a central location on
your system (usually /usr/ports/distfiles, though this value can be
customized) for the associated set of original distribution files that
have been ``ported''. These are generally provided at various places
on the Internet, though if you have a CDROM distribution of FreeBSD
then you've already got them available on your CD for ease of use.
See section 3.1 if you have such a CD distribution, otherwise skip to
section 3.2.
<!--
3.1 Compiling ports from CD
Type something profound here.
-->
<sect2><heading>Compiling ports using an Internet connection</heading>
<p> The ports collection can also use an auto-fetch system to keep
your ports collection source tree up to date, updating the central
``distfiles'' version for you the next time you compile the port.
Of course, this always assumes you have a permanent network link,
or don't mind heavy usage of your telephone. If you don't want heavy
network usage when you compile your ports tree, you can pre-fetch the
necessary tarballs beforehand and put them into /usr/ports/distfiles
(or wherever DISTDIR points) by hand. A good way to see what files a
port is going to need is to cd to that port's directory and do a
``make -n fetch'' to see what it does.
You can also chose to get the source files either from the master
FTP site as defined in the relevant Makefile (in the MASTER_SITES
line), or some FreeBSD mirror site also carrying a set of distfiles,
as does the master FTP site on ftp.FreeBSD.org (aka ftp.cdrom.com) in
the directory /pub/FreeBSD/ports/distfiles. Note that the files in
that directory are not guarenteed to be kept up to date - this is a
volunteer project! We can't make any guarantees about the mirror
sites either - they are obviously under independant control and don't
even have to mirror the distfiles directory.
If you have a non-permanant link, you can fetch all the distfiles by
going to the top of the tree and typing ``make fetch''.
<sect1><heading>It doesn't work?!</heading>
<p>Oh. You can do one of four (4) things :
<enum>
<item> Fix it yourself. Technical details can be found in the GUIDELINES file,
available from URL ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES
<item> Gripe. This is done by e-mail *ONLY*! The people at Walnut Creek are
in no way responsible for the functionality (or lack thereof) of the
FreeBSD system as a whole, and especially the ports system, which
is mainly contributed by 3rd parties. (If you don't believe me, check
the catalogue, especially the line saying "We cannot offer tech-support
on this product")
The e-mail address is Ports@FreeBSD.org. Please include details of
the port, where you got both the port source &amp; distfile(s) from, and
what the error was.
Note: At time of writing, lang/Sather doesn't seem to work on Pentium
machines due to the Intel Curse (aka the Floating Point Division Bug).
Please don't tell us about this - gripe to Intel instead - it's their
bug!
<item> Forget it. This is the easiest for most - very few of the programs in
ports can be classed as `essential'!
<item> Grab the pre-compiled package from a ftp server. The ``master'' package
collection is in:
ftp://ftp.FreeBSD.org/pub/FreeBSD/packages/
though check your local mirror first, please!
These are more likely to work (on the whole) than trying to compile from
source, and a lot faster!
</enum>
<sect1><heading>I've ported a program and I want to make a port out of it. What now?</heading>
<p> See the file GUIDELINES, in:
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES
This contains details of the procedure and structure involved.
<sect1><heading>I've got a good port, what now?</heading>
<p> Upload the fixed version to freefall.cdrom.com /pub/incoming or
ftp.FreeBSD.org /pub/FreeBSD/incoming and send e-mail to
ports@FreeBSD.org with the filename and details. Someone on the
all-volunteer `ports committee' will (hopefully) look it over and
commit it to the ports collection if they like the looks of it.
<sect1><heading>Things go funny during the fetch stage of compilation!</heading>
<p> We know. Please don't blame us. There is a program called `ncftp'
which is used instead of the normal ftp as it can do so-called
``background'' or ``batch'' transfers, ideal for this situation.
Unfortunately it can do strange things, and has crashed at least one
machine (during circumstances stranger than most, I'll admit, but it
was still responsible). Hopefully a future release of ncftp will fix
these problems (it is not maintained by the main FreeBSD team, but a
third party, who is I believe aware of its shortcomings)
<sect1><heading>I want to leave the compile going overnight, but some ports don't like this.</heading>
<p> There is a way around this. Before starting the compilation, type:
<verb>
setenv BATCH yes # (if you use csh/tcsh) or
BATCH=yes # (for sh/bash)
</verb>
This should miss out ports which need user interaction. Unfortunately,
ncftp doesn't know about this trick, and can often screw up and ask
stupid questions in unattended batch mode. See (7).
To compile those ports left out by doing the above, using a
different login shell (or unsetting the above BATCH variable), set the
INTERACTIVE variable instead (you can use the same statements as above
except replace ``BATCH'' with ``INTERACTIVE'') and re-run make. This
should now compile only those ports which will definitely ask for user
interaction.
<sect1><heading>The ports collection is weak. What can I do to help?</heading>
<p> First read the bsd.port.mk file (which may be found in
/usr/share/mk/) and the associated bsd.port.subdir.mk file. A lot of
the weirdness can be explained properly in there (most of the current
weirdness is due to the lack of assumptions about anything, which is
necessary due to the generic nature of these files). Also check that
you have an up-to-date copy, as the file can change from minute to
minute. A reasonably up-to-date copy can be found in:
<url url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk">
If you find that you still need to go in there and alter things,
by all means do so, and then send the diffs to ports@FreeBSD.org if
you'd like them to be a part of the default distribution. Please also
remember that any changes must respect backwards-compatability with
any and all older Makefiles, unless you want a real nightmare of
/usr/ports munging ahead of you! Large scale changes will generally
not be warmly welcomed unless all the existing makefiles work without
alteration. Sorry!
<sect1><heading>This FAQ is weak. What can I do?</heading>
<p> Send changes to ports@FreeBSD.org. Changes are most welcome!
This FAQ is also very green and should be considered no more than
a `good start' for now. Authors? You can come out of hiding any
time now! :-)
<sect1><heading>How do I get more information on all the ports?</heading>
<p> One good method is to cd to the top of the ports tree (say /usr/ports)
and type something like:
<verb>
make describe | sed -e '/===/D' -e 's;/usr/ports/;;' | expand -40
</verb>
The ``make describe'' will try to extract the one-line description from
each port, and the ``sed'' will delete the extraneous output. ``expand''
just makes it a little more readable (sort of - you may want to season
the output of this more to taste).
<sect1><heading>I've heard of a new checksum system. What is this for?</heading>
<p> For various reasons, when using FTP over the Internet to obtain the
source code, you may not always end up with the same copy of the code
that the origional porter worked from, and this can lead to problems.
So a simple checksumming system has been employed to try and highlight
problems in this area.
To check the entire system, go to the top of the ports tree
(defaults to /usr/ports) and type
<verb>
make checksum
</verb>
This will give a report on the validity of the files you have FTP'd. If some
are missing, the system will attempt to retrieve them before running the
checksum routine. The same technique can be applied to a single port.
The system will complain if there is no pre-computed checksum available
for that port. Not all ports currently have checksums, but this should be
cured soon.
Some older versions of the system don't recognise the ``checksum''
target. In that case, try the command
<verb>
make check-md5
</verb>
(``check-md5'' was the pre-cursor to the ``checksum'' target). If neither
work, get the latest copies of bsd.port.mk and bsd.port.subdir.mk from
<url url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk">
and install them in /usr/share/mk. This will get you the latest version
of the ports system.

372
handbook/ppp.sgml Normal file
View file

@ -0,0 +1,372 @@
<!-- $Id: ppp.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>Setting up a PPP link</heading>
<p><em>Contributed by &a.gena;.</em>
Before you start setting up PPP on your machine make
sure that pppd is located in /usr/sbin and directory /etc/ppp
exists.
pppd can work in two modes:
<enum>
<item> as a "client" , i.e. you want to connect your machine to outside
world via PPP serial connection or modem line.
<item> as a "server" , i.e. your machine is located on the network and
used to connect other computers using PPP.
</enum>
In both cases you will need to set up an options file ( /etc/ppp/options
or ~/.ppprc if you have more then one user on your machine that uses
PPP ).
You also will need some modem/serial software ( preferably kermit )
so you can dial and establish connection with remote host.
<sect1><heading>Working as a PPP client</heading>
<p>I used the following /etc/ppp/options to connect to CISCO terminal server PPP
line.
<verb>
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 router
</verb>
To connect:
<enum>
<item> Dial to the remote host using kermit ( or other modem program )
enter your user name and password ( or whatever is needed to enable PPP
ont the remote host )
<item> Exit kermit. ( without hanging up the line )
<item> enter:
<verb>
/usr/src/usr.sbin/pppd.new/pppd /dev/tty01 19200
</verb>
( put the appropriate speed and device name )
</enum>
Now your computer is connected with PPP. If the connection fails for some
reasons you can add the "debug" 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:
<verb>
#!/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 19200
</verb>
/etc/ppp/kermit.dial is kermit script that dials and makes all
necessary authorization on the remote host.
( Example of such script is attached to the end of this document )
Use the follwing /etc/ppp/pppdown script to disconnect the PPP line:
<verb>
#!/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/ppptest
</verb>
Check if PPP is still running (/usr/etc/ppp/ppptest):
<verb>
#!/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 ppp0
</verb>
Hangs up modem line (/etc/ppp/kermit.hup):
<verb>
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
exit
</verb>
<sect1><heading>Working as a PPP server</heading>
<p>/etc/ppp/options:
<verb>
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 line
</verb>
Following /etc/ppp/pppserv script will enable ppp server on your machine
<verb>
#!/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 19200
</verb>
Use this /etc/ppp/pppservdown script to stop ppp server:
<verb>
#!/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.noans
</verb>
Following kermit script will enable/disable autoanswer mode
on your modem (/etc/ppp/kermit.ans):
<verb>
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
exit
</verb>
This /etc/ppp/kermit.dial script is used for dialing and authorizing on remote host.
You will need to customize it for your needs.
Put your login and password in this script , also you'll need
to change input statement depending on responces from your modem
and remote host.
<verb>
;
; 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:
</verb>
<!--
###################################################################
Gennady B. Sorokopud ( gena@NetVision.net.il ) 24/10/94 12:00
-->

688
handbook/scsi.sgml Normal file
View file

@ -0,0 +1,688 @@
<!-- $Id: scsi.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!--
<title>An introduction to SCSI and its use with FreeBSD</title>
<author>(c) 1995, Wilko Bulte, <tt/wilko@yedi.iaf.nl/
<date>V0.2, Thu Apr 20 22:45:23 MET DST 1995</date>
Copyright 1995, W. C. Bulte, Arnhem, The Netherlands
<abstract>
This document attempts to describe the background of SCSI, its
(mis)use with FreeBSD and some common pitfalls.
</abstract>
-->
<sect><heading>SCSI</heading>
<p><em>&copy; 1995, &a.wilko;.</em>
SCSI is an acronym for Small Computer Systems Interface. It is an
ANSI standard that has become one of the leading I/O buses in the
computer industry. The foundation of the SCSI standard was laid by
Shugart Associates (the same guys that gave the world the first
mini floppy disks) when they introduced the SASI bus (Shugart Associates
Standard Interface).
After some time an industry effort was started to come to a more strict
standard allowing devices from different vendors to work together.
This effort was recognised in the ANSI SCSI-1 standard. The SCSI-1
standard (approx 1985) is now more or less obsolete. The current
standard is SCSI-2 (see <ref id="further-reading" name="Further
reading">), with SCSI-3 on the drawing boards.
In addition to a physical interconnection standard, SCSI defines a
logical (command set) standard to which disk devices must adhere.
This standard is called the Common Command Set (CCS) and was
developed more or less in parallel with ANSI SCSI-1. SCSI-2
includes the (revised) CCS as part of the standard itself. The
commands are dependent on the type of device at hand. It does not
make much sense of course to define a Write command for a
scanner...
The SCSI bus is a parallel bus, which comes in a number of
variants. The oldest and most used is an 8 bit wide bus, with
single-ended signals, carried on 50 wires. (If you don't know what
single-ended means, don't worry, that is what this document is all
about.) Modern designs also use 16 bit wides buses, with
differential signals. This allows transfer speeds of
20Mbytes/second, on cables lengths of up to 25 meters. SCSI-2
allows a maximum buswidth of 32 bits, using an additional cable.
Of course the SCSI bus not only has data lines, but also a number
of control signals. A very elaborate protocol is part of the
standard to allow multiple devices to share the bus in an efficient
manner. In SCSI-2, the data is always checked using a seperate
parity line. In pre-SCSI-2 designs parity was optional.
In SCSI-3 even faster bustypes are introduced, along with a serial
SCSI bus that reduces the cabling overhead and allows a higher
maximum buslength.
As you could have guessed from the description above, SCSI devices
are intelligent. They have to be to adhere to the SCSI standard
(which is over 2 inches thick BTW). So, for a hard disk drive for
instance you do not specify a head/cylinder/sector to address a
particular block, but simply the number of the block you want.
Elaborate caching schemes, automatic badblock replacement etc
are all made possible by this 'intelligent device' approach.
On a SCSI bus, each possible pair of devices can communicate. If
their function allows this is another matter, but the standard does
not restrict it. To avoid signal contention, the 2 devices have to
arbitrate for the bus before using it.
The philosophy of SCSI is to have a standard that allows
older-standard devices to work with newer-standard ones. So, an
old SCSI-1 device should normally work on a SCSI-2 bus. Normally,
because it is not absolutely sure that the implementation of an old
device follows the (old) standard closely enough to be acceptable
on a new bus. Modern devices are usually more well-behaved,
because the standardisation has become more strict and is better
adhered to by the device manufacturers. Generally speaking, the
chances of getting a working set of devices on a single bus is
better when all the devices are SCSI-2 or newer. This does not
imply that you have to dump all your old stuff when you get that
shiny 2Gb disk: I own a system on which a pre-SCSI-1 disk, a SCSI-2
QIC tape unit, a SCSI-1 helical scan tape unit and 2 SCSI-1 disks
work together quite happily.
<sect1>Concepts of SCSI
<p>
<sect2>A <it>smart</it> interface
<p>
As said before, SCSI devices are smart. The idea is to put the
knowledge about intimate hardware details onto the SCSI device
itself. In this way, the host system does not have to worry
about things like how many heads are hard disks has, or how many
tracks there are on a specific tape device. If you are curious,
the standard specifies commands with which you can query your
devices on their hardware particulars.
The advantage of intelligent devices is obvious: the device
drivers on the host can be made in a much more generic fashion,
there is no longer a need to change (and qualify!) drivers for
every odd new device that is introduced.
<sect2>Do's and don't's on interconnections
<p>
For cabling and connectors there is a golden rule: get good
stuff. With bus speeds going up all the time you will save
yourself a lot of grief by using good material.
So, gold plated connectors, shielded cabling, sturdy connector
hoods with strain reliefs etc are the way to go. Second golden
rule: don't use cables longer than necessary. I once spent 3 days
hunting down a problem with a flaky machine only to discover that
shortening the SCSI bus with 1 meter solved the problem. And the
original bus length was well within the SCSI specification.
<sect2>SCSI bus types
<p>
From an electrical point of view, there are two Incompatible bus
types: single-ended and differential. This means that there are
two different main groups of SCSI devices and controllers, which
cannot be mixed on the same bus. It is possible however to use
special converter hardware to transform a single-ended bus into a
differential one (and vice versa). The differences between the
bus types are explained in the next sections.
In lots of SCSI related documentation there is a sort of jargon
in use to abbreviate the different bus types. A small list:
<itemize>
<item>FWD: Fast Wide Differential
<item>FND: Fast Narrow Differential
<item>SE: Single Ended
<item>FN: Fast Narrow
<item>etc.
</itemize>
With a minor amount of imagination one can usually imagine what
is meant.
Wide is a bit ambiguous, it can indicate 16 or 32 bit buses. As
far as I know, the 32 bit variant is not (yet) in use, so wide
normally means 16 bit.
Fast means that the timing on the bus is somewhat different, so
that on a narrow (8 bit) bus 10 Mbytes/sec are possible instead
of 5 Mbytes/sec for 'slow' SCSI. More on this later.
It should be noted that the datalines > 8 are only used for
datatransfers and device addressing. The transfers of commands
and status messages etc are only performed on the lowest 8
datalines. The standard allows narrow devices to operate on
a wide bus. The usable buswidth is negotiated
between the devices. You have to watch your device addressing
closely when mixing wide and narrow.
<sect3>Single ended buses
<p>
A single-ended SCSI bus uses signals that are either 5 Volts or
0 Volts (indeed, TTL levels) and are relative to a COMMON
ground reference. A singled ended 8 bit SCSI bus has
approximately 25 ground lines, who are all tied to a single
'rail' on all devices. A standard single ended bus has a
maximum length of 6 meters. If the same bus is used with
fast-SCSI devices, the maximum length allowed drops to 3
meters. Fast-SCSI means that instead of 5Mbytes/sec the bus
allows 10Mbytes/sec transfers.
Please note that this means that
if some devices on your bus use 'fast' to communicate your
bus must adhere to the length restrictions for fast buses!
It is obvious that with the newer fast-SCSI devices the
buslength can become a real bottleneck. This is why the
differential SCSI bus was introduced in the SCSI-2 standard.
For connector pinning and connector types please refer to the
SCSI-2 standard (see <ref id="further-reading" name="Further
reading">) itself, connectors etc are listed there in
painstaking detail.
Beware of devices using non-standard cabling. For instance
Apple uses a 25pin D-type connecter (like the one on serial
ports and parallel printers). Considering
that the official SCSI bus needs 50 pins you can imagine
the use of this connector needs some 'creative cabling'.
The reduction of the number of ground wires they used
is a bad idea, you better stick to 50 pins cabling
in accordance with the SCSI standard.
<sect3>Differential buses
<p>
A differential SCSI bus has a maximum length of 25
meters. Quite a difference from the 3 meters for a single-ended
fast-SCSI bus. The idea behind differential signals is that
each bus signal has it's own return wire. So, each signal is
carried on a (preferably twisted) pair of wires. The voltage
difference between these two wires determines whether the
signal is asserted or de-asserted. To a certain extent the
voltage difference between ground and the signal wire pair is
not relevant (don't try 10 kVolts though..).
It is beyond the scope of this document to explain why this
differential idea is so much better. Just accept that
electrically seen the use of differential signals gives a much
better noise margin. You will normally find differential buses
in use for inter-cabinet connections. Because of the lower cost
single ended is mostly used for shorter buses like inside
cabinets.
There is nothing that stops you from using differential stuff
with FreeBSD, as long as you use a controller that has device
driver support in FreeBSD. As an example, Adaptec marketed the
AH1740 as a single ended board, whereas the AH1744 was differential.
The software interface to the host is identical for both.
<sect3>Terminators
<p>
Terminators in SCSI terminology are resistor networks that are
used to get a correct impedance matching. Impedance matching
is important to get clean signals on the bus, without
reflections or ringing. If you once made a long distance
telephone call on a bad line you probably know what reflections
are. With 20Mbytes/sec travelling over your SCSI bus, you
don't want signals echoing back.
Terminators come in various incarnations, with more or less
sophisticated designs. Of course, there are internal and
external variants. Almost every SCSI device comes with a
number of sockets in which a number of resistor networks can
(must be!) installed. If you remove terminators from a device,
carefully stock 'm. You will need them when you ever decide to
reconfigure your SCSI bus. There is enough variation in even
these simple tiny things to make finding the exact replacement
a frustrating business. There are also SCSI devices that have
a single jumper to enable or disable a builtin terminator.
There are special terminators you can stick onto a flatcable
bus. Others look like external connectors, so a connector hood
without a cable. So, lots of choice as you can see.
There is much debate going on if and when you should switch
from simple resistor (passive) terminators to active
terminators. Active terminators contain more or less elaborate
circuits to give more clean bus signals. The general consensus
seems to be that the usefullnes of active termination increases
when you have long buses and/or fast devices. If you ever have
problems with your SCSI buses you might consider trying an
active terminator. Try to borrow one first, they reputedly are
quite expensive.
Please keep in mind that terminators for differential and
single-ended buses are not identical. You should <bf>not
mix</bf> the two variants.
OK, and now where should you install your terminators? This is
by far the most misunderstood part of SCSI. And it is by far
the simplest.. The rule is: <bf>every SCSI bus has 2 (two)
terminators, one at each end of the bus.</bf> So, two and not
one or three or whatever. Do yourself a favour and stick to
this rule. It will save you endless grief, because wrong
termination has the potential to introduce highly mysterious
bugs.
A common pitfall is to have an internal (flat)cable in a
machine and also an external cable attached to the
controller. It seems almost everybody forgets to remove the
terminators from the controller. The terminator must now be on
the last external device, and not on the controller! In
general, every reconfiguration of a SCSI bus must pay attention
to this.
What I did myself is remove all terminators from my SCSI
devices and controllers. I own a couple of external
terminators, for both the Centronics-type external cabling and
for the internal flat cable connectors. This makes
reconfiguration much easier.
<sect3>Terminator power
<p>
The terminators discussed in the previous chapter need power to
operate properly. On the SCSI bus, a line is dedicated to this
purpose. So, simple huh?
Not so. Each device can provide it's own terminator power to
the terminator sockets it has on-device. But if you have
external terminators, or when the device supplying the
terminator power to the SCSI bus line is switched off you are
in trouble.
The idea is that initiators (these are devices that initiate
actions on the bus, a discussion follows) must supply
terminator power. All SCSI devices are allowed (but not
required) to supply terminator power.
To allow for switched-off devices on a bus, the terminator
power must be supplied to the bus via a diode. This prevents
the backflow of current to switched-off devices.
To prevent all kinds of nastiness, the terminator power is
usually fused. As you can imagine, fuses might blow. This can,
but does not have to, lead to a non functional bus. If multiple
devices supply terminator power, a single blown fuse will not
put you out of business. A single supplier with a blown fuse
certainly will. Clever external terminators sometimes have a
LED indication that shows whether terminator power is present.
In newer designs auto-restoring fuses are used who 'reset'
themselves after some time.
On modern devices, sometimes integrated terminators are
used. These things are special purpose integrated circuits that
can be dis/en-abled with a control pin. It is not necessary to
physically remove them from a device. You may find them on
newer host adapters, sometimes they even are software
configurable, using some sort of setup tool. Consult you
documentation!
<sect3>Device addressing
<p>
Because the SCSI bus is, ehh, a bus there must be a way to
distinguish or address the different devices connected to it.
This is done by means of the SCSI or target ID. Each device has
a unique target ID. You can select the ID to which a device
must respond using a set of jumpers, or a dipswitch, or
something similar. Consult the documentation of your device for
more information.
Beware of multiple devices configured to use the same ID. Chaos
normally reigns in this case.
For an 8 bit bus, a maximum of 8 targets is possible. The
maximum is 8 because the selection is done bitwise using the 8
datalines on the bus. For wide this increases to the number of
datalines.
The higher the SCSI target ID, the higher the priority the
devices has. When it comes to arbitration between devices that
want to use the bus at the same time, the device that has the
highest SCSI ID will win. This also means that the SCSI
hostadapter usually uses target ID 7 (for narrow buses).
For a further subdivision, the standard allows for Logical
Units or LUNs for short. A single target ID may have multiple
LUNs. For example, a tape device including a tape changer may
have LUN 0 for the tape device itself, and LUN 1 for the
tapechanger. In this way, the host system can address each of
the parts of the tape unit as desired.
<sect3>Bus layout
<p>
SCSI buses are linear. So, not shaped like Y-junctions, star
topologies, cobwebbs or whatever else people might want to
invent.
You might notice that the terminator issue discussed earlier
becomes rather hairy if your bus is not linear..
The electrical characteristics, it's noise margins and
ultimately the reliability of it all are tightly related to
linear bus rule.
<bf>Stick to the linear bus rule!</bf>
<sect1>Using SCSI with FreeBSD
<p>
<sect2>About translations, BIOSes and magic..
<p>
As stated before, you should first make sure that you have a
electrically sound bus.
When you want to use a SCSI disk on your PC as boot disk, you
must aware of some quirks related to PC BIOSes. The PC BIOS in
it's first incarnation used a low level physical interface to the
harddisk. So, you had to tell the BIOS (using a setup tool or a
BIOS builtin setup) how your disk physically looked like. This
involved stating number of heads, number of cylinders, number of
sectors per track, obscure things like precompensation and
reduced write current cylinder etc.
One might be inclined to think that since SCSI disks are smart
you can forget about this. Alas, the arcane setup issue is still
present today. The system BIOS needs to know how to access your
SCSI disk with the head/cyl/sector method.
The SCSI host adapter or SCSI controller you have put in your
AT/EISA/PCI/whatever bus to connect your disk therefore has it's
own onboard BIOS. During system startup, the SCSI BIOS takes over
the harddisk interface routines from the system BIOS. To fool the
system BIOS, the system setup is normally set to No harddisk
present. Obvious, isn't it?
The SCSI BIOS itself presents to the system a so called
<bf>translated</bf> drive. This means that a fake drive table is
constructed that allows the PC to boot the drive. This
translation is often (but not always) done using a pseudo drive
with 32 heads and 64 sectors per track. By varying the number of
cylinders, the SCSI BIOS adapts to the actual drive size. It is
useful to note that 32 * 64 / 2 = the size of your drive in
megabytes. The division by 2 is to get from disk blocks that are
normally 512 bytes in size to Kbytes.
Right.. All is well now?! No, it isn't. The system BIOS has
another quirk you might run into. The number of cylinders of a
bootable harddisk cannot be greater than 1024. Using the
translation above, this is a showstopper for disks greater than
1 Gb. With disk capacities going up all the time this is causing
problems.
Fortunately, the solution is simple: just use another
translation, e.g. with 128 heads instead of 32. In most cases new
SCSI BIOS versions are available to upgrade older SCSI host
adapters. Some newer adapters have an option, in the form of a
jumper or software setup selection, to switch the translation the
SCSI BIOS uses.
It is very important that <bf>all</bf> operating systems on the disk use
the <bf>same translation</bf> to get the right idea about where to find
the relevant partitions. So, when installing FreeBSD you must
answer any questions about heads/cylinders etc using the
translated values your host adapter uses.
Failing to observe the translation issue might be un-bootable systems or
operating systems overwriting eachothers partitions. Using fdisk
you should be able to see all partitions.
As promised earlier: what is this talk about 'lying' devices? As
you might already know, the FreeBSD kernel reports the geometry
of SCSI disks when booting. An example from one of my systems:
<verb>
Feb 9 19:33:46 yedi /386bsd: aha0 targ 0 lun 0: <MICROP 1588-15MB1057404HSP4>
Feb 9 19:33:46 yedi /386bsd: sd0: 636MB (1303250 total sec), 1632 cyl, 15 head,
53 sec, bytes/sec 512
</verb>
This info is retrieved from the SCSI disk itself. Newer disks
often use a technique called zone bit recording. The idea is that
on the outer cylinders of the drive there is more space so more
sectors per track can be put on them. This results in disks that
have more tracks on outer cylinders than on the inner cylinders
and, last but not least, have more capacity. You can imagine that
the value reported by the drive when inquiring about the geometry
now becomes fake.
<sect2>SCSI subsystem design
<p>
FreeBSD uses a sort of layered SCSI subsystem. For each different
controller card a so called device driver is written. This driver
knows all the intimate details about the hardware it
controls. The driver has a interface to the upper layers of the
SCSI subsystem through which it receives it's commands and
reports back any status.
On top of the card drivers there are a number of more generic
drivers for a class of devices. More specific: a driver for
tape devices (abbreviation: st), magnetic disks (sd), cdroms (cd)
etc. In case you are wondering where you can find this stuff, it
all lives in <tt>/sys/scsi</tt>. See the man pages in section 4
for more details.
The multi level design allows a decoupling of low-level bit
banging and more high level stuff. Adding support for another
piece of hardware is a much more managable problem.
<sect2>Kernel configuration
<p>
Dependent on your hardware, the kernel configuration file must
contain a line which describes your hostadapter. This includes
I/O addresses, interrupts etc. Consult the man page for your
adapter driver to get more info.
Although it is probably an obvious remark: the kernel config
file should reflect your actual hardware setup. So, interrupts,
I/O addresses etc must match the kernel config file.
An example from the kernel config file (they live in
<tt>/sys/i386/conf</tt> BTW), with some added comments (between
&lsqb;&rsqb;):
<verb>
controller ahb0 at isa? bio irq 11 vector ahbintr &lsqb;driver for Adaptec 174x&rsqb;
controller aha0 at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr &lsqb;for Adaptec 154x&rsqb;
controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr &lsqb;for Seagate
ST01/02&rsqb;
controller scbus0
device sd0 &lsqb;support for 4 SCSI harddisks, sd0 up sd3&rsqb;
device sd1
device sd2
device sd3
device st0 &lsqb;support for 2 SCSI tapes&rsqb;
device st1
device cd0 #Only need one of these, the code dynamically grows &lsqb;for the cdrom&rsqb;
</verb>
So, the ahb driver is used for the Adaptec 1740, the aha driver
for the Adaptec 154x etc. If you have more than one card of the
same type in your system you get an ahb1, ahb2 line etc.
The example above supports 4 SCSI disks. If during boot more
devices of a specific type (e.g. sd disks) are found than are
configured in the booting kernel, the system will complain. You
will have to build and boot a new kernel (after adapting the kernel
configuration file) before you can use all of the devices. It
does not hurt to have 'extra' devices in the kernel, the example
above will work fine when you have only 2 SCSI disks.
Use <tt>man 4 scsi</tt> to check for the latest info on the SCSI
subsystem. For more detailed info on hostadapter drivers use eg
<tt>man 4 aha</tt> for info on the Adaptec 154x driver.
<sect2>Tuning your SCSI kernel setup
<p>
Experience has shown that some devices are slow to respond to INQUIRY
commands after a SCSI bus reset. An INQUIRY command is sent by the kernel
on boot to see what kind of device (disk, tape, cdrom etc) is connected
to a specific target ID. This process is called device probing by the way.
To work around this problem, FreeBSD allows a tunable delay time before
the SCSI devices are probed following a SCSI bus reset. You can set this
delaytime in your kernel configuration file using a line like:
<verb>
options "SCSI_DELAY=15" #Be pessimistic about Joe SCSI device
</verb>
This line sets the delay time to 15 seconds. On my own system I had to
use 3 seconds minimum to get my trusty old CDROM drive to be recognised.
Start with a high value (say 30 seconds or so) when you have problems
with device recognition. If this helps, tune it back until it just stays
working.
<sect2>Rogue SCSI devices
<p>
Although the SCSI standard tries to be complete and concise, it is
a complex standard and implementing things correctly is no easy task.
Some vendors do a better job then others.
This is exactly where the 'rogue' devices come into view. Rogues are
devices that are recognised by the FreeBSD kernel as behaving slightly
(...) non-standard. Rogue devices are reported by the kernel when
booting. An example for two of my cartridge tape units:
<verb>
Feb 25 21:03:34 yedi /386bsd: ahb0 targ 5 lun 0: <TANDBERG TDC 3600 -06:>
Feb 25 21:03:34 yedi /386bsd: st0: Tandberg tdc3600 is a known rogue
Mar 29 21:16:37 yedi /386bsd: aha0 targ 5 lun 0: <ARCHIVE VIPER 150 21247-005>
Mar 29 21:16:37 yedi /386bsd: st1: Archive Viper 150 is a known rogue
</verb>
For instance, there are devices that respond to
all LUNs on a certain target ID, even if they are actually only one
device. It is easy to see that the kernel might be fooled into
believing that there are 8 LUNs at that particular target ID. The
confusion this causes is left as an exercise to the user.
The SCSI subsystem of FreeBSD recognises devices with bad habits by
looking at the INQUIRY response they send when probed. Because the
INQUIRY response also includes the version number of the device
firmware, it is even possible that for different firmware versions
different workarounds are used.
This scheme works fine, but keep in mind that it of course only
works for devices that are KNOWN to be weird. If you are the first
to connect your bogus Mumbletech SCSI cdrom you might be the one
that has to define which workaround is needed.
<sect2>Busmaster host adapters
<p>
Most, but not all, SCSI host adapters are bus mastering controllers.
This means that they can do I/O on their own without putting load onto
the host CPU for data movement.
This is of course an advantage for a multitasking operating system like
FreeBSD. It must be noted however that there might be some rough edges.
For instance an Adaptec 1542 controller can be set to use different
transferspeeds on the host bus (ISA or AT in this case). The controller
is settable to different rates because not all motherboards can handle
the higher speeds. Problems like hangups, bad data etc might be the
result of using a higher data transfer rate then your motherboard
can stomach.
The solution is of course obvious: switch to a lower data transfer rate
and try if that works better.
In the case of a Adaptec 1542, there is an option that can be put
into the kernel config file to allow dynamic determination of the
right, read: fastest feasible, transfer rate. This option is
disabled by default:
<verb>
options "TUNE_1542" #dynamic tune of bus DMA speed
</verb>
Check the man pages for the host adapter that you use. Or better
still, use the ultimate documentation (read: driver source).
<sect1>Tracking down problems
<p>
The following list is an attempt to give a guideline for the most
common SCSI problems and their solutions. It is by no means
complete.
<itemize>
<item>
Check for loose connectors and cables.
<item>
Check and doublecheck the location and number of your terminators.
<item>
Check if your bus has at least one supplier of terminator power
(especially with external terminators.
<item>
Check if no double target IDs are used.
<item>
Check if at least one device provides terminator power to the bus.
<item>
Check if all devices to be used are powered up.
<item>
Make a minimal bus config with as little devices as possible.
<item>
If possible, configure your hostadapter to use slow bus speeds.
</itemize>
<sect1><heading>Further reading<label id="further-reading"></>
<p>
If you intend to do some serious SCSI hacking, you might want to
have the official standard at hand:
Approved American National Standards can be purchased from ANSI at
11 West 42nd Street, 13th Floor, New York, NY 10036, Sales Dept:
(212) 642-4900. You can also buy many ANSI standards and most
committee draft documents from Global Engineering Documents, 15
Inverness Way East, Englewood, CO 80112-5704, Phone: (800)
854-7179, Outside USA and Canada: (303) 792-2181, FAX: (303) 792-
2192.
Many X3T10 draft documents are available electronically on the SCSI
BBS (719-574-0424) and on the ncrinfo.ncr.com anonymous ftp site.
Latest X3T10 committee documents are:
<verb>
AT Attachment (ATA or IDE) &lsqb;X3.221-1994&rsqb; Approved
ATA Extensions (ATA-2) &lsqb;X3T10/948D Rev 2i&rsqb;
Enhanced Small Device Interface (ESDI) &lsqb;X3.170-1990/X3.170a-1991&rsqb; Approved
Small Computer System Interface - 2 (SCSI-2) &lsqb;X3.131-1994&rsqb; Approved
SCSI-2 Common Access Method Transport and SCSI Interface Module (CAM)
&lsqb;X3T10/792D Rev 11&rsqb;
</verb>
Other publications that might provide you with additional information are:
<verb>
"SCSI: Understanding the Small Computer System Interface", written by NCR
Corporation. Available from: Prentice Hall, Englewood Cliffs, NJ, 07632
Phone: (201) 767-5937 ISBN 0-13-796855-8
"Basics of SCSI", a SCSI tutorial written by Ancot Corporation
Contact Ancot for availability information at:
Phone: (415) 322-5322 Fax: (415) 322-0455
"SCSI Interconnection Guide Book", an AMP publication (dated 4/93, Catalog
65237) that lists the various SCSI connectors and suggests cabling schemes.
Available from AMP at (800) 522-6752 or (717) 564-0100
"Fast Track to SCSI", A Product Guide written by Fujitsu.
Available from: Prentice Hall, Englewood Cliffs, NJ, 07632
Phone: (201) 767-5937 ISBN 0-13-307000-X
"The SCSI Bench Reference", "The SCSI Encyclopedia", and the "SCSI Tutor",
ENDL Publications, 14426 Black Walnut Court, Saratoga CA, 95070
Phone: (408) 867-6642
"Zadian SCSI Navigator" (quick ref. book) and "Discover the Power of SCSI"
(First book along with a one-hour video and tutorial book), Zadian Software,
Suite 214, 1210 S. Bascom Ave., San Jose, CA 92128, (408) 293-0800
</verb>
On Usenet the newsgroups comp.periphs.scsi and comp.periphs are
noteworthy places to look for more info. You can also find the
SCSI-Faq there, which posted periodically.
Most major SCSI device and hostadapter suppliers operate ftp sites
and/or BBS systems. They may be valuable sources of information
about the devices you own.

196
handbook/slipc.sgml Normal file
View file

@ -0,0 +1,196 @@
<!-- $Id: slipc.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>Setting up a SLIP client</heading>
<p><em>Contributed by &a.asami;.</em>
The 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.
<!--
This is just "what I did, and it worked for me". I'm sharing this
just for your reference, I'm no expert in SLIP nor networking so your
mileage may vary.
-->
Note: for 1.1 systems (not 1.1.5), you need to use /dev/tty01 instead
of /dev/cua01. substitute all the occurences of "cua" in this document
with "tty".
Note: the default 1.1.5(.1) system only comes with cua/ttyd pairs for
the last two ports (2 and 3), so if your modem is at sio0/sio1
(COM1/COM2), you need to make the devices. Try "cd /dev; sh MAKEDEV
cua01" to make the new special files for sio1 (ditto for sio0). This
will delete tty01, but you shouldn't need it anymore...or you can make
a symbolic link /dev/tty01 -> ttyd1 if you don't want to hunt down all
occurences of tty01 in your setup files.
I actually have a symbolic link /dev/modem -> cua01 (and /dev/mouse ->
ttyd0). I use only the modem/mouse names in my configuration files.
This helped a lot when I switched from 1.1 to 1.1.5.1 (tty01 => cua01)
and when I had to move my modem temporarily to sio2 to enable the
RS-232C port on the serial card. It can become quite cumbersome when
you need to fix a bunch of files in /etc and .kermrc's all over the
system!
First, make sure you have
<verb>
pseudo-device sl 2
</verb>
in your kernel's config file. It is included in the GENERIC, GENERICAH
and GENERICBT kernels, so this won't be a problem unless you deleted it.
<sect1><heading>Things you have to do only once</heading>
<p><enum>
<item> Add your home machine, the gateway and nameservers to your
/etc/hosts file. Mine looks like this:
<verb>
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 ns2
</verb>
By the way, silvia is the name of the car that I had when I was
back in Japan (it's called 2?0SX here in U.S.).
<item> Make sure you have "hosts" before "bind" in your /etc/host.conf.
Otherwise, funny things may happen.
<item> Edit the /etc/netstart and add this to the end of the file:
<verb>
# set up slip
gateway=slip-gateway
ifconfig sl0 inet $hostname $gateway netmask 0xffffff00
route add default $gateway
</verb>
Note that because of the "slip-gateway" entry in /etc/hosts, there
is no local dependency in the netstart file. Also, you might want
to un-comment the "<verb>route add $hostname localhost</verb>" line.
<item> Make a file /etc/resolv.conf which contains:
<verb>
domain HIP.Berkeley.EDU
nameserver 128.32.136.9
nameserver 128.32.136.12
</verb>
As you can see, these set up the nameserver hosts. Of course, the
actual addresses depend on your environment.
<item> Set the password for root and toor (and any other accounts that
doesn't have a password). Use passwd, don't edit the passwd or
passwd.master files!
<item> Edit /etc/myname and reboot the machine.
</enum>
<sect1><heading>Making a SLIP connection</heading>
<p><enum>
<item> Dial up, type "slip" at the prompt, enter your machine name and
password. The things you need to enter depends on your
environment. I use kermit, with a script like this:
<verb>
# kermit setup
set modem hayes
set line /dev/cua01
set speed 57600
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\x0a
</verb>
(of course, you have to change the hostname and password to fit
yours). Then you can just type "slip" from the kermit prompt to
get connected.
Note: leaving your password in plain text anywhere in the
filesystem is generally a BAD idea. Do it at your own risk. I'm
just too lazy.
Note: If you have an 1.1 machine, and kermit doesn't give you a
prompt, try "stty -f /dev/tty01 clocal". I put this in
/etc/rc.local so that it works the first time I boot the machine.
This doesn't apply to 1.1.5(.1) systems, as cua0? are already
configured for dialouts.
<item> Leave the kermit there (you can suspend it by "z") and as root,
type
<verb>
slattach -h -c -s 57600 /dev/cua01
</verb>
if you are able to "ping" hosts on campus, you are connected!
If it doesn't work, you might want to try "-a" instead of "-c".
</enum>
<sect1><heading>How to shutdown the connection</heading>
<p>Type "ps gx" (as root) to find out the PID of slattach, and use
"kill -INT" to kill it.
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 doesn't 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.
When you want to connect again, go back to (XXX). You may have to
watch out for clocal mode. If "stty -f /dev/tty01" doesn't tell
you it's clocal, you need to re-set it before kermitting. Again,
this is only for 1.1 machines.
<sect1><heading>Troubleshooting</heading>
<p>If it doesn't work, feel free to ask me. The things that people
tripped over so far:
<itemize>
<item> Not using "-c" or "-a" in slattach (I have no idea why this can be
fatal, but adding this flag solved the problem for at least one
person)
<item> Using "s10" instead of "sl0" (might be hard to see the difference on
some fonts.
<item> Try "ifconfig sl0" to see your interface status. I get:
<verb>
silvia# ifconfig sl0
sl0: flags=10<POINTOPOINT>
inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00
</verb>
<item>Also, "netstat -r" will give the routing table, in case you get the
"no route to host" messages from ping. Mine looks like:
<verb>
silvia# 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)
</verb>
(this is after transferring a bunch of files, your numbers should be
smaller).
</itemize>

488
handbook/slips.sgml Normal file
View file

@ -0,0 +1,488 @@
<!-- This is an SGML version in the linuxdoc DTD of the SLIP Server
FAQ by Guy Helmer.
This guide provides instruction in configuring and preparing
a FreeBSD system to be a dialup SLIP server.
<title>
Setting up FreeBSD as a SLIP Server
<author>Guy Helmer, <tt/ghelmer@alpha.dsu.edu/
<date>v0.2, 20 March 1995
-->
<sect><heading>Setting up a SLIP server</heading>
<p><em>Contributed by &a.ghelmer;.</em>
This 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.
I've written this document based on my own experience; however, as
your system and needs may be different, this document may not answer
all of your questions, and I cannot be responsible if you damage your
system or lose data due to attempting to follow the suggestions here.
I have only setup SLIP Server services on a FreeBSD 1.1 system, so if
you are running a different version (such as FreeBSD 2.0), your system
may be different.
<sect1><heading>Prerequisites<label id="prereqs"></>
<p>
This document is very technical in nature, so background knowledge is
required. I must assume 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 <em>TCP/IP Network
Administration</em> published by O'Reilly &amp; Associates, Inc. (ISBN
Number 0-937175-82-X), or Douglas Comer's book on the TCP/IP protocol.
I will assume that you have already setup your modem(s) and configured
the appropriate system files to allow logins through your modems (see
the manual pages for <tt>sio(4)</tt> for information on the serial
port device driver and <tt>ttys(5)</tt>, <tt>gettytab(5)</tt>,
<tt>getty(8)</tt>, &amp; <tt>init(8)</tt> for information relevant to
configuring the system to accept logins on modems, and perhaps
<tt>stty(1)</tt> for information on setting serial port parameters
&lsqb;such as <tt>clocal</tt> for directly-connected serial
interfaces&rsqb;).
<sect1>Quick Overview
<p>
In 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 <tt>/usr/sbin/sliplogin</tt>
as the special user's shell. The <tt/sliplogin/ program browses the
file <tt>/etc/slip.hosts</tt> 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
<tt>/etc/slip.login</tt> to configure the SLIP interface.
<sect2>An Example of a SLIP Server Login
<p>
For example, if my SLIP user ID were <tt>Shelmerg</tt>, that user's
entry in <tt>/etc/master.passwd</tt> would look something like this
(except it would be all on one line):
<tscreen><verb>
Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:
/usr/users/Shelmerg:/usr/sbin/sliplogin
</verb></tscreen>
and, when I log in with that user ID, <tt>sliplogin</tt> will search
<tt>/etc/slip.hosts</tt> for a line that had a matching user ID; on my
system, I may have a line in <tt>/etc/slip.hosts</tt> that reads:
<tscreen><verb>
Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp
</verb></tscreen>
sliplogin will find that matching line, hook the serial line I'm on
into the next available SLIP interface, and then execute
<tt>/etc/slip.login</tt> like this:
<tscreen><verb>
/etc/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp
</verb></tscreen>
If all goes well, <tt>/etc/slip.login</tt> will issue an
<tt>ifconfig</tt> 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 <tt>slip.login</tt>) to set the local
IP address (<tt>dc-slip</tt>), remote IP address (<tt>sl-helmer</tt>),
network mask for the SLIP interface (<tt>0xfffffc00</tt>), and any
additional flags (<tt>autocomp</tt>). If something goes wrong,
sliplogin usually logs good informational messages via the daemon
syslog facility, which usually goes into <tt>/var/log/messages</tt>
(see the manual pages for <tt>syslogd(8)</tt> and
<tt>syslog.conf(5)</tt>, and perhaps check <tt>/etc/syslog.conf</tt>
to see to which files <tt>syslogd</tt> is logging).
OK, enough of the examples -- let's dive into setting up the system.
<sect1>Kernel Configuration
<p>
FreeBSD's default kernels usually come with two SLIP interfaces
defined (<tt>sl0</tt> and <tt>sl1</tt>); you can use <tt>netstat
-i</tt> to see whether these interfaces are defined in your kernel.
Sample output from <tt>netstat -i</tt>:
<tscreen><verb>
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 0
</verb></tscreen>
The <tt>sl0</tt> and <tt>sl1</tt> interfaces shown in <tt>netstat
-i</tt>'s output indicate that there are two SLIP interfaces built
into the kernel. (The asterisks after the <tt>sl0</tt> and
<tt>sl1</tt> 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 RFC's 1009
&lsqb;Requirements for Internet Gateways&rsqb;, 1122
&lsqb;Requirements for Internet Hosts -- Communication Layers&rsqb;,
and perhaps 1127 &lsqb;A Perspective on the Host Requirements
RFCs&rsqb;), so if you want your FreeBSD SLIP Server to act as a
router, you'll have to add the line <tt>options GATEWAY </tt> to your
machine's kernel configuration file and re-compile the kernel anyway.
(Trivia: ``Gateways'' are the Internet's old name for what are now
usually called ``routers''.)
Please see the BSD System Manager's Manual chapter on ``Building
Berkeley Kernels with Config'' &lsqb;the source for which is in
<tt>/usr/src/share/doc/smm</tt>&rsqb; and ``FreeBSD Configuration
Options'' &lsqb;in <tt>/sys/doc/options.doc</tt>&rsqb; for more
information on configuring and building kernels. You may have to
unpack the kernel source distribution if haven't installed the system
sources already (<tt>srcdist/srcsys.??</tt> in FreeBSD 1.1,
<tt>srcdist/sys.??</tt> in FreeBSD 1.1.5.1, or the entire source
distribution in FreeBSD 2.0) to be able to configure and build
kernels.
You'll notice that near the end of the default kernel configuration
file (<tt>/sys/i386/conf/GENERICAH</tt>) is a line that reads:
<tscreen><verb>
pseudo-device sl 2
</verb></tscreen>
which 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.
See the document ``Building Berkeley Kernels with Config'' and the
manual page for <tt>config(8)</tt> to see how to configure and build
kernels.
<sect1>Sliplogin Configuration
<p>
As mentioned earlier, there are three files in the <tt>/etc</tt> directory that are part of the configuration for
<tt>/usr/sbin/sliplogin</tt> (see <tt>sliplogin(8)</tt> for the actual
manual page for <tt>sliplogin</tt>): <tt>slip.hosts</tt>, which
defines the SLIP users &amp; their associated IP addresses;
<tt>slip.login</tt>, which usually just configures the SLIP interface;
and (optionally) <tt>slip.logout</tt>, which undoes <tt>slip.login</tt>'s
effects when the serial connection is terminated.
<sect2>slip.hosts Configuration
<p>
<tt>/etc/slip.hosts</tt> contains lines which have at least four items
listed:
<itemize>
<item> SLIP user's login ID
<item> Local address (local to the SLIP server) of the SLIP link
<item> Remote address of the SLIP link
<item> Network mask
</itemize>
The local and remote addresses may be host names (resolved to IP
addresses by <tt>/etc/hosts</tt> or by the domain name service,
depending on your specifications in <tt>/etc/host.conf</tt>), and I
believe the network mask may be a name that can be resolved by a
lookup into <tt>/etc/networks</tt>. On one of my systems,
<tt>/etc/slip.hosts</tt> looks like this:
<tscreen><verb>
----- begin /etc/slip.hosts -----
#
# login local-addr remote-addr mask opt1 opt2
# (normal,compress,noicmp)
#
Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp
----- end /etc/slip.hosts ------
</verb></tscreen>
At the end of the line is one or more of the options:
<itemize>
<item> <tt>normal</tt> - no header compression
<item> <tt>compress</tt> - compress headers
<item> <tt>autocomp</tt> - compress headers if the remote end allows it
<item> <tt>noicmp</tt> - disable ICMP packets (so any ``ping'' packets will be
dropped instead of using up your bandwidth)
</itemize>
Your 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's not ``true'' proxy
ARP, but that is the terminology that I will use in this document to
describe it). If you're not sure which method to select or how to
assign IP addresses, please refer to the TCP/IP books referenced in
the <ref id="prereqs"> section and/or consult your IP network manager.
If 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 <tt>gated</tt> 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.
Otherwise, 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'll also need to adjust your
<tt>/etc/slip.login</tt> and <tt>/etc/slip.logout</tt> scripts to use
<tt>arp(8)</tt> to manage the proxy-ARP entries in the SLIP server's
ARP table.
<sect2>slip.login Configuration
<p>
The typical <tt>/etc/slip.login</tt> file looks like this:
<tscreen><verb>
----- begin /etc/slip.login -----
#!/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
----- end /etc/slip.login -----
</verb></tscreen>
This <tt>slip.login</tt> 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 <tt>/etc/slip.login</tt>
file will need to look something like this:
<tscreen><verb>
----- begin /etc/slip.login for "proxy ARP" -----
#!/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 pub
----- end /etc/slip.login for "proxy ARP" -----
</verb></tscreen>
The additional line in this <tt>slip.login</tt>, <tt>arp -s &dollar;5
00:11:22:33:44:55 pub</tt>, 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.
When using the example above, be sure to replace the Ethernet MAC
address (<tt>00:11:22:33:44:55</tt>) 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 <tt>netstat -i</tt>; the second line of the output
should look something like:
<tscreen><verb>
ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116
^^^^^^^^^^^^^^^
</verb></tscreen>
which indicates that this particular system's Ethernet MAC address is
<tt>00:02:c1:28:5f:4a</tt> -- the periods in the Ethernet MAC address
given by <tt>netstat -i</tt> 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 <tt>arp(8)</tt> desires; see the manual page on
<tt>arp(8)</tt> for complete information on usage.
Note that when you create <tt>/etc/slip.login</tt> and
<tt>/etc/slip.logout</tt>, the ``execute'' bit (ie, <tt>chmod 755
/etc/slip.login /etc/slip.logout</tt>) must be set, or
<tt>sliplogin</tt> will be unable to execute it.
<sect2>slip.logout Configuration
<p>
<tt>/etc/slip.logout</tt> isn't strictly needed (unless you are
implementing ``proxy ARP''), but if you decide to create it, this is
an example of a basic <tt>slip.logout</tt> script:
<tscreen><verb>
----- begin /etc/slip.logout -----
#!/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
----- end /etc/slip.logout -----
</verb></tscreen>
If you are using ``proxy ARP'', you'll want to have
<tt>/etc/slip.logout</tt> remove the ARP entry for the SLIP client:
<tscreen><verb>
----- begin /etc/slip.logout for "proxy ARP" -----
#!/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 $5
----- end /etc/slip.logout for "proxy ARP" -----
</verb></tscreen>
The <tt>arp -d &dollar;5</tt> removes the ARP entry that the ``proxy ARP''
<tt>slip.login</tt> added when the SLIP client logged in.
It bears repeating: make sure <tt>/etc/slip.logout</tt> has the
execute bit set for after you create it (ie, <tt>chmod 755
/etc/slip.logout</tt>).
<sect1>Routing Considerations
<p>
If 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
<tt>gated</tt> on your FreeBSD SLIP server so that it will tell your
routers via appropriate routing protocols about your SLIP subnet.
<sect2>Static Routes
<p>
Adding static routes to your nearest default routers can be
troublesome (or impossible, if you don't 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.
<sect2>Running gated
<p>
An alternative to the headaches of static routes is to install
<tt>gated</tt> 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. <tt/gated/ is available via anonymous ftp from
<tt>ftp.gated.cornell.edu</tt> in the directory <tt>/pub/gated</tt>; I
believe the current version as of this writing is
<tt>gated-R3_5Alpha_8.tar.Z</tt>, which includes support for FreeBSD
``out-of-the-box''. Complete information and documentation on
<tt>gated</tt> is available on the Web starting at
<tt>http://www.gated.cornell.edu/</tt>. Compile and install it, and
then write a <tt>/etc/gated.conf</tt> file to configure your gated;
here's a sample, similar to what I use on my FreeBSD SLIP server:
<tscreen><verb>
----- begin sample /etc/gated.conf for gated version 3.5Alpha5 -----
#
# 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 ;
} ;
----- end sample /etc/gated.conf -----
</verb></tscreen>
The above sample <tt>gated.conf</tt> file broadcasts routing
information regarding the SLIP subnet <tt>xxx.xxx.yy</tt> via RIP onto
the Ethernet; if you are using a different Ethernet driver than the
<tt/ed/ driver, you'll need to change the references to the <tt/ed/
interface appropriately. This sample file also sets up tracing to
<tt>/var/tmp/gated.output</tt> for debugging <tt>gated</tt>'s
activity; you can certainly turn off the tracing options if
<tt>gated</tt> works OK for you. I've changed my SLIP subnet's
address to <tt>xxx.xxx.yy</tt> throughout the above file; you'll need
to change the <tt>xxx.xxx.yy</tt>'s into the network address of your
own SLIP subnet (be sure to change the net mask in the <tt>proto
direct</tt> clause as well).
When you get <tt>gated</tt> built and installed and create a
configuration file for it, you'll need to run <tt>gated</tt> in place
of <tt>routed</tt> on your FreeBSD system; change the
<tt>routed/gated</tt> startup parameters in <tt>/etc/netstart</tt> as
appropriate for your system. Please see the manual page for
<tt>gated</tt> for information on <tt>gated</tt>'s command-line
parameters.
<sect1>Acknowledgements
<p>
Thanks to these people for comments and advice regarding this FAQ:
<descrip>
<tag/Wilko Bulte/ &lt;wilko@yedi.iaf.nl&gt;
<tag/Piero Serini/ &lt;Piero@Strider.Inet.IT&gt;
</descrip>
<!-- </article> -->

181
handbook/submitters.sgml Normal file
View file

@ -0,0 +1,181 @@
<!-- $Id: submitters.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Contributing to FreeBSD</heading>
<p><em>Contributed by &a.jkh;.</em>
This guide is intended for those who are moderately familar with FreeBSD
and are now to the point where they have some locally developed
customizations or fixes to the system which they'd like to incorporate
back into the mainstream sources, thus saving the work of having to
re-integrate the changes for each subsequent FreeBSD release. Submitting
something to the FreeBSD project is also an excellent way of getting your
code seriously *tested*! Many people have developed an original concept
far beyond what they might have envisioned at the start just due to the
flood of feedback and ideas generated by the many thousands of users of
FreeBSD. Contributions are also what FreeBSD lives and grows from,
and so your contributions are very important to the continued survival
of this communal effort of ours - we're very glad to see you reading this
documentation! :-)
Submissions to FreeBSD can generally be classified into four catagories:
<enum>
<item> Ideas, general suggestions, bug reports.
<item> Addition, deletion, renaming or patching of existing sources.
<item> Significant contribution of a large body of independant work.
<item> Porting of freely available software.
</enum>
A submission in *any* of these catagories is highly welcomed as they
are each, in their own way, quite significant to the project.
<sect><heading>Ideas and suggestions</heading>
<p>An idea, suggestion or fix can be communicated in one of the following ways:
<itemize>
<item> An idea or suggestion of general technical interest should be
mailed to &lt;hackers@freebsd.org&gt;. Likewise, people with an interest
in such things (and a tolerance for a HIGH volume of mail!) may
subscribe by sendimg mail to &lt;majordomo@freebsd.org&gt;. See also the
file /usr/share/FAQ/mailing-list.FAQ.
<item> An actual bug report should be filed by using the send-pr(1)
command (``man send-pr'' for information). This will prompt
you for various fields to fill in. Simply go to the fields
surrounded by &lt;&gt;'s and fill in your own information in place of
what's suggested there. You should receive confirmation of your
bug report and a tracking number (which you should also reference in
any subsequent correspondence).
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 send-pr command, then you may also
file a bug report (or follow-up to one) by sending mail to:
&lt;bugs@freebsd.org&gt;
</itemize>
<sect><heading>Changes to the existing code</heading>
<p>An 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" and made available in a variety of
ways (see /usr/share/FAQ/current-policy.FAQ and /usr/share/FAQ/ctm.FAQ) for
the convenience of developers who wish to actively work on the system.
Working from older sources unfortunately means that your changes may
sometimes be too obsolete to use, or too divergent to allow for easy
re-integration. This can be minimized somewhat by subscribing to the
&lt;announce@freebsd.org&gt; mailing list (among others) where periodic
announcements concerning the current state of the system are made.
If you see a change being proposed for which you have a better solution,
then please, by all means come forward with your contribution and we
will do our very best to evaluate it fairly and perhaps integrate it if
it is indeed a better (or easier :) solution.
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 for evaluation and possible adoption. This is done
with the diff(1) command, with the FreeBSD maintainers preferring to receive
diffs in `context diff' form. See the man page for diff for more details
on producing both context and recursive context diffs
(diff -c &lt;oldfile&gt &lt;newfile&gt; or diff -c -r &lt;olddir&gt; &lt;newdir&gt;).
Once you have a set of diffs that are capable of taking a copy of the
original code and bringing it to a state identical to the "new" sources
(you may test this with the patch(1) command - see patch man page), you
should bundle them up in an email message and send it, along with a brief
description of what the diffs are for, to &lt;hackers@freebsd.org&gt;. Someone
will very likely get back in touch with you in 24 hours or less, assuming
of course that your diffs are interesting! :-)
If your changes don't express themselves well as diffs alone (e.g. you've
perhaps added, deleted or renamed files as well) then you may be better off
bundling any new files, diffs and instructions for deleting/renaming any
others into a tar file and running the `uuencode' program on it before
sending the output of that to &lt;hackers@freebsd.org&gt;. See the man pages
on tar and uuencode for more info on bundling files through the mail this
way.
If your change is of a potentially sensitive nature, e.g. you're unsure
of copyright issues governing its further distribution, or you're simply
not ready to release it without a tighter review first, then you should
send it to &lt;core@freebsd.org&gt; rather than &lt;hackers@freebsd.org&gt;. 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 really only mail to them in cases where mailing to hackers
truly is impractical.
<sect><heading>Contributions of new code</heading>
<p>In 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 (see above)
or upload them to our ftp site:
<url url="ftp://freefall.cdrom.com/pub/FreeBSD/incoming">
Users may log in anonymously and upload their work or download the
work-in-progress files left by others.
When working with large amounts of code, the touchy subject of copyrights
also invariably comes up. The view of the FreeBSD project towards
acceptable copyrights (for code included in FreeBSD) are:
<enum>
<item> Contributions under the BSD copyright (see the file
/usr/share/examples/etc/bsd-style-copyright for a template)
is greatly preferred due to its "no strings attached"
nature and general attractiveness to commercial enterprises
who might then be inclined to invest something of their own
into FreeBSD.
<item> Contributions under the GNU Public License, or "GPL". This is
not quite as popular a solution for us, due to (all religious
issues aside) the amount of extra effort demanded of anyone
using the code for commercial purposes. However, given the
sheer quantity of GPL'd code we currently require (compiler,
assembler, text formatter, etc), it would be silly to pretend
that we couldn't deal with the GPL at all and so we have become
more willing to accept code with either the BSD or the GPL
copyright. Code under the GPL also goes into a different part
of the tree, that being /sys/gnu or /usr/src/gnu.
<item> Contributions coming under any other type of copyright must be
carefully reviewed before their inclusion into FreeBSD will even
be considered. Contributions for which particularly restrictive
commercial copyrights apply are generally rejected, though the
authors are always free to make the changes available through
their own channels.
</enum>
<sect><heading>Porting of software</heading>
<p>The porting of freely available software, while perhaps not as gratifying
as developing your own package from scratch, is still a vital part of
FreeBSD's growth and of great usefulness to those who wouldn't otherwise
know where to turn for it. All ported software is organized into a
hierarchy know as ``the ports collection''. This collection enables
a new user to get a complete overview of what's available in a short time,
and with a logical (we hope) framework. The ports collection also saves
considerable space by not actually containing the the majority of the
sources being ported. This can be confusing to the new user and the file
/usr/share/FAQ/ports.FAQ goes some way towards explaing how it all works.
If you have the ports collection on your machine, the file
/usr/ports/GUIDELINES also helps to explain the process of creating
and contributing a port of your own. For more information on the ports
collection (that wasn't available in the FAQ), you may also send mail to
&lt;ports@freebsd.org&gt;.
Whichever way you decide to contribute, we hope you'll find it an enjoyable
process and also realize how valuable your contributions are to the project!
FreeBSD is one of those great projects where the more we all put in, the
more we all get back out of it again, and with enough steady contributions
it begins to aquire a momentum of its own. It is through such momentum
that mountains are moved!

92
handbook/sup.sgml Normal file
View file

@ -0,0 +1,92 @@
<!-- $Id: sup.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>SUP</heading>
<p><em>Contributed by &a.jkh; and &a.gclarkii;.</em>
SUP is a network based software update tool developed at CMU. The
purpose of this document is get the beginner up and running with sup.
<sect1><heading>Getting setup</heading>
<p>First off you will need to pick up the sup binaries. The easiest
way of doing this is to grab the sup.tgz package from:
<verb>
ftp://ftp.FreeBSD.ORG:/pub/FreeBSD/packages/sup.tgz
</verb>
Install the sup package using pkg_add and add the following line to
your /etc/services file:
<verb>
sup 871/tcp #sup
</verb>
SUP gets the information it needs to run from a configuration file
called a supfile. This file tells sup what collections it will be updating
and/or installing and where they go. The supfile in this directory will
sup both the source and ports collection - look for the blank line seperating
the two collections; if you don't want ports, you can simply delete all the
ports entries. If you're inside the United States, you may also uncomment
the `secure' collection line to grab the DES code. If you're outside the
U.S., you should NOT sup this code from FreeBSD.ORG as this will
violate U.S. export restrictions. Simply sup everything *but* the secure
collection and then go look on "braae.ru.ac.za", where it's available for
anonymous ftp for those outside the U.S.
Any other distributions you do not wish to receive can be commented out
with a # at the begining of the distribution line.
Once this is setup, you're ready to go. To start sup type:
<verb>
sup supfile
</verb>
If you wish to see what sup is doing "verbosely", give it the -v option,
like so:
<verb>
sup -v supfile
</verb>
Thats all there is to it! Remember that if you're running current,
which is what you will have if you sup, please join the freebsd-current
mailing list. You should also be sure to read:
<verb>
ftp://ftp.FreeBSD.ORG:/pub/FreeBSD/FAQ/current-policy.FAQ
</verb>
For important information on just what we can and cannot do for you as
a -current user.
<sect1><heading>Description of FreeBSD SUP distributions</heading>
<p>For the main FreeBSD distribution:
<verb>
base: /usr/src/... misc files at the top of /usr/src
bin: /usr/src/bin system binaries
secure: /usr/src/secure DES Sources. U.S./Canada only!
etc: /usr/src/etc system files
games: /usr/src/games games
gnu: /usr/src/gnu sources under the GNU Public License
include: /usr/src/include include files
sys: /usr/src/sys kernel sources
lib: /usr/src/lib libraries
libexec: /usr/src/libexec more system binaries
share: /usr/src/share various shared resources
sbin: /usr/src/sbin even more system binaries
usrbin: /usr/src/usr.bin user binaries
usrsbin: /usr/src/usr.sbin that's it for the system binaries
</verb>
And for the ports collection:
<verb>
ports-base: /usr/ports/... misc files at the top of /usr/ports
ports-editors: /usr/ports/editors text editors
ports-game: /usr/ports/games games
ports-lang: /usr/ports/lang programming languages
ports-mail: /usr/ports/mail mail software
ports-math: /usr/ports/math math software
ports-net: /usr/ports/net networking software
ports-news: /usr/ports/news USENET news software
ports-print: /usr/ports/print printing software
ports-shells: /usr/ports/shells various UN*X shells
ports-utils: /usr/ports/utils miscellaneous utilities
ports-x11: /usr/ports/x11 X11 software
</verb>

185
handbook/troubleshooting.sgml Normal file
View file

@ -0,0 +1,185 @@
<!-- $Id: troubleshooting.sgml,v 1.1.1.1 1995-04-28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Troubleshooting</heading>
<p>The following tips and tricks may help you turn a
failing (or failed) installation attempt into a success.
Please read them carefully.
<sect>
<heading>Hardware conflict or misconfiguration</heading>
<p><descrip>
<tag>Problem:</tag> A device is conflicting with
another or doesn't match the kernel's compiled-in IRQ or
address.
<tag>Cause:</tag> While most device drivers in
FreeBSD are now smart enough to match themselves to your
hardware settings dynamically, there are a few that still
require fairly rigid configuration parameters to be
compiled in (and matched by the hardware) before they'll
work. We're working hard to eliminate as many of these
last hold-outs as we can, but it's not always as easy as
it looks.
<tag>Solution:</tag> There are several possible
solutions. The first, and easiest, is to boot the kernel
with the <tt>-c</tt> flag. When you see the initial boot prompt
(from floppy or hard disk), type:
<tscreen><verb>
/kernel -c
</verb></tscreen>
This will boot just past the memory sizing code and then
drop into a dynamic kernel configuration utility. Type
`<tt>?</tt>' at the prompt to see a list of commands.
You can use this utility to reset the IRQ, memory
address, IO address or a number of other device
configuration parameters. You can also disable a device
entirely if it's causing problems for other devices you'd
much rather have work. Note that this only affects the
kernel being booted temporarily, it does not write out
the information to the kernel so that these settings are
permanantly altered (this would be actually rather hard).
If you reboot, you'll have to make the same changes
again. The goal of the <tt>-c</tt> utility is to get you
up far enough to be able to download the appropriate
sources and configure and rebuild a kernel more specific
to your needs.
Another solution is, obviously, to remove the offending
hardware or simply strip the system down to the bare
essentials until the problem (hopefully) goes away. Once
you're up, you can do the same thing mentioned
above---compile a kernel more suited to your hardware, or
incrementally try to figure out what it was about your
original hardware configuration that didn't work.
</descrip>
<sect>
<heading>My floppy-tape drive isn't probed</heading>
<p>Cause: Last-minute problems with this driver caused it
to be disabled by default.
Solution: Boot with -c (described above) and set the
flags value of fdc0 to 1. This will re-enable the floppy
tape driver. Sorry, but it was causing problems for
other people!
<sect>
<heading>When I boot for the first time, it still looks for
/386bsd!</heading>
<p>Cause: You still have the old FreeBSD 1.x boot blocks on
your boot partition.
Solution: You should re-enter the installation process,
invoke the (F)disk editor and chose the (W)rite option.
This won't hurt an existing installation and will make
sure that the new boot blocks get written to the drive.
If you're installing for the first time, don't forget to
(W)rite out your new boot blocks! :-)
<sect>
<heading>I want to boot FreeBSD off the second drive. It
doesn't!</heading>
<p>Cause: FreeBSD will actually install just fine on a
drive other than 0 (the first drive), and the boot
manager will even allow you to select it, but the boot
blocks rather pathologically assume 0. This should be
fixed in 2.1.
Solution: Easy - follow these steps:
1. Select the first (0) drive from the (F)disk editor
and write out the boot manager with the (B) option.
This will enable the boot manager that allows you to
actually boot off the other drive.
2. Exit the fdisk editor for the first drive and and
re-enter it again for the drive you wish to install
on. Set up a partition on this drive, or select
(A)ll for the entire drive.
3. Enter the disklabel editor and allocate space on
your second drive as normal. Proceed with the
installation.
4. Once you've installed on the disk and are going to
reboot from the hard disk, enter the following at
the boot prompt:
hd(1,a)/kernel
This will ensure that you really boot from the second
drive. If you've actually installed on a drive other
than 1 (the 3rd or 4th drive?), substitute that number
in for the above. You will need to enter this EVERY
time you reboot from the hard disk. If you're feeling
brave and have a srcdist + the requisite experience,
you can hack the boot blocks in:
/usr/src/sys/i386/boot/biosboot
So that this drive you're booting from is hard-coded.
Recompile the boot blocks and reinstall them on your
drive with `disklabel -B ...' You can then have the
default Do The Right Thing.
<sect>
<heading>Newfs crashes, requesting that blocksize be 32K</heading>
<p>Cause: You have your SCSI controller configured to
translate geometries for disks >1GB in size.
Solution: Turn such translation OFF in your controller's
BIOS setup! FreeBSD has no problems with disks >1GB just
so long as the root partition starts and ends BELOW
cylinder 1024. This is a PC hardware limitation.
<sect>
<heading>FreeBSD won't boot off the hard disk</heading>
<p>Cause: Root partition does not start and end below
cylinder 1024.
Solution: See solution for newfs crashes, or move your
root partition. This limitation holds true for ANY
operating system you wish to boot from your hard drive.
<sect>
<heading>FreeBSD still won't boot off the hard disk</heading>
<p>Cause: No boot code is installed in sector 1.
Solution: Chose the Write MBR (B)oot code in the FDISK
editor.
<sect>
<heading>Nope, FreeBSD's still not booting from the hard
disk</heading>
<p>Cause: BIOS disk geometry different from that used when
installing FreeBSD.
Solution: With IDE drives, pay careful attention to the
geometry information that FreeBSD prints out when it's
first booting off the floppy. Use this geometry in your
BIOS setup or use the BIOS geometry when you install
FreeBSD. Either way, they have to match.
With SCSI drives, the values they report is most often
bogus and cannot be used. In this situation, the SCSI
controller is performing geometry translation and it's
probably wise to assume a default of 64 heads, 32 sectors
and 1MB/cylinder. Use these values when you install
FreeBSD. See above comments concerning newfs failures
for more info.