The FreeBSD handbook finds a new home.
John Fieber
29 years ago
commit
4776451dac
Notes:
svn2git
3 years ago
svn path=/head/; revision=2
@ -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>">
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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!
|
||||
-->
|
||||
|
||||
|
||||
|
||||
|
||||
@ -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>
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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>
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
@ -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.
|
||||
@ -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.
|
||||
@ -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>
|
||||
|
||||
@ -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.
|
||||
@ -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
|
||||
-->
|
||||
|
||||
@ -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.
|
||||
@ -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>
|
||||
@ -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> -->
|
||||
|
||||
@ -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!
|
||||
|
||||
@ -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>
|
||||
@ -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.
|
||||
Loading…
Reference in New Issue