commit 4776451dac895d2c78d6aa20083001d7d5c3c535
Author: John Fieber <jfieber@FreeBSD.org>
Date: Fri Apr 28 16:19:59 1995 +0000
The FreeBSD handbook finds a new home.
Notes:
svn path=/head/; revision=2
diff --git a/handbook/authors.sgml b/handbook/authors.sgml
new file mode 100644
index 0000000000..336549c96b
--- /dev/null
+++ b/handbook/authors.sgml
@@ -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><jkh@FreeBSD.org></tt>">
+<!ENTITY a.jfieber "John Fieber <tt><jfieber@FreeBSD.org></tt>">
+<!ENTITY a.phk "Poul-Henning Kamp <tt><phk@FreeBSD.org></tt>">
+<!ENTITY a.gclarkii "Gary Clark II <tt><gclarkii@FreeBSD.org></tt>">
+<!ENTITY a.gena "Gennady B. Sorokopud <tt><gena@NetVision.net.il></tt>">
+<!ENTITY a.ghelmer "Guy Helmer <tt><ghelmer@alpha.dsu.edu></tt>">
+<!ENTITY a.md "Mark Dapoz <tt><md@bsc.no></tt>">
+<!ENTITY a.martin "Martin Renters <tt><martin@innovus.com></tt>">
+<!ENTITY a.gpalmer "Gary Palmer <tt><gpalmer@FreeBSD.org></tt>">
+<!ENTITY a.john "John Lind <tt><john@starfire.MN.ORG></tt>">
+<!ENTITY a.asami "Satoshi Asami <tt><asami@FreeBSD.org></tt>">
+<!ENTITY a.wilko "Wilko Bulte <tt><wilko@yedi.iaf.nl></tt>">
diff --git a/handbook/basics.sgml b/handbook/basics.sgml
new file mode 100644
index 0000000000..dfa49b6569
--- /dev/null
+++ b/handbook/basics.sgml
@@ -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>
+
diff --git a/handbook/bibliography.sgml b/handbook/bibliography.sgml
new file mode 100644
index 0000000000..fea48a3cb9
--- /dev/null
+++ b/handbook/bibliography.sgml
@@ -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 & Associates, Inc. 1990</item>
+ </itemize>
+
+ <sect>
+ <heading>Administrators' guides</heading>
+
+ <p><itemize>
+
+ <item>Albitz, Paul; Liu, Cricket. <em>DNS and
+ BIND</em>. O'Reilley & Associates. 1993. ISBN
+ 1-56592-010-4 </item>
+
+ <item>Costales, Brian; Allman, Eric; Rickert,
+ Neil. <em>sendmail</em> O'Reilley &
+ Associates. 1993. ISBN 1-56592-056-2 </item>
+
+ <item>Frisch, Æleen. <em>Essential System
+ Administration</em>. O'Reilley &
+ Associates. 1993. ISBN 0-937175-80-3 </item>
+
+ <item>Hunt, Craig. <em>TCP/IP Network Administration</em>
+ O'Reilley & 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&D Publications
+ Inc. ISSN 1075-2838</item>
+
+ </itemize>
+
+ </sect>
+
diff --git a/handbook/ctm.sgml b/handbook/ctm.sgml
new file mode 100644
index 0000000000..be80df0e25
--- /dev/null
+++ b/handbook/ctm.sgml
@@ -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/<majordomo@freebsd.org>/ 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#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_[rs]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>
+
diff --git a/handbook/current.sgml b/handbook/current.sgml
new file mode 100644
index 0000000000..bfb0751121
--- /dev/null
+++ b/handbook/current.sgml
@@ -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!
+-->
+
+
+
+
diff --git a/handbook/dialup.sgml b/handbook/dialup.sgml
new file mode 100644
index 0000000000..4eeaf28471
--- /dev/null
+++ b/handbook/dialup.sgml
@@ -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 & 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'' [the source for which is in
+<tt>/usr/src/share/doc/smm</tt>] and ``FreeBSD Configuration
+Options'' [in <tt>/sys/doc/options.doc</tt>] 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
+& 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 & 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><Enter></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 #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
+& 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&C1&D2&H1&I0&R2&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&B1&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&B2&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><Enter></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&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/ <kelly@fsl.noaa.gov> for a number of good
+suggestions
+
+</descrip>
+
+
diff --git a/handbook/diskless.sgml b/handbook/diskless.sgml
new file mode 100644
index 0000000000..25baa4dc03
--- /dev/null
+++ b/handbook/diskless.sgml
@@ -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.
+
diff --git a/handbook/eresources.sgml b/handbook/eresources.sgml
new file mode 100644
index 0000000000..c8da616aae
--- /dev/null
+++ b/handbook/eresources.sgml
@@ -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>
diff --git a/handbook/glossary.sgml b/handbook/glossary.sgml
new file mode 100644
index 0000000000..385e6731a6
--- /dev/null
+++ b/handbook/glossary.sgml
@@ -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>
+
diff --git a/handbook/handbook.sgml b/handbook/handbook.sgml
new file mode 100644
index 0000000000..a53bb2638a
--- /dev/null
+++ b/handbook/handbook.sgml
@@ -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><doc@freebsd.org></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>
+
+ ¤t;
+ &ctm;
+ ⊃
+ &troubleshooting;
+ &submitters;
+
+ &bibliography;
+ &eresources;
+ &glossary;
+
+ </book>
+</linuxdoc>
diff --git a/handbook/kerberos.sgml b/handbook/kerberos.sgml
new file mode 100644
index 0000000000..7eca30e497
--- /dev/null
+++ b/handbook/kerberos.sgml
@@ -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.
diff --git a/handbook/nfs.sgml b/handbook/nfs.sgml
new file mode 100644
index 0000000000..8d0e4b25fb
--- /dev/null
+++ b/handbook/nfs.sgml
@@ -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.
diff --git a/handbook/porting.sgml b/handbook/porting.sgml
new file mode 100644
index 0000000000..a633ac990b
--- /dev/null
+++ b/handbook/porting.sgml
@@ -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>${..}</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><sys/param.h></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_ >
+ 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><foo>.tar.gz</tt> or
+ <tt><foo>.tar.Z</tt>) and copy it into
+ <tt>${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>${DISTDIR}</tt> blown
+ away, which is to say that it should be possible for
+ a user to repopulate all of
+ <tt>${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>${DISTDIR}</tt>.
+ The pre-fetch target hook is optional. If fetch
+ cannot find the required files in
+ <tt>${DISTDIR}</tt> it will look up the URL
+ <tt>${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>${NCFTP}</tt>, assuming that the requesting
+ site has direct access to the Internet. If that
+ succeeds, it will save the file in
+ <tt>${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>${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>${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>${SCRIPTDIR}/pre-configure</tt>
+
+ <item><tt>${SCRIPTDIR/configure</tt> or
+ <tt>${WRKSRC}/configure</tt> if
+ <tt>${HAS_CONFIGURE}</tt> is set.
+
+ <item>If <tt>${USE_IMAKE}</tt> is set, an
+ xmkmf command is done.
+
+ <item><tt>${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>${WRKSRC}</tt>) and
+ building it. If <tt>${USE_GMAKE}</tt> is
+ set, GNU <tt>make</tt> will be used, otherwise
+ the system <tt>${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-<xx></tt>" where <tt><xx></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>${PATCHDIR}</tt>, from where they will be
+ automatically applied. All patches should be
+ relative to <tt>${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>${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>${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>${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>${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>${EXTRACT_CMD}</tt>,
+ <tt>${EXTRACT_ARGS}</tt>,
+ <tt>${EXTRACT_SUFX}</tt>, or
+ <tt>${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>${DISTNAME}</tt> to be the base
+ name of your port. The default rules expect the
+ distribution file list (<tt>${DISTFILES}</tt>) to be
+ named
+ <tt>${DISTDIR}/${DISTFILE}${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>${WRKDIR}/${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>${DISTFILES}</tt> explicitly. If
+ only a subset of <tt>${DISTFILES}</tt> are actual
+ extractable archives, then set them up in
+ <tt>${EXTRACT_ONLY}</tt>, which will override the
+ <tt>${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>${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>${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>${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>${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><bsd.port.mk></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>${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> ${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>
+
diff --git a/handbook/ports.sgml b/handbook/ports.sgml
new file mode 100644
index 0000000000..702c232225
--- /dev/null
+++ b/handbook/ports.sgml
@@ -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 & 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.
diff --git a/handbook/ppp.sgml b/handbook/ppp.sgml
new file mode 100644
index 0000000000..92d82bc289
--- /dev/null
+++ b/handbook/ppp.sgml
@@ -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
+-->
+
diff --git a/handbook/scsi.sgml b/handbook/scsi.sgml
new file mode 100644
index 0000000000..babcd0db8e
--- /dev/null
+++ b/handbook/scsi.sgml
@@ -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>© 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
+ []):
+
+ <verb>
+controller ahb0 at isa? bio irq 11 vector ahbintr [driver for Adaptec 174x]
+controller aha0 at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr [for Adaptec 154x]
+controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr [for Seagate
+ST01/02]
+controller scbus0
+
+device sd0 [support for 4 SCSI harddisks, sd0 up sd3]
+device sd1
+device sd2
+device sd3
+
+device st0 [support for 2 SCSI tapes]
+device st1
+
+device cd0 #Only need one of these, the code dynamically grows [for the cdrom]
+ </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) [X3.221-1994] Approved
+ ATA Extensions (ATA-2) [X3T10/948D Rev 2i]
+ Enhanced Small Device Interface (ESDI) [X3.170-1990/X3.170a-1991] Approved
+ Small Computer System Interface - 2 (SCSI-2) [X3.131-1994] Approved
+ SCSI-2 Common Access Method Transport and SCSI Interface Module (CAM)
+ [X3T10/792D Rev 11]
+ </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.
diff --git a/handbook/slipc.sgml b/handbook/slipc.sgml
new file mode 100644
index 0000000000..9787331388
--- /dev/null
+++ b/handbook/slipc.sgml
@@ -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>
\ No newline at end of file
diff --git a/handbook/slips.sgml b/handbook/slips.sgml
new file mode 100644
index 0000000000..799ead042e
--- /dev/null
+++ b/handbook/slips.sgml
@@ -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 & 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>, & <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
+[such as <tt>clocal</tt> for directly-connected serial
+interfaces]).
+
+<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
+[Requirements for Internet Gateways], 1122
+[Requirements for Internet Hosts -- Communication Layers],
+and perhaps 1127 [A Perspective on the Host Requirements
+RFCs]), so if you want your FreeBSD SLIP Server to act as a
+router, you'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'' [the source for which is in
+<tt>/usr/src/share/doc/smm</tt>] and ``FreeBSD Configuration
+Options'' [in <tt>/sys/doc/options.doc</tt>] 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 & 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 $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 $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/ <wilko@yedi.iaf.nl>
+<tag/Piero Serini/ <Piero@Strider.Inet.IT>
+</descrip>
+
+<!-- </article> -->
+
diff --git a/handbook/submitters.sgml b/handbook/submitters.sgml
new file mode 100644
index 0000000000..6607e5593c
--- /dev/null
+++ b/handbook/submitters.sgml
@@ -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 <hackers@freebsd.org>. Likewise, people with an interest
+ in such things (and a tolerance for a HIGH volume of mail!) may
+ subscribe by sendimg mail to <majordomo@freebsd.org>. 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 <>'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:
+
+ <bugs@freebsd.org>
+</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
+ <announce@freebsd.org> 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 <oldfile> <newfile> or diff -c -r <olddir> <newdir>).
+
+ 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 <hackers@freebsd.org>. 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 <hackers@freebsd.org>. 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 <core@freebsd.org> rather than <hackers@freebsd.org>. 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
+ <ports@freebsd.org>.
+
+
+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!
+
diff --git a/handbook/sup.sgml b/handbook/sup.sgml
new file mode 100644
index 0000000000..600aafa7fd
--- /dev/null
+++ b/handbook/sup.sgml
@@ -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>
\ No newline at end of file
diff --git a/handbook/troubleshooting.sgml b/handbook/troubleshooting.sgml
new file mode 100644
index 0000000000..311821fcee
--- /dev/null
+++ b/handbook/troubleshooting.sgml
@@ -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.